diff --git a/Dockerfile b/Dockerfile
index ed9b2de78..c7ec79b09 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -43,6 +43,7 @@ WORKDIR /app
 ARG APP_VERSION=dev
 ENV APP_VERSION=${APP_VERSION}
 ENV KOBO_CLOUDSCRAPER_PYTHON=/opt/bookorbit-python/bin/python
+ENV KOREADER_PLUGIN_PATH=/app/koreader-plugin/bookorbit.koplugin
 
 COPY server/requirements/kobo-cloudscraper.txt /tmp/kobo-cloudscraper-requirements.txt
 
@@ -60,6 +61,7 @@ COPY --from=server-builder --chown=node:node /deploy ./
 COPY --from=client-builder --chown=node:node /app/client/dist ./public
 COPY --from=server-builder --chown=node:node /app/server/entrypoint.sh ./entrypoint.sh
 COPY --chown=node:node server/bin/kepubify/ ./bin/kepubify/
+COPY --chown=node:node koreader-plugin/bookorbit.koplugin/ ./koreader-plugin/bookorbit.koplugin/
 
 RUN chmod +x /app/entrypoint.sh /app/bin/kepubify/* && mkdir -p /books /data/covers /data/book-bucket /tmp && chown -R node:node /data /tmp
 
diff --git a/client/src/assets/theme/tokens.css b/client/src/assets/theme/tokens.css
index ac8acf51c..e33be19a3 100644
--- a/client/src/assets/theme/tokens.css
+++ b/client/src/assets/theme/tokens.css
@@ -74,6 +74,14 @@
 
   --scrollbar-thumb: oklch(0.8 var(--tint-c) var(--tint-h));
   --scrollbar-thumb-hover: oklch(0.7 var(--tint-c) var(--tint-h));
+
+  /* Annotation pill hues — fixed, accent-independent. Sources get distinct
+     hues; status uses semantic tiers (Exact stays neutral via --muted). */
+  --pill-web: oklch(0.55 0.16 245);
+  --pill-koreader: oklch(0.52 0.2 295);
+  --pill-kobo: oklch(0.55 0.1 195);
+  --pill-repaired: oklch(0.62 0.14 70);
+  --pill-pending: oklch(0.55 0.09 255);
 }
 
 .dark {
@@ -137,4 +145,11 @@
 
   --scrollbar-thumb: oklch(0.35 var(--tint-c) var(--tint-h));
   --scrollbar-thumb-hover: oklch(0.45 var(--tint-c) var(--tint-h));
+
+  /* Lifted lightness so pills read on dark surfaces */
+  --pill-web: oklch(0.72 0.14 245);
+  --pill-koreader: oklch(0.72 0.17 295);
+  --pill-kobo: oklch(0.74 0.1 195);
+  --pill-repaired: oklch(0.78 0.13 70);
+  --pill-pending: oklch(0.72 0.09 255);
 }
diff --git a/client/src/components/AppHeader.vue b/client/src/components/AppHeader.vue
index 18320e999..7945ab94c 100644
--- a/client/src/components/AppHeader.vue
+++ b/client/src/components/AppHeader.vue
@@ -18,6 +18,7 @@ import {
   Star,
   ExternalLink,
   Sparkles,
+  Highlighter,
 } from '@lucide/vue'
 import { useRouter, useRoute } from 'vue-router'
 import { toast } from 'vue-sonner'
@@ -74,6 +75,7 @@ const githubStarPopoverOpen = ref(false)
 const isBookDockActive = computed(() => route.name === 'book-dock')
 const isAchievementsActive = computed(() => route.name === 'achievements')
 const isStatisticsActive = computed(() => route.name === 'statistics')
+const isAnnotationsActive = computed(() => route.name === 'annotations')
 
 const iconRadiusClass = computed(() => (themeStore.radius === 'sharp' ? 'rounded-none' : 'rounded-full'))
 const canChangePassword = computed(
@@ -89,6 +91,10 @@ function navigateToStatistics() {
   router.push({ name: 'statistics', query: { tab: 'library' } })
 }
 
+function navigateToAnnotations() {
+  router.push({ name: 'annotations' })
+}
+
 function navigateToAchievements() {
   router.push({ name: 'achievements' })
 }
@@ -607,6 +613,27 @@ function formatBadgeStyle(fmt: string) {
           <!-- Notifications button -->
           <NotificationSheet v-if="canAccessNotifications" :icon-radius-class="iconRadiusClass" />
 
+          <!-- Annotations button -->
+          <Tooltip>
+            <TooltipTrigger as-child>
+              <Button
+                variant="ghost"
+                size="icon"
+                class="h-8 w-8 border transition-colors"
+                :class="[
+                  isAnnotationsActive
+                    ? 'border-primary/80 bg-primary/8 text-primary'
+                    : 'border-primary/35 text-foreground/70 hover:border-primary/70 hover:text-foreground',
+                  iconRadiusClass,
+                ]"
+                @click="navigateToAnnotations"
+              >
+                <Highlighter :size="15" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Annotations</TooltipContent>
+          </Tooltip>
+
           <!-- Statistics button -->
           <Tooltip>
             <TooltipTrigger as-child>
diff --git a/client/src/features/annotations/components/AnnotationBookCombobox.vue b/client/src/features/annotations/components/AnnotationBookCombobox.vue
new file mode 100644
index 000000000..b6bcc26a7
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationBookCombobox.vue
@@ -0,0 +1,154 @@
+<script setup lang="ts">
+import { computed, onUnmounted, ref } from 'vue'
+import { ChevronsUpDown, X } from '@lucide/vue'
+import type { AnnotationHubBookFacet } from '@bookorbit/types'
+
+const props = defineProps<{
+  searchFn: (q: string) => Promise<AnnotationHubBookFacet[]>
+  placeholder?: string
+}>()
+
+const model = defineModel<number | 'all'>({ required: true })
+const selectedLabel = defineModel<string | null>('selectedLabel', { required: true })
+
+const inputRef = ref<HTMLInputElement | null>(null)
+const query = ref('')
+const options = ref<AnnotationHubBookFacet[]>([])
+const showDropdown = ref(false)
+const isFocused = ref(false)
+const loading = ref(false)
+const activeIndex = ref(-1)
+let debounceTimer: ReturnType<typeof setTimeout> | null = null
+let latestRequestId = 0
+
+const hasSelection = computed(() => model.value !== 'all')
+const inputValue = computed(() => (isFocused.value ? query.value : (selectedLabel.value ?? '')))
+const showEmpty = computed(() => showDropdown.value && !loading.value && options.value.length === 0)
+
+async function runSearch(q: string) {
+  loading.value = true
+  const requestId = ++latestRequestId
+  try {
+    const result = await props.searchFn(q)
+    if (requestId !== latestRequestId) return
+    options.value = result
+    activeIndex.value = -1
+  } finally {
+    if (requestId === latestRequestId) loading.value = false
+  }
+}
+
+function scheduleSearch(q: string) {
+  if (debounceTimer) clearTimeout(debounceTimer)
+  debounceTimer = setTimeout(() => void runSearch(q), 200)
+}
+
+function onFocus() {
+  isFocused.value = true
+  query.value = ''
+  showDropdown.value = true
+  void runSearch('')
+}
+
+function onInput(event: Event) {
+  query.value = (event.target as HTMLInputElement).value
+  showDropdown.value = true
+  scheduleSearch(query.value)
+}
+
+function select(option: AnnotationHubBookFacet) {
+  model.value = option.bookId
+  selectedLabel.value = option.bookTitle ?? 'Unknown book'
+  query.value = ''
+  showDropdown.value = false
+  isFocused.value = false
+  inputRef.value?.blur()
+}
+
+function clear() {
+  model.value = 'all'
+  selectedLabel.value = null
+  query.value = ''
+  options.value = []
+  showDropdown.value = false
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    activeIndex.value = Math.min(activeIndex.value + 1, options.value.length - 1)
+  } else if (event.key === 'ArrowUp') {
+    event.preventDefault()
+    activeIndex.value = Math.max(activeIndex.value - 1, -1)
+  } else if (event.key === 'Enter' && activeIndex.value >= 0) {
+    event.preventDefault()
+    const option = options.value[activeIndex.value]
+    if (option) select(option)
+  } else if (event.key === 'Escape') {
+    showDropdown.value = false
+  }
+}
+
+function onBlur() {
+  setTimeout(() => {
+    isFocused.value = false
+    showDropdown.value = false
+    query.value = ''
+  }, 150)
+}
+
+onUnmounted(() => {
+  if (debounceTimer) clearTimeout(debounceTimer)
+  latestRequestId = -1
+})
+</script>
+
+<template>
+  <div class="relative w-full sm:w-[14rem]">
+    <input
+      ref="inputRef"
+      :value="inputValue"
+      type="text"
+      role="combobox"
+      aria-label="Filter by book"
+      :aria-expanded="showDropdown"
+      :placeholder="placeholder ?? 'All books'"
+      class="h-9 w-full rounded-md border border-border bg-background pl-2.5 pr-8 text-sm focus:outline-none focus:ring-1 focus:ring-primary"
+      @focus="onFocus"
+      @input="onInput"
+      @keydown="onKeydown"
+      @blur="onBlur"
+    />
+    <button
+      v-if="hasSelection"
+      type="button"
+      aria-label="Clear book filter"
+      class="absolute right-1.5 top-1/2 -translate-y-1/2 inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+      @mousedown.prevent="clear"
+    >
+      <X :size="14" />
+    </button>
+    <ChevronsUpDown v-else :size="14" class="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 text-muted-foreground" />
+
+    <div
+      v-if="showDropdown"
+      class="absolute top-full left-0 mt-1 z-50 w-full min-w-[16rem] max-h-64 overflow-y-auto rounded-md border border-border bg-popover shadow-md"
+    >
+      <p v-if="loading && options.length === 0" class="px-3 py-2 text-sm text-muted-foreground">Searching...</p>
+      <p v-else-if="showEmpty" class="px-3 py-2 text-sm text-muted-foreground">No books found</p>
+      <button
+        v-for="(option, index) in options"
+        :key="option.bookId"
+        type="button"
+        role="option"
+        :aria-selected="option.bookId === model"
+        class="flex w-full items-center justify-between gap-2 px-3 py-1.5 text-left text-sm text-foreground transition-colors hover:bg-accent"
+        :class="{ 'bg-accent': index === activeIndex }"
+        @mousedown.prevent="select(option)"
+      >
+        <span class="min-w-0 flex-1 truncate">{{ option.bookTitle ?? 'Unknown book' }}</span>
+        <span class="shrink-0 text-xs text-muted-foreground">{{ option.count }}</span>
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationBookGroup.vue b/client/src/features/annotations/components/AnnotationBookGroup.vue
new file mode 100644
index 000000000..3ff1659bc
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationBookGroup.vue
@@ -0,0 +1,110 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ChevronDown, ChevronRight } from '@lucide/vue'
+import { RouterLink } from 'vue-router'
+import type { AnnotationHubItem } from '@bookorbit/types'
+import AnnotationBookThumb from './AnnotationBookThumb.vue'
+import AnnotationCard from './AnnotationCard.vue'
+
+const props = defineProps<{
+  bookId: number
+  bookTitle: string
+  author: string | null
+  items: AnnotationHubItem[]
+  selectedIds: Set<number>
+  savingIds: Set<number>
+  trashed: boolean
+  density: 'compact' | 'comfortable'
+}>()
+
+const emit = defineEmits<{
+  toggleSelect: [id: number]
+  jump: [annotation: AnnotationHubItem]
+  trash: [id: number]
+  restore: [id: number]
+  purge: [id: number]
+  updateNote: [id: number, note: string | null]
+  updateColor: [id: number, color: string]
+  updateStyle: [id: number, style: string]
+}>()
+
+const expanded = ref(true)
+
+const bookLink = { name: 'book-detail', params: { bookId: props.bookId }, query: { tab: 'highlights' } }
+
+function toggleExpanded() {
+  expanded.value = !expanded.value
+}
+
+function handleToggleSelect(id: number) {
+  emit('toggleSelect', id)
+}
+
+function handleJump(annotation: AnnotationHubItem) {
+  emit('jump', annotation)
+}
+
+function handleTrash(id: number) {
+  emit('trash', id)
+}
+
+function handleRestore(id: number) {
+  emit('restore', id)
+}
+
+function handlePurge(id: number) {
+  emit('purge', id)
+}
+
+function handleUpdateNote(id: number, note: string | null) {
+  emit('updateNote', id, note)
+}
+
+function handleUpdateColor(id: number, color: string) {
+  emit('updateColor', id, color)
+}
+
+function handleUpdateStyle(id: number, style: string) {
+  emit('updateStyle', id, style)
+}
+</script>
+
+<template>
+  <div>
+    <div class="sticky top-0 z-10 flex items-center gap-2 rounded-md bg-background/95 px-1 py-2 backdrop-blur">
+      <button type="button" class="flex shrink-0 items-center text-muted-foreground transition-colors hover:text-foreground" @click="toggleExpanded">
+        <ChevronDown v-if="expanded" :size="16" />
+        <ChevronRight v-else :size="16" />
+      </button>
+      <AnnotationBookThumb :book-id="bookId" :title="bookTitle" class="h-9 w-7" />
+      <div class="flex min-w-0 flex-col">
+        <RouterLink :to="bookLink" class="truncate text-sm font-semibold text-foreground transition-colors hover:text-primary hover:underline">
+          {{ bookTitle }}
+        </RouterLink>
+        <span v-if="author" class="truncate text-xs text-muted-foreground">{{ author }}</span>
+      </div>
+      <span class="shrink-0 text-xs text-muted-foreground">({{ items.length }})</span>
+    </div>
+
+    <div v-if="expanded" class="mt-1 flex flex-col gap-2 md:ml-7">
+      <AnnotationCard
+        v-for="annotation in items"
+        :key="annotation.id"
+        :annotation="annotation"
+        :selected="selectedIds.has(annotation.id)"
+        :trashed="trashed"
+        :density="density"
+        :show-book-header="false"
+        :saving="savingIds.has(annotation.id)"
+        @toggle-select="handleToggleSelect"
+        @jump="handleJump"
+        @trash="handleTrash"
+        @restore="handleRestore"
+        @purge="handlePurge"
+        @update-note="handleUpdateNote"
+        @update-color="handleUpdateColor"
+        @update-style="handleUpdateStyle"
+      />
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationBookThumb.vue b/client/src/features/annotations/components/AnnotationBookThumb.vue
new file mode 100644
index 000000000..8df6cd084
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationBookThumb.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { BookOpen } from '@lucide/vue'
+import { useCoverVersions } from '@/features/book/composables/useCoverVersions'
+
+const props = defineProps<{ bookId: number; title?: string | null }>()
+
+const { coverUrl } = useCoverVersions()
+const failed = ref(false)
+const src = computed(() => coverUrl(props.bookId, 'thumbnail'))
+
+watch(
+  () => props.bookId,
+  () => {
+    failed.value = false
+  },
+)
+
+function handleError() {
+  failed.value = true
+}
+</script>
+
+<template>
+  <span class="relative flex shrink-0 items-center justify-center overflow-hidden rounded border border-border bg-muted">
+    <img v-if="!failed" :src="src" :alt="title ?? ''" loading="lazy" class="h-full w-full object-cover" @error="handleError" />
+    <BookOpen v-else :size="14" class="text-muted-foreground/60" />
+  </span>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationBulkBar.vue b/client/src/features/annotations/components/AnnotationBulkBar.vue
new file mode 100644
index 000000000..b0431e7c2
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationBulkBar.vue
@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { Contrast, Highlighter, Palette, Strikethrough, Underline, Waves } from '@lucide/vue'
+import { ANNOTATION_HIGHLIGHT_COLORS } from '@bookorbit/types'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+
+defineProps<{ count: number; allVisibleSelected: boolean; showRestyle?: boolean }>()
+
+const emit = defineEmits<{ selectPage: []; clear: []; recolor: [hex: string]; restyle: [style: string] }>()
+
+const COLORS = ANNOTATION_HIGHLIGHT_COLORS
+const STYLES = [
+  { value: 'highlight', label: 'Highlight', icon: Highlighter },
+  { value: 'underline', label: 'Underline', icon: Underline },
+  { value: 'strikethrough', label: 'Strike', icon: Strikethrough },
+  { value: 'squiggly', label: 'Squiggle', icon: Waves },
+  { value: 'invert', label: 'Invert', icon: Contrast },
+]
+
+function handleSelectPage() {
+  emit('selectPage')
+}
+
+function handleClear() {
+  emit('clear')
+}
+
+function handleRecolor(hex: string) {
+  emit('recolor', hex)
+}
+
+function handleRestyle(style: string) {
+  emit('restyle', style)
+}
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-2 rounded-md border border-primary/40 bg-primary/5 px-3 py-2 text-sm">
+    <span class="font-medium text-foreground">{{ count }} selected</span>
+    <button
+      type="button"
+      class="rounded px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+      @click="handleSelectPage"
+    >
+      {{ allVisibleSelected ? 'Page selected' : 'Select page' }}
+    </button>
+    <button
+      type="button"
+      class="rounded px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+      @click="handleClear"
+    >
+      Clear
+    </button>
+
+    <template v-if="showRestyle">
+      <div class="h-5 w-px bg-border" />
+      <div class="flex items-center gap-1">
+        <Palette :size="13" class="text-muted-foreground" />
+        <button
+          v-for="color in COLORS"
+          :key="color.hex"
+          type="button"
+          class="h-6 w-6 rounded-full border border-border transition-transform hover:scale-110"
+          :style="{ background: color.hex }"
+          :title="color.label"
+          :aria-label="`Recolor to ${color.label}`"
+          @click="handleRecolor(color.hex)"
+        />
+      </div>
+      <div class="flex flex-wrap items-center gap-1">
+        <Tooltip v-for="style in STYLES" :key="style.value">
+          <TooltipTrigger as-child>
+            <button
+              type="button"
+              class="flex h-7 w-7 items-center justify-center rounded border border-border bg-card text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+              :aria-label="`Restyle to ${style.label}`"
+              @click="handleRestyle(style.value)"
+            >
+              <component :is="style.icon" :size="14" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent>{{ style.label }}</TooltipContent>
+        </Tooltip>
+      </div>
+    </template>
+
+    <div class="flex-1" />
+    <slot name="trailing" />
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationCard.vue b/client/src/features/annotations/components/AnnotationCard.vue
new file mode 100644
index 000000000..60f051dff
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationCard.vue
@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import type { AnnotationHubItem, AnnotationItem } from '@bookorbit/types'
+import AnnotationListItem from './AnnotationListItem.vue'
+
+withDefaults(
+  defineProps<{
+    annotation: AnnotationHubItem
+    selected: boolean
+    trashed: boolean
+    showBookHeader?: boolean
+    density?: 'compact' | 'comfortable'
+    saving?: boolean
+  }>(),
+  {
+    showBookHeader: true,
+    density: 'comfortable',
+    saving: false,
+  },
+)
+
+const emit = defineEmits<{
+  toggleSelect: [id: number]
+  jump: [annotation: AnnotationHubItem]
+  trash: [id: number]
+  restore: [id: number]
+  purge: [id: number]
+  updateNote: [id: number, note: string | null]
+  updateColor: [id: number, color: string]
+  updateStyle: [id: number, style: string]
+}>()
+
+function handleToggleSelect(id: number) {
+  emit('toggleSelect', id)
+}
+
+function handleJump(annotation: AnnotationItem | AnnotationHubItem) {
+  emit('jump', annotation as AnnotationHubItem)
+}
+
+function handleTrash(id: number) {
+  emit('trash', id)
+}
+
+function handleRestore(id: number) {
+  emit('restore', id)
+}
+
+function handlePurge(id: number) {
+  emit('purge', id)
+}
+
+function handleUpdateNote(id: number, note: string | null) {
+  emit('updateNote', id, note)
+}
+
+function handleUpdateColor(id: number, color: string) {
+  emit('updateColor', id, color)
+}
+
+function handleUpdateStyle(id: number, style: string) {
+  emit('updateStyle', id, style)
+}
+</script>
+
+<template>
+  <AnnotationListItem
+    :annotation="annotation"
+    :selected="selected"
+    :trashed="trashed"
+    mode="hub"
+    :density="density"
+    :show-book-header="showBookHeader"
+    :saving="saving"
+    @toggle-select="handleToggleSelect"
+    @jump="handleJump"
+    @trash="handleTrash"
+    @restore="handleRestore"
+    @purge="handlePurge"
+    @update-note="handleUpdateNote"
+    @update-color="handleUpdateColor"
+    @update-style="handleUpdateStyle"
+  />
+</template>
diff --git a/client/src/features/annotations/components/AnnotationFilterChips.vue b/client/src/features/annotations/components/AnnotationFilterChips.vue
new file mode 100644
index 000000000..de70af666
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationFilterChips.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { X } from '@lucide/vue'
+import type { ActiveFilterChip } from '../lib/filter-chips'
+
+defineProps<{ chips: ActiveFilterChip[] }>()
+const emit = defineEmits<{ remove: [id: string]; clearAll: [] }>()
+
+function handleRemove(id: string) {
+  emit('remove', id)
+}
+
+function handleClearAll() {
+  emit('clearAll')
+}
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-2">
+    <span class="text-xs text-muted-foreground">Active:</span>
+    <button
+      v-for="chip in chips"
+      :key="chip.id"
+      type="button"
+      class="inline-flex items-center gap-1 rounded-full border border-border bg-muted px-2.5 py-1 text-xs text-foreground transition-colors hover:bg-muted/70"
+      :aria-label="`Remove filter ${chip.label}`"
+      @click="handleRemove(chip.id)"
+    >
+      {{ chip.label }}
+      <X :size="12" class="text-muted-foreground" />
+    </button>
+    <button
+      type="button"
+      class="text-xs text-muted-foreground underline-offset-2 transition-colors hover:text-foreground hover:underline"
+      @click="handleClearAll"
+    >
+      Clear all
+    </button>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationFiltersPanel.vue b/client/src/features/annotations/components/AnnotationFiltersPanel.vue
new file mode 100644
index 000000000..a1d998d15
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationFiltersPanel.vue
@@ -0,0 +1,88 @@
+<script setup lang="ts">
+import { Check, X } from '@lucide/vue'
+import { ANNOTATION_COLOR_FILTER_OPTIONS } from '@bookorbit/types'
+
+const colors = defineModel<string[]>('colors', { required: true })
+const dateFrom = defineModel<string>('dateFrom', { required: true })
+const dateTo = defineModel<string>('dateTo', { required: true })
+
+const emit = defineEmits<{ clearAll: [] }>()
+
+const COLOR_OPTIONS = ANNOTATION_COLOR_FILTER_OPTIONS
+const FIELD_LABEL_CLASS = 'flex flex-col gap-1.5 text-xs font-medium text-muted-foreground'
+
+function isSelected(hex: string): boolean {
+  return colors.value.includes(hex)
+}
+
+function toggleColor(hex: string) {
+  colors.value = isSelected(hex) ? colors.value.filter((value) => value !== hex) : [...colors.value, hex]
+}
+
+function clearDates() {
+  dateFrom.value = ''
+  dateTo.value = ''
+}
+
+function handleClearAll() {
+  emit('clearAll')
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-3">
+    <div :class="FIELD_LABEL_CLASS">
+      <span>Colors</span>
+      <div class="flex flex-wrap gap-1.5">
+        <button
+          v-for="option in COLOR_OPTIONS"
+          :key="option.hex"
+          type="button"
+          class="flex h-6 w-6 items-center justify-center rounded-full border-2 transition-transform hover:scale-110"
+          :class="isSelected(option.hex) ? 'border-foreground' : 'border-transparent'"
+          :style="{ background: option.hex }"
+          :title="option.label"
+          :aria-label="option.label"
+          :aria-pressed="isSelected(option.hex)"
+          @click="toggleColor(option.hex)"
+        >
+          <Check v-if="isSelected(option.hex)" :size="12" class="text-white drop-shadow" />
+        </button>
+      </div>
+    </div>
+
+    <div :class="FIELD_LABEL_CLASS">
+      <span>Date range</span>
+      <div class="flex items-center gap-1.5">
+        <input
+          v-model="dateFrom"
+          type="date"
+          aria-label="From date"
+          class="h-9 min-w-0 flex-1 px-2 rounded-md border border-border bg-background text-sm"
+        />
+        <span class="text-xs text-muted-foreground">to</span>
+        <input
+          v-model="dateTo"
+          type="date"
+          aria-label="To date"
+          class="h-9 min-w-0 flex-1 px-2 rounded-md border border-border bg-background text-sm"
+        />
+        <button
+          v-if="dateFrom || dateTo"
+          type="button"
+          aria-label="Clear date range"
+          class="inline-flex h-9 items-center rounded-md border border-border bg-background px-2 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          @click="clearDates"
+        >
+          <X :size="13" />
+        </button>
+      </div>
+    </div>
+
+    <slot name="extra" />
+
+    <div class="flex justify-end border-t border-border pt-3">
+      <button type="button" class="text-sm text-muted-foreground transition-colors hover:text-foreground" @click="handleClearAll">Clear all</button>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationListItem.vue b/client/src/features/annotations/components/AnnotationListItem.vue
new file mode 100644
index 000000000..e7bfe3e8e
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationListItem.vue
@@ -0,0 +1,486 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import {
+  ArchiveRestore,
+  BookOpen,
+  Check,
+  ChevronDown,
+  ChevronUp,
+  Contrast,
+  Copy,
+  FileEdit,
+  Highlighter,
+  Info,
+  Palette,
+  Smartphone,
+  Strikethrough,
+  Trash2,
+  TriangleAlert,
+  Underline,
+  Waves,
+  X,
+} from '@lucide/vue'
+import { RouterLink } from 'vue-router'
+import { ANNOTATION_HIGHLIGHT_COLORS, type AnnotationHubItem, type AnnotationItem } from '@bookorbit/types'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { PILL_CLASS, sourcePill, statusPill } from '@/features/annotations/lib/pill-styles'
+import HighlightNoteEditor from '@/features/book/components/detail/tabs/HighlightNoteEditor.vue'
+import AnnotationBookThumb from './AnnotationBookThumb.vue'
+import AnnotationSyncDetailPanel from './AnnotationSyncDetailPanel.vue'
+import { copyToClipboard } from '@/lib/clipboard'
+
+type AnnotationListItemMode = 'book' | 'hub'
+type AnnotationListDensity = 'compact' | 'comfortable'
+type AnnotationListItem = AnnotationItem | AnnotationHubItem
+
+const props = withDefaults(
+  defineProps<{
+    annotation: AnnotationListItem
+    selected?: boolean
+    selectable?: boolean
+    trashed?: boolean
+    mode?: AnnotationListItemMode
+    density?: AnnotationListDensity
+    saving?: boolean
+    showBookHeader?: boolean
+  }>(),
+  {
+    selected: false,
+    selectable: true,
+    trashed: false,
+    mode: 'hub',
+    density: 'comfortable',
+    saving: false,
+    showBookHeader: false,
+  },
+)
+
+const emit = defineEmits<{
+  toggleSelect: [id: number]
+  jump: [annotation: AnnotationListItem]
+  trash: [id: number]
+  restore: [id: number]
+  purge: [id: number]
+  updateNote: [id: number, note: string | null]
+  updateColor: [id: number, color: string]
+  updateStyle: [id: number, style: string]
+}>()
+
+const COLORS = ANNOTATION_HIGHLIGHT_COLORS
+
+const STYLES = [
+  { value: 'highlight', label: 'Highlight', icon: Highlighter },
+  { value: 'underline', label: 'Underline', icon: Underline },
+  { value: 'strikethrough', label: 'Strike', icon: Strikethrough },
+  { value: 'squiggly', label: 'Squiggle', icon: Waves },
+  { value: 'invert', label: 'Invert', icon: Contrast },
+]
+
+const expanded = ref(false)
+const editingNote = ref(false)
+const showStylePanel = ref(false)
+const showSyncDetail = ref(false)
+const confirmTrash = ref(false)
+const copied = ref(false)
+const pendingNote = ref<string | null | undefined>(undefined)
+
+const canEdit = computed(() => !props.trashed)
+const canJump = computed(() => props.annotation.jumpFileId != null && !props.trashed)
+const isLong = computed(() => props.annotation.text.length > (props.density === 'compact' ? 180 : 260))
+const isApproximate = computed(() => props.annotation.cfi == null && props.annotation.origin !== 'web')
+const hasBookTitle = computed(() => 'bookTitle' in props.annotation && props.annotation.bookTitle != null)
+const showBookHeader = computed(() => props.mode === 'hub' && props.showBookHeader)
+const bookTitleText = computed(() => (hasBookTitle.value && 'bookTitle' in props.annotation ? props.annotation.bookTitle : 'Unknown book'))
+const bookAuthor = computed(() => ('author' in props.annotation ? props.annotation.author : null))
+const bookLink = computed(() => ({ name: 'book-detail', params: { bookId: props.annotation.bookId }, query: { tab: 'highlights' } }))
+
+const styleLabel = computed(() => {
+  return STYLES.find((s) => s.value === props.annotation.style)?.label ?? props.annotation.style
+})
+
+const styleIcon = computed(() => {
+  return STYLES.find((s) => s.value === props.annotation.style)?.icon ?? Highlighter
+})
+
+const originPill = computed(() => sourcePill(props.annotation.origin))
+const positionPill = computed(() => statusPill(props.annotation.positionStatus, isApproximate.value))
+const hasMetadataBeforeSource = computed(() => showBookHeader.value || metadataItems.value.length > 0)
+
+const cardClass = computed(() => [
+  props.selected ? 'ring-1 ring-primary border-primary/50' : 'hover:border-primary/30',
+  props.density === 'compact' ? 'p-2.5 gap-2' : 'p-3 gap-3',
+])
+
+const quoteClampClass = computed(() => (expanded.value ? '' : props.density === 'compact' ? 'line-clamp-2' : 'line-clamp-3'))
+const noteClampClass = computed(() => (expanded.value ? '' : props.density === 'compact' ? 'line-clamp-1' : 'line-clamp-2'))
+
+const metadataItems = computed(() => {
+  const items: string[] = []
+  if (props.mode !== 'hub' && hasBookTitle.value && 'bookTitle' in props.annotation) items.push(props.annotation.bookTitle ?? 'Unknown book')
+  if (props.annotation.chapterTitle) items.push(props.annotation.chapterTitle)
+  if (props.annotation.pageno != null) items.push(`p. ${props.annotation.pageno}`)
+  if (props.annotation.chapterIndex != null) items.push(`chapter ${props.annotation.chapterIndex + 1}`)
+  const date = formatDate(props.annotation.createdAt)
+  if (date) items.push(date)
+  return items
+})
+
+watch(
+  () => props.saving,
+  (saving, wasSaving) => {
+    if (saving || !wasSaving || pendingNote.value === undefined) return
+    if (props.annotation.note === pendingNote.value) {
+      editingNote.value = false
+      pendingNote.value = undefined
+    }
+  },
+)
+
+function formatDate(value: string): string {
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? '' : date.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' })
+}
+
+function handleToggleSelect() {
+  emit('toggleSelect', props.annotation.id)
+}
+
+function handleJump() {
+  emit('jump', props.annotation)
+}
+
+function handleCopy() {
+  void copyToClipboard(props.annotation.text)
+  copied.value = true
+  setTimeout(() => {
+    copied.value = false
+  }, 1500)
+}
+
+function handleTrash() {
+  if (props.mode === 'book' && !confirmTrash.value) {
+    confirmTrash.value = true
+    return
+  }
+  emit('trash', props.annotation.id)
+  confirmTrash.value = false
+}
+
+function handleCancelTrash() {
+  confirmTrash.value = false
+}
+
+function handleRestore() {
+  emit('restore', props.annotation.id)
+}
+
+function handlePurge() {
+  emit('purge', props.annotation.id)
+}
+
+function handleNoteSave(note: string | null) {
+  pendingNote.value = note
+  emit('updateNote', props.annotation.id, note)
+}
+
+function handleNoteCancel() {
+  editingNote.value = false
+}
+
+function toggleExpanded() {
+  expanded.value = !expanded.value
+}
+
+function toggleNoteEditor() {
+  editingNote.value = !editingNote.value
+}
+
+function toggleStylePanel() {
+  showStylePanel.value = !showStylePanel.value
+}
+
+function toggleSyncDetail() {
+  showSyncDetail.value = !showSyncDetail.value
+}
+
+function handleColorSelect(color: string) {
+  if (color !== props.annotation.color) emit('updateColor', props.annotation.id, color)
+}
+
+function handleStyleSelect(style: string) {
+  if (style !== props.annotation.style) emit('updateStyle', props.annotation.id, style)
+}
+
+function shouldSeparateMetadataItem(index: number): boolean {
+  return showBookHeader.value || index > 0
+}
+</script>
+
+<template>
+  <div class="flex items-start rounded-lg border border-border bg-card transition-colors" :class="cardClass">
+    <input
+      v-if="selectable"
+      type="checkbox"
+      class="mt-1 h-4 w-4 shrink-0 accent-[var(--primary)] cursor-pointer"
+      :checked="selected"
+      aria-label="Select annotation"
+      @change="handleToggleSelect"
+    />
+
+    <RouterLink
+      v-if="showBookHeader"
+      :to="bookLink"
+      class="mt-0.5 block shrink-0 transition-opacity hover:opacity-90"
+      :class="density === 'compact' ? 'w-11' : 'w-14'"
+    >
+      <AnnotationBookThumb :book-id="annotation.bookId" :title="bookTitleText" class="w-full" style="aspect-ratio: 2 / 3" />
+    </RouterLink>
+
+    <Tooltip v-else>
+      <TooltipTrigger as-child>
+        <span
+          class="mt-0.5 flex h-6 w-6 shrink-0 items-center justify-center rounded border border-border bg-muted"
+          :style="{ color: annotation.color }"
+        >
+          <component :is="styleIcon" :size="16" />
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>{{ styleLabel }}</TooltipContent>
+    </Tooltip>
+
+    <div class="flex flex-1 min-w-0 flex-col self-stretch">
+      <p class="text-sm leading-relaxed text-foreground" :class="quoteClampClass">
+        {{ annotation.text }}
+      </p>
+
+      <button
+        v-if="isLong"
+        type="button"
+        class="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground"
+        @click="toggleExpanded"
+      >
+        <ChevronUp v-if="expanded" :size="13" />
+        <ChevronDown v-else :size="13" />
+        {{ expanded ? 'Collapse' : 'Expand' }}
+      </button>
+
+      <p
+        v-if="annotation.note && !editingNote"
+        class="mt-2 border-l-2 border-muted pl-2 text-xs italic text-muted-foreground"
+        :class="noteClampClass"
+      >
+        {{ annotation.note }}
+      </p>
+
+      <HighlightNoteEditor v-if="editingNote" :initial-note="annotation.note" :saving="saving" @save="handleNoteSave" @cancel="handleNoteCancel" />
+
+      <AnnotationSyncDetailPanel v-if="showSyncDetail" :annotation-id="annotation.id" />
+
+      <div v-if="showStylePanel && canEdit" class="mt-2 flex flex-col gap-2 rounded-md border border-border bg-background p-2">
+        <div class="flex flex-wrap items-center gap-1.5">
+          <button
+            v-for="c in COLORS"
+            :key="c.hex"
+            type="button"
+            class="h-6 w-6 rounded-full border-2 transition-transform hover:scale-110"
+            :class="annotation.color === c.hex ? 'border-foreground scale-110' : 'border-transparent'"
+            :style="{ background: c.hex }"
+            :title="c.label"
+            @click="() => handleColorSelect(c.hex)"
+          />
+        </div>
+        <div class="flex flex-wrap items-center gap-1">
+          <Tooltip v-for="s in STYLES" :key="s.value">
+            <TooltipTrigger as-child>
+              <button
+                type="button"
+                class="flex h-7 w-7 items-center justify-center rounded border text-xs transition-colors"
+                :class="
+                  annotation.style === s.value
+                    ? 'border-primary bg-primary/10 text-primary'
+                    : 'border-border text-muted-foreground hover:text-foreground'
+                "
+                :style="annotation.style === s.value ? { color: annotation.color } : undefined"
+                @click="() => handleStyleSelect(s.value)"
+              >
+                <component :is="s.icon" :size="13" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>{{ s.label }}</TooltipContent>
+          </Tooltip>
+        </div>
+      </div>
+
+      <div class="mt-auto flex flex-col gap-2 pt-2 sm:flex-row sm:items-center sm:justify-between">
+        <div class="flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-1 text-[11px] text-muted-foreground">
+          <template v-if="showBookHeader">
+            <component :is="styleIcon" :size="13" class="shrink-0" :style="{ color: annotation.color }" />
+            <RouterLink
+              :to="bookLink"
+              class="truncate max-w-[16rem] text-xs font-semibold text-foreground transition-colors hover:text-primary hover:underline"
+            >
+              {{ bookTitleText }}
+            </RouterLink>
+            <span v-if="bookAuthor" aria-hidden="true" class="mx-0.5 block h-1 w-1 shrink-0 rounded-full bg-muted-foreground/70" />
+            <span v-if="bookAuthor" class="truncate max-w-[12rem]">{{ bookAuthor }}</span>
+          </template>
+          <template v-for="(item, index) in metadataItems" :key="`${item}-${index}`">
+            <span
+              v-if="shouldSeparateMetadataItem(index)"
+              aria-hidden="true"
+              class="mx-0.5 block h-1 w-1 shrink-0 rounded-full bg-muted-foreground/70"
+            />
+            <span class="truncate max-w-[14rem]">{{ item }}</span>
+          </template>
+          <span v-if="hasMetadataBeforeSource" aria-hidden="true" class="mx-0.5 block h-1 w-1 shrink-0 rounded-full bg-muted-foreground/70" />
+          <span :class="[PILL_CLASS, originPill.class]">
+            <Smartphone v-if="annotation.origin === 'koreader' || annotation.origin === 'kobo'" :size="10" />
+            {{ originPill.label }}
+          </span>
+          <Tooltip v-if="positionPill">
+            <TooltipTrigger as-child>
+              <button type="button" :class="[PILL_CLASS, positionPill.class, 'transition-colors hover:opacity-80']" @click="toggleSyncDetail">
+                {{ positionPill.label }}
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>{{ showSyncDetail ? 'Hide sync detail' : 'Show sync detail' }}</TooltipContent>
+          </Tooltip>
+          <Tooltip v-if="isApproximate">
+            <TooltipTrigger as-child>
+              <TriangleAlert :size="12" class="text-muted-foreground" />
+            </TooltipTrigger>
+            <TooltipContent>Exact reader position unavailable</TooltipContent>
+          </Tooltip>
+          <span v-if="saving" class="text-primary">Saving</span>
+        </div>
+
+        <div class="flex shrink-0 flex-wrap justify-start gap-0.5 sm:flex-nowrap sm:justify-end">
+          <Tooltip>
+            <TooltipTrigger as-child>
+              <RouterLink
+                :to="{ name: 'book-detail', params: { bookId: annotation.bookId }, query: { tab: 'details' } }"
+                class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-primary"
+              >
+                <Info :size="15" />
+              </RouterLink>
+            </TooltipTrigger>
+            <TooltipContent>Book details</TooltipContent>
+          </Tooltip>
+
+          <Tooltip v-if="canJump">
+            <TooltipTrigger as-child>
+              <button
+                type="button"
+                class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-primary"
+                @click="handleJump"
+              >
+                <BookOpen :size="15" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>Open in reader</TooltipContent>
+          </Tooltip>
+
+          <template v-if="trashed">
+            <Tooltip>
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-primary"
+                  @click="handleRestore"
+                >
+                  <ArchiveRestore :size="15" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>Restore</TooltipContent>
+            </Tooltip>
+            <Tooltip>
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-destructive"
+                  @click="handlePurge"
+                >
+                  <Trash2 :size="15" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>Delete forever</TooltipContent>
+            </Tooltip>
+          </template>
+
+          <template v-else>
+            <Tooltip v-if="canEdit">
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  @click="toggleNoteEditor"
+                >
+                  <FileEdit :size="14" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>{{ annotation.note ? 'Edit note' : 'Add note' }}</TooltipContent>
+            </Tooltip>
+
+            <Tooltip v-if="canEdit">
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded transition-colors hover:bg-muted hover:text-foreground"
+                  :class="showStylePanel ? 'bg-muted text-foreground' : 'text-muted-foreground'"
+                  @click="toggleStylePanel"
+                >
+                  <Palette :size="14" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>Color and style</TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  @click="handleCopy"
+                >
+                  <Check v-if="copied" :size="14" class="text-primary" />
+                  <Copy v-else :size="14" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>{{ copied ? 'Copied' : 'Copy text' }}</TooltipContent>
+            </Tooltip>
+
+            <template v-if="confirmTrash && mode === 'book'">
+              <button
+                type="button"
+                class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                title="Cancel"
+                @click="handleCancelTrash"
+              >
+                <X :size="14" />
+              </button>
+              <button
+                type="button"
+                class="h-7 rounded bg-destructive/15 px-2 text-[10px] font-medium uppercase text-destructive ring-1 ring-destructive/40"
+                @click="handleTrash"
+              >
+                Trash
+              </button>
+            </template>
+            <Tooltip v-else>
+              <TooltipTrigger as-child>
+                <button
+                  type="button"
+                  class="flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-destructive"
+                  @click="handleTrash"
+                >
+                  <Trash2 :size="14" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>Move to trash</TooltipContent>
+            </Tooltip>
+          </template>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationPagination.vue b/client/src/features/annotations/components/AnnotationPagination.vue
new file mode 100644
index 000000000..7e3b839fd
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationPagination.vue
@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from '@lucide/vue'
+import { Button } from '@/components/ui/button'
+
+const props = defineProps<{
+  page: number
+  totalPages: number
+  rangeStart: number
+  rangeEnd: number
+  total: number
+  unit?: string
+}>()
+
+const emit = defineEmits<{ 'update:page': [page: number] }>()
+
+function goTo(page: number) {
+  const clamped = Math.min(Math.max(page, 1), props.totalPages)
+  if (clamped !== props.page) emit('update:page', clamped)
+}
+
+function firstPage() {
+  goTo(1)
+}
+
+function previousPage() {
+  goTo(props.page - 1)
+}
+
+function nextPage() {
+  goTo(props.page + 1)
+}
+
+function lastPage() {
+  goTo(props.totalPages)
+}
+</script>
+
+<template>
+  <div class="mt-6 flex items-center justify-between gap-3 text-sm text-muted-foreground">
+    <span>Showing {{ rangeStart }}-{{ rangeEnd }} of {{ total }}{{ unit ? ` ${unit}` : '' }}</span>
+    <div v-if="totalPages > 1" class="flex items-center gap-1.5">
+      <Button variant="outline" size="icon-sm" :disabled="page <= 1" aria-label="First page" @click="firstPage">
+        <ChevronsLeft :size="14" />
+      </Button>
+      <Button variant="outline" size="icon-sm" :disabled="page <= 1" aria-label="Previous page" @click="previousPage">
+        <ChevronLeft :size="14" />
+      </Button>
+      <span class="px-1">Page {{ page }} of {{ totalPages }}</span>
+      <Button variant="outline" size="icon-sm" :disabled="page >= totalPages" aria-label="Next page" @click="nextPage">
+        <ChevronRight :size="14" />
+      </Button>
+      <Button variant="outline" size="icon-sm" :disabled="page >= totalPages" aria-label="Last page" @click="lastPage">
+        <ChevronsRight :size="14" />
+      </Button>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationSummaryBar.vue b/client/src/features/annotations/components/AnnotationSummaryBar.vue
new file mode 100644
index 000000000..cbf52bcd5
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationSummaryBar.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  texts: string[]
+  origins: { origin: string; label: string; class: string; count: number }[]
+  activeOrigin?: string | null
+}>()
+
+const emit = defineEmits<{ originClick: [origin: string] }>()
+
+const PILL_CLASS = 'inline-flex items-center gap-1 rounded border px-2 py-0.5 text-xs font-medium transition-colors'
+
+const interactive = computed(() => props.activeOrigin !== undefined)
+
+function handleOriginClick(origin: string) {
+  emit('originClick', origin)
+}
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
+    <span v-for="text in texts" :key="text">{{ text }}</span>
+    <span v-if="texts.length > 0 && origins.length > 0" class="h-4 w-px bg-border" />
+    <template v-for="origin in origins" :key="origin.origin">
+      <button
+        v-if="interactive"
+        type="button"
+        :aria-pressed="activeOrigin === origin.origin"
+        :class="[PILL_CLASS, origin.class, activeOrigin === origin.origin ? 'ring-1 ring-primary' : 'hover:opacity-80']"
+        @click="handleOriginClick(origin.origin)"
+      >
+        {{ origin.label }} {{ origin.count }}
+      </button>
+      <span v-else :class="[PILL_CLASS, origin.class]">{{ origin.label }} {{ origin.count }}</span>
+    </template>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationSyncDetailPanel.vue b/client/src/features/annotations/components/AnnotationSyncDetailPanel.vue
new file mode 100644
index 000000000..0cbd49392
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationSyncDetailPanel.vue
@@ -0,0 +1,122 @@
+<script setup lang="ts">
+import { computed, onMounted } from 'vue'
+import { Globe, Loader2, MonitorSmartphone, RefreshCw, Tablet } from '@lucide/vue'
+import type { AnnotationPositionFormat } from '@bookorbit/types'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { useAnnotationSyncDetail } from '../composables/useAnnotationSyncDetail'
+
+const props = defineProps<{ annotationId: number }>()
+
+const { detail, loading, retrying, error, load, retry } = useAnnotationSyncDetail()
+
+const FORMAT_LABELS: Record<AnnotationPositionFormat, string> = {
+  cfi: 'Web reader',
+  xpointer: 'KOReader',
+  pdf: 'PDF',
+  kobo_span: 'Kobo',
+}
+
+const STATUS_LABELS: Record<string, string> = {
+  exact: 'Exact',
+  repaired: 'Repaired',
+  failed: 'Failed',
+  pending: 'Pending',
+}
+
+const positions = computed(() => detail.value?.positions ?? [])
+const devices = computed(() => detail.value?.devices ?? [])
+
+function formatLabel(format: AnnotationPositionFormat): string {
+  return FORMAT_LABELS[format] ?? format
+}
+
+function statusLabel(status: string): string {
+  return STATUS_LABELS[status] ?? status
+}
+
+function statusClass(status: string): string {
+  if (status === 'exact' || status === 'repaired') return 'border-primary/30 bg-primary/10 text-primary'
+  if (status === 'failed') return 'border-destructive/30 bg-destructive/10 text-destructive'
+  return 'border-border bg-muted text-muted-foreground'
+}
+
+function deviceLabel(device: { source: string; deviceId: string; deviceName: string | null }): string {
+  if (device.deviceName) return device.deviceName
+  if (device.source === 'koreader') return `KOReader ${device.deviceId.slice(0, 8)}`
+  return `Kobo ${device.deviceId}`
+}
+
+function formatDate(value: string): string {
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? '' : date.toLocaleString(undefined, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' })
+}
+
+function handleRetry(format: AnnotationPositionFormat) {
+  void retry(props.annotationId, format)
+}
+
+onMounted(() => {
+  void load(props.annotationId)
+})
+</script>
+
+<template>
+  <div class="mt-2 rounded-md border border-border bg-background p-2.5 text-xs">
+    <div v-if="loading" class="flex items-center gap-2 text-muted-foreground">
+      <Loader2 :size="13" class="animate-spin" />
+      Loading sync detail
+    </div>
+
+    <div v-else-if="error" class="text-destructive">{{ error }}</div>
+
+    <template v-else-if="detail">
+      <p class="mb-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">Positions</p>
+      <ul class="flex flex-col gap-1">
+        <li v-for="position in positions" :key="position.format" class="flex flex-wrap items-center gap-2">
+          <span class="w-24 shrink-0 text-muted-foreground">{{ formatLabel(position.format) }}</span>
+          <span class="inline-flex items-center rounded border px-1.5 py-0.5 text-[10px] font-medium" :class="statusClass(position.status)">
+            {{ statusLabel(position.status) }}
+          </span>
+          <span v-if="position.reason" class="truncate text-muted-foreground">{{ position.reason }}</span>
+          <Tooltip v-if="position.status === 'failed' || position.status === 'pending'">
+            <TooltipTrigger as-child>
+              <button
+                type="button"
+                class="flex h-6 w-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                :disabled="retrying === position.format"
+                @click="() => handleRetry(position.format)"
+              >
+                <Loader2 v-if="retrying === position.format" :size="12" class="animate-spin" />
+                <RefreshCw v-else :size="12" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>Retry conversion</TooltipContent>
+          </Tooltip>
+        </li>
+        <li v-if="positions.length === 0" class="text-muted-foreground">No stored positions.</li>
+      </ul>
+
+      <p class="mb-1.5 mt-3 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">Devices</p>
+      <ul class="flex flex-col gap-1">
+        <li v-for="device in devices" :key="`${device.source}-${device.deviceId}`" class="flex flex-wrap items-center gap-2">
+          <span class="inline-flex w-40 shrink-0 items-center gap-1.5 truncate text-foreground">
+            <Tablet v-if="device.source === 'kobo'" :size="12" class="shrink-0 text-muted-foreground" />
+            <MonitorSmartphone v-else :size="12" class="shrink-0 text-muted-foreground" />
+            {{ deviceLabel(device) }}
+          </span>
+          <span
+            class="inline-flex items-center rounded border px-1.5 py-0.5 text-[10px] font-medium"
+            :class="device.upToDate ? 'border-primary/30 bg-primary/10 text-primary' : 'border-border bg-muted text-muted-foreground'"
+          >
+            {{ device.upToDate ? 'Up to date' : `Pending v${detail.version}` }}
+          </span>
+          <span class="text-muted-foreground">synced {{ formatDate(device.lastSyncedAt) }}</span>
+        </li>
+        <li v-if="devices.length === 0" class="flex items-center gap-1.5 text-muted-foreground">
+          <Globe :size="12" />
+          Not synced to any device yet.
+        </li>
+      </ul>
+    </template>
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/AnnotationToolbar.vue b/client/src/features/annotations/components/AnnotationToolbar.vue
new file mode 100644
index 000000000..ac5cc8d44
--- /dev/null
+++ b/client/src/features/annotations/components/AnnotationToolbar.vue
@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { Maximize2, Minimize2, Search, SlidersHorizontal } from '@lucide/vue'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '@/components/ui/sheet'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import AnnotationFilterChips from './AnnotationFilterChips.vue'
+import type { ActiveFilterChip } from '../lib/filter-chips'
+import type { AnnotationDensity } from '../composables/useDensity'
+
+defineProps<{
+  sortOptions: { value: string; label: string }[]
+  filterCount: number
+  chips: ActiveFilterChip[]
+  searchPlaceholder?: string
+}>()
+
+const search = defineModel<string>('search', { required: true })
+const sortKey = defineModel<string>('sortKey', { required: true })
+const density = defineModel<AnnotationDensity>('density', { required: true })
+
+const emit = defineEmits<{ removeChip: [id: string]; clearFilters: [] }>()
+
+function toggleDensity() {
+  density.value = density.value === 'comfortable' ? 'compact' : 'comfortable'
+}
+
+function handleRemoveChip(id: string) {
+  emit('removeChip', id)
+}
+
+function handleClearFilters() {
+  emit('clearFilters')
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-3">
+    <div class="flex flex-wrap items-center gap-2">
+      <div class="relative w-full sm:w-auto sm:flex-1 sm:min-w-[14rem]">
+        <Search :size="14" class="absolute left-2.5 top-1/2 -translate-y-1/2 text-muted-foreground" />
+        <input
+          v-model="search"
+          type="search"
+          :placeholder="searchPlaceholder ?? 'Search text and notes'"
+          class="w-full h-9 pl-8 pr-3 rounded-md border border-border bg-background text-sm focus:outline-none focus:ring-1 focus:ring-primary"
+        />
+      </div>
+
+      <slot name="inline-filters" />
+
+      <div class="hidden sm:block">
+        <Popover>
+          <PopoverTrigger as-child>
+            <Button variant="outline" size="sm" class="gap-1.5">
+              <SlidersHorizontal :size="14" />
+              Filters
+              <Badge v-if="filterCount > 0" variant="secondary" class="ml-0.5 h-5 min-w-5 justify-center px-1">{{ filterCount }}</Badge>
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent align="start" class="w-80">
+            <slot name="filters" />
+          </PopoverContent>
+        </Popover>
+      </div>
+      <div class="sm:hidden">
+        <Sheet>
+          <SheetTrigger as-child>
+            <Button variant="outline" size="sm" class="gap-1.5">
+              <SlidersHorizontal :size="14" />
+              Filters
+              <Badge v-if="filterCount > 0" variant="secondary" class="ml-0.5 h-5 min-w-5 justify-center px-1">{{ filterCount }}</Badge>
+            </Button>
+          </SheetTrigger>
+          <SheetContent side="bottom" class="max-h-[85vh] overflow-y-auto">
+            <SheetHeader>
+              <SheetTitle>Filters</SheetTitle>
+            </SheetHeader>
+            <div class="px-4 pb-6">
+              <slot name="filters" />
+            </div>
+          </SheetContent>
+        </Sheet>
+      </div>
+
+      <select v-model="sortKey" aria-label="Sort order" class="h-9 px-2 rounded-md border border-border bg-background text-sm">
+        <option v-for="option in sortOptions" :key="option.value" :value="option.value">{{ option.label }}</option>
+      </select>
+      <button
+        type="button"
+        :aria-label="density === 'comfortable' ? 'Switch to compact view' : 'Switch to comfortable view'"
+        :title="density === 'comfortable' ? 'Compact view' : 'Comfortable view'"
+        class="inline-flex h-9 w-9 items-center justify-center rounded-md border border-border bg-background text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        @click="toggleDensity"
+      >
+        <Minimize2 v-if="density === 'comfortable'" :size="14" />
+        <Maximize2 v-else :size="14" />
+      </button>
+    </div>
+
+    <AnnotationFilterChips v-if="chips.length > 0" :chips="chips" @remove="handleRemoveChip" @clear-all="handleClearFilters" />
+  </div>
+</template>
diff --git a/client/src/features/annotations/components/__tests__/AnnotationBookCombobox.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationBookCombobox.spec.ts
new file mode 100644
index 000000000..cca8ebefd
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationBookCombobox.spec.ts
@@ -0,0 +1,60 @@
+import { mount, flushPromises } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import type { AnnotationHubBookFacet } from '@bookorbit/types'
+import AnnotationBookCombobox from '../AnnotationBookCombobox.vue'
+
+const BOOKS: AnnotationHubBookFacet[] = [
+  { bookId: 5, bookTitle: 'Dune', author: 'FH', count: 9 },
+  { bookId: 6, bookTitle: 'Hyperion', author: 'DS', count: 4 },
+]
+
+function mountCombobox(props: Partial<{ modelValue: number | 'all'; selectedLabel: string | null }> = {}, books = BOOKS) {
+  const searchFn = vi.fn<(q: string) => Promise<AnnotationHubBookFacet[]>>().mockResolvedValue(books)
+  const wrapper = mount(AnnotationBookCombobox, {
+    props: { modelValue: 'all', selectedLabel: null, searchFn, ...props },
+  })
+  return { wrapper, searchFn }
+}
+
+describe('AnnotationBookCombobox', () => {
+  it('shows the selected label and a clear control when a book is selected', () => {
+    const { wrapper } = mountCombobox({ modelValue: 5, selectedLabel: 'Dune' })
+
+    expect((wrapper.get('input').element as HTMLInputElement).value).toBe('Dune')
+    expect(wrapper.find('[aria-label="Clear book filter"]').exists()).toBe(true)
+  })
+
+  it('loads the recent list on focus and emits id + label on select', async () => {
+    const { wrapper, searchFn } = mountCombobox()
+
+    await wrapper.get('input').trigger('focus')
+    await flushPromises()
+
+    expect(searchFn).toHaveBeenCalledWith('')
+    const options = wrapper.findAll('[role="option"]')
+    expect(options).toHaveLength(2)
+
+    await options[0]!.trigger('mousedown')
+
+    expect(wrapper.emitted('update:modelValue')?.[0]).toEqual([5])
+    expect(wrapper.emitted('update:selectedLabel')?.[0]).toEqual(['Dune'])
+  })
+
+  it('clears the selection back to all books', async () => {
+    const { wrapper } = mountCombobox({ modelValue: 5, selectedLabel: 'Dune' })
+
+    await wrapper.get('[aria-label="Clear book filter"]').trigger('mousedown')
+
+    expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['all'])
+    expect(wrapper.emitted('update:selectedLabel')?.[0]).toEqual([null])
+  })
+
+  it('shows an empty state when the search returns nothing', async () => {
+    const { wrapper } = mountCombobox({}, [])
+
+    await wrapper.get('input').trigger('focus')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('No books found')
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationBulkBar.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationBulkBar.spec.ts
new file mode 100644
index 000000000..6be164515
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationBulkBar.spec.ts
@@ -0,0 +1,50 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { ANNOTATION_HIGHLIGHT_COLORS } from '@bookorbit/types'
+import AnnotationBulkBar from '../AnnotationBulkBar.vue'
+
+const stubs = {
+  Tooltip: { template: '<div><slot /></div>' },
+  TooltipTrigger: { template: '<div><slot /></div>' },
+  TooltipContent: { template: '<div><slot /></div>' },
+}
+
+function mountBar(props: Record<string, unknown> = {}) {
+  return mount(AnnotationBulkBar, {
+    props: { count: 2, allVisibleSelected: false, ...props },
+    global: { stubs },
+  })
+}
+
+describe('AnnotationBulkBar', () => {
+  it('renders the selected count', () => {
+    expect(mountBar({ count: 5 }).text()).toContain('5 selected')
+  })
+
+  it('labels the select-page toggle by visibility state', () => {
+    expect(mountBar({ allVisibleSelected: false }).text()).toContain('Select page')
+    expect(mountBar({ allVisibleSelected: true }).text()).toContain('Page selected')
+  })
+
+  it('emits selectPage and clear', async () => {
+    const wrapper = mountBar()
+    const buttons = wrapper.findAll('button')
+    await buttons.find((button) => button.text().includes('Select page'))!.trigger('click')
+    await buttons.find((button) => button.text() === 'Clear')!.trigger('click')
+    expect(wrapper.emitted('selectPage')).toBeTruthy()
+    expect(wrapper.emitted('clear')).toBeTruthy()
+  })
+
+  it('hides the restyle controls by default', () => {
+    expect(mountBar().find('[aria-label="Recolor to Yellow"]').exists()).toBe(false)
+  })
+
+  it('emits recolor and restyle when showRestyle is enabled', async () => {
+    const wrapper = mountBar({ showRestyle: true })
+    await wrapper.get('[aria-label="Recolor to Yellow"]').trigger('click')
+    expect(wrapper.emitted('recolor')!.slice(-1)[0]).toEqual([ANNOTATION_HIGHLIGHT_COLORS[0]!.hex])
+
+    await wrapper.get('[aria-label="Restyle to Underline"]').trigger('click')
+    expect(wrapper.emitted('restyle')!.slice(-1)[0]).toEqual(['underline'])
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationFiltersPanel.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationFiltersPanel.spec.ts
new file mode 100644
index 000000000..ad97e4eac
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationFiltersPanel.spec.ts
@@ -0,0 +1,50 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { ANNOTATION_COLOR_FILTER_OPTIONS } from '@bookorbit/types'
+import AnnotationFiltersPanel from '../AnnotationFiltersPanel.vue'
+
+function mountPanel(props: Record<string, unknown> = {}) {
+  return mount(AnnotationFiltersPanel, {
+    props: { colors: [], dateFrom: '', dateTo: '', ...props },
+  })
+}
+
+describe('AnnotationFiltersPanel', () => {
+  it('renders one toggleable swatch per filterable color', () => {
+    const swatches = mountPanel().findAll('button[aria-pressed]')
+    expect(swatches).toHaveLength(ANNOTATION_COLOR_FILTER_OPTIONS.length)
+  })
+
+  it('adds a color to the selection when toggled on', async () => {
+    const wrapper = mountPanel({ colors: [] })
+    await wrapper.get('button[aria-label="Yellow"]').trigger('click')
+    expect(wrapper.emitted('update:colors')!.slice(-1)[0]).toEqual([['#FACC15']])
+  })
+
+  it('removes a color from the selection when toggled off', async () => {
+    const wrapper = mountPanel({ colors: ['#FACC15'] })
+    expect(wrapper.get('button[aria-label="Yellow"]').attributes('aria-pressed')).toBe('true')
+    await wrapper.get('button[aria-label="Yellow"]').trigger('click')
+    expect(wrapper.emitted('update:colors')!.slice(-1)[0]).toEqual([[]])
+  })
+
+  it('updates and clears the date range', async () => {
+    const wrapper = mountPanel({ dateFrom: '2026-01-01', dateTo: '2026-01-31' })
+    const dateInputs = wrapper.findAll('input[type="date"]')
+    await dateInputs[0]!.setValue('2026-02-01')
+    expect(wrapper.emitted('update:dateFrom')!.slice(-1)[0]).toEqual(['2026-02-01'])
+    await dateInputs[1]!.setValue('2026-02-28')
+    expect(wrapper.emitted('update:dateTo')!.slice(-1)[0]).toEqual(['2026-02-28'])
+
+    await wrapper.get('[aria-label="Clear date range"]').trigger('click')
+    expect(wrapper.emitted('update:dateFrom')!.slice(-1)[0]).toEqual([''])
+    expect(wrapper.emitted('update:dateTo')!.slice(-1)[0]).toEqual([''])
+  })
+
+  it('emits clearAll from the footer button', async () => {
+    const wrapper = mountPanel()
+    const clearAll = wrapper.findAll('button').find((button) => button.text() === 'Clear all')
+    await clearAll!.trigger('click')
+    expect(wrapper.emitted('clearAll')).toBeTruthy()
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationListItem.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationListItem.spec.ts
new file mode 100644
index 000000000..c275b9694
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationListItem.spec.ts
@@ -0,0 +1,119 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import type { VueWrapper } from '@vue/test-utils'
+import type { AnnotationItem } from '@bookorbit/types'
+import AnnotationListItem from '../AnnotationListItem.vue'
+
+const stubs = {
+  RouterLink: { template: '<a><slot /></a>' },
+  Tooltip: { template: '<div><slot /></div>' },
+  TooltipTrigger: { template: '<div><slot /></div>' },
+  TooltipContent: { template: '<div><slot /></div>' },
+  AnnotationBookThumb: { template: '<div class="book-thumb" />' },
+  AnnotationSyncDetailPanel: { template: '<div class="sync-detail" />' },
+  HighlightNoteEditor: {
+    template: '<div class="note-editor"><button class="save" type="button" @click="$emit(\'save\', \'edited\')">save</button></div>',
+  },
+}
+
+function makeAnnotation(overrides: Partial<AnnotationItem> = {}): AnnotationItem {
+  return {
+    id: 1,
+    bookId: 5,
+    cfi: 'epubcfi(/6/4!/4/2/1:0)',
+    jumpFileId: 9,
+    pageno: 3,
+    text: 'a short highlight',
+    color: '#FACC15',
+    style: 'highlight',
+    note: 'my note',
+    chapterTitle: 'Chapter 1',
+    origin: 'web',
+    positionStatus: 'exact',
+    chapterIndex: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+function mountItem(props: Record<string, unknown> = {}) {
+  return mount(AnnotationListItem, { props: { annotation: makeAnnotation(), ...props }, global: { stubs } })
+}
+
+function iconButton(wrapper: VueWrapper, iconClass: string) {
+  return wrapper.findAll('button').find((button) => button.find(`.${iconClass}`).exists())
+}
+
+describe('AnnotationListItem', () => {
+  it('renders the quote and the note', () => {
+    const wrapper = mountItem()
+    expect(wrapper.text()).toContain('a short highlight')
+    expect(wrapper.text()).toContain('my note')
+  })
+
+  it('emits toggleSelect when the checkbox changes', async () => {
+    const wrapper = mountItem()
+    await wrapper.get('input[type="checkbox"]').setValue(true)
+    expect(wrapper.emitted('toggleSelect')!.slice(-1)[0]).toEqual([1])
+  })
+
+  it('requires a confirm step before trashing in book mode', async () => {
+    const wrapper = mountItem({ mode: 'book' })
+    await iconButton(wrapper, 'lucide-trash-2')!.trigger('click')
+    expect(wrapper.emitted('trash')).toBeFalsy()
+
+    const confirm = wrapper.findAll('button').find((button) => button.text() === 'Trash')
+    await confirm!.trigger('click')
+    expect(wrapper.emitted('trash')!.slice(-1)[0]).toEqual([1])
+  })
+
+  it('trashes immediately in hub mode', async () => {
+    const wrapper = mountItem({ mode: 'hub' })
+    await iconButton(wrapper, 'lucide-trash-2')!.trigger('click')
+    expect(wrapper.emitted('trash')!.slice(-1)[0]).toEqual([1])
+  })
+
+  it('exposes restore and purge actions when trashed', async () => {
+    const wrapper = mountItem({ trashed: true })
+    await iconButton(wrapper, 'lucide-archive-restore')!.trigger('click')
+    expect(wrapper.emitted('restore')!.slice(-1)[0]).toEqual([1])
+    await iconButton(wrapper, 'lucide-trash-2')!.trigger('click')
+    expect(wrapper.emitted('purge')!.slice(-1)[0]).toEqual([1])
+  })
+
+  it('emits jump when a reader location is available', async () => {
+    const wrapper = mountItem({ mode: 'hub' })
+    await iconButton(wrapper, 'lucide-book-open')!.trigger('click')
+    expect(wrapper.emitted('jump')).toBeTruthy()
+  })
+
+  it('emits updateColor from the style panel only when the color differs', async () => {
+    const wrapper = mountItem()
+    await iconButton(wrapper, 'lucide-palette')!.trigger('click')
+    await wrapper.get('button[title="Green"]').trigger('click')
+    expect(wrapper.emitted('updateColor')!.slice(-1)[0]).toEqual([1, '#4ADE80'])
+  })
+
+  it('emits updateNote when the note editor saves', async () => {
+    const wrapper = mountItem()
+    await iconButton(wrapper, 'lucide-file-pen')!.trigger('click')
+    await wrapper.get('.note-editor .save').trigger('click')
+    expect(wrapper.emitted('updateNote')!.slice(-1)[0]).toEqual([1, 'edited'])
+  })
+
+  it('copies the quote text to the clipboard', async () => {
+    const writeText = vi.fn<(text: string) => Promise<void>>().mockResolvedValue(undefined)
+    Object.assign(navigator, { clipboard: { writeText } })
+    const wrapper = mountItem()
+    await iconButton(wrapper, 'lucide-copy')!.trigger('click')
+    expect(writeText).toHaveBeenCalledWith('a short highlight')
+  })
+
+  it('toggles expansion for long quotes', async () => {
+    const wrapper = mountItem({ annotation: makeAnnotation({ text: 'x'.repeat(300) }) })
+    const expand = wrapper.findAll('button').find((button) => button.text().includes('Expand'))
+    expect(expand).toBeTruthy()
+    await expand!.trigger('click')
+    expect(wrapper.findAll('button').some((button) => button.text().includes('Collapse'))).toBe(true)
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationPagination.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationPagination.spec.ts
new file mode 100644
index 000000000..877cafb42
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationPagination.spec.ts
@@ -0,0 +1,50 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import AnnotationPagination from '../AnnotationPagination.vue'
+
+const stubs = { Button: { template: '<button><slot /></button>' } }
+
+function mountPagination(props: Record<string, unknown> = {}) {
+  return mount(AnnotationPagination, {
+    props: { page: 2, totalPages: 5, rangeStart: 26, rangeEnd: 50, total: 120, ...props },
+    global: { stubs },
+  })
+}
+
+describe('AnnotationPagination', () => {
+  it('renders the range summary with an optional unit', () => {
+    expect(mountPagination().text()).toContain('Showing 26-50 of 120')
+    expect(mountPagination({ unit: 'highlights' }).text()).toContain('of 120 highlights')
+  })
+
+  it('hides the navigation when there is a single page', () => {
+    const wrapper = mountPagination({ totalPages: 1, page: 1 })
+    expect(wrapper.find('[aria-label="Next page"]').exists()).toBe(false)
+  })
+
+  it('emits the next and previous pages', async () => {
+    const wrapper = mountPagination({ page: 2, totalPages: 5 })
+    await wrapper.get('[aria-label="Next page"]').trigger('click')
+    await wrapper.get('[aria-label="Previous page"]').trigger('click')
+    expect(wrapper.emitted('update:page')).toEqual([[3], [1]])
+  })
+
+  it('jumps to the first and last pages', async () => {
+    const wrapper = mountPagination({ page: 3, totalPages: 5 })
+    await wrapper.get('[aria-label="First page"]').trigger('click')
+    await wrapper.get('[aria-label="Last page"]').trigger('click')
+    expect(wrapper.emitted('update:page')).toEqual([[1], [5]])
+  })
+
+  it('disables the edges and never emits past the bounds', async () => {
+    const first = mountPagination({ page: 1, totalPages: 3 })
+    expect(first.get('[aria-label="Previous page"]').attributes('disabled')).toBeDefined()
+    await first.get('[aria-label="Previous page"]').trigger('click')
+    expect(first.emitted('update:page')).toBeUndefined()
+
+    const last = mountPagination({ page: 3, totalPages: 3 })
+    expect(last.get('[aria-label="Next page"]').attributes('disabled')).toBeDefined()
+    await last.get('[aria-label="Next page"]').trigger('click')
+    expect(last.emitted('update:page')).toBeUndefined()
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationSummaryBar.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationSummaryBar.spec.ts
new file mode 100644
index 000000000..b976c0c18
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationSummaryBar.spec.ts
@@ -0,0 +1,40 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import AnnotationSummaryBar from '../AnnotationSummaryBar.vue'
+
+const origins = [
+  { origin: 'web', label: 'Web', class: 'web-class', count: 3 },
+  { origin: 'koreader', label: 'KOReader', class: 'ko-class', count: 5 },
+]
+
+describe('AnnotationSummaryBar', () => {
+  it('renders text summaries and origin counts', () => {
+    const wrapper = mount(AnnotationSummaryBar, { props: { texts: ['12 highlights', '4 notes'], origins } })
+    expect(wrapper.text()).toContain('12 highlights')
+    expect(wrapper.text()).toContain('Web 3')
+    expect(wrapper.text()).toContain('KOReader 5')
+  })
+
+  it('is non-interactive when no activeOrigin is provided', () => {
+    const wrapper = mount(AnnotationSummaryBar, { props: { texts: [], origins } })
+    expect(wrapper.findAll('button')).toHaveLength(0)
+  })
+
+  it('emits originClick and marks the active origin when interactive', async () => {
+    const wrapper = mount(AnnotationSummaryBar, { props: { texts: [], origins, activeOrigin: 'web' } })
+    const buttons = wrapper.findAll('button')
+    expect(buttons).toHaveLength(2)
+    expect(buttons[0]!.attributes('aria-pressed')).toBe('true')
+    expect(buttons[1]!.attributes('aria-pressed')).toBe('false')
+
+    await buttons[1]!.trigger('click')
+    expect(wrapper.emitted('originClick')!.slice(-1)[0]).toEqual(['koreader'])
+  })
+
+  it('treats a null activeOrigin as interactive with none pressed', () => {
+    const wrapper = mount(AnnotationSummaryBar, { props: { texts: [], origins, activeOrigin: null } })
+    const buttons = wrapper.findAll('button')
+    expect(buttons).toHaveLength(2)
+    expect(buttons.every((button) => button.attributes('aria-pressed') === 'false')).toBe(true)
+  })
+})
diff --git a/client/src/features/annotations/components/__tests__/AnnotationToolbar.spec.ts b/client/src/features/annotations/components/__tests__/AnnotationToolbar.spec.ts
new file mode 100644
index 000000000..0a90bacec
--- /dev/null
+++ b/client/src/features/annotations/components/__tests__/AnnotationToolbar.spec.ts
@@ -0,0 +1,68 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import AnnotationToolbar from '../AnnotationToolbar.vue'
+
+const stubs = {
+  Popover: { template: '<div><slot /></div>' },
+  PopoverTrigger: { template: '<div><slot /></div>' },
+  PopoverContent: { template: '<div><slot /></div>' },
+  Sheet: { template: '<div><slot /></div>' },
+  SheetTrigger: { template: '<div><slot /></div>' },
+  SheetContent: { template: '<div><slot /></div>' },
+  SheetHeader: { template: '<div><slot /></div>' },
+  SheetTitle: { template: '<div><slot /></div>' },
+  Badge: { template: '<span><slot /></span>' },
+  Button: { template: '<button><slot /></button>' },
+}
+
+function mountToolbar(props: Record<string, unknown> = {}) {
+  return mount(AnnotationToolbar, {
+    props: {
+      sortOptions: [
+        { value: 'newest', label: 'Newest first' },
+        { value: 'oldest', label: 'Oldest first' },
+      ],
+      filterCount: 0,
+      chips: [],
+      search: '',
+      sortKey: 'newest',
+      density: 'comfortable',
+      ...props,
+    },
+    global: { stubs },
+  })
+}
+
+describe('AnnotationToolbar', () => {
+  it('emits search updates', async () => {
+    const wrapper = mountToolbar()
+    await wrapper.get('input[type="search"]').setValue('dune')
+    expect(wrapper.emitted('update:search')!.slice(-1)[0]).toEqual(['dune'])
+  })
+
+  it('emits sort-key updates', async () => {
+    const wrapper = mountToolbar()
+    await wrapper.get('select').setValue('oldest')
+    expect(wrapper.emitted('update:sortKey')!.slice(-1)[0]).toEqual(['oldest'])
+  })
+
+  it('toggles density from comfortable to compact', async () => {
+    const wrapper = mountToolbar({ density: 'comfortable' })
+    await wrapper.get('button[aria-label="Switch to compact view"]').trigger('click')
+    expect(wrapper.emitted('update:density')!.slice(-1)[0]).toEqual(['compact'])
+  })
+
+  it('shows the active filter count', () => {
+    expect(mountToolbar({ filterCount: 3 }).text()).toContain('3')
+  })
+
+  it('re-emits chip removal and clear-all from the chip row', async () => {
+    const wrapper = mountToolbar({ chips: [{ id: 'style', label: 'Style: Underline' }] })
+    await wrapper.get('[aria-label="Remove filter Style: Underline"]').trigger('click')
+    expect(wrapper.emitted('removeChip')!.slice(-1)[0]).toEqual(['style'])
+
+    const clearAll = wrapper.findAll('button').find((button) => button.text() === 'Clear all')
+    await clearAll!.trigger('click')
+    expect(wrapper.emitted('clearFilters')).toBeTruthy()
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useAnnotationMutations.spec.ts b/client/src/features/annotations/composables/__tests__/useAnnotationMutations.spec.ts
new file mode 100644
index 000000000..065a01efc
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useAnnotationMutations.spec.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { nextTick, ref } from 'vue'
+
+const apiMock = vi.hoisted(() => vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>())
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}))
+
+import { useAnnotationMutations } from '../useAnnotationMutations'
+
+function makeResponse(ok = true): Response {
+  return { ok, status: ok ? 200 : 500, json: async () => ({}) } as Response
+}
+
+describe('useAnnotationMutations', () => {
+  beforeEach(() => {
+    apiMock.mockReset()
+  })
+
+  it('optimistically patches the item and PATCHes the resolved book endpoint', async () => {
+    apiMock.mockResolvedValue(makeResponse())
+    const items = ref([{ id: 1, bookId: 7, note: 'old' }])
+    const mutations = useAnnotationMutations(items, () => 7)
+
+    await mutations.updateNote(1, 'new')
+
+    expect(items.value[0]!.note).toBe('new')
+    const [url, req] = apiMock.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('/api/v1/books/7/annotations/1')
+    expect(req.method).toBe('PATCH')
+    expect(JSON.parse(String(req.body))).toEqual({ note: 'new' })
+    expect(mutations.savingIds.value.has(1)).toBe(false)
+  })
+
+  it('reverts the optimistic change on failure', async () => {
+    apiMock.mockResolvedValue(makeResponse(false))
+    const items = ref([{ id: 1, bookId: 7, color: '#000000' }])
+    const mutations = useAnnotationMutations(items, () => 7)
+
+    await mutations.updateColor(1, '#ffffff')
+
+    expect(items.value[0]!.color).toBe('#000000')
+  })
+
+  it('does nothing when the book id cannot be resolved', async () => {
+    const items = ref([{ id: 1, bookId: 7, style: 'highlight' }])
+    const mutations = useAnnotationMutations(items, () => null)
+
+    await mutations.updateStyle(1, 'underline')
+
+    expect(apiMock).not.toHaveBeenCalled()
+    expect(items.value[0]!.style).toBe('highlight')
+  })
+
+  it('prunes saving ids whose item leaves the list', async () => {
+    const items = ref([
+      { id: 1, bookId: 7 },
+      { id: 2, bookId: 7 },
+    ])
+    const mutations = useAnnotationMutations(items, () => 7)
+
+    mutations.setSaving(1, true)
+    mutations.setSaving(2, true)
+    expect(mutations.savingIds.value.size).toBe(2)
+
+    items.value = [{ id: 2, bookId: 7 }]
+    await nextTick()
+
+    expect(mutations.savingIds.value.has(1)).toBe(false)
+    expect(mutations.savingIds.value.size).toBe(1)
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useAnnotationSelection.spec.ts b/client/src/features/annotations/composables/__tests__/useAnnotationSelection.spec.ts
new file mode 100644
index 000000000..8f5f35804
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useAnnotationSelection.spec.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { nextTick, ref } from 'vue'
+import { useAnnotationSelection } from '../useAnnotationSelection'
+
+describe('useAnnotationSelection', () => {
+  it('toggles, selects the page, clears, and reports state', () => {
+    const items = ref([{ id: 1 }, { id: 2 }, { id: 3 }])
+    const selection = useAnnotationSelection(items)
+
+    expect(selection.hasSelection.value).toBe(false)
+
+    selection.toggleSelected(1)
+    expect(selection.selectedIds.value.has(1)).toBe(true)
+    expect(selection.hasSelection.value).toBe(true)
+
+    selection.toggleSelected(1)
+    expect(selection.selectedIds.value.has(1)).toBe(false)
+
+    selection.selectAllOnPage()
+    expect(selection.allVisibleSelected.value).toBe(true)
+    expect(selection.selectedItems.value).toHaveLength(3)
+
+    selection.clearSelection()
+    expect(selection.hasSelection.value).toBe(false)
+  })
+
+  it('prunes selected ids that leave the list', async () => {
+    const items = ref([{ id: 1 }, { id: 2 }])
+    const selection = useAnnotationSelection(items)
+
+    selection.selectAllOnPage()
+    expect(selection.selectedIds.value.size).toBe(2)
+
+    items.value = [{ id: 1 }]
+    await nextTick()
+
+    expect(selection.selectedIds.value.has(2)).toBe(false)
+    expect(selection.selectedIds.value.size).toBe(1)
+  })
+
+  it('reports allVisibleSelected as false for an empty list', () => {
+    const items = ref<{ id: number }[]>([])
+    const selection = useAnnotationSelection(items)
+
+    expect(selection.allVisibleSelected.value).toBe(false)
+    selection.selectAllOnPage()
+    expect(selection.hasSelection.value).toBe(false)
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useAnnotationsHub.spec.ts b/client/src/features/annotations/composables/__tests__/useAnnotationsHub.spec.ts
new file mode 100644
index 000000000..a8968cfdb
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useAnnotationsHub.spec.ts
@@ -0,0 +1,516 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+const apiMock = vi.hoisted(() => vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>())
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}))
+
+function makeResponse(data: unknown, options: { ok?: boolean; status?: number } = {}): Response {
+  const { ok = true, status = ok ? 200 : 500 } = options
+  return {
+    ok,
+    status,
+    json: async () => data,
+  } as Response
+}
+
+const emptyHub = { items: [], total: 0, page: 1, pageSize: 25, stats: { books: 0, withNotes: 0, originBreakdown: [] } }
+
+function paramsFromUrl(url: string): URLSearchParams {
+  return new URLSearchParams(url.split('?')[1] ?? '')
+}
+
+describe('useAnnotationsHub', () => {
+  beforeEach(() => {
+    // Fake only the timer functions so the search-debounce setTimeout can never
+    // leak a real timer into a later test (which would call the mock mid-reset).
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval'] })
+    vi.resetModules()
+    apiMock.mockReset()
+    // Safe default so any watcher-triggered reload resolves cleanly.
+    apiMock.mockResolvedValue(makeResponse(emptyHub))
+  })
+
+  afterEach(() => {
+    if (vi.isFakeTimers()) {
+      vi.clearAllTimers()
+      vi.useRealTimers()
+    }
+  })
+
+  describe('query building', () => {
+    it('builds the query with the date range as local-day-boundary ISO and the notes-only flag', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.dateFrom.value = '2026-01-10'
+      hub.dateTo.value = '2026-01-12'
+      hub.notesOnly.value = true
+
+      const params = paramsFromUrl(hub.exportUrl('json'))
+      expect(params.get('dateFrom')).toBe(new Date('2026-01-10T00:00:00.000').toISOString())
+      expect(params.get('dateTo')).toBe(new Date('2026-01-12T23:59:59.999').toISOString())
+      expect(params.get('hasNote')).toBe('true')
+      expect(params.get('format')).toBe('json')
+    })
+
+    it('omits the date range and notes-only params when they are unset', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const params = paramsFromUrl(hub.exportUrl('md'))
+      expect(params.has('dateFrom')).toBe(false)
+      expect(params.has('dateTo')).toBe(false)
+      expect(params.has('hasNote')).toBe(false)
+      expect(params.get('status')).toBe('active')
+    })
+
+    it('includes the search, book, color, style and origin filters when set', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.search.value = '  needle  '
+      hub.bookFilter.value = 5
+      hub.colors.value = ['#FACC15', '#4ADE80']
+      hub.styleFilter.value = 'underline'
+      hub.originFilter.value = 'koreader'
+
+      const params = paramsFromUrl(hub.exportUrl('csv'))
+      expect(params.get('search')).toBe('needle')
+      expect(params.get('bookId')).toBe('5')
+      expect(params.get('colors')).toBe('#FACC15,#4ADE80')
+      expect(params.get('styles')).toBe('underline')
+      expect(params.get('origins')).toBe('koreader')
+    })
+
+    it('ignores an unparseable date value instead of sending an empty param', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.dateFrom.value = 'not-a-date'
+
+      const params = paramsFromUrl(hub.exportUrl('csv'))
+      expect(params.has('dateFrom')).toBe(false)
+    })
+  })
+
+  describe('toggles', () => {
+    it('toggleNotesOnly flips the flag and clearDates resets both dates', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      expect(hub.notesOnly.value).toBe(false)
+      hub.toggleNotesOnly()
+      expect(hub.notesOnly.value).toBe(true)
+
+      hub.dateFrom.value = '2026-01-01'
+      hub.dateTo.value = '2026-01-02'
+      hub.clearDates()
+      expect(hub.dateFrom.value).toBe('')
+      expect(hub.dateTo.value).toBe('')
+    })
+
+    it('manages selection state', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+      hub.items.value = [{ id: 1 }, { id: 2 }, { id: 3 }] as never
+
+      hub.toggleSelected(1)
+      hub.toggleSelected(2)
+      expect(hub.hasSelection.value).toBe(true)
+      expect(hub.selectedIds.value.has(1)).toBe(true)
+
+      hub.toggleSelected(1)
+      expect(hub.selectedIds.value.has(1)).toBe(false)
+
+      hub.selectAllOnPage()
+      expect(hub.selectedIds.value.size).toBe(3)
+
+      hub.clearSelection()
+      expect(hub.selectedIds.value.size).toBe(0)
+    })
+
+    it('computes pagination ranges', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.total.value = 0
+      expect(hub.rangeStart.value).toBe(0)
+
+      hub.total.value = 60
+      hub.pageSize.value = 25
+      hub.page.value = 2
+      expect(hub.totalPages.value).toBe(3)
+      expect(hub.rangeStart.value).toBe(26)
+      expect(hub.rangeEnd.value).toBe(50)
+    })
+  })
+
+  describe('requests', () => {
+    it('load fetches the hub list and populates items, total and stats', async () => {
+      const body = {
+        items: [{ id: 1, bookId: 5, note: 'n' }],
+        total: 1,
+        page: 1,
+        pageSize: 25,
+        stats: { books: 1, withNotes: 1, originBreakdown: [{ origin: 'web', count: 1 }] },
+      }
+      apiMock.mockResolvedValueOnce(makeResponse(body))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      await hub.load()
+
+      const url = String(apiMock.mock.calls[0][0])
+      expect(url.startsWith('/api/v1/annotations?')).toBe(true)
+      expect(hub.items.value).toEqual(body.items)
+      expect(hub.total.value).toBe(1)
+      expect(hub.stats.value).toEqual(body.stats)
+    })
+
+    it('load surfaces an error message when the request fails', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}, { ok: false, status: 500 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      await hub.load()
+
+      expect(hub.error.value).toBe('Failed to load annotations')
+    })
+
+    it('searchBooks queries the books facet endpoint with the trimmed term', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse([{ bookId: 5, bookTitle: 'B', author: 'A', count: 3 }]))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const facets = await hub.searchBooks('  dune  ')
+
+      const url = String(apiMock.mock.calls[0][0])
+      expect(url).toContain('/api/v1/annotations/books?')
+      expect(url).toContain('status=active')
+      expect(url).toContain('q=dune')
+      expect(facets).toEqual([{ bookId: 5, bookTitle: 'B', author: 'A', count: 3 }])
+    })
+
+    it('resolveSelectedBook fills the label for the selected book id', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse([{ bookId: 7, bookTitle: 'Dune', author: 'FH', count: 9 }]))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+      hub.hydrate({ bookFilter: 7 })
+
+      await hub.resolveSelectedBook()
+
+      const url = String(apiMock.mock.calls[0][0])
+      expect(url).toContain('selectedId=7')
+      expect(hub.selectedBookLabel.value).toBe('Dune')
+    })
+
+    it('resolveSelectedBook clears the label when no book is selected', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      await hub.resolveSelectedBook()
+
+      expect(apiMock).not.toHaveBeenCalled()
+      expect(hub.selectedBookLabel.value).toBeNull()
+    })
+
+    it('bulk returns 0 and skips the request when nothing is selected', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      expect(await hub.bulk('trash')).toBe(0)
+      expect(apiMock).not.toHaveBeenCalled()
+    })
+
+    it('bulk posts the action and returns the affected count', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({ affected: 2 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+      hub.selectedIds.value = new Set([1, 2])
+
+      const affected = await hub.bulk('restyle', { color: '#FACC15' })
+
+      expect(affected).toBe(2)
+      const [url, req] = apiMock.mock.calls[0] as [string, RequestInit]
+      expect(url).toBe('/api/v1/annotations/bulk')
+      expect(req.method).toBe('POST')
+      expect(JSON.parse(String(req.body))).toEqual({ ids: [1, 2], action: 'restyle', color: '#FACC15' })
+      expect(hub.selectedIds.value.size).toBe(0)
+    })
+
+    it('restore posts and resolves true on success', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const ok = await hub.restore(7)
+
+      expect(ok).toBe(true)
+      expect(apiMock).toHaveBeenCalledWith('/api/v1/annotations/7/restore', { method: 'POST' })
+    })
+
+    it('purge deletes and resolves ok on success', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}, { ok: true, status: 204 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const result = await hub.purge(7)
+
+      expect(result.ok).toBe(true)
+      expect(apiMock).toHaveBeenCalledWith('/api/v1/annotations/7', { method: 'DELETE' })
+    })
+
+    it('purge surfaces the conflict message on 409', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({ message: 'Still queued' }, { ok: false, status: 409 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const result = await hub.purge(7)
+
+      expect(result).toEqual({ ok: false, message: 'Still queued' })
+    })
+
+    it('purge returns a generic failure on other errors', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}, { ok: false, status: 500 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const result = await hub.purge(7)
+
+      expect(result).toEqual({ ok: false, message: 'Failed to delete' })
+    })
+  })
+
+  describe('reactivity', () => {
+    it('reloads on filter changes and resets the book filter when the tab changes', async () => {
+      const { nextTick } = await import('vue')
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.bookFilter.value = 5
+      hub.status.value = 'trashed'
+      await nextTick()
+      expect(hub.bookFilter.value).toBe('all')
+
+      apiMock.mockClear()
+      hub.page.value = 2
+      await nextTick()
+      expect(apiMock).toHaveBeenCalled()
+    })
+  })
+
+  describe('sort key', () => {
+    it('maps the merged sort key to sortBy/sortDir and back', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      expect(hub.sortKey.value).toBe('newest')
+
+      hub.sortKey.value = 'oldest'
+      expect(hub.sortBy.value).toBe('createdAt')
+      expect(hub.sortDir.value).toBe('asc')
+
+      hub.sortKey.value = 'book-asc'
+      expect(hub.sortBy.value).toBe('book')
+      expect(hub.sortDir.value).toBe('asc')
+
+      hub.sortBy.value = 'book'
+      hub.sortDir.value = 'desc'
+      expect(hub.sortKey.value).toBe('book-desc')
+    })
+  })
+
+  describe('popover filters', () => {
+    it('builds chips, counts them, and clears individually or all at once', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      expect(hub.popoverFilterCount.value).toBe(0)
+      expect(hub.activeFilterChips.value).toEqual([])
+
+      hub.colors.value = ['#FACC15']
+      hub.styleFilter.value = 'underline'
+      hub.originFilter.value = 'koreader'
+      hub.dateFrom.value = '2026-01-10'
+
+      expect(hub.popoverFilterCount.value).toBe(4)
+      expect(hub.activeFilterChips.value.map((chip) => chip.id)).toEqual(['color:#FACC15', 'style', 'origin', 'date'])
+      expect(hub.activeFilterChips.value[0].label).toBe('Color: Yellow')
+      expect(hub.activeFilterChips.value[3].label).toBe('Date: From 2026-01-10')
+
+      hub.removeFilterChip('color:#FACC15')
+      expect(hub.colors.value).toEqual([])
+      expect(hub.popoverFilterCount.value).toBe(3)
+
+      hub.clearPopoverFilters()
+      expect(hub.popoverFilterCount.value).toBe(0)
+      expect(hub.styleFilter.value).toBe('all')
+      expect(hub.originFilter.value).toBe('all')
+      expect(hub.dateFrom.value).toBe('')
+    })
+
+    it('does not chip the book or notes-only filters', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.bookFilter.value = 5
+      hub.notesOnly.value = true
+
+      expect(hub.activeFilterChips.value).toEqual([])
+      expect(hub.popoverFilterCount.value).toBe(0)
+    })
+  })
+
+  describe('hydrate', () => {
+    it('restores state and keeps the hydrated page despite the filter watcher', async () => {
+      const { nextTick } = await import('vue')
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.hydrate({ colors: ['#FACC15'], notesOnly: true, sortKey: 'oldest', page: 3 })
+
+      expect(hub.colors.value).toEqual(['#FACC15'])
+      expect(hub.notesOnly.value).toBe(true)
+      expect(hub.sortBy.value).toBe('createdAt')
+      expect(hub.sortDir.value).toBe('asc')
+      expect(hub.page.value).toBe(3)
+
+      await nextTick()
+      expect(hub.page.value).toBe(3)
+      expect(hub.hydrating.value).toBe(false)
+    })
+  })
+
+  describe('search debounce', () => {
+    it('defers the search-triggered reload until the debounce elapses', async () => {
+      vi.useFakeTimers()
+      try {
+        const { nextTick } = await import('vue')
+        const { useAnnotationsHub } = await import('../useAnnotationsHub')
+        const hub = useAnnotationsHub()
+        apiMock.mockClear()
+
+        hub.search.value = 'dune'
+        await nextTick()
+        expect(apiMock).not.toHaveBeenCalled()
+
+        vi.advanceTimersByTime(300)
+        expect(apiMock).toHaveBeenCalledTimes(1)
+        expect(String(apiMock.mock.calls[0][0])).toContain('search=dune')
+      } finally {
+        vi.useRealTimers()
+      }
+    })
+  })
+
+  describe('filter reset', () => {
+    it('hasActiveFilters reflects active filters and resetAllFilters clears them', async () => {
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      expect(hub.hasActiveFilters.value).toBe(false)
+
+      hub.colors.value = ['#FACC15']
+      hub.bookFilter.value = 5
+      hub.selectedBookLabel.value = 'Dune'
+      hub.notesOnly.value = true
+      hub.dateFrom.value = '2026-01-01'
+      expect(hub.hasActiveFilters.value).toBe(true)
+
+      hub.resetAllFilters()
+      expect(hub.hasActiveFilters.value).toBe(false)
+      expect(hub.bookFilter.value).toBe('all')
+      expect(hub.selectedBookLabel.value).toBeNull()
+      expect(hub.notesOnly.value).toBe(false)
+      expect(hub.colors.value).toEqual([])
+      expect(hub.dateFrom.value).toBe('')
+    })
+  })
+
+  describe('updateAnnotation', () => {
+    it('optimistically patches the item and PATCHes the book-scoped endpoint', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+      hub.items.value = [{ id: 1, bookId: 5, note: 'old', color: '#FACC15' }] as never
+
+      await hub.updateNote(1, 'new')
+
+      const [url, req] = apiMock.mock.calls[0] as [string, RequestInit]
+      expect(url).toBe('/api/v1/books/5/annotations/1')
+      expect(req.method).toBe('PATCH')
+      expect(JSON.parse(String(req.body))).toEqual({ note: 'new' })
+      expect(hub.items.value[0]!.note).toBe('new')
+      expect(hub.savingIds.value.has(1)).toBe(false)
+    })
+
+    it('reverts the optimistic change when the request fails', async () => {
+      apiMock.mockResolvedValueOnce(makeResponse({}, { ok: false, status: 500 }))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+      hub.items.value = [{ id: 1, bookId: 5, note: 'old' }] as never
+
+      await hub.updateNote(1, 'new')
+
+      expect(hub.items.value[0]!.note).toBe('old')
+      expect(hub.savingIds.value.has(1)).toBe(false)
+    })
+  })
+
+  describe('load sequencing', () => {
+    it('reloads exactly once when a filter changes while on a later page', async () => {
+      const { nextTick } = await import('vue')
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      hub.page.value = 3
+      await nextTick()
+      apiMock.mockClear()
+
+      hub.colors.value = ['#FACC15']
+      await nextTick()
+
+      expect(hub.page.value).toBe(1)
+      expect(apiMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('discards a stale load when a newer load has superseded it', async () => {
+      apiMock.mockReset()
+      let resolveStale!: (res: Response) => void
+      const stalePending = new Promise<Response>((resolve) => {
+        resolveStale = resolve
+      })
+      const freshBody = { items: [{ id: 2 }], total: 2, page: 1, pageSize: 25, stats: emptyHub.stats }
+      apiMock.mockReturnValueOnce(stalePending).mockResolvedValueOnce(makeResponse(freshBody))
+
+      const { useAnnotationsHub } = await import('../useAnnotationsHub')
+      const hub = useAnnotationsHub()
+
+      const stale = hub.load()
+      const fresh = hub.load()
+      await fresh
+
+      expect(hub.total.value).toBe(2)
+      expect(hub.loading.value).toBe(false)
+
+      resolveStale(makeResponse({ items: [{ id: 1 }], total: 1, page: 1, pageSize: 25, stats: emptyHub.stats }))
+      await stale
+
+      expect(hub.total.value).toBe(2)
+      expect(hub.loading.value).toBe(false)
+    })
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.spec.ts b/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.spec.ts
new file mode 100644
index 000000000..11315d393
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.spec.ts
@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest'
+import type { LocationQuery } from 'vue-router'
+import { annotationsQueryFromState, annotationsStateFromQuery } from '../useAnnotationsUrlSync'
+import type { AnnotationsHubState } from '../useAnnotationsHub'
+
+const DEFAULT_STATE: AnnotationsHubState = {
+  status: 'active',
+  search: '',
+  bookFilter: 'all',
+  colors: [],
+  styleFilter: 'all',
+  originFilter: 'all',
+  notesOnly: false,
+  dateFrom: '',
+  dateTo: '',
+  sortKey: 'newest',
+  page: 1,
+}
+
+describe('annotationsStateFromQuery', () => {
+  it('parses a full query into hub state', () => {
+    const state = annotationsStateFromQuery({
+      status: 'trashed',
+      search: 'dune',
+      bookId: '42',
+      colors: '#FACC15,#4ADE80',
+      style: 'underline',
+      origin: 'koreader',
+      notes: '1',
+      from: '2026-01-10',
+      to: '2026-01-12',
+      sort: 'oldest',
+      page: '3',
+    })
+
+    expect(state).toEqual({
+      status: 'trashed',
+      search: 'dune',
+      bookFilter: 42,
+      colors: ['#FACC15', '#4ADE80'],
+      styleFilter: 'underline',
+      originFilter: 'koreader',
+      notesOnly: true,
+      dateFrom: '2026-01-10',
+      dateTo: '2026-01-12',
+      sortKey: 'oldest',
+      page: 3,
+    })
+  })
+
+  it('drops defaults, malformed numbers, and unknown sort keys', () => {
+    expect(annotationsStateFromQuery({ status: 'active', bookId: 'abc', sort: 'bogus', page: '1', notes: '0' })).toEqual({})
+    expect(annotationsStateFromQuery({ page: '0', bookId: '-2' })).toEqual({})
+    expect(annotationsStateFromQuery({})).toEqual({})
+  })
+
+  it('takes the first value when a param repeats', () => {
+    expect(annotationsStateFromQuery({ search: ['needle', 'other'] }).search).toBe('needle')
+  })
+})
+
+describe('annotationsQueryFromState', () => {
+  it('omits every default value', () => {
+    expect(annotationsQueryFromState(DEFAULT_STATE)).toEqual({})
+  })
+
+  it('serializes only non-default fields and trims search', () => {
+    expect(
+      annotationsQueryFromState({
+        ...DEFAULT_STATE,
+        status: 'trashed',
+        search: '  dune  ',
+        bookFilter: 42,
+        colors: ['#FACC15'],
+        notesOnly: true,
+        sortKey: 'book-asc',
+        page: 2,
+      }),
+    ).toEqual({
+      status: 'trashed',
+      search: 'dune',
+      bookId: '42',
+      colors: '#FACC15',
+      notes: '1',
+      sort: 'book-asc',
+      page: '2',
+    })
+  })
+
+  it('round-trips through the query string', () => {
+    const state: AnnotationsHubState = {
+      ...DEFAULT_STATE,
+      originFilter: 'web',
+      styleFilter: 'invert',
+      dateFrom: '2026-01-01',
+      dateTo: '2026-02-01',
+      sortKey: 'book-desc',
+      page: 5,
+    }
+    expect(annotationsStateFromQuery(annotationsQueryFromState(state) as LocationQuery)).toEqual({
+      originFilter: 'web',
+      styleFilter: 'invert',
+      dateFrom: '2026-01-01',
+      dateTo: '2026-02-01',
+      sortKey: 'book-desc',
+      page: 5,
+    })
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.wiring.spec.ts b/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.wiring.spec.ts
new file mode 100644
index 000000000..d762151da
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useAnnotationsUrlSync.wiring.spec.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { nextTick } from 'vue'
+
+const replaceMock = vi.hoisted(() => vi.fn<(to: unknown) => void>())
+const routeStub = vi.hoisted(() => ({ query: {} as Record<string, unknown> }))
+const apiMock = vi.hoisted(() => vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>())
+
+vi.mock('vue-router', () => ({
+  useRoute: () => routeStub,
+  useRouter: () => ({ replace: replaceMock }),
+}))
+vi.mock('@/lib/api', () => ({ api: apiMock }))
+
+import { useAnnotationsUrlSync } from '../useAnnotationsUrlSync'
+import { useAnnotationsHub } from '../useAnnotationsHub'
+
+function hubResponse(): Response {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({ items: [], total: 0, page: 1, pageSize: 25, stats: { books: 0, withNotes: 0, originBreakdown: [] } }),
+  } as Response
+}
+
+describe('useAnnotationsUrlSync wiring', () => {
+  beforeEach(() => {
+    replaceMock.mockReset()
+    routeStub.query = {}
+    apiMock.mockReset()
+    apiMock.mockResolvedValue(hubResponse())
+  })
+
+  it('hydrates the hub from the query and does not write while hydrating', async () => {
+    routeStub.query = { status: 'trashed', page: '2' }
+    const hub = useAnnotationsHub()
+    useAnnotationsUrlSync(hub)
+
+    expect(replaceMock).not.toHaveBeenCalled()
+    await nextTick()
+    expect(hub.status.value).toBe('trashed')
+    expect(hub.page.value).toBe(2)
+  })
+
+  it('mirrors a later filter change into the URL via router.replace', async () => {
+    const hub = useAnnotationsHub()
+    useAnnotationsUrlSync(hub)
+    await nextTick()
+
+    hub.status.value = 'trashed'
+    await nextTick()
+
+    expect(replaceMock.mock.calls.slice(-1)[0]![0]).toEqual({ query: { status: 'trashed' } })
+  })
+
+  it('debounces search writes', async () => {
+    vi.useFakeTimers()
+    try {
+      const hub = useAnnotationsHub()
+      useAnnotationsUrlSync(hub)
+      await nextTick()
+      replaceMock.mockClear()
+
+      hub.search.value = 'dune'
+      await nextTick()
+      expect(replaceMock).not.toHaveBeenCalled()
+
+      vi.advanceTimersByTime(300)
+      expect(replaceMock).toHaveBeenCalledWith({ query: { search: 'dune' } })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
diff --git a/client/src/features/annotations/composables/__tests__/useDensity.spec.ts b/client/src/features/annotations/composables/__tests__/useDensity.spec.ts
new file mode 100644
index 000000000..bce9a9917
--- /dev/null
+++ b/client/src/features/annotations/composables/__tests__/useDensity.spec.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { nextTick } from 'vue'
+import { useDensity } from '../useDensity'
+
+const STORAGE_KEY = 'annotations:density'
+
+describe('useDensity', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('defaults to comfortable when nothing is stored', () => {
+    const { density } = useDensity()
+    expect(density.value).toBe('comfortable')
+  })
+
+  it('restores a valid stored value', () => {
+    localStorage.setItem(STORAGE_KEY, 'compact')
+    const { density } = useDensity()
+    expect(density.value).toBe('compact')
+  })
+
+  it('falls back to comfortable for an unrecognized stored value', () => {
+    localStorage.setItem(STORAGE_KEY, 'cozy')
+    const { density } = useDensity()
+    expect(density.value).toBe('comfortable')
+  })
+
+  it('persists changes back to localStorage', async () => {
+    const { density } = useDensity()
+    density.value = 'compact'
+    await nextTick()
+    expect(localStorage.getItem(STORAGE_KEY)).toBe('compact')
+  })
+})
diff --git a/client/src/features/annotations/composables/useAnnotationMutations.ts b/client/src/features/annotations/composables/useAnnotationMutations.ts
new file mode 100644
index 000000000..1b7703790
--- /dev/null
+++ b/client/src/features/annotations/composables/useAnnotationMutations.ts
@@ -0,0 +1,66 @@
+import { ref, watch, type Ref } from 'vue'
+import { api } from '@/lib/api'
+
+export interface AnnotationPatch {
+  note?: string | null
+  color?: string
+  style?: string
+}
+
+type Editable = { id: number; bookId: number; note?: string | null; color?: string; style?: string }
+
+/**
+ * Shared per-item note/color/style editing for an annotation list: optimistic local patch,
+ * book-scoped PATCH, revert on failure, and per-id saving state. `resolveBookId` lets the hub
+ * look the book up per item while a single-book view returns a constant.
+ */
+export function useAnnotationMutations<T extends Editable>(items: Ref<T[]>, resolveBookId: (id: number) => number | null) {
+  const savingIds = ref<Set<number>>(new Set())
+
+  function setSaving(id: number, saving: boolean) {
+    const next = new Set(savingIds.value)
+    if (saving) next.add(id)
+    else next.delete(id)
+    savingIds.value = next
+  }
+
+  async function patch(id: number, body: AnnotationPatch) {
+    const bookId = resolveBookId(id)
+    if (bookId == null) return
+    const previous = items.value
+    items.value = items.value.map((item) => (item.id === id ? { ...item, ...body } : item))
+    setSaving(id, true)
+    try {
+      const res = await api(`/api/v1/books/${bookId}/annotations/${id}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+      if (!res.ok) items.value = previous
+    } catch {
+      items.value = previous
+    } finally {
+      setSaving(id, false)
+    }
+  }
+
+  function updateNote(id: number, note: string | null) {
+    return patch(id, { note })
+  }
+
+  function updateColor(id: number, color: string) {
+    return patch(id, { color })
+  }
+
+  function updateStyle(id: number, style: string) {
+    return patch(id, { style })
+  }
+
+  watch(items, (nextItems) => {
+    const currentIds = new Set(nextItems.map((item) => item.id))
+    const pruned = new Set([...savingIds.value].filter((id) => currentIds.has(id)))
+    if (pruned.size !== savingIds.value.size) savingIds.value = pruned
+  })
+
+  return { savingIds, setSaving, updateNote, updateColor, updateStyle }
+}
diff --git a/client/src/features/annotations/composables/useAnnotationSelection.ts b/client/src/features/annotations/composables/useAnnotationSelection.ts
new file mode 100644
index 000000000..7b2a41240
--- /dev/null
+++ b/client/src/features/annotations/composables/useAnnotationSelection.ts
@@ -0,0 +1,36 @@
+import { computed, ref, watch, type Ref } from 'vue'
+
+/** Shared bulk-selection state for an annotation list. Prunes ids that leave the list. */
+export function useAnnotationSelection<T extends { id: number }>(items: Ref<T[]>) {
+  const selectedIds = ref<Set<number>>(new Set())
+
+  const visibleIds = computed(() => items.value.map((item) => item.id))
+  const hasSelection = computed(() => selectedIds.value.size > 0)
+  const allVisibleSelected = computed(() => visibleIds.value.length > 0 && visibleIds.value.every((id) => selectedIds.value.has(id)))
+  const selectedItems = computed(() => items.value.filter((item) => selectedIds.value.has(item.id)))
+
+  function toggleSelected(id: number) {
+    const next = new Set(selectedIds.value)
+    if (next.has(id)) next.delete(id)
+    else next.add(id)
+    selectedIds.value = next
+  }
+
+  function selectAllOnPage() {
+    const next = new Set(selectedIds.value)
+    for (const id of visibleIds.value) next.add(id)
+    selectedIds.value = next
+  }
+
+  function clearSelection() {
+    if (selectedIds.value.size > 0) selectedIds.value = new Set()
+  }
+
+  watch(items, (nextItems) => {
+    const currentIds = new Set(nextItems.map((item) => item.id))
+    const pruned = new Set([...selectedIds.value].filter((id) => currentIds.has(id)))
+    if (pruned.size !== selectedIds.value.size) selectedIds.value = pruned
+  })
+
+  return { selectedIds, hasSelection, allVisibleSelected, selectedItems, toggleSelected, selectAllOnPage, clearSelection }
+}
diff --git a/client/src/features/annotations/composables/useAnnotationSyncDetail.ts b/client/src/features/annotations/composables/useAnnotationSyncDetail.ts
new file mode 100644
index 000000000..cf42f3036
--- /dev/null
+++ b/client/src/features/annotations/composables/useAnnotationSyncDetail.ts
@@ -0,0 +1,44 @@
+import { ref } from 'vue'
+import { api } from '@/lib/api'
+import type { AnnotationPositionFormat, AnnotationSyncDetail } from '@bookorbit/types'
+
+export function useAnnotationSyncDetail() {
+  const detail = ref<AnnotationSyncDetail | null>(null)
+  const loading = ref(false)
+  const retrying = ref<AnnotationPositionFormat | null>(null)
+  const error = ref<string | null>(null)
+
+  async function load(annotationId: number): Promise<void> {
+    loading.value = true
+    error.value = null
+    try {
+      const res = await api(`/api/v1/annotations/${annotationId}/sync-detail`)
+      if (!res.ok) throw new Error('Failed to load sync detail')
+      detail.value = (await res.json()) as AnnotationSyncDetail
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load sync detail'
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function retry(annotationId: number, format: AnnotationPositionFormat): Promise<void> {
+    retrying.value = format
+    error.value = null
+    try {
+      const res = await api(`/api/v1/annotations/${annotationId}/positions/retry`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ format }),
+      })
+      if (!res.ok) throw new Error('Failed to retry position conversion')
+      detail.value = (await res.json()) as AnnotationSyncDetail
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to retry position conversion'
+    } finally {
+      retrying.value = null
+    }
+  }
+
+  return { detail, loading, retrying, error, load, retry }
+}
diff --git a/client/src/features/annotations/composables/useAnnotationsHub.ts b/client/src/features/annotations/composables/useAnnotationsHub.ts
new file mode 100644
index 000000000..5f1a3c1d4
--- /dev/null
+++ b/client/src/features/annotations/composables/useAnnotationsHub.ts
@@ -0,0 +1,356 @@
+import { computed, nextTick, ref, watch } from 'vue'
+import type { AnnotationHubBookFacet, AnnotationHubItem, AnnotationHubResponse, AnnotationHubStats } from '@bookorbit/types'
+import { api } from '@/lib/api'
+import { type SortKey } from '../lib/filter-options'
+import { buildFilterChips } from '../lib/filter-chips'
+import { useAnnotationSelection } from './useAnnotationSelection'
+import { useAnnotationMutations } from './useAnnotationMutations'
+
+export type HubStatus = 'active' | 'trashed'
+
+/** The slice of hub state that can be restored from the URL on load. */
+export interface AnnotationsHubState {
+  status: HubStatus
+  search: string
+  bookFilter: number | 'all'
+  colors: string[]
+  styleFilter: string
+  originFilter: string
+  notesOnly: boolean
+  dateFrom: string
+  dateTo: string
+  sortKey: SortKey
+  page: number
+}
+
+const SEARCH_RELOAD_DEBOUNCE_MS = 300
+
+/**
+ * Turns a yyyy-mm-dd value from an `<input type="date">` into a UTC ISO instant at the
+ * start or end of that calendar day in the user's local timezone, so a "to" date includes
+ * the whole day. Returns '' for empty or unparseable input.
+ */
+function toDayBoundaryIso(date: string, edge: 'start' | 'end'): string {
+  if (!date) return ''
+  const parsed = new Date(`${date}T${edge === 'start' ? '00:00:00.000' : '23:59:59.999'}`)
+  return Number.isNaN(parsed.getTime()) ? '' : parsed.toISOString()
+}
+
+export function useAnnotationsHub() {
+  const items = ref<AnnotationHubItem[]>([])
+  const total = ref(0)
+  const page = ref(1)
+  const pageSize = ref(25)
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  const status = ref<HubStatus>('active')
+  const search = ref('')
+  const colors = ref<string[]>([])
+  const styleFilter = ref('all')
+  const originFilter = ref('all')
+  const bookFilter = ref<number | 'all'>('all')
+  const sortBy = ref<'createdAt' | 'book'>('createdAt')
+  const sortDir = ref<'asc' | 'desc'>('desc')
+  const dateFrom = ref('')
+  const dateTo = ref('')
+  const notesOnly = ref(false)
+  const hydrating = ref(false)
+
+  const selectedBookLabel = ref<string | null>(null)
+  const stats = ref<AnnotationHubStats | null>(null)
+
+  const selection = useAnnotationSelection(items)
+  const mutations = useAnnotationMutations(items, (id) => items.value.find((item) => item.id === id)?.bookId ?? null)
+
+  const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)))
+  const rangeStart = computed(() => (total.value === 0 ? 0 : (page.value - 1) * pageSize.value + 1))
+  const rangeEnd = computed(() => Math.min(page.value * pageSize.value, total.value))
+
+  const sortKey = computed<SortKey>({
+    get() {
+      if (sortBy.value === 'book') return sortDir.value === 'asc' ? 'book-asc' : 'book-desc'
+      return sortDir.value === 'desc' ? 'newest' : 'oldest'
+    },
+    set(value) {
+      switch (value) {
+        case 'newest':
+          sortBy.value = 'createdAt'
+          sortDir.value = 'desc'
+          break
+        case 'oldest':
+          sortBy.value = 'createdAt'
+          sortDir.value = 'asc'
+          break
+        case 'book-asc':
+          sortBy.value = 'book'
+          sortDir.value = 'asc'
+          break
+        case 'book-desc':
+          sortBy.value = 'book'
+          sortDir.value = 'desc'
+          break
+      }
+    },
+  })
+
+  const activeFilterChips = computed(() =>
+    buildFilterChips({
+      colors: colors.value,
+      styleFilter: styleFilter.value,
+      originFilter: originFilter.value,
+      dateFrom: dateFrom.value,
+      dateTo: dateTo.value,
+    }),
+  )
+
+  const popoverFilterCount = computed(() => activeFilterChips.value.length)
+
+  const hasActiveFilters = computed(
+    () =>
+      search.value.trim() !== '' ||
+      bookFilter.value !== 'all' ||
+      notesOnly.value ||
+      colors.value.length > 0 ||
+      styleFilter.value !== 'all' ||
+      originFilter.value !== 'all' ||
+      dateFrom.value !== '' ||
+      dateTo.value !== '',
+  )
+
+  function buildQuery(extra: Record<string, string> = {}): string {
+    const params = new URLSearchParams()
+    params.set('page', String(page.value))
+    params.set('pageSize', String(pageSize.value))
+    params.set('status', status.value)
+    params.set('sortBy', sortBy.value)
+    params.set('sortDir', sortDir.value)
+    if (search.value.trim()) params.set('search', search.value.trim())
+    if (colors.value.length > 0) params.set('colors', colors.value.join(','))
+    if (styleFilter.value !== 'all') params.set('styles', styleFilter.value)
+    if (originFilter.value !== 'all') params.set('origins', originFilter.value)
+    if (bookFilter.value !== 'all') params.set('bookId', String(bookFilter.value))
+    const from = toDayBoundaryIso(dateFrom.value, 'start')
+    if (from) params.set('dateFrom', from)
+    const to = toDayBoundaryIso(dateTo.value, 'end')
+    if (to) params.set('dateTo', to)
+    if (notesOnly.value) params.set('hasNote', 'true')
+    for (const [key, value] of Object.entries(extra)) params.set(key, value)
+    return params.toString()
+  }
+
+  let loadSeq = 0
+  async function load() {
+    const seq = ++loadSeq
+    loading.value = true
+    error.value = null
+    try {
+      const res = await api(`/api/v1/annotations?${buildQuery()}`)
+      if (seq !== loadSeq) return
+      if (!res.ok) {
+        error.value = 'Failed to load annotations'
+        return
+      }
+      const body: AnnotationHubResponse = await res.json()
+      if (seq !== loadSeq) return
+      items.value = body.items
+      total.value = body.total
+      stats.value = body.stats
+    } finally {
+      if (seq === loadSeq) loading.value = false
+    }
+  }
+
+  async function searchBooks(q: string): Promise<AnnotationHubBookFacet[]> {
+    const params = new URLSearchParams({ status: status.value })
+    if (q.trim()) params.set('q', q.trim())
+    const res = await api(`/api/v1/annotations/books?${params.toString()}`)
+    if (!res.ok) return []
+    return (await res.json()) as AnnotationHubBookFacet[]
+  }
+
+  async function resolveSelectedBook() {
+    if (bookFilter.value === 'all') {
+      selectedBookLabel.value = null
+      return
+    }
+    if (selectedBookLabel.value) return
+    const params = new URLSearchParams({ status: status.value, selectedId: String(bookFilter.value) })
+    const res = await api(`/api/v1/annotations/books?${params.toString()}`)
+    if (!res.ok) return
+    const facets = (await res.json()) as AnnotationHubBookFacet[]
+    const match = facets.find((facet) => facet.bookId === bookFilter.value)
+    if (match) selectedBookLabel.value = match.bookTitle ?? 'Unknown book'
+  }
+
+  function toggleNotesOnly() {
+    notesOnly.value = !notesOnly.value
+  }
+
+  function clearDates() {
+    dateFrom.value = ''
+    dateTo.value = ''
+  }
+
+  function clearPopoverFilters() {
+    colors.value = []
+    styleFilter.value = 'all'
+    originFilter.value = 'all'
+    clearDates()
+  }
+
+  function resetAllFilters() {
+    search.value = ''
+    bookFilter.value = 'all'
+    selectedBookLabel.value = null
+    notesOnly.value = false
+    clearPopoverFilters()
+  }
+
+  function removeFilterChip(id: string) {
+    if (id.startsWith('color:')) {
+      const hex = id.slice('color:'.length)
+      colors.value = colors.value.filter((value) => value !== hex)
+      return
+    }
+    if (id === 'style') styleFilter.value = 'all'
+    else if (id === 'origin') originFilter.value = 'all'
+    else if (id === 'date') clearDates()
+  }
+
+  function hydrate(state: Partial<AnnotationsHubState>) {
+    hydrating.value = true
+    if (state.status !== undefined) status.value = state.status
+    if (state.search !== undefined) search.value = state.search
+    if (state.bookFilter !== undefined) bookFilter.value = state.bookFilter
+    if (state.colors !== undefined) colors.value = state.colors
+    if (state.styleFilter !== undefined) styleFilter.value = state.styleFilter
+    if (state.originFilter !== undefined) originFilter.value = state.originFilter
+    if (state.notesOnly !== undefined) notesOnly.value = state.notesOnly
+    if (state.dateFrom !== undefined) dateFrom.value = state.dateFrom
+    if (state.dateTo !== undefined) dateTo.value = state.dateTo
+    if (state.sortKey !== undefined) sortKey.value = state.sortKey
+    if (state.page !== undefined) page.value = state.page
+    void nextTick(() => {
+      hydrating.value = false
+    })
+  }
+
+  async function bulk(action: 'trash' | 'restore' | 'restyle', patch?: { color?: string; style?: string }): Promise<number> {
+    const ids = [...selection.selectedIds.value]
+    if (ids.length === 0) return 0
+    const res = await api('/api/v1/annotations/bulk', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ids, action, ...patch }),
+    })
+    if (!res.ok) return 0
+    const body = (await res.json()) as { affected: number }
+    selection.clearSelection()
+    await load()
+    return body.affected
+  }
+
+  async function restore(id: number): Promise<boolean> {
+    const res = await api(`/api/v1/annotations/${id}/restore`, { method: 'POST' })
+    if (res.ok) await load()
+    return res.ok
+  }
+
+  async function purge(id: number): Promise<{ ok: boolean; message?: string }> {
+    const res = await api(`/api/v1/annotations/${id}`, { method: 'DELETE' })
+    if (res.ok) {
+      await load()
+      return { ok: true }
+    }
+    if (res.status === 409) {
+      const body = (await res.json().catch(() => null)) as { message?: string } | null
+      return { ok: false, message: body?.message ?? 'Still pending device sync' }
+    }
+    return { ok: false, message: 'Failed to delete' }
+  }
+
+  function exportUrl(format: 'md' | 'csv' | 'json'): string {
+    return `/api/v1/annotations/export?${buildQuery({ format })}`
+  }
+
+  function reloadFromFilterChange() {
+    selection.clearSelection()
+    if (page.value === 1) void load()
+    else page.value = 1
+  }
+
+  watch([status, colors, styleFilter, originFilter, bookFilter, sortBy, sortDir, dateFrom, dateTo, notesOnly], () => {
+    if (hydrating.value) return
+    reloadFromFilterChange()
+  })
+  let searchDebounce: ReturnType<typeof setTimeout> | null = null
+  watch(search, () => {
+    if (hydrating.value) return
+    if (searchDebounce) clearTimeout(searchDebounce)
+    searchDebounce = setTimeout(reloadFromFilterChange, SEARCH_RELOAD_DEBOUNCE_MS)
+  })
+  watch(status, () => {
+    if (hydrating.value) return
+    bookFilter.value = 'all'
+    selectedBookLabel.value = null
+  })
+  watch(page, () => {
+    if (hydrating.value) return
+    selection.clearSelection()
+    void load()
+  })
+
+  return {
+    items,
+    total,
+    page,
+    pageSize,
+    totalPages,
+    rangeStart,
+    rangeEnd,
+    loading,
+    error,
+    status,
+    search,
+    colors,
+    styleFilter,
+    originFilter,
+    bookFilter,
+    sortBy,
+    sortDir,
+    sortKey,
+    dateFrom,
+    dateTo,
+    notesOnly,
+    hydrating,
+    activeFilterChips,
+    popoverFilterCount,
+    hasActiveFilters,
+    selectedBookLabel,
+    stats,
+    selectedIds: selection.selectedIds,
+    savingIds: mutations.savingIds,
+    hasSelection: selection.hasSelection,
+    allVisibleSelected: selection.allVisibleSelected,
+    load,
+    searchBooks,
+    resolveSelectedBook,
+    toggleSelected: selection.toggleSelected,
+    clearSelection: selection.clearSelection,
+    selectAllOnPage: selection.selectAllOnPage,
+    toggleNotesOnly,
+    clearDates,
+    clearPopoverFilters,
+    resetAllFilters,
+    removeFilterChip,
+    updateNote: mutations.updateNote,
+    updateColor: mutations.updateColor,
+    updateStyle: mutations.updateStyle,
+    hydrate,
+    bulk,
+    restore,
+    purge,
+    exportUrl,
+  }
+}
diff --git a/client/src/features/annotations/composables/useAnnotationsUrlSync.ts b/client/src/features/annotations/composables/useAnnotationsUrlSync.ts
new file mode 100644
index 000000000..e844971aa
--- /dev/null
+++ b/client/src/features/annotations/composables/useAnnotationsUrlSync.ts
@@ -0,0 +1,135 @@
+import { watch } from 'vue'
+import { useRoute, useRouter, type LocationQuery, type LocationQueryRaw } from 'vue-router'
+import { SORT_OPTIONS, type SortKey } from '../lib/filter-options'
+import type { AnnotationsHubState, useAnnotationsHub } from './useAnnotationsHub'
+
+type Hub = ReturnType<typeof useAnnotationsHub>
+
+const VALID_SORT_KEYS = new Set<string>(SORT_OPTIONS.map((option) => option.value))
+const SEARCH_WRITE_DELAY_MS = 300
+
+function firstString(value: LocationQuery[string] | undefined): string | undefined {
+  if (Array.isArray(value)) {
+    const first = value[0]
+    return typeof first === 'string' ? first : undefined
+  }
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Restores the saved filter/sort/page slice from a URL query (ignoring unknown or malformed values). */
+export function annotationsStateFromQuery(query: LocationQuery): Partial<AnnotationsHubState> {
+  const state: Partial<AnnotationsHubState> = {}
+
+  if (firstString(query.status) === 'trashed') state.status = 'trashed'
+
+  const search = firstString(query.search)
+  if (search) state.search = search
+
+  const bookId = firstString(query.bookId)
+  if (bookId) {
+    const parsed = Number(bookId)
+    if (Number.isInteger(parsed) && parsed > 0) state.bookFilter = parsed
+  }
+
+  const colorsParam = firstString(query.colors)
+  if (colorsParam) {
+    const list = colorsParam.split(',').filter(Boolean)
+    if (list.length > 0) state.colors = list
+  }
+
+  const style = firstString(query.style)
+  if (style) state.styleFilter = style
+
+  const origin = firstString(query.origin)
+  if (origin) state.originFilter = origin
+
+  if (firstString(query.notes) === '1') state.notesOnly = true
+
+  const from = firstString(query.from)
+  if (from) state.dateFrom = from
+
+  const to = firstString(query.to)
+  if (to) state.dateTo = to
+
+  const sort = firstString(query.sort)
+  if (sort && VALID_SORT_KEYS.has(sort)) state.sortKey = sort as SortKey
+
+  const page = firstString(query.page)
+  if (page) {
+    const parsed = Number(page)
+    if (Number.isInteger(parsed) && parsed > 1) state.page = parsed
+  }
+
+  return state
+}
+
+/** Serializes the current hub state into a minimal query (defaults are omitted). */
+export function annotationsQueryFromState(state: AnnotationsHubState): LocationQueryRaw {
+  const query: LocationQueryRaw = {}
+  if (state.status !== 'active') query.status = state.status
+  const search = state.search.trim()
+  if (search) query.search = search
+  if (state.bookFilter !== 'all') query.bookId = String(state.bookFilter)
+  if (state.colors.length > 0) query.colors = state.colors.join(',')
+  if (state.styleFilter !== 'all') query.style = state.styleFilter
+  if (state.originFilter !== 'all') query.origin = state.originFilter
+  if (state.notesOnly) query.notes = '1'
+  if (state.dateFrom) query.from = state.dateFrom
+  if (state.dateTo) query.to = state.dateTo
+  if (state.sortKey !== 'newest') query.sort = state.sortKey
+  if (state.page > 1) query.page = String(state.page)
+  return query
+}
+
+function sameQuery(next: LocationQueryRaw, current: LocationQuery): boolean {
+  const nextKeys = Object.keys(next)
+  if (nextKeys.length !== Object.keys(current).length) return false
+  return nextKeys.every((key) => String(next[key]) === firstString(current[key]))
+}
+
+/**
+ * Two-way binds the annotations filter/sort/page state to the URL query: hydrates the hub from
+ * the query on setup, then mirrors later changes back via `router.replace` so refresh, bookmark,
+ * and share restore the exact view without polluting browser history. Search writes are debounced.
+ */
+export function useAnnotationsUrlSync(hub: Hub) {
+  const route = useRoute()
+  const router = useRouter()
+
+  hub.hydrate(annotationsStateFromQuery(route.query))
+  void hub.resolveSelectedBook()
+
+  function snapshot(): AnnotationsHubState {
+    return {
+      status: hub.status.value,
+      search: hub.search.value,
+      bookFilter: hub.bookFilter.value,
+      colors: hub.colors.value,
+      styleFilter: hub.styleFilter.value,
+      originFilter: hub.originFilter.value,
+      notesOnly: hub.notesOnly.value,
+      dateFrom: hub.dateFrom.value,
+      dateTo: hub.dateTo.value,
+      sortKey: hub.sortKey.value,
+      page: hub.page.value,
+    }
+  }
+
+  function write() {
+    if (hub.hydrating.value) return
+    const query = annotationsQueryFromState(snapshot())
+    if (sameQuery(query, route.query)) return
+    void router.replace({ query })
+  }
+
+  let searchTimer: ReturnType<typeof setTimeout> | null = null
+  watch(hub.search, () => {
+    if (searchTimer) clearTimeout(searchTimer)
+    searchTimer = setTimeout(write, SEARCH_WRITE_DELAY_MS)
+  })
+
+  watch(
+    [hub.status, hub.bookFilter, hub.colors, hub.styleFilter, hub.originFilter, hub.notesOnly, hub.dateFrom, hub.dateTo, hub.sortKey, hub.page],
+    write,
+  )
+}
diff --git a/client/src/features/annotations/composables/useDensity.ts b/client/src/features/annotations/composables/useDensity.ts
new file mode 100644
index 000000000..c96668ba2
--- /dev/null
+++ b/client/src/features/annotations/composables/useDensity.ts
@@ -0,0 +1,15 @@
+import { ref, watch } from 'vue'
+
+export type AnnotationDensity = 'compact' | 'comfortable'
+
+const STORAGE_KEY = 'annotations:density'
+
+/** Density preference shared across the annotations hub and the book highlights tab. */
+export function useDensity() {
+  const stored = localStorage.getItem(STORAGE_KEY)
+  const density = ref<AnnotationDensity>(stored === 'compact' || stored === 'comfortable' ? stored : 'comfortable')
+
+  watch(density, (value) => localStorage.setItem(STORAGE_KEY, value))
+
+  return { density }
+}
diff --git a/client/src/features/annotations/lib/__tests__/filter-chips.spec.ts b/client/src/features/annotations/lib/__tests__/filter-chips.spec.ts
new file mode 100644
index 000000000..16284a25f
--- /dev/null
+++ b/client/src/features/annotations/lib/__tests__/filter-chips.spec.ts
@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { buildFilterChips, dateRangeLabel } from '../filter-chips'
+
+describe('dateRangeLabel', () => {
+  it('formats both, from-only, and to-only ranges', () => {
+    expect(dateRangeLabel('2026-01-01', '2026-01-31')).toBe('2026-01-01 to 2026-01-31')
+    expect(dateRangeLabel('2026-01-01', '')).toBe('From 2026-01-01')
+    expect(dateRangeLabel('', '2026-01-31')).toBe('Until 2026-01-31')
+  })
+})
+
+describe('buildFilterChips', () => {
+  it('returns an empty list when no filters are active', () => {
+    expect(buildFilterChips({ colors: [], dateFrom: '', dateTo: '' })).toEqual([])
+    expect(buildFilterChips({ colors: [], styleFilter: 'all', originFilter: 'all', dateFrom: '', dateTo: '' })).toEqual([])
+  })
+
+  it('builds one chip per color, resolving both app and KOReader-exact labels', () => {
+    const chips = buildFilterChips({ colors: ['#FACC15', '#FF3300'], dateFrom: '', dateTo: '' })
+    expect(chips).toEqual([
+      { id: 'color:#FACC15', label: 'Color: Yellow' },
+      { id: 'color:#FF3300', label: 'Color: KOReader Red' },
+    ])
+  })
+
+  it('builds style, origin, and date chips when set', () => {
+    const chips = buildFilterChips({
+      colors: [],
+      styleFilter: 'underline',
+      originFilter: 'koreader',
+      dateFrom: '2026-01-01',
+      dateTo: '2026-02-01',
+    })
+    expect(chips.map((chip) => chip.id)).toEqual(['style', 'origin', 'date'])
+    expect(chips[0].label).toBe('Style: Underline')
+    expect(chips[1].label).toBe('Source: KOReader')
+    expect(chips[2].label).toBe('Date: 2026-01-01 to 2026-02-01')
+  })
+})
diff --git a/client/src/features/annotations/lib/filter-chips.ts b/client/src/features/annotations/lib/filter-chips.ts
new file mode 100644
index 000000000..1a3c3c8f1
--- /dev/null
+++ b/client/src/features/annotations/lib/filter-chips.ts
@@ -0,0 +1,28 @@
+import { colorLabel, originLabel, styleLabel } from './filter-options'
+
+export interface ActiveFilterChip {
+  id: string
+  label: string
+}
+
+export function dateRangeLabel(from: string, to: string): string {
+  if (from && to) return `${from} to ${to}`
+  if (from) return `From ${from}`
+  return `Until ${to}`
+}
+
+/** Builds the dismissible chip list for the filters that live inside the Filters popover. */
+export function buildFilterChips(opts: {
+  colors: string[]
+  styleFilter?: string
+  originFilter?: string
+  dateFrom: string
+  dateTo: string
+}): ActiveFilterChip[] {
+  const chips: ActiveFilterChip[] = []
+  for (const hex of opts.colors) chips.push({ id: `color:${hex}`, label: `Color: ${colorLabel(hex)}` })
+  if (opts.styleFilter && opts.styleFilter !== 'all') chips.push({ id: 'style', label: `Style: ${styleLabel(opts.styleFilter)}` })
+  if (opts.originFilter && opts.originFilter !== 'all') chips.push({ id: 'origin', label: `Source: ${originLabel(opts.originFilter)}` })
+  if (opts.dateFrom || opts.dateTo) chips.push({ id: 'date', label: `Date: ${dateRangeLabel(opts.dateFrom, opts.dateTo)}` })
+  return chips
+}
diff --git a/client/src/features/annotations/lib/filter-options.ts b/client/src/features/annotations/lib/filter-options.ts
new file mode 100644
index 000000000..38298a337
--- /dev/null
+++ b/client/src/features/annotations/lib/filter-options.ts
@@ -0,0 +1,52 @@
+import { ANNOTATION_COLOR_FILTER_OPTIONS } from '@bookorbit/types'
+
+export interface FilterOption {
+  value: string
+  label: string
+}
+
+export const COLOR_OPTIONS: FilterOption[] = [
+  { value: 'all', label: 'All colors' },
+  ...ANNOTATION_COLOR_FILTER_OPTIONS.map((color) => ({ value: color.hex, label: color.label })),
+]
+
+export const STYLE_OPTIONS: FilterOption[] = [
+  { value: 'all', label: 'All styles' },
+  { value: 'highlight', label: 'Highlight' },
+  { value: 'underline', label: 'Underline' },
+  { value: 'strikethrough', label: 'Strikethrough' },
+  { value: 'squiggly', label: 'Squiggly' },
+  { value: 'invert', label: 'Invert' },
+]
+
+export const ORIGIN_OPTIONS: FilterOption[] = [
+  { value: 'all', label: 'All sources' },
+  { value: 'web', label: 'Web' },
+  { value: 'koreader', label: 'KOReader' },
+  { value: 'kobo', label: 'Kobo' },
+]
+
+export type SortKey = 'newest' | 'oldest' | 'book-asc' | 'book-desc'
+
+export const SORT_OPTIONS: { value: SortKey; label: string }[] = [
+  { value: 'newest', label: 'Newest first' },
+  { value: 'oldest', label: 'Oldest first' },
+  { value: 'book-asc', label: 'Book A to Z' },
+  { value: 'book-desc', label: 'Book Z to A' },
+]
+
+function labelFor(options: FilterOption[], value: string): string {
+  return options.find((option) => option.value === value)?.label ?? value
+}
+
+export function colorLabel(value: string): string {
+  return labelFor(COLOR_OPTIONS, value)
+}
+
+export function styleLabel(value: string): string {
+  return labelFor(STYLE_OPTIONS, value)
+}
+
+export function originLabel(value: string): string {
+  return labelFor(ORIGIN_OPTIONS, value)
+}
diff --git a/client/src/features/annotations/lib/pill-styles.ts b/client/src/features/annotations/lib/pill-styles.ts
new file mode 100644
index 000000000..e542f62e0
--- /dev/null
+++ b/client/src/features/annotations/lib/pill-styles.ts
@@ -0,0 +1,41 @@
+import type { AnnotationItem, AnnotationPositionStatus } from '@bookorbit/types'
+
+type AnnotationOrigin = AnnotationItem['origin']
+
+export interface PillStyle {
+  label: string
+  class: string
+}
+
+const PILL_BASE = 'inline-flex items-center gap-1 rounded border px-1.5 py-0.5 text-[10px] font-medium'
+
+export const SOURCE_PILLS: Record<AnnotationOrigin, PillStyle> = {
+  web: { label: 'Web', class: 'border-[var(--pill-web)]/40 bg-[var(--pill-web)]/10 text-[var(--pill-web)]' },
+  koreader: { label: 'KOReader', class: 'border-[var(--pill-koreader)]/40 bg-[var(--pill-koreader)]/10 text-[var(--pill-koreader)]' },
+  kobo: { label: 'Kobo', class: 'border-[var(--pill-kobo)]/40 bg-[var(--pill-kobo)]/10 text-[var(--pill-kobo)]' },
+}
+
+const STATUS_QUIET = 'border-border bg-muted text-muted-foreground'
+
+const STATUS_PILLS: Record<AnnotationPositionStatus, PillStyle> = {
+  exact: { label: 'Exact', class: STATUS_QUIET },
+  repaired: { label: 'Repaired', class: 'border-[var(--pill-repaired)]/40 bg-[var(--pill-repaired)]/10 text-[var(--pill-repaired)]' },
+  pending: { label: 'Pending', class: 'border-[var(--pill-pending)]/40 bg-[var(--pill-pending)]/10 text-[var(--pill-pending)]' },
+  failed: { label: 'Failed', class: 'border-destructive/40 bg-destructive/10 text-destructive' },
+}
+
+const APPROXIMATE_PILL: PillStyle = {
+  label: 'Approximate',
+  class: 'border-[var(--pill-repaired)]/40 bg-[var(--pill-repaired)]/10 text-[var(--pill-repaired)]',
+}
+
+export const PILL_CLASS = PILL_BASE
+
+export function sourcePill(origin: AnnotationOrigin): PillStyle {
+  return SOURCE_PILLS[origin]
+}
+
+export function statusPill(status: AnnotationPositionStatus | null, isApproximate: boolean): PillStyle | null {
+  if (!status) return isApproximate ? APPROXIMATE_PILL : null
+  return STATUS_PILLS[status]
+}
diff --git a/client/src/features/annotations/views/AnnotationsHubView.vue b/client/src/features/annotations/views/AnnotationsHubView.vue
new file mode 100644
index 000000000..224fe33c4
--- /dev/null
+++ b/client/src/features/annotations/views/AnnotationsHubView.vue
@@ -0,0 +1,345 @@
+<script setup lang="ts">
+import { computed, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+import { Download, Highlighter, RotateCcw, StickyNote, Trash2 } from '@lucide/vue'
+import { toast } from 'vue-sonner'
+import type { AnnotationHubItem } from '@bookorbit/types'
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@/components/ui/dropdown-menu'
+import { Button } from '@/components/ui/button'
+import AnnotationCard from '../components/AnnotationCard.vue'
+import AnnotationBookGroup from '../components/AnnotationBookGroup.vue'
+import AnnotationBookCombobox from '../components/AnnotationBookCombobox.vue'
+import AnnotationToolbar from '../components/AnnotationToolbar.vue'
+import AnnotationFiltersPanel from '../components/AnnotationFiltersPanel.vue'
+import AnnotationSummaryBar from '../components/AnnotationSummaryBar.vue'
+import AnnotationBulkBar from '../components/AnnotationBulkBar.vue'
+import AnnotationPagination from '../components/AnnotationPagination.vue'
+import { ORIGIN_OPTIONS, SORT_OPTIONS, STYLE_OPTIONS } from '../lib/filter-options'
+import { sourcePill } from '../lib/pill-styles'
+import { useAnnotationsHub } from '../composables/useAnnotationsHub'
+import { useAnnotationsUrlSync } from '../composables/useAnnotationsUrlSync'
+import { useDensity } from '../composables/useDensity'
+
+const router = useRouter()
+const hub = useAnnotationsHub()
+useAnnotationsUrlSync(hub)
+const { density } = useDensity()
+
+const SELECT_CLASS = 'h-9 w-full px-2 rounded-md border border-border bg-background text-sm'
+const FIELD_LABEL_CLASS = 'flex flex-col gap-1.5 text-xs font-medium text-muted-foreground'
+
+const isGrouped = computed(() => hub.sortBy.value === 'book')
+
+const groupedByBook = computed(() => {
+  const groups: { bookId: number; bookTitle: string; author: string | null; items: AnnotationHubItem[] }[] = []
+  let current: (typeof groups)[number] | null = null
+  for (const item of hub.items.value) {
+    if (!current || current.bookId !== item.bookId) {
+      current = { bookId: item.bookId, bookTitle: item.bookTitle ?? 'Unknown book', author: item.author, items: [] }
+      groups.push(current)
+    }
+    current.items.push(item)
+  }
+  return groups
+})
+
+const summaryTexts = computed(() => {
+  const stats = hub.stats.value
+  if (!stats) return []
+  const texts: string[] = []
+  if (stats.books > 0) texts.push(`${stats.books} ${stats.books === 1 ? 'book' : 'books'}`)
+  if (stats.withNotes > 0) texts.push(`${stats.withNotes} ${stats.withNotes === 1 ? 'note' : 'notes'}`)
+  return texts
+})
+
+const originSummary = computed(() =>
+  (hub.stats.value?.originBreakdown ?? [])
+    .filter((entry) => entry.count > 0)
+    .map((entry) => ({ origin: entry.origin, ...sourcePill(entry.origin), count: entry.count })),
+)
+
+onMounted(() => {
+  void hub.load()
+})
+
+function setActiveTab() {
+  hub.status.value = 'active'
+}
+
+function setTrashTab() {
+  hub.status.value = 'trashed'
+}
+
+function toggleOriginFilter(origin: string) {
+  hub.originFilter.value = hub.originFilter.value === origin ? 'all' : origin
+}
+
+function handleSetPage(page: number) {
+  hub.page.value = page
+}
+
+function handleJump(annotation: AnnotationHubItem) {
+  if (!annotation.jumpFileId) return
+  const query: Record<string, string> = {}
+  if (annotation.cfi) query.cfi = annotation.cfi
+  else if (annotation.pageno != null) query.page = String(annotation.pageno)
+  void router.push({ name: 'reader', params: { bookId: annotation.bookId, fileId: annotation.jumpFileId }, query })
+}
+
+async function handleTrash(id: number) {
+  hub.selectedIds.value = new Set([id])
+  const affected = await hub.bulk('trash')
+  if (affected > 0) toast.success('Moved to trash')
+}
+
+async function handleRestore(id: number) {
+  const ok = await hub.restore(id)
+  if (ok) toast.success('Annotation restored')
+}
+
+async function handlePurge(id: number) {
+  const result = await hub.purge(id)
+  if (result.ok) toast.success('Annotation deleted forever')
+  else toast.error(result.message ?? 'Failed to delete')
+}
+
+async function handleBulkTrash() {
+  const affected = await hub.bulk('trash')
+  if (affected > 0) toast.success(`Moved ${affected} annotation(s) to trash`)
+}
+
+async function handleBulkRestore() {
+  const affected = await hub.bulk('restore')
+  if (affected > 0) toast.success(`Restored ${affected} annotation(s)`)
+}
+
+async function handleBulkRecolor(color: string) {
+  const affected = await hub.bulk('restyle', { color })
+  if (affected > 0) toast.success(`Recolored ${affected} annotation(s)`)
+}
+
+async function handleBulkRestyle(style: string) {
+  const affected = await hub.bulk('restyle', { style })
+  if (affected > 0) toast.success(`Restyled ${affected} annotation(s)`)
+}
+
+function handleExport(format: 'md' | 'csv' | 'json') {
+  window.open(hub.exportUrl(format), '_blank')
+}
+
+function handleExportMarkdown() {
+  handleExport('md')
+}
+
+function handleExportCsv() {
+  handleExport('csv')
+}
+
+function handleExportJson() {
+  handleExport('json')
+}
+</script>
+
+<template>
+  <div class="w-full max-w-8xl py-4 sm:py-6">
+    <div class="flex flex-wrap items-center justify-between gap-3 mb-5">
+      <div class="flex flex-wrap items-center gap-2.5">
+        <Highlighter :size="22" class="text-primary" />
+        <h1 class="text-xl font-semibold">Annotations</h1>
+        <span class="text-sm text-muted-foreground">{{ hub.total.value }} total</span>
+        <template v-if="summaryTexts.length > 0 || originSummary.length > 0">
+          <span class="hidden h-5 w-px bg-border sm:block" />
+          <AnnotationSummaryBar
+            class="hidden sm:flex"
+            :texts="summaryTexts"
+            :origins="originSummary"
+            :active-origin="hub.originFilter.value"
+            @origin-click="toggleOriginFilter"
+          />
+        </template>
+      </div>
+      <div class="flex items-center gap-3">
+        <DropdownMenu>
+          <DropdownMenuTrigger as-child>
+            <Button variant="outline" size="sm" class="gap-1.5">
+              <Download :size="14" />
+              Export
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem @click="handleExportMarkdown">Markdown</DropdownMenuItem>
+            <DropdownMenuItem @click="handleExportCsv">CSV</DropdownMenuItem>
+            <DropdownMenuItem @click="handleExportJson">JSON</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </div>
+
+    <div class="flex items-center gap-1 border-b border-border mb-4">
+      <button
+        type="button"
+        class="px-3 py-2 text-sm transition-colors border-b-2 -mb-px"
+        :class="hub.status.value === 'active' ? 'border-primary text-primary' : 'border-transparent text-muted-foreground hover:text-foreground'"
+        @click="setActiveTab"
+      >
+        Highlights
+      </button>
+      <button
+        type="button"
+        class="px-3 py-2 text-sm transition-colors border-b-2 -mb-px inline-flex items-center gap-1.5"
+        :class="hub.status.value === 'trashed' ? 'border-primary text-primary' : 'border-transparent text-muted-foreground hover:text-foreground'"
+        @click="setTrashTab"
+      >
+        <Trash2 :size="13" />
+        Trash
+      </button>
+    </div>
+
+    <AnnotationToolbar
+      v-model:search="hub.search.value"
+      v-model:sort-key="hub.sortKey.value"
+      v-model:density="density"
+      class="mb-4"
+      :sort-options="SORT_OPTIONS"
+      :filter-count="hub.popoverFilterCount.value"
+      :chips="hub.activeFilterChips.value"
+      @remove-chip="hub.removeFilterChip"
+      @clear-filters="hub.clearPopoverFilters"
+    >
+      <template #inline-filters>
+        <AnnotationBookCombobox v-model="hub.bookFilter.value" v-model:selected-label="hub.selectedBookLabel.value" :search-fn="hub.searchBooks" />
+        <button
+          type="button"
+          :aria-pressed="hub.notesOnly.value"
+          class="inline-flex h-9 items-center gap-1.5 rounded-md border px-2.5 text-sm transition-colors"
+          :class="
+            hub.notesOnly.value
+              ? 'border-primary bg-primary/10 text-primary'
+              : 'border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground'
+          "
+          @click="hub.toggleNotesOnly"
+        >
+          <StickyNote :size="14" />
+          Notes only
+        </button>
+      </template>
+      <template #filters>
+        <AnnotationFiltersPanel
+          v-model:colors="hub.colors.value"
+          v-model:date-from="hub.dateFrom.value"
+          v-model:date-to="hub.dateTo.value"
+          @clear-all="hub.clearPopoverFilters"
+        >
+          <template #extra>
+            <label :class="FIELD_LABEL_CLASS">
+              Style
+              <select v-model="hub.styleFilter.value" :class="SELECT_CLASS">
+                <option v-for="option in STYLE_OPTIONS" :key="option.value" :value="option.value">{{ option.label }}</option>
+              </select>
+            </label>
+            <label :class="FIELD_LABEL_CLASS">
+              Source
+              <select v-model="hub.originFilter.value" :class="SELECT_CLASS">
+                <option v-for="option in ORIGIN_OPTIONS" :key="option.value" :value="option.value">{{ option.label }}</option>
+              </select>
+            </label>
+          </template>
+        </AnnotationFiltersPanel>
+      </template>
+    </AnnotationToolbar>
+
+    <AnnotationBulkBar
+      v-if="hub.hasSelection.value"
+      class="mb-4"
+      :count="hub.selectedIds.value.size"
+      :all-visible-selected="hub.allVisibleSelected.value"
+      :show-restyle="hub.status.value === 'active'"
+      @select-page="hub.selectAllOnPage"
+      @clear="hub.clearSelection"
+      @recolor="handleBulkRecolor"
+      @restyle="handleBulkRestyle"
+    >
+      <template #trailing>
+        <Button v-if="hub.status.value === 'active'" variant="destructive" size="sm" class="gap-1.5" @click="handleBulkTrash">
+          <Trash2 :size="13" />
+          Trash
+        </Button>
+        <Button v-else variant="outline" size="sm" @click="handleBulkRestore">Restore</Button>
+      </template>
+    </AnnotationBulkBar>
+
+    <div v-if="hub.loading.value && hub.items.value.length === 0" class="flex flex-col gap-2">
+      <div v-for="i in 6" :key="i" class="h-24 rounded-lg bg-muted animate-shimmer" />
+    </div>
+    <div v-else-if="hub.error.value" class="py-12 text-center text-sm text-destructive">{{ hub.error.value }}</div>
+    <div v-else-if="hub.items.value.length === 0" class="py-12 text-center">
+      <template v-if="hub.hasActiveFilters.value">
+        <p class="text-sm text-muted-foreground">No highlights match your filters.</p>
+        <button
+          type="button"
+          class="mt-3 inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm text-foreground transition-colors hover:bg-muted"
+          @click="hub.resetAllFilters"
+        >
+          <RotateCcw :size="14" />
+          Reset filters
+        </button>
+      </template>
+      <p v-else class="text-sm text-muted-foreground">
+        {{ hub.status.value === 'trashed' ? 'Trash is empty' : 'No annotations yet. Highlights you create on the web or your e-reader appear here.' }}
+      </p>
+    </div>
+    <div v-else class="transition-opacity" :class="{ 'opacity-50 pointer-events-none': hub.loading.value }">
+      <div v-if="isGrouped" class="flex flex-col gap-4">
+        <AnnotationBookGroup
+          v-for="group in groupedByBook"
+          :key="group.bookId"
+          :book-id="group.bookId"
+          :book-title="group.bookTitle"
+          :author="group.author"
+          :items="group.items"
+          :selected-ids="hub.selectedIds.value"
+          :saving-ids="hub.savingIds.value"
+          :trashed="hub.status.value === 'trashed'"
+          :density="density"
+          @toggle-select="hub.toggleSelected"
+          @jump="handleJump"
+          @trash="handleTrash"
+          @restore="handleRestore"
+          @purge="handlePurge"
+          @update-note="hub.updateNote"
+          @update-color="hub.updateColor"
+          @update-style="hub.updateStyle"
+        />
+      </div>
+      <div v-else class="flex flex-col gap-2">
+        <AnnotationCard
+          v-for="annotation in hub.items.value"
+          :key="annotation.id"
+          :annotation="annotation"
+          :selected="hub.selectedIds.value.has(annotation.id)"
+          :saving="hub.savingIds.value.has(annotation.id)"
+          :trashed="hub.status.value === 'trashed'"
+          :density="density"
+          @toggleSelect="hub.toggleSelected"
+          @jump="handleJump"
+          @trash="handleTrash"
+          @restore="handleRestore"
+          @purge="handlePurge"
+          @update-note="hub.updateNote"
+          @update-color="hub.updateColor"
+          @update-style="hub.updateStyle"
+        />
+      </div>
+    </div>
+
+    <AnnotationPagination
+      v-if="hub.total.value > 0"
+      :page="hub.page.value"
+      :total-pages="hub.totalPages.value"
+      :range-start="hub.rangeStart.value"
+      :range-end="hub.rangeEnd.value"
+      :total="hub.total.value"
+      @update:page="handleSetPage"
+    />
+  </div>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/AddSessionDialog.vue b/client/src/features/book/components/detail/tabs/AddSessionDialog.vue
new file mode 100644
index 000000000..6413ce1a6
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/AddSessionDialog.vue
@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { X } from '@lucide/vue'
+
+const props = defineProps<{
+  open: boolean
+  formats: string[]
+  saving: boolean
+  error: string | null
+}>()
+
+const emit = defineEmits<{
+  close: []
+  submit: [payload: { startedAt: string; durationMinutes: number; endProgress?: number; format?: string }]
+}>()
+
+const startedAt = ref('')
+const durationMinutes = ref(30)
+const endProgress = ref<number | null>(null)
+const format = ref('')
+const localError = ref<string | null>(null)
+
+function toLocalInputValue(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+const maxStartedAt = computed(() => toLocalInputValue(new Date()))
+
+watch(
+  () => props.open,
+  (open) => {
+    if (!open) return
+    const now = new Date()
+    now.setMinutes(now.getMinutes() - (now.getMinutes() % 5), 0, 0)
+    startedAt.value = toLocalInputValue(now)
+    durationMinutes.value = 30
+    endProgress.value = null
+    format.value = ''
+    localError.value = null
+  },
+)
+
+function handleClose() {
+  if (props.saving) return
+  emit('close')
+}
+
+function handleSubmit() {
+  localError.value = null
+  const parsed = new Date(startedAt.value)
+  if (!startedAt.value || Number.isNaN(parsed.getTime())) {
+    localError.value = 'Pick a valid date and time.'
+    return
+  }
+  if (parsed.getTime() > Date.now()) {
+    localError.value = 'The session cannot start in the future.'
+    return
+  }
+  if (!Number.isInteger(durationMinutes.value) || durationMinutes.value < 1 || durationMinutes.value > 1440) {
+    localError.value = 'Duration must be between 1 and 1440 minutes.'
+    return
+  }
+  if (endProgress.value != null && (endProgress.value < 0 || endProgress.value > 100)) {
+    localError.value = 'End progress must be between 0 and 100.'
+    return
+  }
+  emit('submit', {
+    startedAt: parsed.toISOString(),
+    durationMinutes: durationMinutes.value,
+    ...(endProgress.value != null ? { endProgress: endProgress.value } : {}),
+    ...(format.value ? { format: format.value } : {}),
+  })
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="open" class="fixed inset-0 z-50 flex items-center justify-center">
+      <div class="absolute inset-0 bg-black/40 backdrop-blur-sm" @click="handleClose" />
+      <div class="relative z-10 w-full max-w-md mx-4 bg-card border border-border rounded-lg shadow-2xl p-6">
+        <div class="flex items-center justify-between mb-5">
+          <h2 class="text-base font-semibold text-foreground">Add reading session</h2>
+          <button class="text-muted-foreground hover:text-foreground transition-colors" @click="handleClose">
+            <X :size="18" />
+          </button>
+        </div>
+
+        <form class="flex flex-col gap-4" @submit.prevent="handleSubmit">
+          <div class="flex flex-col gap-1.5">
+            <label class="text-sm font-medium text-foreground">Started at</label>
+            <input
+              v-model="startedAt"
+              type="datetime-local"
+              :max="maxStartedAt"
+              class="h-9 rounded-md border border-input bg-background text-foreground text-sm px-3 focus:outline-none focus:ring-2 focus:ring-primary"
+            />
+          </div>
+
+          <div class="grid grid-cols-2 gap-3">
+            <div class="flex flex-col gap-1.5">
+              <label class="text-sm font-medium text-foreground">Duration (minutes)</label>
+              <input
+                v-model.number="durationMinutes"
+                type="number"
+                min="1"
+                max="1440"
+                class="h-9 rounded-md border border-input bg-background text-foreground text-sm px-3 focus:outline-none focus:ring-2 focus:ring-primary"
+              />
+            </div>
+            <div class="flex flex-col gap-1.5">
+              <label class="text-sm font-medium text-foreground">End progress %</label>
+              <input
+                v-model.number="endProgress"
+                type="number"
+                min="0"
+                max="100"
+                step="0.1"
+                placeholder="Optional"
+                class="h-9 rounded-md border border-input bg-background text-foreground text-sm px-3 focus:outline-none focus:ring-2 focus:ring-primary placeholder:text-muted-foreground"
+              />
+            </div>
+          </div>
+
+          <div v-if="formats.length >= 2" class="flex flex-col gap-1.5">
+            <label class="text-sm font-medium text-foreground">Format</label>
+            <select
+              v-model="format"
+              class="h-9 rounded-md border border-input bg-background text-foreground text-sm px-3 focus:outline-none focus:ring-2 focus:ring-primary"
+            >
+              <option value="">No specific format</option>
+              <option v-for="fmt in formats" :key="fmt" :value="fmt">{{ fmt.toUpperCase() }}</option>
+            </select>
+          </div>
+
+          <p v-if="localError || error" class="text-sm text-destructive">{{ localError ?? error }}</p>
+
+          <div class="flex justify-end gap-2 mt-1">
+            <button
+              type="button"
+              class="h-9 px-4 rounded-md border border-input bg-background text-sm text-foreground hover:bg-muted transition-colors"
+              @click="handleClose"
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              :disabled="saving"
+              class="h-9 px-4 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary/90 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              {{ saving ? 'Saving...' : 'Add session' }}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  </Teleport>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/HighlightCard.vue b/client/src/features/book/components/detail/tabs/HighlightCard.vue
index 1d67dc4dd..b805840de 100644
--- a/client/src/features/book/components/detail/tabs/HighlightCard.vue
+++ b/client/src/features/book/components/detail/tabs/HighlightCard.vue
@@ -1,187 +1,44 @@
 <script setup lang="ts">
-import { onUnmounted, ref } from 'vue'
-import { Copy, FileEdit, Palette, Trash2, X, Check } from '@lucide/vue'
 import type { AnnotationItem } from '@bookorbit/types'
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
-import { copyToClipboard } from '@/lib/clipboard'
-import HighlightNoteEditor from './HighlightNoteEditor.vue'
+import AnnotationListItem from '@/features/annotations/components/AnnotationListItem.vue'
 
-const props = defineProps<{
+defineProps<{
   highlight: AnnotationItem
 }>()
 
 const emit = defineEmits<{
   updateNote: [id: number, note: string | null]
   updateColor: [id: number, color: string]
+  updateStyle: [id: number, style: string]
   delete: [id: number]
 }>()
 
-const COLORS = [
-  { hex: '#FACC15', label: 'Yellow' },
-  { hex: '#4ADE80', label: 'Green' },
-  { hex: '#38BDF8', label: 'Blue' },
-  { hex: '#F472B6', label: 'Pink' },
-  { hex: '#FB923C', label: 'Orange' },
-]
-
-const editingNote = ref(false)
-const showColorPicker = ref(false)
-const confirmDelete = ref(false)
-const copied = ref(false)
-let copiedTimer: ReturnType<typeof setTimeout> | null = null
-
-onUnmounted(() => {
-  if (copiedTimer) clearTimeout(copiedTimer)
-})
-
-async function handleCopy() {
-  const didCopy = await copyToClipboard(props.highlight.text)
-  if (!didCopy) return
-
-  copied.value = true
-  if (copiedTimer) clearTimeout(copiedTimer)
-  copiedTimer = setTimeout(() => {
-    copied.value = false
-    copiedTimer = null
-  }, 1500)
+function handleUpdateNote(id: number, note: string | null) {
+  emit('updateNote', id, note)
 }
 
-function handleNoteSave(note: string | null) {
-  emit('updateNote', props.highlight.id, note)
-  editingNote.value = false
+function handleUpdateColor(id: number, color: string) {
+  emit('updateColor', id, color)
 }
 
-function handleNoteCancel() {
-  editingNote.value = false
+function handleUpdateStyle(id: number, style: string) {
+  emit('updateStyle', id, style)
 }
 
-function handleColorSelect(color: string) {
-  if (color !== props.highlight.color) {
-    emit('updateColor', props.highlight.id, color)
-  }
-  showColorPicker.value = false
-}
-
-function handleDeleteClick() {
-  if (confirmDelete.value) {
-    emit('delete', props.highlight.id)
-    confirmDelete.value = false
-  } else {
-    confirmDelete.value = true
-  }
-}
-
-function handleCancelDelete() {
-  confirmDelete.value = false
-}
-
-function toggleNoteEditor() {
-  editingNote.value = !editingNote.value
-}
-
-function toggleColorPicker() {
-  showColorPicker.value = !showColorPicker.value
+function handleTrash(id: number) {
+  emit('delete', id)
 }
 </script>
 
 <template>
-  <div class="rounded-lg border border-border bg-card overflow-hidden transition-colors hover:border-border/80">
-    <div class="flex">
-      <div class="w-1 shrink-0" :style="{ backgroundColor: highlight.color }" />
-      <div class="flex-1 min-w-0 p-3 sm:p-4">
-        <p class="text-sm leading-relaxed text-foreground">{{ highlight.text }}</p>
-
-        <p v-if="highlight.note && !editingNote" class="mt-2 text-xs text-muted-foreground italic border-l-2 border-muted pl-2">
-          {{ highlight.note }}
-        </p>
-
-        <HighlightNoteEditor v-if="editingNote" :initial-note="highlight.note" @save="handleNoteSave" @cancel="handleNoteCancel" />
-
-        <div v-if="showColorPicker" class="mt-2 flex items-center gap-1.5">
-          <button
-            v-for="c in COLORS"
-            :key="c.hex"
-            class="w-6 h-6 rounded-full border-2 transition-all hover:scale-110"
-            :class="highlight.color === c.hex ? 'border-foreground scale-110' : 'border-transparent'"
-            :style="{ background: c.hex }"
-            :title="c.label"
-            @click="() => handleColorSelect(c.hex)"
-          />
-        </div>
-
-        <div class="mt-2 flex items-center justify-between">
-          <span class="text-[11px] text-muted-foreground">
-            {{ new Date(highlight.createdAt).toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' }) }}
-          </span>
-
-          <div class="flex items-center gap-0.5">
-            <Tooltip>
-              <TooltipTrigger as-child>
-                <button
-                  class="inline-flex items-center justify-center w-7 h-7 rounded text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-                  @click="toggleNoteEditor"
-                >
-                  <FileEdit :size="14" />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent>{{ highlight.note ? 'Edit note' : 'Add note' }}</TooltipContent>
-            </Tooltip>
-
-            <Tooltip>
-              <TooltipTrigger as-child>
-                <button
-                  class="inline-flex items-center justify-center w-7 h-7 rounded transition-colors"
-                  :class="showColorPicker ? 'text-foreground bg-muted' : 'text-muted-foreground hover:text-foreground hover:bg-muted'"
-                  @click="toggleColorPicker"
-                >
-                  <Palette :size="14" />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent>Change color</TooltipContent>
-            </Tooltip>
-
-            <Tooltip>
-              <TooltipTrigger as-child>
-                <button
-                  class="inline-flex items-center justify-center w-7 h-7 rounded text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-                  @click="handleCopy"
-                >
-                  <Check v-if="copied" :size="14" class="text-green-500" />
-                  <Copy v-else :size="14" />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent>{{ copied ? 'Copied!' : 'Copy text' }}</TooltipContent>
-            </Tooltip>
-
-            <template v-if="confirmDelete">
-              <button
-                class="inline-flex items-center justify-center w-7 h-7 rounded text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-                title="Cancel"
-                @click="handleCancelDelete"
-              >
-                <X :size="14" />
-              </button>
-              <button
-                class="inline-flex h-7 items-center justify-center rounded px-2 text-xs font-medium uppercase tracking-wide transition-colors bg-destructive/15 text-destructive ring-1 ring-destructive/40"
-                @click="handleDeleteClick"
-              >
-                Confirm
-              </button>
-            </template>
-            <Tooltip v-else>
-              <TooltipTrigger as-child>
-                <button
-                  class="inline-flex items-center justify-center w-7 h-7 rounded text-muted-foreground hover:text-destructive hover:bg-muted transition-colors"
-                  @click="handleDeleteClick"
-                >
-                  <Trash2 :size="14" />
-                </button>
-              </TooltipTrigger>
-              <TooltipContent>Delete</TooltipContent>
-            </Tooltip>
-          </div>
-        </div>
-      </div>
-    </div>
-  </div>
+  <AnnotationListItem
+    :annotation="highlight"
+    :selectable="false"
+    mode="book"
+    density="comfortable"
+    @update-note="handleUpdateNote"
+    @update-color="handleUpdateColor"
+    @update-style="handleUpdateStyle"
+    @trash="handleTrash"
+  />
 </template>
diff --git a/client/src/features/book/components/detail/tabs/HighlightChapterGroup.vue b/client/src/features/book/components/detail/tabs/HighlightChapterGroup.vue
index fd22e01fb..e3cbbb467 100644
--- a/client/src/features/book/components/detail/tabs/HighlightChapterGroup.vue
+++ b/client/src/features/book/components/detail/tabs/HighlightChapterGroup.vue
@@ -1,18 +1,24 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { ChevronDown, ChevronRight } from '@lucide/vue'
-import type { AnnotationItem } from '@bookorbit/types'
-import HighlightCard from './HighlightCard.vue'
+import type { AnnotationHubItem, AnnotationItem } from '@bookorbit/types'
+import AnnotationListItem from '@/features/annotations/components/AnnotationListItem.vue'
 
 defineProps<{
   chapterTitle: string
   highlights: AnnotationItem[]
+  selectedIds: Set<number>
+  density: 'compact' | 'comfortable'
+  savingIds: Set<number>
 }>()
 
 const emit = defineEmits<{
+  toggleSelect: [id: number]
+  jump: [annotation: AnnotationItem]
   updateNote: [id: number, note: string | null]
   updateColor: [id: number, color: string]
-  delete: [id: number]
+  updateStyle: [id: number, style: string]
+  trash: [id: number]
 }>()
 
 const expanded = ref(true)
@@ -20,25 +26,59 @@ const expanded = ref(true)
 function toggleExpanded() {
   expanded.value = !expanded.value
 }
+
+function handleToggleSelect(id: number) {
+  emit('toggleSelect', id)
+}
+
+function handleJump(annotation: AnnotationItem | AnnotationHubItem) {
+  emit('jump', annotation as AnnotationItem)
+}
+
+function handleUpdateNote(id: number, note: string | null) {
+  emit('updateNote', id, note)
+}
+
+function handleUpdateColor(id: number, color: string) {
+  emit('updateColor', id, color)
+}
+
+function handleUpdateStyle(id: number, style: string) {
+  emit('updateStyle', id, style)
+}
+
+function handleTrash(id: number) {
+  emit('trash', id)
+}
 </script>
 
 <template>
   <div>
-    <button class="flex items-center gap-2 w-full text-left py-2 px-1 rounded-md hover:bg-muted/50 transition-colors group" @click="toggleExpanded">
+    <button
+      class="sticky top-0 z-10 flex w-full items-center gap-2 rounded-md bg-background/95 px-1 py-2 text-left transition-colors hover:bg-muted/50"
+      @click="toggleExpanded"
+    >
       <ChevronDown v-if="expanded" :size="16" class="text-muted-foreground shrink-0" />
       <ChevronRight v-else :size="16" class="text-muted-foreground shrink-0" />
-      <span class="text-sm font-medium text-foreground truncate">{{ chapterTitle }}</span>
+      <span class="truncate text-sm font-medium text-foreground">{{ chapterTitle }}</span>
       <span class="text-xs text-muted-foreground shrink-0">({{ highlights.length }})</span>
     </button>
 
-    <div v-if="expanded" class="space-y-2 ml-6 mt-1">
-      <HighlightCard
+    <div v-if="expanded" class="mt-1 space-y-2 md:ml-6">
+      <AnnotationListItem
         v-for="h in highlights"
         :key="h.id"
-        :highlight="h"
-        @update-note="(id, note) => emit('updateNote', id, note)"
-        @update-color="(id, color) => emit('updateColor', id, color)"
-        @delete="(id) => emit('delete', id)"
+        :annotation="h"
+        :selected="selectedIds.has(h.id)"
+        :density="density"
+        :saving="savingIds.has(h.id)"
+        mode="book"
+        @toggle-select="handleToggleSelect"
+        @jump="handleJump"
+        @update-note="handleUpdateNote"
+        @update-color="handleUpdateColor"
+        @update-style="handleUpdateStyle"
+        @trash="handleTrash"
       />
     </div>
   </div>
diff --git a/client/src/features/book/components/detail/tabs/HighlightNoteEditor.vue b/client/src/features/book/components/detail/tabs/HighlightNoteEditor.vue
index 7a398a40e..056b226ad 100644
--- a/client/src/features/book/components/detail/tabs/HighlightNoteEditor.vue
+++ b/client/src/features/book/components/detail/tabs/HighlightNoteEditor.vue
@@ -2,9 +2,13 @@
 import { ref } from 'vue'
 import { Save, X } from '@lucide/vue'
 
-const props = defineProps<{
-  initialNote: string | null
-}>()
+const props = withDefaults(
+  defineProps<{
+    initialNote: string | null
+    saving?: boolean
+  }>(),
+  { saving: false },
+)
 
 const emit = defineEmits<{
   save: [note: string | null]
@@ -14,9 +18,15 @@ const emit = defineEmits<{
 const noteText = ref(props.initialNote ?? '')
 
 function handleSave() {
+  if (props.saving) return
   const trimmed = noteText.value.trim()
   emit('save', trimmed || null)
 }
+
+function handleCancel() {
+  if (props.saving) return
+  emit('cancel')
+}
 </script>
 
 <template>
@@ -25,22 +35,27 @@ function handleSave() {
       v-model="noteText"
       placeholder="Add a note..."
       rows="3"
+      :disabled="saving"
       class="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-primary resize-y"
     />
     <div class="flex items-center gap-2 justify-end">
       <button
+        type="button"
         class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm border border-border bg-card text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-        @click="emit('cancel')"
+        :disabled="saving"
+        @click="handleCancel"
       >
         <X :size="14" />
         Cancel
       </button>
       <button
+        type="button"
         class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
+        :disabled="saving"
         @click="handleSave"
       >
         <Save :size="14" />
-        Save
+        {{ saving ? 'Saving' : 'Save' }}
       </button>
     </div>
   </div>
diff --git a/client/src/features/book/components/detail/tabs/HighlightsExportMenu.vue b/client/src/features/book/components/detail/tabs/HighlightsExportMenu.vue
index f3700b958..e0da6ef72 100644
--- a/client/src/features/book/components/detail/tabs/HighlightsExportMenu.vue
+++ b/client/src/features/book/components/detail/tabs/HighlightsExportMenu.vue
@@ -2,18 +2,19 @@
 import { ref } from 'vue'
 import { Download, FileText, FileJson, FileType } from '@lucide/vue'
 import type { AnnotationItem } from '@bookorbit/types'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 
-const props = defineProps<{
-  items: AnnotationItem[]
-  bookTitle: string
-}>()
+const props = withDefaults(
+  defineProps<{
+    items: AnnotationItem[]
+    bookTitle: string
+    label?: string
+  }>(),
+  { label: 'Export' },
+)
 
 const open = ref(false)
 
-function toggleMenu() {
-  open.value = !open.value
-}
-
 function closeMenu() {
   open.value = false
 }
@@ -100,33 +101,35 @@ function exportJson() {
 </script>
 
 <template>
-  <div class="relative">
-    <button
-      class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm border border-border bg-card text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-      :disabled="items.length === 0"
-      @click="toggleMenu"
-    >
-      <Download :size="14" />
-      Export
-    </button>
-
-    <Teleport to="body">
-      <div v-if="open" class="fixed inset-0 z-40" @click="closeMenu" />
-    </Teleport>
-
-    <div v-if="open" class="absolute right-0 bottom-full mb-1 z-50 w-44 rounded-md border border-border bg-card shadow-lg py-1">
-      <button class="flex items-center gap-2 w-full px-3 py-2 text-sm text-foreground hover:bg-muted transition-colors" @click="exportMarkdown">
+  <Popover v-model:open="open">
+    <PopoverTrigger as-child>
+      <button
+        class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm border border-border bg-card text-muted-foreground hover:text-foreground hover:bg-muted transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+        :disabled="items.length === 0"
+      >
+        <Download :size="14" />
+        {{ label }}
+      </button>
+    </PopoverTrigger>
+    <PopoverContent align="end" class="w-44 p-1">
+      <button
+        class="flex items-center gap-2 w-full px-3 py-2 rounded text-sm text-foreground hover:bg-muted transition-colors"
+        @click="exportMarkdown"
+      >
         <FileText :size="14" class="text-muted-foreground" />
         Markdown
       </button>
-      <button class="flex items-center gap-2 w-full px-3 py-2 text-sm text-foreground hover:bg-muted transition-colors" @click="exportPlainText">
+      <button
+        class="flex items-center gap-2 w-full px-3 py-2 rounded text-sm text-foreground hover:bg-muted transition-colors"
+        @click="exportPlainText"
+      >
         <FileType :size="14" class="text-muted-foreground" />
         Plain Text
       </button>
-      <button class="flex items-center gap-2 w-full px-3 py-2 text-sm text-foreground hover:bg-muted transition-colors" @click="exportJson">
+      <button class="flex items-center gap-2 w-full px-3 py-2 rounded text-sm text-foreground hover:bg-muted transition-colors" @click="exportJson">
         <FileJson :size="14" class="text-muted-foreground" />
         JSON
       </button>
-    </div>
-  </div>
+    </PopoverContent>
+  </Popover>
 </template>
diff --git a/client/src/features/book/components/detail/tabs/HighlightsFilterBar.vue b/client/src/features/book/components/detail/tabs/HighlightsFilterBar.vue
deleted file mode 100644
index b6c01c11c..000000000
--- a/client/src/features/book/components/detail/tabs/HighlightsFilterBar.vue
+++ /dev/null
@@ -1,126 +0,0 @@
-<script setup lang="ts">
-import { ref, watch } from 'vue'
-import { Search, X } from '@lucide/vue'
-
-const props = defineProps<{
-  activeColors: string[]
-  chapters: string[]
-  selectedChapter: string | undefined
-  dateFrom: string | undefined
-  dateTo: string | undefined
-}>()
-
-const emit = defineEmits<{
-  toggleColor: [color: string]
-  search: [query: string]
-  chapterChange: [chapter: string | undefined]
-  dateRangeChange: [from: string | undefined, to: string | undefined]
-}>()
-
-const COLORS = [
-  { hex: '#FACC15', label: 'Yellow' },
-  { hex: '#4ADE80', label: 'Green' },
-  { hex: '#38BDF8', label: 'Blue' },
-  { hex: '#F472B6', label: 'Pink' },
-  { hex: '#FB923C', label: 'Orange' },
-]
-
-const searchInput = ref('')
-let searchTimeout: ReturnType<typeof setTimeout> | null = null
-
-function handleSearchInput(e: Event) {
-  const value = (e.target as HTMLInputElement).value
-  searchInput.value = value
-  if (searchTimeout) clearTimeout(searchTimeout)
-  searchTimeout = setTimeout(() => emit('search', value), 300)
-}
-
-function clearSearch() {
-  searchInput.value = ''
-  if (searchTimeout) clearTimeout(searchTimeout)
-  emit('search', '')
-}
-
-function handleChapterChange(e: Event) {
-  const value = (e.target as HTMLSelectElement).value || undefined
-  emit('chapterChange', value)
-}
-
-function handleDateFromChange(e: Event) {
-  const value = (e.target as HTMLInputElement).value || undefined
-  emit('dateRangeChange', value, props.dateTo)
-}
-
-function handleDateToChange(e: Event) {
-  const value = (e.target as HTMLInputElement).value || undefined
-  emit('dateRangeChange', props.dateFrom, value)
-}
-
-watch(
-  () => props.activeColors,
-  () => {},
-  { deep: true },
-)
-</script>
-
-<template>
-  <div class="flex flex-col gap-2 sm:flex-row sm:flex-wrap sm:items-center">
-    <div class="relative sm:flex-1 sm:min-w-[140px]">
-      <Search :size="15" class="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground pointer-events-none" />
-      <input
-        type="text"
-        :value="searchInput"
-        placeholder="Search highlights..."
-        class="w-full h-9 pl-9 pr-8 rounded-md border border-border bg-card text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-primary"
-        @input="handleSearchInput"
-      />
-      <button v-if="searchInput" class="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground" @click="clearSearch">
-        <X :size="14" />
-      </button>
-    </div>
-
-    <div class="flex items-center gap-1.5 shrink-0">
-      <button
-        v-for="c in COLORS"
-        :key="c.hex"
-        class="w-7 h-7 rounded-full border-2 transition-all hover:scale-110"
-        :class="
-          activeColors.includes(c.hex) ? 'border-foreground scale-110 ring-1 ring-foreground/20' : 'border-transparent opacity-60 hover:opacity-100'
-        "
-        :style="{ background: c.hex }"
-        :title="c.label"
-        @click="emit('toggleColor', c.hex)"
-      />
-    </div>
-
-    <select
-      v-if="chapters.length > 0"
-      class="h-9 px-3 rounded-md text-sm border border-border bg-card text-foreground focus:outline-none focus:ring-1 focus:ring-primary w-full sm:w-auto sm:max-w-[160px] shrink-0"
-      :value="selectedChapter ?? ''"
-      @change="handleChapterChange"
-    >
-      <option value="">All chapters</option>
-      <option v-for="ch in chapters" :key="ch" :value="ch">{{ ch }}</option>
-    </select>
-
-    <div class="flex items-center gap-2 shrink-0">
-      <input
-        type="date"
-        class="h-9 px-2 rounded-md text-sm border border-border bg-card text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
-        :value="dateFrom ?? ''"
-        @change="handleDateFromChange"
-      />
-      <span class="text-xs text-muted-foreground">to</span>
-      <input
-        type="date"
-        class="h-9 px-2 rounded-md text-sm border border-border bg-card text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
-        :value="dateTo ?? ''"
-        @change="handleDateToChange"
-      />
-    </div>
-
-    <div class="flex items-center gap-2 shrink-0 sm:ml-auto">
-      <slot />
-    </div>
-  </div>
-</template>
diff --git a/client/src/features/book/components/detail/tabs/HighlightsTab.vue b/client/src/features/book/components/detail/tabs/HighlightsTab.vue
index 4a4903794..cfb55c60a 100644
--- a/client/src/features/book/components/detail/tabs/HighlightsTab.vue
+++ b/client/src/features/book/components/detail/tabs/HighlightsTab.vue
@@ -1,44 +1,37 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import { ArrowUpDown, Highlighter } from '@lucide/vue'
-import type { BookDetail } from '@bookorbit/types'
+import { useRouter } from 'vue-router'
+import { Highlighter, RotateCcw, Trash2 } from '@lucide/vue'
+import type { AnnotationItem, BookDetail } from '@bookorbit/types'
+import { Button } from '@/components/ui/button'
+import AnnotationListItem from '@/features/annotations/components/AnnotationListItem.vue'
+import AnnotationToolbar from '@/features/annotations/components/AnnotationToolbar.vue'
+import AnnotationFiltersPanel from '@/features/annotations/components/AnnotationFiltersPanel.vue'
+import AnnotationSummaryBar from '@/features/annotations/components/AnnotationSummaryBar.vue'
+import AnnotationBulkBar from '@/features/annotations/components/AnnotationBulkBar.vue'
+import AnnotationPagination from '@/features/annotations/components/AnnotationPagination.vue'
+import { sourcePill } from '@/features/annotations/lib/pill-styles'
 import { useBookHighlights } from '@/features/book/composables/useBookHighlights'
-import HighlightsFilterBar from './HighlightsFilterBar.vue'
+import { useDensity } from '@/features/annotations/composables/useDensity'
 import HighlightChapterGroup from './HighlightChapterGroup.vue'
-import HighlightCard from './HighlightCard.vue'
 import HighlightsExportMenu from './HighlightsExportMenu.vue'
 
 const props = defineProps<{ book: BookDetail }>()
 
+const router = useRouter()
 const bookIdRef = computed(() => props.book.id)
-const {
-  items,
-  total,
-  loading,
-  error,
-  page,
-  pageSize,
-  sortBy,
-  sortDir,
-  colors: activeColors,
-  chapter: selectedChapter,
-  dateFrom,
-  dateTo,
-  chapters,
-  updateNote,
-  updateColor,
-  deleteHighlight,
-  setPage,
-  setSort,
-  toggleColor,
-  setSearch,
-  setChapter,
-  setDateRange,
-} = useBookHighlights(bookIdRef)
+const hl = useBookHighlights(bookIdRef)
+const { density } = useDensity()
+
+const SORT_OPTIONS = [
+  { value: 'position', label: 'Position' },
+  { value: 'newest', label: 'Newest first' },
+  { value: 'oldest', label: 'Oldest first' },
+]
 
 const groupedHighlights = computed(() => {
-  const groups = new Map<string, typeof items.value>()
-  for (const item of items.value) {
+  const groups = new Map<string, AnnotationItem[]>()
+  for (const item of hl.items.value) {
     const key = item.chapterTitle ?? ''
     if (!groups.has(key)) groups.set(key, [])
     groups.get(key)!.push(item)
@@ -52,94 +45,136 @@ const hasChapterGroups = computed(() => {
   return true
 })
 
-const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)))
-const startItem = computed(() => Math.min((page.value - 1) * pageSize.value + 1, total.value))
-const endItem = computed(() => Math.min(page.value * pageSize.value, total.value))
-
-const sortLabel = computed(() => {
-  if (sortBy.value === 'position') return 'Position'
-  return sortDir.value === 'desc' ? 'Newest' : 'Oldest'
+const summaryTexts = computed(() => {
+  const texts = [`${hl.total.value} ${hl.total.value === 1 ? 'highlight' : 'highlights'}`]
+  if (hl.stats.value) {
+    texts.push(`${hl.stats.value.highlightsWithNotes} notes`)
+    texts.push(`${hl.stats.value.chaptersWithHighlights} chapters`)
+  }
+  return texts
 })
 
-function handleToggleSort() {
-  if (sortBy.value === 'position') {
-    setSort('createdAt', 'desc')
-  } else if (sortDir.value === 'desc') {
-    setSort('createdAt', 'asc')
-  } else {
-    setSort('position', 'asc')
-  }
+const originSummary = computed(() =>
+  (hl.stats.value?.originBreakdown ?? [])
+    .filter((entry) => entry.count > 0)
+    .map((entry) => ({ origin: entry.origin, ...sourcePill(entry.origin), count: entry.count })),
+)
+
+function handleJump(annotation: AnnotationItem) {
+  if (!annotation.jumpFileId) return
+  const query: Record<string, string> = {}
+  const file = props.book.files.find((bookFile) => bookFile.id === annotation.jumpFileId)
+  if (file?.format) query.format = file.format
+  if (annotation.cfi) query.cfi = annotation.cfi
+  else if (annotation.pageno != null) query.page = String(annotation.pageno)
+  void router.push({ name: 'reader', params: { bookId: annotation.bookId, fileId: annotation.jumpFileId }, query })
 }
 
-async function handleUpdateNote(id: number, note: string | null) {
-  await updateNote(id, note)
-}
-
-async function handleUpdateColor(id: number, color: string) {
-  await updateColor(id, color)
+function handleSetPage(page: number) {
+  hl.page.value = page
 }
 
 async function handleDelete(id: number) {
-  await deleteHighlight(id)
+  await hl.deleteHighlight(id)
 }
 
-function handlePrevPage() {
-  setPage(page.value - 1)
+async function handleBulkColor(color: string) {
+  const affected = await hl.bulkRestyle([...hl.selectedIds.value], { color })
+  if (affected > 0) hl.clearSelection()
 }
 
-function handleNextPage() {
-  setPage(page.value + 1)
+async function handleBulkStyle(style: string) {
+  const affected = await hl.bulkRestyle([...hl.selectedIds.value], { style })
+  if (affected > 0) hl.clearSelection()
 }
 
-function handleSearchChange(query: string) {
-  setSearch(query)
-}
-
-function handleChapterChange(ch: string | undefined) {
-  setChapter(ch)
-}
-
-function handleDateRangeChange(from: string | undefined, to: string | undefined) {
-  setDateRange(from, to)
+async function handleBulkTrash() {
+  const affected = await hl.bulkTrash([...hl.selectedIds.value])
+  if (affected > 0) hl.clearSelection()
 }
 </script>
 
 <template>
-  <div class="space-y-5">
-    <div v-if="error" class="rounded-md border border-destructive bg-destructive/10 px-4 py-3 text-sm text-destructive">
-      {{ error }}
+  <div class="space-y-3">
+    <div v-if="hl.error.value" class="rounded-md border border-destructive bg-destructive/10 px-4 py-3 text-sm text-destructive">
+      {{ hl.error.value }}
     </div>
 
-    <HighlightsFilterBar
-      :active-colors="activeColors"
-      :chapters="chapters"
-      :selected-chapter="selectedChapter"
-      :date-from="dateFrom"
-      :date-to="dateTo"
-      @toggle-color="toggleColor"
-      @search="handleSearchChange"
-      @chapter-change="handleChapterChange"
-      @date-range-change="handleDateRangeChange"
+    <AnnotationToolbar
+      v-model:search="hl.search.value"
+      v-model:sort-key="hl.sortKey.value"
+      v-model:density="density"
+      :sort-options="SORT_OPTIONS"
+      :filter-count="hl.popoverFilterCount.value"
+      :chips="hl.activeFilterChips.value"
+      @remove-chip="hl.removeFilterChip"
+      @clear-filters="hl.clearPopoverFilters"
     >
-      <div class="flex items-center gap-2">
-        <button
-          class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm border border-border bg-card text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
-          @click="handleToggleSort"
+      <template #inline-filters>
+        <select
+          v-if="hl.chapters.value.length > 0"
+          v-model="hl.chapter.value"
+          aria-label="Filter by chapter"
+          class="h-9 max-w-[14rem] px-2 rounded-md border border-border bg-background text-sm"
         >
-          <ArrowUpDown :size="14" />
-          {{ sortLabel }}
-        </button>
-        <HighlightsExportMenu :items="items" :book-title="book.title ?? 'Untitled'" />
-      </div>
-    </HighlightsFilterBar>
+          <option value="">All chapters</option>
+          <option v-for="ch in hl.chapters.value" :key="ch" :value="ch">{{ ch }}</option>
+        </select>
+      </template>
+      <template #filters>
+        <AnnotationFiltersPanel
+          v-model:colors="hl.colors.value"
+          v-model:date-from="hl.dateFrom.value"
+          v-model:date-to="hl.dateTo.value"
+          @clear-all="hl.clearPopoverFilters"
+        />
+      </template>
+    </AnnotationToolbar>
 
-    <div class="transition-opacity" :class="{ 'opacity-50 pointer-events-none': loading && items.length > 0 }">
-      <div v-if="items.length === 0 && !loading" class="flex flex-col items-center justify-center py-16 gap-3">
+    <div v-if="hl.total.value > 0" class="flex flex-wrap items-center justify-between gap-2">
+      <AnnotationSummaryBar :texts="summaryTexts" :origins="originSummary" />
+      <HighlightsExportMenu :items="hl.items.value" :book-title="book.title ?? 'Untitled'" label="Export page" />
+    </div>
+
+    <AnnotationBulkBar
+      v-if="hl.hasSelection.value"
+      :count="hl.selectedIds.value.size"
+      :all-visible-selected="hl.allVisibleSelected.value"
+      show-restyle
+      @select-page="hl.selectAllOnPage"
+      @clear="hl.clearSelection"
+      @recolor="handleBulkColor"
+      @restyle="handleBulkStyle"
+    >
+      <template #trailing>
+        <HighlightsExportMenu :items="hl.selectedItems.value" :book-title="book.title ?? 'Untitled'" label="Export selected" />
+        <Button variant="destructive" size="sm" class="gap-1.5" @click="handleBulkTrash">
+          <Trash2 :size="14" />
+          Trash
+        </Button>
+      </template>
+    </AnnotationBulkBar>
+
+    <div class="transition-opacity" :class="{ 'opacity-50 pointer-events-none': hl.loading.value && hl.items.value.length > 0 }">
+      <div v-if="hl.items.value.length === 0 && !hl.loading.value" class="flex flex-col items-center justify-center py-16 gap-3">
         <div class="flex h-12 w-12 items-center justify-center rounded-full bg-muted">
           <Highlighter :size="20" class="text-muted-foreground/60" />
         </div>
-        <p class="text-sm text-muted-foreground">No highlights yet</p>
-        <p class="text-xs text-muted-foreground/70">Select text while reading to create highlights</p>
+        <template v-if="hl.hasActiveFilters.value">
+          <p class="text-sm text-muted-foreground">No highlights match your filters.</p>
+          <button
+            type="button"
+            class="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm text-foreground transition-colors hover:bg-muted"
+            @click="hl.resetAllFilters"
+          >
+            <RotateCcw :size="14" />
+            Reset filters
+          </button>
+        </template>
+        <template v-else>
+          <p class="text-sm text-muted-foreground">No highlights yet</p>
+          <p class="text-xs text-muted-foreground/70">Select text while reading to create highlights</p>
+        </template>
       </div>
 
       <div v-else class="space-y-4">
@@ -149,43 +184,46 @@ function handleDateRangeChange(from: string | undefined, to: string | undefined)
             :key="chapterTitle"
             :chapter-title="chapterTitle || 'Uncategorized'"
             :highlights="highlights"
-            @update-note="handleUpdateNote"
-            @update-color="handleUpdateColor"
-            @delete="handleDelete"
+            :selected-ids="hl.selectedIds.value"
+            :density="density"
+            :saving-ids="hl.savingIds.value"
+            @toggle-select="hl.toggleSelected"
+            @jump="handleJump"
+            @update-note="hl.updateNote"
+            @update-color="hl.updateColor"
+            @update-style="hl.updateStyle"
+            @trash="handleDelete"
           />
         </template>
         <template v-else>
-          <HighlightCard
-            v-for="h in items"
+          <AnnotationListItem
+            v-for="h in hl.items.value"
             :key="h.id"
-            :highlight="h"
-            @update-note="handleUpdateNote"
-            @update-color="handleUpdateColor"
-            @delete="handleDelete"
+            :annotation="h"
+            :selected="hl.selectedIds.value.has(h.id)"
+            :density="density"
+            :saving="hl.savingIds.value.has(h.id)"
+            mode="book"
+            @toggle-select="hl.toggleSelected"
+            @jump="handleJump"
+            @update-note="hl.updateNote"
+            @update-color="hl.updateColor"
+            @update-style="hl.updateStyle"
+            @trash="handleDelete"
           />
         </template>
       </div>
     </div>
 
-    <div v-if="total > 0" class="flex items-center justify-between text-sm text-muted-foreground">
-      <span>Showing {{ startItem }}-{{ endItem }} of {{ total }} highlights</span>
-      <div class="flex items-center gap-2">
-        <button
-          class="px-3 py-1.5 rounded border border-border bg-card hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed text-foreground text-sm"
-          :disabled="page <= 1"
-          @click="handlePrevPage"
-        >
-          Prev
-        </button>
-        <span class="text-xs">{{ page }} / {{ totalPages }}</span>
-        <button
-          class="px-3 py-1.5 rounded border border-border bg-card hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed text-foreground text-sm"
-          :disabled="page >= totalPages"
-          @click="handleNextPage"
-        >
-          Next
-        </button>
-      </div>
-    </div>
+    <AnnotationPagination
+      v-if="hl.total.value > 0"
+      :page="hl.page.value"
+      :total-pages="hl.totalPages.value"
+      :range-start="hl.rangeStart.value"
+      :range-end="hl.rangeEnd.value"
+      :total="hl.total.value"
+      unit="highlights"
+      @update:page="handleSetPage"
+    />
   </div>
 </template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogExportMenu.vue b/client/src/features/book/components/detail/tabs/ReadingLogExportMenu.vue
new file mode 100644
index 000000000..5b6ec7fa1
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/ReadingLogExportMenu.vue
@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Download, FileJson, FileSpreadsheet, Loader2 } from '@lucide/vue'
+import type { BookReadingSession } from '@bookorbit/types'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+
+const props = defineProps<{
+  bookTitle: string
+  total: number
+  exportAll: () => Promise<BookReadingSession[]>
+}>()
+
+const open = ref(false)
+const exporting = ref(false)
+
+function safeName(): string {
+  return props.bookTitle
+    .replace(/[^a-zA-Z0-9 ]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+}
+
+function downloadFile(content: string, filename: string, mimeType: string) {
+  const blob = new Blob([content], { type: mimeType })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  a.click()
+  URL.revokeObjectURL(url)
+}
+
+function csvEscape(value: string): string {
+  if (/[",\n]/.test(value)) return `"${value.replace(/"/g, '""')}"`
+  return value
+}
+
+function pacePercentPerHour(session: BookReadingSession): string {
+  if (session.progressDelta == null || session.durationSeconds === 0) return ''
+  return ((session.progressDelta / session.durationSeconds) * 3600).toFixed(2)
+}
+
+async function exportCsv() {
+  if (exporting.value) return
+  exporting.value = true
+  try {
+    const items = await props.exportAll()
+    const header = 'startedAt,endedAt,durationSeconds,progressDelta,endProgress,pacePercentPerHour,format,source'
+    const rows = items.map((s) =>
+      [
+        s.startedAt,
+        s.endedAt,
+        String(s.durationSeconds),
+        s.progressDelta != null ? String(s.progressDelta) : '',
+        s.endProgress != null ? String(s.endProgress) : '',
+        pacePercentPerHour(s),
+        s.format ?? '',
+        s.source ?? '',
+      ]
+        .map(csvEscape)
+        .join(','),
+    )
+    downloadFile([header, ...rows].join('\n'), `${safeName()}-reading-log.csv`, 'text/csv')
+    open.value = false
+  } finally {
+    exporting.value = false
+  }
+}
+
+async function exportJson() {
+  if (exporting.value) return
+  exporting.value = true
+  try {
+    const items = await props.exportAll()
+    const data = {
+      bookTitle: props.bookTitle,
+      exportedAt: new Date().toISOString(),
+      totalSessions: items.length,
+      sessions: items,
+    }
+    downloadFile(JSON.stringify(data, null, 2), `${safeName()}-reading-log.json`, 'application/json')
+    open.value = false
+  } finally {
+    exporting.value = false
+  }
+}
+</script>
+
+<template>
+  <Popover v-model:open="open">
+    <PopoverTrigger as-child>
+      <button
+        class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md text-sm border border-border bg-card text-muted-foreground hover:text-foreground hover:bg-muted transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+        :disabled="total === 0 || exporting"
+      >
+        <Loader2 v-if="exporting" :size="14" class="animate-spin" />
+        <Download v-else :size="14" />
+        Export
+      </button>
+    </PopoverTrigger>
+    <PopoverContent align="end" class="w-44 p-1">
+      <button
+        class="flex items-center gap-2 w-full px-3 py-2 rounded text-sm text-foreground hover:bg-muted transition-colors disabled:opacity-50"
+        :disabled="exporting"
+        @click="exportCsv"
+      >
+        <FileSpreadsheet :size="14" class="text-muted-foreground" />
+        CSV
+      </button>
+      <button
+        class="flex items-center gap-2 w-full px-3 py-2 rounded text-sm text-foreground hover:bg-muted transition-colors disabled:opacity-50"
+        :disabled="exporting"
+        @click="exportJson"
+      >
+        <FileJson :size="14" class="text-muted-foreground" />
+        JSON
+      </button>
+    </PopoverContent>
+  </Popover>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogHeatmap.vue b/client/src/features/book/components/detail/tabs/ReadingLogHeatmap.vue
new file mode 100644
index 000000000..ffed4c93e
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/ReadingLogHeatmap.vue
@@ -0,0 +1,185 @@
+<script setup lang="ts">
+import { computed, shallowRef, watchEffect } from 'vue'
+import VChart from 'vue-echarts'
+import { CalendarDays } from '@lucide/vue'
+import type { BookReadingSessionStats } from '@bookorbit/types'
+import { useThemeStore } from '@/stores/theme'
+import { buildHeatmapPalette } from '@/lib/heatmap-palette'
+
+const props = defineProps<{
+  stats: BookReadingSessionStats | null
+  loading: boolean
+  quickFilter: 'all' | 'last30' | 'last90' | 'thisYear'
+}>()
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const DAY_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const
+
+const themeStore = useThemeStore()
+const option = shallowRef({})
+
+function toUtcDayStart(date: Date): number {
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+}
+
+function parseDayKeyToUtcStart(dayKey: string): number | null {
+  const [yy, mm, dd] = dayKey.split('-').map(Number)
+  if (!yy || !mm || !dd) return null
+  return Date.UTC(yy, mm - 1, dd)
+}
+
+const todayUtcStart = computed(() => toUtcDayStart(new Date()))
+
+const consistencyWindowDays = computed(() => {
+  if (props.quickFilter === 'last30') return 30
+  if (props.quickFilter === 'last90') return 90
+  if (props.quickFilter === 'thisYear') {
+    const jan1 = Date.UTC(new Date().getUTCFullYear(), 0, 1)
+    return Math.floor((todayUtcStart.value - jan1) / DAY_MS) + 1
+  }
+  if (!props.stats?.firstSessionAt) return 0
+  const firstDay = toUtcDayStart(new Date(props.stats.firstSessionAt))
+  return Math.max(1, Math.floor((todayUtcStart.value - firstDay) / DAY_MS) + 1)
+})
+
+const activeDays = computed(() => {
+  if (consistencyWindowDays.value <= 0) return 0
+  const windowStart = todayUtcStart.value - (consistencyWindowDays.value - 1) * DAY_MS
+  let count = 0
+  for (const row of props.stats?.dailySummary ?? []) {
+    const dayStart = parseDayKeyToUtcStart(row.day)
+    if (dayStart == null) continue
+    if (dayStart < windowStart || dayStart > todayUtcStart.value) continue
+    if (row.totalMinutes > 0) count += 1
+  }
+  return count
+})
+
+const subtitle = computed(() => {
+  if (consistencyWindowDays.value <= 0) return ''
+  const ratio = Math.round((activeDays.value / consistencyWindowDays.value) * 100)
+  const dayWord = activeDays.value === 1 ? 'day' : 'days'
+  return `${activeDays.value} active ${dayWord} · ${ratio}% consistency`
+})
+
+const hasData = computed(() => (props.stats?.dailySummary ?? []).some((row) => row.totalMinutes > 0))
+
+function buildContributionPieces(scale: string[]) {
+  const b1 = 15
+  const b2 = 30
+  const b3 = 60
+  return [
+    { value: 0, label: '0m', color: scale[0] },
+    { gt: 0, lte: b1, label: `1-${b1}m`, color: scale[1] },
+    { gt: b1, lte: b2, label: `${b1 + 1}-${b2}m`, color: scale[2] },
+    { gt: b2, lte: b3, label: `${b2 + 1}-${b3}m`, color: scale[3] },
+    { gt: b3, label: `${b3}m+`, color: scale[4] },
+  ]
+}
+
+watchEffect(() => {
+  option.value = {}
+  if (!hasData.value) return
+
+  const palette = buildHeatmapPalette({ theme: themeStore.theme, profile: 'github' })
+  // Touching accent makes this effect re-run when the palette source changes.
+  void themeStore.accent
+
+  const rangeEnd = todayUtcStart.value
+  const rangeStart = rangeEnd - 364 * DAY_MS
+  const rangeStartKey = new Date(rangeStart).toISOString().slice(0, 10)
+  const rangeEndKey = new Date(rangeEnd).toISOString().slice(0, 10)
+
+  const byDay = new Map((props.stats?.dailySummary ?? []).map((row) => [row.day, row.totalMinutes]))
+  const values: Array<readonly [string, number]> = []
+  for (let cursor = rangeStart; cursor <= rangeEnd; cursor += DAY_MS) {
+    const day = new Date(cursor).toISOString().slice(0, 10)
+    values.push([day, byDay.get(day) ?? 0] as const)
+  }
+
+  option.value = {
+    tooltip: {
+      appendToBody: true,
+      backgroundColor: palette.tooltipBackground,
+      borderColor: palette.tooltipBorder,
+      borderWidth: 1,
+      textStyle: { color: palette.tooltipText, fontSize: 12 },
+      formatter: (params: { value: [string, number] }) => {
+        const [day, minutes] = params.value
+        return `${day}<br/><strong>${minutes}</strong> min`
+      },
+    },
+    visualMap: {
+      type: 'piecewise',
+      show: true,
+      calculable: false,
+      dimension: 1,
+      pieces: buildContributionPieces(palette.scale),
+      orient: 'horizontal',
+      left: 'center',
+      top: 0,
+      itemWidth: 9,
+      itemHeight: 9,
+      itemGap: 6,
+      textStyle: { color: palette.axisColor, fontSize: 10 },
+    },
+    calendar: {
+      top: 50,
+      left: 34,
+      right: 4,
+      bottom: 4,
+      cellSize: ['auto', 'auto'],
+      range: [rangeStartKey, rangeEndKey],
+      yearLabel: { show: false },
+      splitLine: { show: false },
+      monthLabel: {
+        show: true,
+        fontSize: 9,
+        color: palette.axisColor,
+        margin: 6,
+        nameMap: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
+      },
+      dayLabel: {
+        show: true,
+        firstDay: 1,
+        fontSize: 8,
+        color: palette.axisColor,
+        margin: 6,
+        nameMap: DAY_LABELS,
+      },
+      itemStyle: {
+        color: 'transparent',
+        borderWidth: 0.5,
+        borderColor: palette.borderColor,
+        borderRadius: 1,
+      },
+    },
+    series: [
+      {
+        type: 'heatmap',
+        coordinateSystem: 'calendar',
+        data: values,
+        emphasis: { disabled: true },
+      },
+    ],
+  }
+})
+</script>
+
+<template>
+  <div class="flex h-full flex-col rounded-lg border border-border bg-card p-3 sm:p-4">
+    <div class="mb-2 flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
+      <span class="flex items-center gap-2 text-sm font-medium text-foreground">
+        <CalendarDays class="size-4 text-muted-foreground" />
+        Activity
+      </span>
+      <span v-if="subtitle" class="text-xs text-muted-foreground">{{ subtitle }}</span>
+    </div>
+    <div v-if="hasData" class="relative min-h-0 flex-1 transition-opacity" :class="{ 'opacity-50': loading }" style="min-height: 220px">
+      <VChart :option autoresize class="absolute inset-0" />
+    </div>
+    <div v-else class="flex flex-1 items-center justify-center py-12 text-sm text-muted-foreground" style="min-height: 220px">
+      No reading activity in this window.
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogHero.vue b/client/src/features/book/components/detail/tabs/ReadingLogHero.vue
new file mode 100644
index 000000000..7573f3b7f
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/ReadingLogHero.vue
@@ -0,0 +1,431 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { Check, ChevronDown, Clock, Minus, Plus, TrendingDown, TrendingUp } from '@lucide/vue'
+import type { BookDetail, BookReadingSessionStats, ReadStatus, UserBookStatus } from '@bookorbit/types'
+import { isAudioFormat } from '@bookorbit/types'
+import { api } from '@/lib/api'
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@/components/ui/dropdown-menu'
+import { STATUS_COLORS, STATUS_ICONS, STATUS_OPTIONS, useBookStatus } from '@/features/book/composables/useBookStatus'
+import AchievementProgressRing from '@/features/achievements/components/AchievementProgressRing.vue'
+
+const props = defineProps<{
+  book: BookDetail
+  stats: BookReadingSessionStats | null
+  loading: boolean
+}>()
+
+const emit = defineEmits<{
+  saved: [readStatus: UserBookStatus]
+  addSession: []
+}>()
+
+const { setStatus, updateStatus } = useBookStatus()
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const DATE_KEY_RE = /^\d{4}-\d{2}-\d{2}$/
+
+function dateToDateKey(value: Date): string {
+  const year = value.getFullYear()
+  const month = String(value.getMonth() + 1).padStart(2, '0')
+  const day = String(value.getDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+function toDateInputValue(value: string | null | undefined): string {
+  if (!value) return ''
+  if (DATE_KEY_RE.test(value)) return value
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) return ''
+  return dateToDateKey(parsed)
+}
+
+function formatDisplayDate(dateKey: string): string {
+  if (!dateKey) return 'Not set'
+  const [year, month, day] = dateKey.split('-').map(Number)
+  const d = new Date(year!, month! - 1, day!)
+  return d.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
+}
+
+function formatDuration(seconds: number): string {
+  const h = Math.floor(seconds / 3600)
+  const m = Math.floor((seconds % 3600) / 60)
+  const s = Math.floor(seconds % 60)
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m`
+  return `${s}s`
+}
+
+function formatRelative(iso: string | null): string {
+  if (!iso) return '-'
+  const diff = Date.now() - new Date(iso).getTime()
+  const s = Math.floor(diff / 1000)
+  if (s < 60) return `${s}s ago`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ago`
+  const d = Math.floor(h / 24)
+  if (d < 30) return `${d}d ago`
+  const mo = Math.floor(d / 30)
+  if (mo < 12) return `${mo} month${mo === 1 ? '' : 's'} ago`
+  const yr = Math.floor(mo / 12)
+  return `${yr} year${yr === 1 ? '' : 's'} ago`
+}
+
+function formatSessionDate(iso: string | null): string {
+  if (!iso) return 'No sessions'
+  return new Date(iso).toLocaleString(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+const todayDateInput = computed(() => dateToDateKey(new Date()))
+
+const localReadStatus = ref<ReadStatus | null>(props.book.readStatus?.status ?? null)
+const savedDates = ref({ startedAt: '', finishedAt: '' })
+const draftDates = ref({ startedAt: '', finishedAt: '' })
+const activeDateField = ref<'startedAt' | 'finishedAt' | null>(null)
+const savingDates = ref(false)
+const datesError = ref<string | null>(null)
+
+function normalizeDates(readStatus: UserBookStatus | null | undefined) {
+  return {
+    startedAt: toDateInputValue(readStatus?.startedAt),
+    finishedAt: toDateInputValue(readStatus?.finishedAt),
+  }
+}
+
+watch(
+  () => props.book.readStatus,
+  (value) => {
+    activeDateField.value = null
+    localReadStatus.value = value?.status ?? null
+    const normalized = normalizeDates(value)
+    savedDates.value = normalized
+    draftDates.value = { ...normalized }
+    datesError.value = null
+  },
+  { immediate: true },
+)
+
+function validateDates(values: { startedAt: string; finishedAt: string }): string | null {
+  if (values.startedAt && values.startedAt > todayDateInput.value) return 'Start date cannot be in the future.'
+  if (values.finishedAt && values.finishedAt > todayDateInput.value) return 'Finish date cannot be in the future.'
+  if (values.startedAt && values.finishedAt && values.finishedAt < values.startedAt) return 'Finish date must be on or after the start date.'
+  return null
+}
+
+function applyReadStatusUpdate(updated: UserBookStatus) {
+  localReadStatus.value = updated.status
+  const normalized = normalizeDates(updated)
+  savedDates.value = normalized
+  draftDates.value = { ...normalized }
+  datesError.value = null
+  emit('saved', updated)
+}
+
+async function handleSetReadStatus(status: ReadStatus) {
+  const prev = localReadStatus.value
+  localReadStatus.value = status
+  try {
+    const updated = await setStatus(props.book.id, status)
+    applyReadStatusUpdate(updated)
+  } catch {
+    localReadStatus.value = prev
+  }
+}
+
+function startEditingDate(field: 'startedAt' | 'finishedAt') {
+  if (savingDates.value) return
+  draftDates.value = { ...savedDates.value }
+  activeDateField.value = field
+  datesError.value = null
+}
+
+function handleStartedClick() {
+  startEditingDate('startedAt')
+}
+
+function handleFinishedClick() {
+  startEditingDate('finishedAt')
+}
+
+async function saveDateField(field: 'startedAt' | 'finishedAt') {
+  if (activeDateField.value !== field || savingDates.value) return
+  const validationError = validateDates(draftDates.value)
+  datesError.value = validationError
+  if (validationError) return
+  if (draftDates.value[field] === savedDates.value[field]) {
+    activeDateField.value = null
+    return
+  }
+  savingDates.value = true
+  try {
+    const patch = field === 'startedAt' ? { startedAt: draftDates.value.startedAt || null } : { finishedAt: draftDates.value.finishedAt || null }
+    const updated = await updateStatus(props.book.id, patch)
+    applyReadStatusUpdate(updated)
+    activeDateField.value = null
+  } catch {
+    datesError.value = 'Failed to save reading dates.'
+  } finally {
+    savingDates.value = false
+  }
+}
+
+function cancelDateEdit(field: 'startedAt' | 'finishedAt') {
+  if (activeDateField.value !== field) return
+  activeDateField.value = null
+  draftDates.value[field] = savedDates.value[field]
+  datesError.value = null
+}
+
+function handleStartedSave() {
+  void saveDateField('startedAt')
+}
+
+function handleStartedCancel() {
+  cancelDateEdit('startedAt')
+}
+
+function handleFinishedSave() {
+  void saveDateField('finishedAt')
+}
+
+function handleFinishedCancel() {
+  cancelDateEdit('finishedAt')
+}
+
+const currentProgress = ref(0)
+const progressLoaded = ref(false)
+
+async function loadProgress() {
+  progressLoaded.value = false
+  const bookId = props.book.id
+  const hasAudio = props.book.files.some((f) => f.format != null && isAudioFormat(f.format))
+  try {
+    const [progressRes, audioRes] = await Promise.all([
+      api(`/api/v1/books/${bookId}/progress`).catch(() => null),
+      hasAudio ? api(`/api/v1/books/${bookId}/audio-progress`).catch(() => null) : Promise.resolve(null),
+    ])
+    if (bookId !== props.book.id) return
+
+    let max = 0
+    if (progressRes?.ok) {
+      const rows = (await progressRes.json()) as { fileId: number; percentage: number }[]
+      for (const row of rows) {
+        if (Number.isFinite(row.percentage)) max = Math.max(max, row.percentage)
+      }
+    }
+    if (audioRes?.ok) {
+      const data = (await audioRes.json()) as { percentage?: number } | null
+      if (data && Number.isFinite(data.percentage)) max = Math.max(max, data.percentage!)
+    }
+    currentProgress.value = Math.min(100, Math.max(0, max))
+  } catch {
+    currentProgress.value = 0
+  } finally {
+    progressLoaded.value = true
+  }
+}
+
+watch(() => props.book.id, loadProgress, { immediate: true })
+
+const progressLabel = computed(() => {
+  const value = currentProgress.value
+  if (value > 0 && value < 1) return '<1%'
+  if (value > 99 && value < 100) return '>99%'
+  return `${Math.round(value)}%`
+})
+
+const pacePercentPerHour = computed(() => {
+  const stats = props.stats
+  if (!stats || stats.paceProgressDelta <= 0 || stats.paceDurationSeconds <= 0) return null
+  return stats.paceProgressDelta / (stats.paceDurationSeconds / 3600)
+})
+
+const etaLabel = computed(() => {
+  const status = localReadStatus.value
+  if (status === 'read' || status === 'abandoned') return null
+  const pace = pacePercentPerHour.value
+  if (pace == null || !progressLoaded.value) return null
+  const remaining = 100 - currentProgress.value
+  if (remaining <= 0) return null
+  const totalMinutes = (remaining / pace) * 60
+  if (!Number.isFinite(totalMinutes) || totalMinutes <= 0) return null
+  if (totalMinutes > 99 * 60) return '99h+ to finish'
+  const rounded = Math.max(5, Math.round(totalMinutes / 5) * 5)
+  const h = Math.floor(rounded / 60)
+  const m = rounded % 60
+  if (h <= 0) return `~${m}m to finish`
+  if (m === 0) return `~${h}h to finish`
+  return `~${h}h ${m}m to finish`
+})
+
+function toUtcDayStart(date: Date): number {
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+}
+
+function toUtcDayKey(dayStartMs: number): string {
+  return new Date(dayStartMs).toISOString().slice(0, 10)
+}
+
+const momentum = computed(() => {
+  const summary = props.stats?.dailySummary ?? []
+  const map = new Map(summary.map((row) => [row.day, row.totalMinutes]))
+  const todayStart = toUtcDayStart(new Date())
+  let last7 = 0
+  let prev7 = 0
+  for (let offset = 0; offset < 7; offset += 1) {
+    last7 += map.get(toUtcDayKey(todayStart - offset * DAY_MS)) ?? 0
+    prev7 += map.get(toUtcDayKey(todayStart - (offset + 7) * DAY_MS)) ?? 0
+  }
+  if (last7 === 0 && prev7 === 0) return { direction: 'flat' as const, title: 'No activity in the last two weeks' }
+  if (prev7 <= 0) return { direction: 'up' as const, title: 'New activity this week' }
+  const pct = Math.round(((last7 - prev7) / prev7) * 100)
+  if (pct > 0) return { direction: 'up' as const, title: `+${pct}% vs previous 7 days` }
+  if (pct < 0) return { direction: 'down' as const, title: `${pct}% vs previous 7 days` }
+  return { direction: 'flat' as const, title: 'Unchanged vs previous 7 days' }
+})
+
+const statCells = computed(() => [
+  { label: 'Total Time', value: props.stats ? formatDuration(props.stats.totalSeconds) : '0s', withMomentum: true },
+  { label: 'Sessions', value: String(props.stats?.totalSessions ?? 0), withMomentum: false },
+  { label: 'Avg Session', value: props.stats ? formatDuration(props.stats.avgDurationSeconds) : '0s', withMomentum: false },
+  { label: 'Last Read', value: props.stats ? formatRelative(props.stats.lastSessionAt) : '-', withMomentum: false },
+])
+
+const currentStatusOption = computed(() => STATUS_OPTIONS.find((o) => o.value === (localReadStatus.value ?? 'unread')))
+const firstReadLabel = computed(() => formatSessionDate(props.stats?.firstSessionAt ?? null))
+const lastReadLabel = computed(() => formatSessionDate(props.stats?.lastSessionAt ?? null))
+
+function handleAddSession() {
+  emit('addSession')
+}
+</script>
+
+<template>
+  <div class="rounded-lg border border-border bg-card p-4 sm:p-5">
+    <div class="flex flex-col gap-5 lg:flex-row lg:items-center lg:gap-8">
+      <div class="flex items-center gap-4">
+        <div class="relative shrink-0">
+          <AchievementProgressRing :percent="currentProgress" color="text-primary" :size="76" />
+          <span class="absolute inset-0 flex items-center justify-center text-sm font-semibold text-foreground">
+            {{ progressLoaded ? progressLabel : '' }}
+          </span>
+        </div>
+
+        <div class="flex min-w-0 flex-col gap-1">
+          <DropdownMenu>
+            <DropdownMenuTrigger as-child>
+              <button class="flex w-fit items-center gap-1.5 rounded-md text-sm font-medium text-foreground hover:text-primary transition-colors">
+                <component :is="STATUS_ICONS[localReadStatus ?? 'unread']" class="size-4" :class="STATUS_COLORS[localReadStatus ?? 'unread']" />
+                {{ currentStatusOption?.label }}
+                <ChevronDown class="size-3.5 opacity-60" />
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="start">
+              <DropdownMenuItem v-for="opt in STATUS_OPTIONS" :key="opt.value" @click="handleSetReadStatus(opt.value)">
+                <component :is="STATUS_ICONS[opt.value]" class="size-4 mr-2" :class="STATUS_COLORS[opt.value]" />
+                {{ opt.label }}
+                <Check v-if="localReadStatus === opt.value" class="size-3 ml-auto text-primary" />
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+
+          <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+            <span class="flex items-center gap-1">
+              First Read
+              <span class="font-medium text-foreground">{{ firstReadLabel }}</span>
+            </span>
+            <span class="flex items-center gap-1">
+              Last Read
+              <span class="font-medium text-foreground">{{ lastReadLabel }}</span>
+            </span>
+          </div>
+
+          <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+            <span class="flex items-center gap-1">
+              Date Started
+              <input
+                v-if="activeDateField === 'startedAt'"
+                v-model="draftDates.startedAt"
+                type="date"
+                :max="todayDateInput"
+                :disabled="savingDates"
+                class="h-6 rounded border border-input bg-background px-1 text-xs text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
+                autofocus
+                @blur="handleStartedSave"
+                @keydown.enter.prevent="handleStartedSave"
+                @keydown.esc.prevent="handleStartedCancel"
+              />
+              <button v-else class="font-medium text-foreground hover:text-primary transition-colors" @click="handleStartedClick">
+                {{ formatDisplayDate(savedDates.startedAt) }}
+              </button>
+            </span>
+            <span class="flex items-center gap-1">
+              Date Finished
+              <input
+                v-if="activeDateField === 'finishedAt'"
+                v-model="draftDates.finishedAt"
+                type="date"
+                :max="todayDateInput"
+                :disabled="savingDates"
+                class="h-6 rounded border border-input bg-background px-1 text-xs text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
+                autofocus
+                @blur="handleFinishedSave"
+                @keydown.enter.prevent="handleFinishedSave"
+                @keydown.esc.prevent="handleFinishedCancel"
+              />
+              <button v-else class="font-medium text-foreground hover:text-primary transition-colors" @click="handleFinishedClick">
+                {{ formatDisplayDate(savedDates.finishedAt) }}
+              </button>
+            </span>
+          </div>
+
+          <p v-if="datesError" class="text-xs text-destructive">{{ datesError }}</p>
+
+          <p v-if="etaLabel" class="flex items-center gap-1 text-xs text-muted-foreground">
+            <Clock class="size-3" />
+            {{ etaLabel }}
+          </p>
+        </div>
+      </div>
+
+      <div class="grid flex-1 grid-cols-2 gap-2 sm:grid-cols-4 sm:gap-3 transition-opacity" :class="{ 'opacity-50': loading && stats !== null }">
+        <template v-if="stats === null && loading">
+          <div v-for="i in 4" :key="i" class="rounded-lg border border-border bg-background/40 px-3 py-2.5">
+            <div class="mb-2 h-3 w-16 rounded bg-muted animate-shimmer" />
+            <div class="h-6 w-12 rounded bg-muted animate-shimmer" />
+          </div>
+        </template>
+        <template v-else>
+          <div v-for="cell in statCells" :key="cell.label" class="rounded-lg border border-border bg-background/40 px-3 py-2.5">
+            <p class="mb-0.5 text-[11px] text-muted-foreground">{{ cell.label }}</p>
+            <p class="flex items-center gap-1.5 text-lg font-semibold text-foreground">
+              {{ cell.value }}
+              <span v-if="cell.withMomentum" :title="momentum.title" class="inline-flex">
+                <TrendingUp v-if="momentum.direction === 'up'" class="size-4 text-green-600" />
+                <TrendingDown v-else-if="momentum.direction === 'down'" class="size-4 text-destructive" />
+                <Minus v-else class="size-4 text-muted-foreground" />
+              </span>
+            </p>
+          </div>
+        </template>
+      </div>
+
+      <div class="lg:self-start">
+        <button
+          class="inline-flex items-center gap-1.5 rounded-md border border-border bg-card px-3 py-1.5 text-sm text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
+          @click="handleAddSession"
+        >
+          <Plus :size="14" />
+          Add session
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogJourneyChart.vue b/client/src/features/book/components/detail/tabs/ReadingLogJourneyChart.vue
new file mode 100644
index 000000000..dd0de1926
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/ReadingLogJourneyChart.vue
@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { computed, onMounted, shallowRef, watchEffect } from 'vue'
+import VChart from 'vue-echarts'
+import { TrendingUp } from '@lucide/vue'
+import type { BookReadingSessionStats } from '@bookorbit/types'
+import { useThemeStore } from '@/stores/theme'
+import { getBookorbitThemeName, initChartThemes } from '@/lib/echarts'
+
+const props = defineProps<{
+  stats: BookReadingSessionStats | null
+  loading: boolean
+}>()
+
+const themeStore = useThemeStore()
+const chartTheme = computed(() => getBookorbitThemeName(themeStore.theme, themeStore.accent))
+const option = shallowRef({})
+
+onMounted(() => initChartThemes())
+
+const hasData = computed(() => {
+  const stats = props.stats
+  if (!stats) return false
+  return stats.progressSummary.length > 0 || stats.dailySummary.length > 0
+})
+
+watchEffect(() => {
+  const stats = props.stats
+  if (!stats || !hasData.value) {
+    option.value = {}
+    return
+  }
+
+  const progressPoints = stats.progressSummary.map((p) => [p.day, p.endProgress])
+  const minutesBars = stats.dailySummary.map((d) => [d.day, d.totalMinutes])
+
+  option.value = {
+    tooltip: {
+      trigger: 'axis',
+      formatter: (params: { seriesName: string; value: [string, number] }[]) => {
+        if (!params.length) return ''
+        const day = params[0]!.value[0]
+        const lines = params.map((p) =>
+          p.seriesName === 'Progress' ? `Progress: <strong>${p.value[1].toFixed(1)}%</strong>` : `Reading: <strong>${p.value[1]} min</strong>`,
+        )
+        return [day, ...lines].join('<br/>')
+      },
+    },
+    grid: { left: '2%', right: '2%', top: '8%', bottom: '6%', containLabel: true },
+    xAxis: {
+      type: 'time',
+      axisTick: { show: false },
+      axisLabel: { fontSize: 10 },
+    },
+    yAxis: [
+      {
+        type: 'value',
+        min: 0,
+        max: 100,
+        axisLabel: { fontSize: 10, formatter: (v: number) => `${v}%` },
+      },
+      {
+        type: 'value',
+        minInterval: 1,
+        splitLine: { show: false },
+        axisLabel: { fontSize: 10, formatter: (v: number) => `${v}m` },
+      },
+    ],
+    series: [
+      {
+        name: 'Reading',
+        type: 'bar',
+        yAxisIndex: 1,
+        data: minutesBars,
+        barMaxWidth: 10,
+        itemStyle: { borderRadius: [2, 2, 0, 0], opacity: 0.45 },
+      },
+      {
+        name: 'Progress',
+        type: 'line',
+        yAxisIndex: 0,
+        data: progressPoints,
+        showSymbol: progressPoints.length <= 30,
+        symbolSize: 5,
+        lineStyle: { width: 2 },
+        areaStyle: { opacity: 0.12 },
+        z: 3,
+      },
+    ],
+  }
+})
+</script>
+
+<template>
+  <div class="flex h-full flex-col rounded-lg border border-border bg-card p-3 sm:p-4">
+    <div class="mb-2 flex items-center gap-2 text-sm font-medium text-foreground">
+      <TrendingUp class="size-4 text-muted-foreground" />
+      Progress journey
+    </div>
+    <div v-if="hasData" class="relative min-h-0 flex-1 transition-opacity" :class="{ 'opacity-50': loading }" style="min-height: 220px">
+      <VChart :theme="chartTheme" :option autoresize class="absolute inset-0" />
+    </div>
+    <div v-else class="flex flex-1 items-center justify-center py-12 text-sm text-muted-foreground" style="min-height: 220px">
+      No progress data in this window.
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogSourceSplit.vue b/client/src/features/book/components/detail/tabs/ReadingLogSourceSplit.vue
new file mode 100644
index 000000000..2bd4dd30e
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/ReadingLogSourceSplit.vue
@@ -0,0 +1,68 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { MonitorSmartphone } from '@lucide/vue'
+import type { BookReadingSessionStats, ReadingSessionSourceBucket } from '@bookorbit/types'
+import { READING_SESSION_SOURCE_BUCKET_LABELS } from '@bookorbit/types'
+
+const props = defineProps<{
+  stats: BookReadingSessionStats | null
+}>()
+
+const BUCKET_TOKEN: Record<ReadingSessionSourceBucket, string> = {
+  bookorbit: '--pill-web',
+  koreader: '--pill-koreader',
+  kobo: '--pill-kobo',
+}
+
+function formatDuration(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m`
+  return `${total}s`
+}
+
+const totalSeconds = computed(() => (props.stats?.bySource ?? []).reduce((sum, slice) => sum + slice.totalSeconds, 0))
+
+const segments = computed(() => {
+  const total = totalSeconds.value
+  return (props.stats?.bySource ?? []).map((slice) => ({
+    bucket: slice.bucket,
+    label: READING_SESSION_SOURCE_BUCKET_LABELS[slice.bucket],
+    token: BUCKET_TOKEN[slice.bucket],
+    seconds: slice.totalSeconds,
+    sessions: slice.totalSessions,
+    widthPercent: total > 0 ? (slice.totalSeconds / total) * 100 : 0,
+    percent: total > 0 ? Math.round((slice.totalSeconds / total) * 100) : 0,
+  }))
+})
+
+// Only meaningful once a book has been read across more than one source.
+const shouldShow = computed(() => segments.value.length >= 2 && totalSeconds.value > 0)
+</script>
+
+<template>
+  <div v-if="shouldShow" class="rounded-lg border border-border bg-card p-4">
+    <p class="mb-3 flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+      <MonitorSmartphone class="size-3.5" />
+      Where you read this book
+    </p>
+    <div class="flex h-3 w-full overflow-hidden rounded-full bg-muted">
+      <div
+        v-for="seg in segments"
+        :key="seg.bucket"
+        class="h-full"
+        :style="{ width: `${seg.widthPercent}%`, backgroundColor: `var(${seg.token})` }"
+        :title="`${seg.label}: ${seg.percent}%`"
+      />
+    </div>
+    <div class="mt-3 flex flex-wrap gap-x-4 gap-y-1.5">
+      <div v-for="seg in segments" :key="seg.bucket" class="flex items-center gap-1.5 text-xs">
+        <span class="size-2.5 rounded-full" :style="{ backgroundColor: `var(${seg.token})` }" />
+        <span class="font-medium text-foreground">{{ seg.label }}</span>
+        <span class="text-muted-foreground">{{ seg.percent }}% · {{ formatDuration(seg.seconds) }}</span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogSparkline.vue b/client/src/features/book/components/detail/tabs/ReadingLogSparkline.vue
deleted file mode 100644
index d44d9eed4..000000000
--- a/client/src/features/book/components/detail/tabs/ReadingLogSparkline.vue
+++ /dev/null
@@ -1,65 +0,0 @@
-<script setup lang="ts">
-import { computed, onMounted, shallowRef, watchEffect } from 'vue'
-import VChart from 'vue-echarts'
-import type { BookReadingSessionStats } from '@bookorbit/types'
-import { useThemeStore } from '@/stores/theme'
-import { getBookorbitThemeName, initChartThemes } from '@/lib/echarts'
-
-const props = defineProps<{
-  stats: BookReadingSessionStats | null
-  loading: boolean
-}>()
-
-const themeStore = useThemeStore()
-const chartTheme = computed(() => getBookorbitThemeName(themeStore.theme, themeStore.accent))
-const hasSummary = computed(() => (props.stats?.dailySummary ?? []).length > 0)
-const option = shallowRef({})
-
-onMounted(() => initChartThemes())
-
-watchEffect(() => {
-  const summary = props.stats?.dailySummary
-  if (!summary || summary.length === 0) return
-
-  option.value = {
-    tooltip: {
-      trigger: 'axis',
-      formatter: (params: { name: string; value: number }[]) => {
-        const p = params[0]
-        if (!p) return ''
-        return `${p.name}: <strong>${p.value} min</strong>`
-      },
-    },
-    grid: { left: '2%', right: '2%', top: '6%', bottom: '12%', containLabel: true },
-    xAxis: {
-      type: 'category',
-      data: summary.map((d) => d.day),
-      axisTick: { show: false },
-      axisLabel: {
-        fontSize: 10,
-        interval: Math.max(0, Math.floor(summary.length / 6) - 1),
-        formatter: (val: string) => val.slice(5),
-      },
-    },
-    yAxis: {
-      type: 'value',
-      minInterval: 1,
-      axisLabel: { fontSize: 10, formatter: (v: number) => `${v}m` },
-    },
-    series: [
-      {
-        type: 'bar',
-        data: summary.map((d) => d.totalMinutes),
-        barMaxWidth: 12,
-        itemStyle: { borderRadius: [2, 2, 0, 0] },
-      },
-    ],
-  }
-})
-</script>
-
-<template>
-  <div v-if="hasSummary" class="w-full transition-opacity" :class="{ 'opacity-50': loading }" style="height: 120px">
-    <VChart :theme="chartTheme" :option autoresize class="h-full w-full" />
-  </div>
-</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogStatsStrip.vue b/client/src/features/book/components/detail/tabs/ReadingLogStatsStrip.vue
deleted file mode 100644
index f03faf4f3..000000000
--- a/client/src/features/book/components/detail/tabs/ReadingLogStatsStrip.vue
+++ /dev/null
@@ -1,182 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import type { BookReadingSessionStats } from '@bookorbit/types'
-
-const props = defineProps<{
-  stats: BookReadingSessionStats | null
-  loading: boolean
-  quickFilter: 'all' | 'last30' | 'last90' | 'thisYear'
-}>()
-
-const DAY_MS = 24 * 60 * 60 * 1000
-const CARD_COUNT = 8
-const CARD_CLASS = 'rounded-lg border border-border bg-card px-3 py-2.5 sm:px-4 sm:py-3'
-
-function toUtcDayStart(date: Date): number {
-  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
-}
-
-function toUtcDayKey(dayStartMs: number): string {
-  return new Date(dayStartMs).toISOString().slice(0, 10)
-}
-
-function parseDayKeyToUtcStart(dayKey: string): number | null {
-  const [yy, mm, dd] = dayKey.split('-').map(Number)
-  if (!yy || !mm || !dd) return null
-  return Date.UTC(yy, mm - 1, dd)
-}
-
-function formatDuration(seconds: number): string {
-  const h = Math.floor(seconds / 3600)
-  const m = Math.floor((seconds % 3600) / 60)
-  const s = Math.floor(seconds % 60)
-  if (h > 0) return `${h}h ${m}m`
-  if (m > 0) return `${m}m`
-  return `${s}s`
-}
-
-function formatRelative(iso: string | null): string {
-  if (!iso) return '-'
-  const diff = Date.now() - new Date(iso).getTime()
-  const s = Math.floor(diff / 1000)
-  if (s < 60) return `${s}s ago`
-  const m = Math.floor(s / 60)
-  if (m < 60) return `${m}m ago`
-  const h = Math.floor(m / 60)
-  if (h < 24) return `${h}h ago`
-  const d = Math.floor(h / 24)
-  if (d < 30) return `${d}d ago`
-  const mo = Math.floor(d / 30)
-  if (mo < 12) return `${mo} month${mo === 1 ? '' : 's'} ago`
-  const yr = Math.floor(mo / 12)
-  return `${yr} year${yr === 1 ? '' : 's'} ago`
-}
-
-const dailyMap = computed(() => {
-  const map = new Map<string, number>()
-  for (const row of props.stats?.dailySummary ?? []) {
-    map.set(row.day, row.totalMinutes)
-  }
-  return map
-})
-
-const todayUtcStart = computed(() => toUtcDayStart(new Date()))
-
-const consistencyWindowDays = computed(() => {
-  if (props.quickFilter === 'last30') return 30
-  if (props.quickFilter === 'last90') return 90
-  if (props.quickFilter === 'thisYear') {
-    const jan1 = Date.UTC(new Date().getUTCFullYear(), 0, 1)
-    return Math.floor((todayUtcStart.value - jan1) / DAY_MS) + 1
-  }
-  if (!props.stats?.firstSessionAt) return 0
-  const firstDay = toUtcDayStart(new Date(props.stats.firstSessionAt))
-  return Math.max(1, Math.floor((todayUtcStart.value - firstDay) / DAY_MS) + 1)
-})
-
-const consistencyWindowStart = computed(() => {
-  if (consistencyWindowDays.value <= 0) return null
-  return todayUtcStart.value - (consistencyWindowDays.value - 1) * DAY_MS
-})
-
-const activeDays = computed(() => {
-  const windowStart = consistencyWindowStart.value
-  if (windowStart == null) return 0
-  let count = 0
-  for (const row of props.stats?.dailySummary ?? []) {
-    const dayStart = parseDayKeyToUtcStart(row.day)
-    if (dayStart == null) continue
-    if (dayStart < windowStart || dayStart > todayUtcStart.value) continue
-    if (row.totalMinutes > 0) count += 1
-  }
-  return count
-})
-
-const consistencyLabel = computed(() => {
-  if (consistencyWindowDays.value <= 0) return '-'
-  const ratio = Math.round((activeDays.value / consistencyWindowDays.value) * 100)
-  return `${activeDays.value}/${consistencyWindowDays.value} (${ratio}%)`
-})
-
-const momentum = computed(() => {
-  const map = dailyMap.value
-  let last7 = 0
-  let prev7 = 0
-  for (let offset = 0; offset < 7; offset += 1) {
-    last7 += map.get(toUtcDayKey(todayUtcStart.value - offset * DAY_MS)) ?? 0
-    prev7 += map.get(toUtcDayKey(todayUtcStart.value - (offset + 7) * DAY_MS)) ?? 0
-  }
-
-  if (last7 === 0 && prev7 === 0) return { text: '-', tone: 'text-muted-foreground' }
-  if (prev7 <= 0) return { text: 'New activity', tone: 'text-green-600' }
-
-  const pct = ((last7 - prev7) / prev7) * 100
-  const rounded = Math.round(pct)
-  if (rounded > 0) return { text: `+${rounded}%`, tone: 'text-green-600' }
-  if (rounded < 0) return { text: `${rounded}%`, tone: 'text-destructive' }
-  return { text: '0%', tone: 'text-muted-foreground' }
-})
-
-const statCards = computed(() => [
-  {
-    label: 'Consistency',
-    value: consistencyLabel.value,
-    tone: 'text-foreground',
-  },
-  {
-    label: 'Active Days',
-    value: String(activeDays.value),
-    tone: 'text-foreground',
-  },
-  {
-    label: 'Momentum',
-    value: momentum.value.text,
-    tone: momentum.value.tone,
-  },
-  {
-    label: 'Total Time',
-    value: props.stats ? formatDuration(props.stats.totalSeconds) : '0s',
-    tone: 'text-foreground',
-  },
-  {
-    label: 'Sessions',
-    value: String(props.stats?.totalSessions ?? 0),
-    tone: 'text-foreground',
-  },
-  {
-    label: 'Avg Session',
-    value: props.stats ? formatDuration(props.stats.avgDurationSeconds) : '0s',
-    tone: 'text-foreground',
-  },
-  {
-    label: 'Last Read',
-    value: props.stats ? formatRelative(props.stats.lastSessionAt) : '-',
-    tone: 'text-foreground',
-  },
-  {
-    label: 'First Read',
-    value: props.stats ? formatRelative(props.stats.firstSessionAt) : '-',
-    tone: 'text-foreground',
-  },
-])
-</script>
-
-<template>
-  <div
-    class="grid grid-cols-2 gap-2 sm:gap-3 transition-opacity md:grid-cols-8"
-    :class="{ 'opacity-50 pointer-events-none': loading && stats !== null }"
-  >
-    <template v-if="stats === null && loading">
-      <div v-for="i in CARD_COUNT" :key="i" :class="CARD_CLASS">
-        <div class="h-3 w-16 rounded bg-muted animate-shimmer mb-2" />
-        <div class="h-6 w-12 rounded bg-muted animate-shimmer" />
-      </div>
-    </template>
-    <template v-else>
-      <div v-for="card in statCards" :key="card.label" :class="CARD_CLASS">
-        <p class="mb-0.5 text-[11px] text-muted-foreground sm:mb-1 sm:text-xs">{{ card.label }}</p>
-        <p class="text-lg font-semibold sm:text-xl" :class="card.tone">{{ card.value }}</p>
-      </div>
-    </template>
-  </div>
-</template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogTab.vue b/client/src/features/book/components/detail/tabs/ReadingLogTab.vue
index 22ed0afa0..722f8c59b 100644
--- a/client/src/features/book/components/detail/tabs/ReadingLogTab.vue
+++ b/client/src/features/book/components/detail/tabs/ReadingLogTab.vue
@@ -1,16 +1,39 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import type { BookDetail } from '@bookorbit/types'
-import { useBookReadingLog } from '@/features/book/composables/useBookReadingLog'
-import ReadingLogStatsStrip from './ReadingLogStatsStrip.vue'
-import ReadingLogSparkline from './ReadingLogSparkline.vue'
+import type { BookDetail, UserBookStatus } from '@bookorbit/types'
+import { useBookReadingLog, type AddReadingSessionPayload } from '@/features/book/composables/useBookReadingLog'
+import ReadingLogHero from './ReadingLogHero.vue'
+import ReadingLogSourceSplit from './ReadingLogSourceSplit.vue'
+import ReadingLogJourneyChart from './ReadingLogJourneyChart.vue'
+import ReadingLogHeatmap from './ReadingLogHeatmap.vue'
 import ReadingLogTable from './ReadingLogTable.vue'
+import ReadingLogExportMenu from './ReadingLogExportMenu.vue'
+import AddSessionDialog from './AddSessionDialog.vue'
 
 const props = defineProps<{ book: BookDetail }>()
 
+const emit = defineEmits<{
+  saved: [book: BookDetail]
+}>()
+
 const bookIdRef = computed(() => props.book.id)
-const { sessions, total, stats, loading, error, page, pageSize, sortBy, sortDir, deleteSession, setPage, setSort, setFilters } =
-  useBookReadingLog(bookIdRef)
+const {
+  sessions,
+  total,
+  stats,
+  loading,
+  loadingMore,
+  error,
+  sortBy,
+  sortDir,
+  hasMore,
+  deleteSession,
+  addSession,
+  exportAll,
+  loadMore,
+  setSort,
+  setFilters,
+} = useBookReadingLog(bookIdRef)
 
 type QuickFilter = 'all' | 'last30' | 'last90' | 'thisYear'
 const activeQuick = ref<QuickFilter>('all')
@@ -23,6 +46,8 @@ const uniqueFormats = computed(() => {
 
 const hasMultipleFormats = computed(() => uniqueFormats.value.length >= 2)
 
+const bookTitle = computed(() => props.book.title ?? 'Untitled')
+
 function buildDateFrom(q: QuickFilter): string | undefined {
   const now = new Date()
   if (q === 'last30') return new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString()
@@ -46,14 +71,45 @@ function handleSortChange(by: string, dir: 'asc' | 'desc') {
   setSort(by as 'startedAt' | 'durationSeconds' | 'progressDelta' | 'endProgress', dir)
 }
 
-function handlePageChange(p: number) {
-  setPage(p)
+function handleLoadMore() {
+  void loadMore()
 }
 
 async function handleDeleteSession(sessionId: number) {
   await deleteSession(sessionId)
 }
 
+function handleHeroSaved(readStatus: UserBookStatus) {
+  emit('saved', { ...props.book, readStatus })
+}
+
+const addDialogOpen = ref(false)
+const addSaving = ref(false)
+const addError = ref<string | null>(null)
+
+function handleOpenAddSession() {
+  addError.value = null
+  addDialogOpen.value = true
+}
+
+function handleCloseAddSession() {
+  if (addSaving.value) return
+  addDialogOpen.value = false
+}
+
+async function handleAddSessionSubmit(payload: AddReadingSessionPayload) {
+  addSaving.value = true
+  addError.value = null
+  try {
+    await addSession(payload)
+    addDialogOpen.value = false
+  } catch (e) {
+    addError.value = e instanceof Error ? e.message : 'Failed to add session'
+  } finally {
+    addSaving.value = false
+  }
+}
+
 const quickFilters: { label: string; value: QuickFilter }[] = [
   { label: 'All time', value: 'all' },
   { label: 'Last 30 days', value: 'last30' },
@@ -68,6 +124,10 @@ const quickFilters: { label: string; value: QuickFilter }[] = [
       {{ error }}
     </div>
 
+    <ReadingLogHero :book="book" :stats="stats" :loading="loading" @saved="handleHeroSaved" @add-session="handleOpenAddSession" />
+
+    <ReadingLogSourceSplit :stats="stats" />
+
     <div class="flex flex-wrap items-center gap-2">
       <button
         v-for="qf in quickFilters"
@@ -83,33 +143,51 @@ const quickFilters: { label: string; value: QuickFilter }[] = [
         {{ qf.label }}
       </button>
 
-      <select
-        v-if="hasMultipleFormats"
-        class="ml-auto px-3 py-1.5 rounded-md text-sm border border-border bg-card text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
-        :value="selectedFormat ?? ''"
-        @change="handleFormatChange"
-      >
-        <option value="">All formats</option>
-        <option v-for="fmt in uniqueFormats" :key="fmt" :value="fmt">{{ fmt.toUpperCase() }}</option>
-      </select>
+      <div class="ml-auto flex items-center gap-2">
+        <select
+          v-if="hasMultipleFormats"
+          class="px-3 py-1.5 rounded-md text-sm border border-border bg-card text-foreground focus:outline-none focus:ring-1 focus:ring-primary"
+          :value="selectedFormat ?? ''"
+          @change="handleFormatChange"
+        >
+          <option value="">All formats</option>
+          <option v-for="fmt in uniqueFormats" :key="fmt" :value="fmt">{{ fmt.toUpperCase() }}</option>
+        </select>
+
+        <ReadingLogExportMenu :book-title="bookTitle" :total="total" :export-all="exportAll" />
+      </div>
     </div>
 
-    <ReadingLogSparkline :stats="stats" :loading="loading" />
-
-    <ReadingLogStatsStrip :stats="stats" :loading="loading" :quick-filter="activeQuick" />
+    <div class="grid grid-cols-1 gap-4 lg:grid-cols-5 lg:items-start">
+      <div class="lg:col-span-3">
+        <ReadingLogJourneyChart :stats="stats" :loading="loading" />
+      </div>
+      <div class="lg:col-span-2">
+        <ReadingLogHeatmap :stats="stats" :loading="loading" :quick-filter="activeQuick" />
+      </div>
+    </div>
 
     <ReadingLogTable
       :sessions="sessions"
       :total="total"
-      :page="page"
-      :page-size="pageSize"
       :sort-by="sortBy"
       :sort-dir="sortDir"
       :loading="loading"
+      :loading-more="loadingMore"
+      :has-more="hasMore"
       :has-multiple-formats="hasMultipleFormats"
       @sort-change="handleSortChange"
-      @page-change="handlePageChange"
+      @load-more="handleLoadMore"
       @delete-session="handleDeleteSession"
     />
+
+    <AddSessionDialog
+      :open="addDialogOpen"
+      :formats="uniqueFormats"
+      :saving="addSaving"
+      :error="addError"
+      @close="handleCloseAddSession"
+      @submit="handleAddSessionSubmit"
+    />
   </div>
 </template>
diff --git a/client/src/features/book/components/detail/tabs/ReadingLogTable.vue b/client/src/features/book/components/detail/tabs/ReadingLogTable.vue
index c1122fae6..d4a47d232 100644
--- a/client/src/features/book/components/detail/tabs/ReadingLogTable.vue
+++ b/client/src/features/book/components/detail/tabs/ReadingLogTable.vue
@@ -1,22 +1,22 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import { ChevronDown, ChevronUp, ChevronsUpDown, Trash2, X } from '@lucide/vue'
-import type { BookReadingSession } from '@bookorbit/types'
+import { ChevronDown, ChevronUp, ChevronsUpDown, Loader2, Trash2, X } from '@lucide/vue'
+import type { BookReadingSession, ReadingSessionSource } from '@bookorbit/types'
 
 const props = defineProps<{
   sessions: BookReadingSession[]
   total: number
-  page: number
-  pageSize: number
   sortBy: string
   sortDir: 'asc' | 'desc'
   loading: boolean
+  loadingMore: boolean
+  hasMore: boolean
   hasMultipleFormats: boolean
 }>()
 
 const emit = defineEmits<{
   sortChange: [sortBy: string, sortDir: 'asc' | 'desc']
-  pageChange: [page: number]
+  loadMore: []
   deleteSession: [sessionId: number]
 }>()
 
@@ -38,6 +38,18 @@ function formatDuration(seconds: number): string {
   return `${s}s`
 }
 
+function formatDayDuration(seconds: number): string {
+  const h = Math.floor(seconds / 3600)
+  const m = Math.floor((seconds % 3600) / 60)
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m`
+  return `${Math.floor(seconds % 60)}s`
+}
+
+function formatTime(iso: string): string {
+  return new Date(iso).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })
+}
+
 function formatDate(iso: string): string {
   return new Date(iso).toLocaleString(undefined, {
     year: 'numeric',
@@ -63,6 +75,22 @@ function formatProgressDelta(progressDelta: number | null): string {
   return `${prefix}${progressDelta.toFixed(1)}%`
 }
 
+function formatPace(session: BookReadingSession): string {
+  if (session.progressDelta == null || session.progressDelta <= 0 || session.durationSeconds === 0) return '-'
+  return `${((session.progressDelta / session.durationSeconds) * 3600).toFixed(1)}%/hr`
+}
+
+const PILL_BASE = 'inline-flex items-center gap-1 rounded border px-1.5 py-0.5 text-[10px] font-medium'
+
+const SESSION_SOURCE_PILLS: Record<ReadingSessionSource, { label: string; class: string }> = {
+  web: { label: 'Web', class: 'border-[var(--pill-web)]/40 bg-[var(--pill-web)]/10 text-[var(--pill-web)]' },
+  koreader: { label: 'KOReader', class: 'border-[var(--pill-koreader)]/40 bg-[var(--pill-koreader)]/10 text-[var(--pill-koreader)]' },
+  kobo: { label: 'Kobo', class: 'border-[var(--pill-kobo)]/40 bg-[var(--pill-kobo)]/10 text-[var(--pill-kobo)]' },
+  manual: { label: 'Manual', class: 'border-border bg-muted text-muted-foreground' },
+}
+
+const showSource = computed(() => props.sessions.some((s) => s.source != null))
+
 function handleDeleteClick(sessionId: number) {
   if (confirmDeleteId.value === sessionId) {
     emit('deleteSession', sessionId)
@@ -76,14 +104,9 @@ function clearConfirmDelete() {
   confirmDeleteId.value = null
 }
 
-function handlePrevPage() {
+function handleLoadMore() {
   confirmDeleteId.value = null
-  emit('pageChange', props.page - 1)
-}
-
-function handleNextPage() {
-  confirmDeleteId.value = null
-  emit('pageChange', props.page + 1)
+  emit('loadMore')
 }
 
 function handleSort(col: string) {
@@ -92,16 +115,62 @@ function handleSort(col: string) {
   emit('sortChange', col, dir)
 }
 
-const totalPages = computed(() => Math.max(1, Math.ceil(props.total / props.pageSize)))
-const startItem = computed(() => Math.min((props.page - 1) * props.pageSize + 1, props.total))
-const endItem = computed(() => Math.min(props.page * props.pageSize, props.total))
-
 const SORTABLE_COLS = [
   { id: 'startedAt', label: 'Date', mobileLabel: 'Date' },
   { id: 'durationSeconds', label: 'Duration', mobileLabel: 'Duration' },
   { id: 'progressDelta', label: 'Progress Change', mobileLabel: 'Delta' },
   { id: 'endProgress', label: 'End Progress', mobileLabel: 'End' },
 ] as const
+
+const columnCount = computed(() => {
+  let count = SORTABLE_COLS.length + 2
+  if (showSource.value) count += 1
+  if (props.hasMultipleFormats) count += 1
+  return count
+})
+
+function localDayKey(iso: string): string {
+  const d = new Date(iso)
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+function formatDayLabel(dayKey: string): string {
+  const [year, month, day] = dayKey.split('-').map(Number)
+  const d = new Date(year!, month! - 1, day!)
+  return d.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric', year: 'numeric' })
+}
+
+type TableRow =
+  | { kind: 'header'; key: string; label: string; totalSeconds: number; netDelta: number | null }
+  | { kind: 'session'; key: string; session: BookReadingSession }
+
+const grouped = computed(() => props.sortBy === 'startedAt')
+
+const rows = computed<TableRow[]>(() => {
+  if (!grouped.value) {
+    return props.sessions.map((session) => ({ kind: 'session' as const, key: `s-${session.id}`, session }))
+  }
+
+  const out: TableRow[] = []
+  let currentKey: string | null = null
+  let headerIndex = -1
+  for (const session of props.sessions) {
+    const dayKey = localDayKey(session.startedAt)
+    if (dayKey !== currentKey) {
+      currentKey = dayKey
+      out.push({ kind: 'header', key: `h-${dayKey}`, label: formatDayLabel(dayKey), totalSeconds: 0, netDelta: null })
+      headerIndex = out.length - 1
+    }
+    const header = out[headerIndex] as Extract<TableRow, { kind: 'header' }>
+    header.totalSeconds += session.durationSeconds
+    if (session.progressDelta != null) {
+      header.netDelta = (header.netDelta ?? 0) + session.progressDelta
+    }
+    out.push({ kind: 'session', key: `s-${session.id}`, session })
+  }
+  return out
+})
 </script>
 
 <template>
@@ -127,6 +196,17 @@ const SORTABLE_COLS = [
                 <ChevronsUpDown v-else :size="12" class="opacity-40" />
               </button>
             </th>
+            <th
+              class="hidden px-2 py-2.5 text-left text-[11px] font-medium text-muted-foreground uppercase tracking-wide sm:table-cell sm:px-4 sm:py-3 sm:text-xs"
+            >
+              Pace
+            </th>
+            <th
+              v-if="showSource"
+              class="hidden px-2 py-2.5 text-left text-[11px] font-medium text-muted-foreground uppercase tracking-wide sm:table-cell sm:px-4 sm:py-3 sm:text-xs"
+            >
+              Source
+            </th>
             <th
               v-if="hasMultipleFormats"
               class="px-2 py-2.5 text-left text-[11px] font-medium text-muted-foreground uppercase tracking-wide sm:px-4 sm:py-3 sm:text-xs"
@@ -138,81 +218,104 @@ const SORTABLE_COLS = [
           </tr>
         </thead>
         <tbody>
-          <tr
-            v-for="session in sessions"
-            :key="session.id"
-            class="border-b border-border odd:bg-muted/20 last:border-0 hover:bg-muted/30 transition-colors"
-          >
-            <td class="px-2 py-2.5 text-foreground whitespace-nowrap sm:px-4 sm:py-3">
-              <span class="sm:hidden">{{ formatDateCompact(session.startedAt) }}</span>
-              <span class="hidden sm:inline">{{ formatDate(session.startedAt) }}</span>
-            </td>
-            <td class="px-2 py-2.5 text-foreground whitespace-nowrap sm:px-4 sm:py-3">{{ formatDuration(session.durationSeconds) }}</td>
-            <td
-              class="px-2 py-2.5 whitespace-nowrap sm:px-4 sm:py-3"
-              :class="session.progressDelta != null && session.progressDelta > 0 ? 'text-green-600' : 'text-muted-foreground'"
-            >
-              {{ formatProgressDelta(session.progressDelta) }}
-            </td>
-            <td class="px-2 py-2.5 text-foreground whitespace-nowrap sm:px-4 sm:py-3">
-              {{ session.endProgress != null ? `${session.endProgress.toFixed(1)}%` : '-' }}
-            </td>
-            <td v-if="hasMultipleFormats" class="px-2 py-2.5 text-foreground whitespace-nowrap sm:px-4 sm:py-3">{{ session.format ?? '-' }}</td>
-            <td class="w-28 px-2 py-2.5 sm:px-4 sm:py-3">
-              <div class="ml-auto flex h-7 w-[5.75rem] items-center justify-end gap-1">
-                <template v-if="confirmDeleteId === session.id">
+          <template v-for="row in rows" :key="row.key">
+            <tr v-if="row.kind === 'header'" class="border-b border-border bg-muted/40">
+              <td :colspan="columnCount" class="px-2 py-1.5 sm:px-4">
+                <div class="flex items-center justify-between gap-2 text-[11px] sm:text-xs">
+                  <span class="font-medium text-foreground">{{ row.label }}</span>
+                  <span class="text-muted-foreground whitespace-nowrap">
+                    {{ formatDayDuration(row.totalSeconds) }}
+                    <template v-if="row.netDelta != null">
+                      · <span :class="row.netDelta > 0 ? 'text-green-600' : 'text-muted-foreground'">{{ formatProgressDelta(row.netDelta) }}</span>
+                    </template>
+                  </span>
+                </div>
+              </td>
+            </tr>
+            <tr v-else class="border-b border-border last:border-0 hover:bg-muted/30 transition-colors">
+              <td class="px-2 py-1.5 text-foreground whitespace-nowrap sm:px-4 sm:py-2">
+                <span class="sm:hidden">
+                  <template v-if="grouped">{{ formatTime(row.session.startedAt) }}</template>
+                  <template v-else>{{ formatDateCompact(row.session.startedAt) }}</template>
+                  <span v-if="row.session.source" class="ml-1.5" :class="[PILL_BASE, SESSION_SOURCE_PILLS[row.session.source].class]">
+                    {{ SESSION_SOURCE_PILLS[row.session.source].label }}
+                  </span>
+                </span>
+                <span class="hidden sm:inline">
+                  <template v-if="grouped">{{ formatTime(row.session.startedAt) }}</template>
+                  <template v-else>{{ formatDate(row.session.startedAt) }}</template>
+                </span>
+              </td>
+              <td class="px-2 py-1.5 text-foreground whitespace-nowrap sm:px-4 sm:py-2">{{ formatDuration(row.session.durationSeconds) }}</td>
+              <td
+                class="px-2 py-1.5 whitespace-nowrap sm:px-4 sm:py-2"
+                :class="row.session.progressDelta != null && row.session.progressDelta > 0 ? 'text-green-600' : 'text-muted-foreground'"
+              >
+                {{ formatProgressDelta(row.session.progressDelta) }}
+              </td>
+              <td class="px-2 py-1.5 text-foreground whitespace-nowrap sm:px-4 sm:py-2">
+                {{ row.session.endProgress != null ? `${row.session.endProgress.toFixed(1)}%` : '-' }}
+              </td>
+              <td class="hidden px-2 py-1.5 text-muted-foreground whitespace-nowrap sm:table-cell sm:px-4 sm:py-2">
+                {{ formatPace(row.session) }}
+              </td>
+              <td v-if="showSource" class="hidden px-2 py-1.5 whitespace-nowrap sm:table-cell sm:px-4 sm:py-2">
+                <span v-if="row.session.source" :class="[PILL_BASE, SESSION_SOURCE_PILLS[row.session.source].class]">
+                  {{ SESSION_SOURCE_PILLS[row.session.source].label }}
+                </span>
+                <span v-else class="text-muted-foreground">-</span>
+              </td>
+              <td v-if="hasMultipleFormats" class="px-2 py-1.5 text-foreground whitespace-nowrap sm:px-4 sm:py-2">
+                {{ row.session.format ?? '-' }}
+              </td>
+              <td class="w-28 px-2 py-1.5 sm:px-4 sm:py-2">
+                <div class="ml-auto flex h-6 w-[5.75rem] items-center justify-end gap-1">
+                  <template v-if="confirmDeleteId === row.session.id">
+                    <button
+                      class="inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                      title="Cancel delete"
+                      aria-label="Cancel delete session"
+                      @click="clearConfirmDelete"
+                    >
+                      <X :size="14" />
+                    </button>
+                    <button
+                      class="inline-flex h-6 items-center justify-center rounded px-1.5 text-[10px] font-medium uppercase tracking-wide transition-colors bg-destructive/15 text-destructive ring-1 ring-destructive/40"
+                      title="Click again to confirm delete"
+                      aria-label="Confirm delete session"
+                      @click="() => handleDeleteClick(row.session.id)"
+                    >
+                      Confirm
+                    </button>
+                  </template>
                   <button
-                    class="inline-flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-                    title="Cancel delete"
-                    aria-label="Cancel delete session"
-                    @click="clearConfirmDelete"
+                    v-else
+                    class="inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-destructive"
+                    title="Delete"
+                    aria-label="Delete session"
+                    @click="() => handleDeleteClick(row.session.id)"
                   >
-                    <X :size="14" />
+                    <Trash2 :size="14" />
                   </button>
-                  <button
-                    class="inline-flex h-7 items-center justify-center rounded px-2 text-xs font-medium uppercase tracking-wide transition-colors bg-destructive/15 text-destructive ring-1 ring-destructive/40"
-                    title="Click again to confirm delete"
-                    aria-label="Confirm delete session"
-                    @click="() => handleDeleteClick(session.id)"
-                  >
-                    Confirm
-                  </button>
-                </template>
-                <button
-                  v-else
-                  class="inline-flex h-7 w-7 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-destructive"
-                  title="Delete"
-                  aria-label="Delete session"
-                  @click="() => handleDeleteClick(session.id)"
-                >
-                  <Trash2 :size="14" />
-                </button>
-              </div>
-            </td>
-          </tr>
+                </div>
+              </td>
+            </tr>
+          </template>
         </tbody>
       </table>
     </div>
 
-    <div v-if="total > 0" class="flex items-center justify-between mt-4 text-sm text-muted-foreground">
-      <span>Showing {{ startItem }}-{{ endItem }} of {{ total }} sessions</span>
-      <div class="flex items-center gap-2">
-        <button
-          class="px-3 py-1.5 rounded border border-border bg-card hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed text-foreground text-sm"
-          :disabled="page <= 1"
-          @click="handlePrevPage"
-        >
-          Prev
-        </button>
-        <span class="text-xs">{{ page }} / {{ totalPages }}</span>
-        <button
-          class="px-3 py-1.5 rounded border border-border bg-card hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed text-foreground text-sm"
-          :disabled="page >= totalPages"
-          @click="handleNextPage"
-        >
-          Next
-        </button>
-      </div>
+    <div v-if="total > 0" class="mt-4 flex flex-col items-center gap-2">
+      <button
+        v-if="hasMore"
+        class="inline-flex items-center gap-1.5 px-4 py-1.5 rounded border border-border bg-card hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed text-foreground text-sm transition-colors"
+        :disabled="loadingMore"
+        @click="handleLoadMore"
+      >
+        <Loader2 v-if="loadingMore" :size="14" class="animate-spin" />
+        Load more
+      </button>
+      <span class="text-xs text-muted-foreground">Showing {{ sessions.length }} of {{ total }} sessions</span>
     </div>
   </div>
 </template>
diff --git a/client/src/features/book/components/detail/tabs/__tests__/HighlightsExportMenu.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/HighlightsExportMenu.spec.ts
index 8d5c9629f..ada8a8d5b 100644
--- a/client/src/features/book/components/detail/tabs/__tests__/HighlightsExportMenu.spec.ts
+++ b/client/src/features/book/components/detail/tabs/__tests__/HighlightsExportMenu.spec.ts
@@ -8,11 +8,16 @@ function makeHighlight(overrides: Partial<AnnotationItem> = {}): AnnotationItem
     id: 1,
     bookId: 5,
     cfi: 'epubcfi(/6/4)',
+    jumpFileId: 10,
+    pageno: null,
     text: 'highlighted text',
     color: '#FACC15',
     style: 'highlight',
     note: null,
     chapterTitle: 'Chapter 1',
+    origin: 'web',
+    positionStatus: 'exact',
+    chapterIndex: null,
     createdAt: '2026-01-01T00:00:00.000Z',
     ...overrides,
   }
@@ -40,10 +45,16 @@ function setupDownloadMocks() {
   return { createObjectURL, revokeObjectURL, clickMock }
 }
 
+const stubs = {
+  Popover: { name: 'Popover', props: ['open'], template: '<div><slot /></div>' },
+  PopoverTrigger: { template: '<div><slot /></div>' },
+  PopoverContent: { template: '<div><slot /></div>' },
+}
+
 function mountMenu(items: AnnotationItem[], bookTitle = 'Test Book') {
   return mount(HighlightsExportMenu, {
     props: { items, bookTitle },
-    global: { stubs: { teleport: true } },
+    global: { stubs },
   })
 }
 
@@ -63,9 +74,8 @@ describe('HighlightsExportMenu', () => {
     expect(btn.attributes('disabled')).toBeDefined()
   })
 
-  it('opens menu on click', async () => {
+  it('shows export options', () => {
     const wrapper = mountMenu([makeHighlight()])
-    await wrapper.find('button').trigger('click')
     expect(wrapper.text()).toContain('Markdown')
     expect(wrapper.text()).toContain('Plain Text')
     expect(wrapper.text()).toContain('JSON')
@@ -76,7 +86,6 @@ describe('HighlightsExportMenu', () => {
 
     const wrapper = mountMenu([makeHighlight({ text: 'my highlight', note: 'my note', chapterTitle: 'Ch 1' })], 'Test Book')
 
-    await wrapper.find('button').trigger('click')
     const mdBtn = wrapper.findAll('button').find((b) => b.text().includes('Markdown'))!
     await mdBtn.trigger('click')
 
@@ -90,7 +99,6 @@ describe('HighlightsExportMenu', () => {
 
     const wrapper = mountMenu([makeHighlight()])
 
-    await wrapper.find('button').trigger('click')
     const jsonBtn = wrapper.findAll('button').find((b) => b.text().includes('JSON'))!
     await jsonBtn.trigger('click')
 
@@ -103,7 +111,6 @@ describe('HighlightsExportMenu', () => {
 
     const wrapper = mountMenu([makeHighlight()])
 
-    await wrapper.find('button').trigger('click')
     const txtBtn = wrapper.findAll('button').find((b) => b.text().includes('Plain Text'))!
     await txtBtn.trigger('click')
 
@@ -115,12 +122,10 @@ describe('HighlightsExportMenu', () => {
     setupDownloadMocks()
 
     const wrapper = mountMenu([makeHighlight()])
-    await wrapper.find('button').trigger('click')
-    expect(wrapper.text()).toContain('Markdown')
 
     const mdBtn = wrapper.findAll('button').find((b) => b.text().includes('Markdown'))!
     await mdBtn.trigger('click')
 
-    expect(wrapper.text()).not.toContain('Plain Text')
+    expect(wrapper.findComponent({ name: 'Popover' }).props('open')).toBe(false)
   })
 })
diff --git a/client/src/features/book/components/detail/tabs/__tests__/HighlightsFilterBar.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/HighlightsFilterBar.spec.ts
deleted file mode 100644
index 945fac0c2..000000000
--- a/client/src/features/book/components/detail/tabs/__tests__/HighlightsFilterBar.spec.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-import { mount } from '@vue/test-utils'
-import { describe, expect, it, vi } from 'vitest'
-import HighlightsFilterBar from '../HighlightsFilterBar.vue'
-
-function makeProps(overrides = {}) {
-  return {
-    activeColors: [] as string[],
-    chapters: ['Chapter 1', 'Chapter 2'],
-    selectedChapter: undefined as string | undefined,
-    dateFrom: undefined as string | undefined,
-    dateTo: undefined as string | undefined,
-    ...overrides,
-  }
-}
-
-describe('HighlightsFilterBar', () => {
-  it('renders search input', () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const input = wrapper.find('input[type="text"]')
-    expect(input.exists()).toBe(true)
-    expect(input.attributes('placeholder')).toBe('Search highlights...')
-  })
-
-  it('renders color filter buttons', () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const colorButtons = wrapper.findAll('button[title]')
-    expect(colorButtons.length).toBe(5)
-  })
-
-  it('emits toggleColor when a color button is clicked', async () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const yellowBtn = wrapper.find('button[title="Yellow"]')
-    await yellowBtn.trigger('click')
-    expect(wrapper.emitted('toggleColor')).toBeTruthy()
-    expect(wrapper.emitted('toggleColor')![0]).toEqual(['#FACC15'])
-  })
-
-  it('highlights active color buttons', () => {
-    const wrapper = mount(HighlightsFilterBar, {
-      props: makeProps({ activeColors: ['#FACC15'] }),
-    })
-    const yellowBtn = wrapper.find('button[title="Yellow"]')
-    expect(yellowBtn.classes()).toContain('border-foreground')
-  })
-
-  it('renders chapter dropdown when chapters exist', () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const select = wrapper.find('select')
-    expect(select.exists()).toBe(true)
-    const options = select.findAll('option')
-    expect(options.length).toBe(3)
-    expect(options[0]?.text()).toBe('All chapters')
-  })
-
-  it('does not render chapter dropdown when no chapters', () => {
-    const wrapper = mount(HighlightsFilterBar, {
-      props: makeProps({ chapters: [] }),
-    })
-    expect(wrapper.find('select').exists()).toBe(false)
-  })
-
-  it('emits chapterChange when chapter is selected', async () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const select = wrapper.find('select')
-    await select.setValue('Chapter 1')
-    expect(wrapper.emitted('chapterChange')).toBeTruthy()
-    expect(wrapper.emitted('chapterChange')![0]).toEqual(['Chapter 1'])
-  })
-
-  it('renders date range inputs', () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const dateInputs = wrapper.findAll('input[type="date"]')
-    expect(dateInputs.length).toBe(2)
-  })
-
-  it('emits dateRangeChange when date from changes', async () => {
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const dateInputs = wrapper.findAll('input[type="date"]')
-    await dateInputs[0]?.setValue('2026-01-01')
-    expect(wrapper.emitted('dateRangeChange')).toBeTruthy()
-    expect(wrapper.emitted('dateRangeChange')![0]).toEqual(['2026-01-01', undefined])
-  })
-
-  it('emits search with debounce on input', async () => {
-    vi.useFakeTimers()
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const input = wrapper.find('input[type="text"]')
-
-    await input.setValue('test')
-    await input.trigger('input')
-    expect(wrapper.emitted('search')).toBeFalsy()
-
-    vi.advanceTimersByTime(300)
-    expect(wrapper.emitted('search')).toBeTruthy()
-
-    vi.useRealTimers()
-  })
-
-  it('shows clear button when search has value and emits on click', async () => {
-    vi.useFakeTimers()
-    const wrapper = mount(HighlightsFilterBar, { props: makeProps() })
-    const input = wrapper.find('input[type="text"]')
-
-    await input.setValue('test')
-    const clearBtn = wrapper.findAll('button').find((b) => !b.attributes('title'))
-    expect(clearBtn).toBeTruthy()
-
-    vi.useRealTimers()
-  })
-})
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHeatmap.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHeatmap.spec.ts
new file mode 100644
index 000000000..88b8d4fe8
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHeatmap.spec.ts
@@ -0,0 +1,41 @@
+import { mount } from '@vue/test-utils'
+import { createPinia } from 'pinia'
+import { describe, expect, it, vi } from 'vitest'
+import type { BookReadingSessionStats } from '@bookorbit/types'
+
+vi.mock('vue-echarts', () => ({
+  default: { name: 'VChart', props: ['option'], template: '<div />' },
+}))
+
+import ReadingLogHeatmap from '../ReadingLogHeatmap.vue'
+
+function makeStats(): BookReadingSessionStats {
+  return {
+    totalSessions: 1,
+    totalSeconds: 1800,
+    avgDurationSeconds: 1800,
+    firstSessionAt: '2026-06-08T10:00:00.000Z',
+    lastSessionAt: '2026-06-08T10:30:00.000Z',
+    dailySummary: [{ day: '2026-06-08', totalMinutes: 30 }],
+    paceProgressDelta: 0,
+    paceDurationSeconds: 0,
+    progressSummary: [],
+    bySource: [],
+  }
+}
+
+describe('ReadingLogHeatmap', () => {
+  it('configures the activity axis with every weekday starting on Monday', () => {
+    const wrapper = mount(ReadingLogHeatmap, {
+      props: { stats: makeStats(), loading: false, quickFilter: 'all' },
+      global: { plugins: [createPinia()] },
+    })
+
+    const option = wrapper.findComponent({ name: 'VChart' }).props('option') as {
+      calendar?: { dayLabel?: { firstDay?: number; nameMap?: string[] } }
+    }
+
+    expect(option.calendar?.dayLabel?.firstDay).toBe(1)
+    expect(option.calendar?.dayLabel?.nameMap).toEqual(['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'])
+  })
+})
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHero.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHero.spec.ts
new file mode 100644
index 000000000..55cc0f98c
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogHero.spec.ts
@@ -0,0 +1,492 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import type { Component } from 'vue'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { BookDetail, BookReadingSessionStats, UserBookStatus } from '@bookorbit/types'
+
+const mocks = vi.hoisted(() => ({
+  api: vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>(),
+  setStatus: vi.fn<(bookId: number, status: string) => Promise<UserBookStatus>>(),
+  updateStatus: vi.fn<(bookId: number, patch: Record<string, string | null>) => Promise<UserBookStatus>>(),
+}))
+
+vi.mock('@/lib/api', () => ({
+  api: mocks.api,
+}))
+
+vi.mock('@/features/book/composables/useBookStatus', () => {
+  const MockIcon = { template: '<span />' }
+  return {
+    STATUS_COLORS: {
+      unread: '',
+      want_to_read: '',
+      reading: '',
+      on_hold: '',
+      rereading: '',
+      read: '',
+      skimmed: '',
+      abandoned: '',
+    },
+    STATUS_ICONS: {
+      unread: MockIcon,
+      want_to_read: MockIcon,
+      reading: MockIcon,
+      on_hold: MockIcon,
+      rereading: MockIcon,
+      read: MockIcon,
+      skimmed: MockIcon,
+      abandoned: MockIcon,
+    },
+    STATUS_OPTIONS: [
+      { value: 'reading', label: 'Reading' },
+      { value: 'read', label: 'Read' },
+    ],
+    useBookStatus: () => ({
+      setStatus: mocks.setStatus,
+      updateStatus: mocks.updateStatus,
+    }),
+  }
+})
+
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenu: { template: '<div><slot /></div>' },
+  DropdownMenuContent: { template: '<div><slot /></div>' },
+  DropdownMenuItem: { template: '<button type="button"><slot /></button>' },
+  DropdownMenuTrigger: { template: '<div><slot /></div>' },
+}))
+
+vi.mock('@/features/achievements/components/AchievementProgressRing.vue', () => ({
+  default: { template: '<div />' },
+}))
+
+import ReadingLogHero from '../ReadingLogHero.vue'
+
+function makeReadStatus(overrides: Partial<UserBookStatus> = {}): UserBookStatus {
+  return {
+    status: 'reading',
+    source: 'manual',
+    startedAt: '2026-04-01',
+    finishedAt: '2026-04-20',
+    updatedAt: '2026-04-21T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+function makeBook(overrides: Partial<BookDetail> = {}): BookDetail {
+  return {
+    id: 10,
+    libraryId: 1,
+    libraryName: 'My Library',
+    status: 'ok',
+    folderPath: '/books',
+    addedAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: null,
+    title: 'Test Book',
+    subtitle: null,
+    description: null,
+    isbn10: null,
+    isbn13: null,
+    publisher: null,
+    publishedYear: null,
+    language: null,
+    pageCount: null,
+    seriesName: null,
+    seriesIndex: null,
+    rating: null,
+    coverSource: null,
+    providerIds: {},
+    authors: [],
+    genres: [],
+    tags: [],
+    files: [],
+    lastWrittenAt: null,
+    metadataScore: null,
+    hardcoverEditionId: null,
+    communityRatings: [],
+    readStatus: makeReadStatus(),
+    audioMetadata: null,
+    formatPriority: [],
+    comicMetadata: null,
+    customMetadata: [],
+    lockedFields: [],
+    collections: [],
+    ...overrides,
+  }
+}
+
+function makeStats(overrides: Partial<BookReadingSessionStats> = {}): BookReadingSessionStats {
+  return {
+    totalSessions: 1,
+    totalSeconds: 1800,
+    avgDurationSeconds: 1800,
+    firstSessionAt: '2026-04-15T10:00:00.000Z',
+    lastSessionAt: '2026-04-16T10:00:00.000Z',
+    dailySummary: [],
+    paceProgressDelta: 0,
+    paceDurationSeconds: 0,
+    progressSummary: [],
+    bySource: [],
+    ...overrides,
+  }
+}
+
+function mountHero(book = makeBook(), stats = makeStats()) {
+  return mount(ReadingLogHero as Component, {
+    props: { book, stats, loading: false },
+  })
+}
+
+function makeResponse(data: unknown): Response {
+  return {
+    ok: true,
+    json: async () => data,
+  } as Response
+}
+
+describe('ReadingLogHero', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-06-24T12:00:00.000Z'))
+    mocks.api.mockReset()
+    mocks.api.mockResolvedValue(makeResponse([]))
+    mocks.setStatus.mockReset()
+    mocks.updateStatus.mockReset()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('renders session dates separately from editable lifecycle dates', async () => {
+    const wrapper = mountHero()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('First Read')
+    expect(wrapper.text()).toContain('Last Read')
+    expect(wrapper.text()).toContain('Date Started')
+    expect(wrapper.text()).toContain('Apr 1, 2026')
+    expect(wrapper.text()).toContain('Date Finished')
+    expect(wrapper.text()).toContain('Apr 20, 2026')
+  })
+
+  it('keeps lifecycle date editing wired to the read status API', async () => {
+    const updated = makeReadStatus({ startedAt: '2026-04-02' })
+    mocks.updateStatus.mockResolvedValue(updated)
+    const wrapper = mountHero()
+    await flushPromises()
+
+    const startButton = wrapper.findAll('button').find((button) => button.text() === 'Apr 1, 2026')
+    expect(startButton).toBeDefined()
+    await startButton!.trigger('click')
+
+    const input = wrapper.find('input[type="date"]')
+    await input.setValue('2026-04-02')
+    await input.trigger('blur')
+    await flushPromises()
+
+    expect(mocks.updateStatus).toHaveBeenCalledWith(10, { startedAt: '2026-04-02' })
+    expect(wrapper.emitted('saved')?.[0]).toEqual([updated])
+  })
+
+  it('validates lifecycle dates before saving', async () => {
+    const wrapper = mountHero()
+    await flushPromises()
+
+    const finishButton = wrapper.findAll('button').find((button) => button.text() === 'Apr 20, 2026')
+    expect(finishButton).toBeDefined()
+    await finishButton!.trigger('click')
+
+    const input = wrapper.find('input[type="date"]')
+    await input.setValue('2026-07-01')
+    await input.trigger('blur')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Finish date cannot be in the future.')
+    expect(mocks.updateStatus).not.toHaveBeenCalled()
+  })
+
+  it('rejects invalid lifecycle date order and failed date saves', async () => {
+    const invalidWrapper = mountHero()
+    await flushPromises()
+
+    const invalidFinishButton = invalidWrapper.findAll('button').find((button) => button.text() === 'Apr 20, 2026')
+    await invalidFinishButton!.trigger('click')
+    await invalidWrapper.find('input[type="date"]').setValue('2026-03-31')
+    await invalidWrapper.find('input[type="date"]').trigger('blur')
+    await flushPromises()
+
+    expect(invalidWrapper.text()).toContain('Finish date must be on or after the start date.')
+
+    mocks.updateStatus.mockRejectedValue(new Error('save failed'))
+    const failedWrapper = mountHero()
+    await flushPromises()
+
+    const startButton = failedWrapper.findAll('button').find((button) => button.text() === 'Apr 1, 2026')
+    await startButton!.trigger('click')
+    await failedWrapper.find('input[type="date"]').setValue('2026-04-02')
+    await failedWrapper.find('input[type="date"]').trigger('blur')
+    await flushPromises()
+
+    expect(failedWrapper.text()).toContain('Failed to save reading dates.')
+  })
+
+  it('closes lifecycle date editing when unchanged or canceled', async () => {
+    const wrapper = mountHero()
+    await flushPromises()
+
+    const startButton = wrapper.findAll('button').find((button) => button.text() === 'Apr 1, 2026')
+    await startButton!.trigger('click')
+    await wrapper.find('input[type="date"]').trigger('blur')
+    await flushPromises()
+
+    expect(mocks.updateStatus).not.toHaveBeenCalled()
+    expect(wrapper.find('input[type="date"]').exists()).toBe(false)
+
+    await startButton!.trigger('click')
+    await wrapper.find('input[type="date"]').setValue('2026-04-03')
+    await wrapper.find('input[type="date"]').trigger('keydown', { key: 'Escape' })
+    await flushPromises()
+
+    expect(mocks.updateStatus).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('Apr 1, 2026')
+
+    const finishButton = wrapper.findAll('button').find((button) => button.text() === 'Apr 20, 2026')
+    await finishButton!.trigger('click')
+    await wrapper.find('input[type="date"]').setValue('2026-04-21')
+    await wrapper.find('input[type="date"]').trigger('keydown', { key: 'Escape' })
+    await flushPromises()
+
+    expect(mocks.updateStatus).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('Apr 20, 2026')
+  })
+
+  it('updates status through the status menu', async () => {
+    const updated = makeReadStatus({ status: 'read' })
+    mocks.setStatus.mockResolvedValue(updated)
+    const wrapper = mountHero()
+    await flushPromises()
+
+    const readButton = wrapper.findAll('button').find((button) => button.text() === 'Read')
+    expect(readButton).toBeDefined()
+    await readButton!.trigger('click')
+    await flushPromises()
+
+    expect(mocks.setStatus).toHaveBeenCalledWith(10, 'read')
+    expect(wrapper.emitted('saved')?.[0]).toEqual([updated])
+  })
+
+  it('reverts local status when the status update fails', async () => {
+    mocks.setStatus.mockRejectedValue(new Error('network failed'))
+    const wrapper = mountHero()
+    await flushPromises()
+
+    const readButton = wrapper.findAll('button').find((button) => button.text() === 'Read')
+    await readButton!.trigger('click')
+    await flushPromises()
+
+    expect(mocks.setStatus).toHaveBeenCalledWith(10, 'read')
+    expect(wrapper.emitted('saved')).toBeUndefined()
+    expect(wrapper.text()).toContain('Reading')
+  })
+
+  it('loads progress from ebook and audiobook progress endpoints', async () => {
+    mocks.api.mockImplementation(async (input) => {
+      const url = String(input)
+      if (url.includes('audio-progress')) return makeResponse({ percentage: 99.6 })
+      return makeResponse([{ fileId: 1, percentage: 0.5 }])
+    })
+    const wrapper = mountHero(
+      makeBook({
+        files: [
+          {
+            id: 1,
+            format: 'mp3',
+            role: 'primary',
+            sizeBytes: null,
+            absolutePath: '/books/audio.mp3',
+            createdAt: '2026-01-01T00:00:00.000Z',
+            filename: 'audio.mp3',
+            durationSeconds: null,
+          },
+        ],
+      }),
+    )
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('>99%')
+    expect(mocks.api).toHaveBeenCalledWith('/api/v1/books/10/audio-progress')
+  })
+
+  it('ignores non-ok and malformed progress responses', async () => {
+    mocks.api.mockImplementation(async (input) => {
+      const url = String(input)
+      if (url.includes('audio-progress')) return makeResponse({ percentage: Number.NaN })
+      return { ok: false, json: async () => [] } as Response
+    })
+    const wrapper = mountHero(
+      makeBook({
+        files: [
+          {
+            id: 1,
+            format: 'm4b',
+            role: 'primary',
+            sizeBytes: null,
+            absolutePath: '/books/audio.m4b',
+            createdAt: '2026-01-01T00:00:00.000Z',
+            filename: 'audio.m4b',
+            durationSeconds: null,
+          },
+        ],
+      }),
+    )
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('0%')
+  })
+
+  it('renders eta and emits add-session actions', async () => {
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 50 }]))
+    const wrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 50, paceDurationSeconds: 3600 }))
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('~1h to finish')
+    const addButton = wrapper.findAll('button').find((button) => button.text() === 'Add session')
+    await addButton!.trigger('click')
+
+    expect(wrapper.emitted('addSession')).toHaveLength(1)
+  })
+
+  it('renders mixed hour and minute eta labels', async () => {
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 10 }]))
+    const wrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 20, paceDurationSeconds: 3600 }))
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('~4h 30m to finish')
+  })
+
+  it('renders minute-only, whole-hour, and capped eta labels', async () => {
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 99 }]))
+    const minuteWrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 50, paceDurationSeconds: 3600 }))
+    await flushPromises()
+    expect(minuteWrapper.text()).toContain('~5m to finish')
+
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 50 }]))
+    const hourWrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 25, paceDurationSeconds: 3600 }))
+    await flushPromises()
+    expect(hourWrapper.text()).toContain('~2h to finish')
+
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 1 }]))
+    const cappedWrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 0.1, paceDurationSeconds: 3600 }))
+    await flushPromises()
+    expect(cappedWrapper.text()).toContain('99h+ to finish')
+  })
+
+  it('hides eta for terminal statuses and invalid pace inputs', async () => {
+    mocks.api.mockResolvedValue(makeResponse([{ fileId: 1, percentage: 50 }]))
+    const readWrapper = mountHero(
+      makeBook({ readStatus: makeReadStatus({ status: 'read' }) }),
+      makeStats({ paceProgressDelta: 50, paceDurationSeconds: 3600 }),
+    )
+    await flushPromises()
+    expect(readWrapper.text()).not.toContain('to finish')
+
+    const noPaceWrapper = mountHero(makeBook(), makeStats({ paceProgressDelta: 0, paceDurationSeconds: 3600 }))
+    await flushPromises()
+    expect(noPaceWrapper.text()).not.toContain('to finish')
+  })
+
+  it('falls back to zero progress when progress loading fails', async () => {
+    mocks.api.mockRejectedValue(new Error('progress failed'))
+    const wrapper = mountHero()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('0%')
+  })
+
+  it('falls back to zero progress when progress parsing fails', async () => {
+    mocks.api.mockResolvedValue({
+      ok: true,
+      json: async () => {
+        throw new Error('bad json')
+      },
+    } as unknown as Response)
+    const wrapper = mountHero()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('0%')
+  })
+
+  it('renders momentum titles for upward, downward, and unchanged trends', async () => {
+    const newActivity = mountHero(
+      makeBook(),
+      makeStats({
+        dailySummary: [{ day: '2026-06-24', totalMinutes: 20 }],
+      }),
+    )
+    await flushPromises()
+    expect(newActivity.find('[title="New activity this week"]').exists()).toBe(true)
+
+    const upward = mountHero(
+      makeBook(),
+      makeStats({
+        dailySummary: [
+          { day: '2026-06-24', totalMinutes: 20 },
+          { day: '2026-06-17', totalMinutes: 10 },
+        ],
+      }),
+    )
+    await flushPromises()
+    expect(upward.find('[title="+100% vs previous 7 days"]').exists()).toBe(true)
+
+    const downward = mountHero(
+      makeBook(),
+      makeStats({
+        dailySummary: [
+          { day: '2026-06-24', totalMinutes: 10 },
+          { day: '2026-06-17', totalMinutes: 20 },
+        ],
+      }),
+    )
+    await flushPromises()
+    expect(downward.find('[title="-50% vs previous 7 days"]').exists()).toBe(true)
+
+    const unchanged = mountHero(
+      makeBook(),
+      makeStats({
+        dailySummary: [
+          { day: '2026-06-24', totalMinutes: 10 },
+          { day: '2026-06-17', totalMinutes: 10 },
+        ],
+      }),
+    )
+    await flushPromises()
+    expect(unchanged.find('[title="Unchanged vs previous 7 days"]').exists()).toBe(true)
+  })
+
+  it('renders empty and loading states without session dates', async () => {
+    const emptyWrapper = mountHero(makeBook({ readStatus: null }), makeStats({ firstSessionAt: null, lastSessionAt: null }))
+    await flushPromises()
+
+    expect(emptyWrapper.text()).toContain('No sessions')
+    expect(emptyWrapper.text()).toContain('Not set')
+
+    const loadingWrapper = mount(ReadingLogHero as Component, {
+      props: { book: makeBook(), stats: null, loading: true },
+    })
+    await flushPromises()
+
+    expect(loadingWrapper.text()).toContain('Add session')
+  })
+
+  it('normalizes invalid lifecycle dates to empty display values', async () => {
+    const wrapper = mountHero(
+      makeBook({
+        readStatus: makeReadStatus({ startedAt: 'not-a-date', finishedAt: 'also-not-a-date' }),
+      }),
+      makeStats({ lastSessionAt: '2024-04-15T10:00:00.000Z' }),
+    )
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Not set')
+    expect(wrapper.text()).toContain('2 years ago')
+  })
+})
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogSourceSplit.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogSourceSplit.spec.ts
new file mode 100644
index 000000000..8bbb98f4b
--- /dev/null
+++ b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogSourceSplit.spec.ts
@@ -0,0 +1,94 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import type { BookReadingSourceSlice } from '@bookorbit/types'
+
+import ReadingLogSourceSplit from '../ReadingLogSourceSplit.vue'
+
+function makeStats(bySource: BookReadingSourceSlice[]) {
+  return {
+    totalSessions: 0,
+    totalSeconds: 0,
+    avgDurationSeconds: 0,
+    firstSessionAt: null,
+    lastSessionAt: null,
+    dailySummary: [],
+    paceProgressDelta: 0,
+    paceDurationSeconds: 0,
+    progressSummary: [],
+    bySource,
+  }
+}
+
+describe('ReadingLogSourceSplit', () => {
+  it('renders nothing when stats is null', () => {
+    const wrapper = mount(ReadingLogSourceSplit, { props: { stats: null } })
+    expect(wrapper.find('div').exists()).toBe(false)
+  })
+
+  it('renders nothing when there are no source slices', () => {
+    const wrapper = mount(ReadingLogSourceSplit, { props: { stats: makeStats([]) } })
+    expect(wrapper.find('div').exists()).toBe(false)
+  })
+
+  it('renders nothing when the book was read from a single source', () => {
+    const wrapper = mount(ReadingLogSourceSplit, {
+      props: { stats: makeStats([{ bucket: 'koreader', totalSeconds: 100, totalSessions: 2 }]) },
+    })
+    expect(wrapper.find('div').exists()).toBe(false)
+  })
+
+  it('renders a labelled split with percentages and durations across sources', () => {
+    const wrapper = mount(ReadingLogSourceSplit, {
+      props: {
+        stats: makeStats([
+          { bucket: 'bookorbit', totalSeconds: 3600, totalSessions: 4 },
+          { bucket: 'koreader', totalSeconds: 120, totalSessions: 1 },
+          { bucket: 'kobo', totalSeconds: 30, totalSessions: 1 },
+        ]),
+      },
+    })
+
+    expect(wrapper.find('div').exists()).toBe(true)
+    const text = wrapper.text()
+    expect(text).toContain('Where you read this book')
+    expect(text).toContain('BookOrbit')
+    expect(text).toContain('KOReader')
+    expect(text).toContain('Kobo')
+    // total = 3750s -> 96% / 3% / 1%
+    expect(text).toContain('96%')
+    expect(text).toContain('3%')
+    expect(text).toContain('1%')
+    // formatDuration: hours, minutes and seconds branches
+    expect(text).toContain('1h 0m')
+    expect(text).toContain('2m')
+    expect(text).toContain('30s')
+  })
+
+  it('stays hidden when buckets exist but carry no reading time', () => {
+    const wrapper = mount(ReadingLogSourceSplit, {
+      props: {
+        stats: makeStats([
+          { bucket: 'bookorbit', totalSeconds: 0, totalSessions: 1 },
+          { bucket: 'kobo', totalSeconds: 0, totalSessions: 1 },
+        ]),
+      },
+    })
+    expect(wrapper.find('div').exists()).toBe(false)
+  })
+
+  it('sizes each bar segment proportionally to its reading time', () => {
+    const wrapper = mount(ReadingLogSourceSplit, {
+      props: {
+        stats: makeStats([
+          { bucket: 'bookorbit', totalSeconds: 300, totalSessions: 2 },
+          { bucket: 'kobo', totalSeconds: 100, totalSessions: 1 },
+        ]),
+      },
+    })
+
+    const segments = wrapper.findAll('.h-full')
+    expect(segments).toHaveLength(2)
+    expect(segments[0]!.attributes('style')).toContain('width: 75%')
+    expect(segments[1]!.attributes('style')).toContain('width: 25%')
+  })
+})
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogStatsStrip.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogStatsStrip.spec.ts
deleted file mode 100644
index c6c491cb3..000000000
--- a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogStatsStrip.spec.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { mount } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
-import ReadingLogStatsStrip from '../ReadingLogStatsStrip.vue'
-
-function makeStats(overrides = {}) {
-  return {
-    totalSessions: 5,
-    totalSeconds: 3780,
-    avgDurationSeconds: 756,
-    firstSessionAt: '2026-01-15T10:00:00.000Z',
-    lastSessionAt: '2026-04-15T10:00:00.000Z',
-    dailySummary: [],
-    ...overrides,
-  }
-}
-
-function makeProps(overrides = {}) {
-  return {
-    stats: makeStats(),
-    loading: false,
-    quickFilter: 'all' as const,
-    ...overrides,
-  }
-}
-
-describe('ReadingLogStatsStrip', () => {
-  it('shows skeleton cards on initial load (stats=null and loading=true)', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: null, loading: true }),
-    })
-    expect(wrapper.findAll('.animate-shimmer').length).toBeGreaterThan(0)
-  })
-
-  it('does not show skeleton when loading=true but stats already loaded (uses opacity instead)', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ loading: true }),
-    })
-    expect(wrapper.find('.animate-shimmer').exists()).toBe(false)
-    expect(wrapper.find('.opacity-50').exists()).toBe(true)
-  })
-
-  it('renders 8 stat cards when stats loaded and not loading', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps(),
-    })
-    expect(wrapper.findAll('.rounded-lg.border').length).toBe(8)
-  })
-
-  it('renders 8 stat cards when stats loaded even while re-fetching', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ loading: true }),
-    })
-    expect(wrapper.findAll('.rounded-lg.border').length).toBe(8)
-  })
-
-  it('formats 3780 seconds as "1h 3m"', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: makeStats({ totalSeconds: 3780 }) }),
-    })
-    expect(wrapper.text()).toContain('1h 3m')
-  })
-
-  it('shows "-" for null firstSessionAt', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: makeStats({ firstSessionAt: null }) }),
-    })
-    expect(wrapper.text()).toContain('-')
-  })
-
-  it('shows 0 for 0 total sessions', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: makeStats({ totalSessions: 0 }) }),
-    })
-    expect(wrapper.text()).toContain('0')
-  })
-
-  it('formats 0 seconds as "0s"', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: makeStats({ totalSeconds: 0, avgDurationSeconds: 0 }) }),
-    })
-    expect(wrapper.text()).toContain('0s')
-  })
-
-  it('shows 0s total when stats is null and not loading', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps({ stats: null }),
-    })
-    expect(wrapper.text()).toContain('0s')
-  })
-
-  it('does not apply opacity class when not loading', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps(),
-    })
-    expect(wrapper.find('.opacity-50').exists()).toBe(false)
-  })
-
-  it('renders new derived stats cards', () => {
-    const wrapper = mount(ReadingLogStatsStrip, {
-      props: makeProps(),
-    })
-    expect(wrapper.text()).toContain('Consistency')
-    expect(wrapper.text()).toContain('Momentum')
-    expect(wrapper.text()).toContain('Active Days')
-  })
-})
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTab.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTab.spec.ts
index f547e468a..cba81702d 100644
--- a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTab.spec.ts
+++ b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTab.spec.ts
@@ -67,7 +67,17 @@ function makeListResponse(items = []) {
       total: items.length,
       page: 1,
       pageSize: 25,
-      stats: { totalSessions: items.length, totalSeconds: 0, avgDurationSeconds: 0, firstSessionAt: null, lastSessionAt: null, dailySummary: [] },
+      stats: {
+        totalSessions: items.length,
+        totalSeconds: 0,
+        avgDurationSeconds: 0,
+        firstSessionAt: null,
+        lastSessionAt: null,
+        dailySummary: [],
+        paceProgressDelta: 0,
+        paceDurationSeconds: 0,
+        progressSummary: [],
+      },
     }),
   } as Response
 }
@@ -88,14 +98,13 @@ describe('ReadingLogTab', () => {
     expect(wrapper.text()).toContain('This year')
   })
 
-  it('sparkline is rendered but chart area is hidden when dailySummary is empty', async () => {
+  it('renders the hero and chart empty states when there is no data', async () => {
     const wrapper = mount(ReadingLogTab, { props: { book: makeBook() }, global: { plugins: [createPinia()] } })
     await flushPromises()
 
-    const sparkline = wrapper.findComponent({ name: 'ReadingLogSparkline' })
-    expect(sparkline.exists()).toBe(true)
-    const chartArea = sparkline.find('[style*="height: 120px"]')
-    expect(chartArea.exists()).toBe(false)
+    expect(wrapper.text()).toContain('Add session')
+    expect(wrapper.text()).toContain('No progress data in this window.')
+    expect(wrapper.text()).toContain('No reading activity in this window.')
   })
 
   it('calls setFilters with dateFrom when "Last 30 days" is clicked', async () => {
diff --git a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTable.spec.ts b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTable.spec.ts
index 6a9d430e3..4fe09f2ae 100644
--- a/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTable.spec.ts
+++ b/client/src/features/book/components/detail/tabs/__tests__/ReadingLogTable.spec.ts
@@ -11,6 +11,7 @@ function makeSession(overrides = {}) {
     progressDelta: 5.5,
     endProgress: 42.0,
     format: 'epub',
+    source: null,
     ...overrides,
   }
 }
@@ -20,11 +21,11 @@ function mountTable(props = {}) {
     props: {
       sessions: [makeSession()],
       total: 1,
-      page: 1,
-      pageSize: 25,
       sortBy: 'startedAt',
       sortDir: 'desc' as const,
       loading: false,
+      loadingMore: false,
+      hasMore: false,
       hasMultipleFormats: false,
       ...props,
     },
@@ -42,16 +43,6 @@ describe('ReadingLogTable', () => {
     expect(wrapper.text()).toContain('No reading sessions recorded yet')
   })
 
-  it('does not show edit inputs (edit mode removed)', () => {
-    const wrapper = mountTable()
-    expect(wrapper.find('input[type="datetime-local"]').exists()).toBe(false)
-  })
-
-  it('does not show edit pencil button (edit mode removed)', () => {
-    const wrapper = mountTable()
-    expect(wrapper.find('button[title="Edit"]').exists()).toBe(false)
-  })
-
   it('first delete click enters confirm state', async () => {
     const wrapper = mountTable()
     const deleteBtn = wrapper.find('button[title="Delete"]')
@@ -116,6 +107,78 @@ describe('ReadingLogTable', () => {
     expect(wrapper.find('tbody').text()).toContain('-')
   })
 
+  it('shows pace per hour derived from delta and duration', () => {
+    const wrapper = mountTable({ sessions: [makeSession({ progressDelta: 5, durationSeconds: 1800 })] })
+    expect(wrapper.text()).toContain('10.0%/hr')
+  })
+
+  it('shows "-" pace when progressDelta is null', () => {
+    const wrapper = mountTable({ sessions: [makeSession({ progressDelta: null })] })
+    const paceCells = wrapper.findAll('td.hidden')
+    expect(paceCells.some((cell) => cell.text() === '-')).toBe(true)
+  })
+
+  it('shows "-" pace when progressDelta is negative', () => {
+    const wrapper = mountTable({ sessions: [makeSession({ progressDelta: -70.2, durationSeconds: 26 })] })
+    const paceCells = wrapper.findAll('td.hidden')
+    expect(paceCells.some((cell) => cell.text() === '-')).toBe(true)
+    expect(wrapper.text()).not.toContain('-9715.3%/hr')
+  })
+
+  it('groups sessions under day headers with subtotals when sorted by date', () => {
+    // Local-time constructors keep the grouping assertions timezone-agnostic.
+    const day1Morning = new Date(2026, 3, 15, 10, 0).toISOString()
+    const day1Evening = new Date(2026, 3, 15, 20, 0).toISOString()
+    const day2Morning = new Date(2026, 3, 14, 9, 0).toISOString()
+    const wrapper = mountTable({
+      sessions: [
+        makeSession({ id: 1, startedAt: day1Morning, durationSeconds: 1800, progressDelta: 3 }),
+        makeSession({ id: 2, startedAt: day1Evening, durationSeconds: 1800, progressDelta: 2 }),
+        makeSession({ id: 3, startedAt: day2Morning, durationSeconds: 600, progressDelta: null }),
+      ],
+      total: 3,
+    })
+
+    const headerRows = wrapper.findAll('tbody tr.bg-muted\\/40')
+    expect(headerRows.length).toBe(2)
+    expect(headerRows[0]!.text()).toContain('1h 0m')
+    expect(headerRows[0]!.text()).toContain('+5.0%')
+    expect(headerRows[1]!.text()).toContain('10m')
+    expect(headerRows[1]!.text()).not.toContain('%')
+  })
+
+  it('renders flat rows without day headers when sorted by another column', () => {
+    const wrapper = mountTable({
+      sessions: [
+        makeSession({ id: 1, startedAt: new Date(2026, 3, 15, 10, 0).toISOString() }),
+        makeSession({ id: 2, startedAt: new Date(2026, 3, 14, 9, 0).toISOString() }),
+      ],
+      total: 2,
+      sortBy: 'durationSeconds',
+    })
+
+    expect(wrapper.findAll('tbody tr.bg-muted\\/40').length).toBe(0)
+    expect(wrapper.find('tbody').findAll('tr').length).toBe(2)
+  })
+
+  it('shows source pills when sessions carry a source', () => {
+    const wrapper = mountTable({
+      sessions: [makeSession({ id: 1, source: 'koreader' }), makeSession({ id: 2, source: 'manual' })],
+      total: 2,
+    })
+
+    expect(wrapper.text()).toContain('KOReader')
+    expect(wrapper.text()).toContain('Manual')
+    const headers = wrapper.findAll('th')
+    expect(headers.some((h) => h.text() === 'Source')).toBe(true)
+  })
+
+  it('hides the source column when no session has a source', () => {
+    const wrapper = mountTable({ sessions: [makeSession({ source: null })] })
+    const headers = wrapper.findAll('th')
+    expect(headers.some((h) => h.text() === 'Source')).toBe(false)
+  })
+
   it('does not show format column when hasMultipleFormats is false', () => {
     const wrapper = mountTable({ hasMultipleFormats: false })
     const headers = wrapper.findAll('th')
@@ -157,36 +220,29 @@ describe('ReadingLogTable', () => {
     expect(wrapper.emitted('sortChange')?.[0]).toEqual(['startedAt', 'asc'])
   })
 
-  it('prev button emits pageChange with page-1', async () => {
-    const wrapper = mountTable({ total: 30, page: 2, pageSize: 25 })
-    const prevBtn = wrapper.findAll('button').find((b) => b.text() === 'Prev')
-    expect(prevBtn).toBeDefined()
-    await prevBtn!.trigger('click')
-    expect(wrapper.emitted('pageChange')?.[0]).toEqual([1])
+  it('shows a Load more button when hasMore is true and emits loadMore', async () => {
+    const wrapper = mountTable({ total: 30, hasMore: true })
+    const loadMoreBtn = wrapper.findAll('button').find((b) => b.text().includes('Load more'))
+    expect(loadMoreBtn).toBeDefined()
+    await loadMoreBtn!.trigger('click')
+    expect(wrapper.emitted('loadMore')).toBeTruthy()
   })
 
-  it('next button emits pageChange with page+1', async () => {
-    const wrapper = mountTable({ total: 30, page: 1, pageSize: 25 })
-    const nextBtn = wrapper.findAll('button').find((b) => b.text() === 'Next')
-    await nextBtn!.trigger('click')
-    expect(wrapper.emitted('pageChange')?.[0]).toEqual([2])
+  it('hides the Load more button when everything is loaded', () => {
+    const wrapper = mountTable({ total: 1, hasMore: false })
+    const loadMoreBtn = wrapper.findAll('button').find((b) => b.text().includes('Load more'))
+    expect(loadMoreBtn).toBeUndefined()
   })
 
-  it('prev button is disabled on first page', () => {
-    const wrapper = mountTable({ page: 1 })
-    const prevBtn = wrapper.findAll('button').find((b) => b.text() === 'Prev')
-    expect(prevBtn?.attributes('disabled')).toBeDefined()
+  it('disables the Load more button while loading more', () => {
+    const wrapper = mountTable({ total: 30, hasMore: true, loadingMore: true })
+    const loadMoreBtn = wrapper.findAll('button').find((b) => b.text().includes('Load more'))
+    expect(loadMoreBtn?.attributes('disabled')).toBeDefined()
   })
 
-  it('next button is disabled on last page', () => {
-    const wrapper = mountTable({ total: 1, page: 1, pageSize: 25 })
-    const nextBtn = wrapper.findAll('button').find((b) => b.text() === 'Next')
-    expect(nextBtn?.attributes('disabled')).toBeDefined()
-  })
-
-  it('shows pagination range correctly', () => {
-    const wrapper = mountTable({ total: 50, page: 2, pageSize: 25 })
-    expect(wrapper.text()).toContain('26-50 of 50')
+  it('shows the accumulated count', () => {
+    const wrapper = mountTable({ sessions: [makeSession({ id: 1 }), makeSession({ id: 2 })], total: 50 })
+    expect(wrapper.text()).toContain('Showing 2 of 50 sessions')
   })
 
   it('clears confirm state when sessions prop changes', async () => {
@@ -209,16 +265,6 @@ describe('ReadingLogTable', () => {
     expect(wrapper.find('button[title="Click again to confirm delete"]').exists()).toBe(false)
   })
 
-  it('clears confirm state when navigating to next page', async () => {
-    const wrapper = mountTable({ total: 30, page: 1, pageSize: 25 })
-    const deleteBtn = wrapper.find('button[title="Delete"]')
-    await deleteBtn.trigger('click')
-    expect(wrapper.find('button[title="Click again to confirm delete"]').exists()).toBe(true)
-    const nextBtn = wrapper.findAll('button').find((b) => b.text() === 'Next')
-    await nextBtn!.trigger('click')
-    expect(wrapper.find('button[title="Click again to confirm delete"]').exists()).toBe(false)
-  })
-
   it('clears confirm state when cancel delete is clicked', async () => {
     const wrapper = mountTable()
     const deleteBtn = wrapper.find('button[title="Delete"]')
diff --git a/client/src/features/book/composables/__tests__/useBookReadingLog.spec.ts b/client/src/features/book/composables/__tests__/useBookReadingLog.spec.ts
index 0d60430dc..36e50dddc 100644
--- a/client/src/features/book/composables/__tests__/useBookReadingLog.spec.ts
+++ b/client/src/features/book/composables/__tests__/useBookReadingLog.spec.ts
@@ -19,13 +19,39 @@ function makeResponse(data: unknown, status = 200): Response {
   } as Response
 }
 
-function makeListResponse(items = [], total?: number) {
+const emptyStats = {
+  totalSessions: 0,
+  totalSeconds: 0,
+  avgDurationSeconds: 0,
+  firstSessionAt: null,
+  lastSessionAt: null,
+  dailySummary: [],
+  paceProgressDelta: 0,
+  paceDurationSeconds: 0,
+  progressSummary: [],
+}
+
+function makeSession(id: number, overrides?: Record<string, unknown>) {
+  return {
+    id,
+    startedAt: '2026-04-15T10:00:00.000Z',
+    endedAt: '2026-04-15T10:30:00.000Z',
+    durationSeconds: 1800,
+    progressDelta: null,
+    endProgress: null,
+    format: null,
+    source: 'web',
+    ...overrides,
+  }
+}
+
+function makeListResponse(items: unknown[] = [], total?: number) {
   return makeResponse({
     items,
     total: total ?? items.length,
     page: 1,
     pageSize: 25,
-    stats: { totalSessions: 0, totalSeconds: 0, avgDurationSeconds: 0, firstSessionAt: null, lastSessionAt: null, dailySummary: [] },
+    stats: emptyStats,
   })
 }
 
@@ -44,29 +70,14 @@ describe('useBookReadingLog', () => {
   })
 
   it('updates sessions and stats after fetch', async () => {
-    const session = {
-      id: 1,
-      startedAt: '2026-04-15T10:00:00.000Z',
-      endedAt: '2026-04-15T10:30:00.000Z',
-      durationSeconds: 1800,
-      progressDelta: null,
-      endProgress: null,
-      format: 'epub',
-    }
+    const session = makeSession(1, { format: 'epub' })
     mocks.api.mockResolvedValue(
       makeResponse({
         items: [session],
         total: 1,
         page: 1,
         pageSize: 25,
-        stats: {
-          totalSessions: 1,
-          totalSeconds: 1800,
-          avgDurationSeconds: 1800,
-          firstSessionAt: session.startedAt,
-          lastSessionAt: session.startedAt,
-          dailySummary: [],
-        },
+        stats: { ...emptyStats, totalSessions: 1, totalSeconds: 1800, avgDurationSeconds: 1800 },
       }),
     )
 
@@ -107,60 +118,30 @@ describe('useBookReadingLog', () => {
     expect(error.value).toContain('network error')
   })
 
-  it('deleteSession removes item optimistically then refetches', async () => {
-    const session = {
-      id: 1,
-      startedAt: '2026-04-15T10:00:00.000Z',
-      endedAt: '2026-04-15T10:30:00.000Z',
-      durationSeconds: 1800,
-      progressDelta: null,
-      endProgress: null,
-      format: null,
-    }
+  it('deleteSession removes item optimistically then refreshes stats only', async () => {
     mocks.api
-      .mockResolvedValueOnce(
-        makeResponse({
-          items: [session],
-          total: 1,
-          page: 1,
-          pageSize: 25,
-          stats: { totalSessions: 1, totalSeconds: 1800, avgDurationSeconds: 1800, firstSessionAt: null, lastSessionAt: null, dailySummary: [] },
-        }),
-      )
+      .mockResolvedValueOnce(makeListResponse([makeSession(1), makeSession(2)], 2))
       .mockResolvedValueOnce({ ok: true, status: 204, json: async () => null } as Response)
-      .mockResolvedValueOnce(makeListResponse())
+      .mockResolvedValueOnce(makeListResponse([makeSession(2)], 1))
 
     const bookId = ref(10)
-    const { sessions, deleteSession } = useBookReadingLog(bookId)
+    const { sessions, total, deleteSession } = useBookReadingLog(bookId)
     await nextTick()
     await nextTick()
 
     await deleteSession(1)
     await nextTick()
 
-    expect(sessions.value).toHaveLength(0)
+    expect(sessions.value.map((s) => s.id)).toEqual([2])
+    expect(total.value).toBe(1)
+    const statsUrl = mocks.api.mock.calls[2]?.[0] as string
+    expect(statsUrl).toContain('page=1')
+    expect(statsUrl).toContain('pageSize=1')
   })
 
   it('deleteSession rolls back sessions and total on error', async () => {
-    const session = {
-      id: 1,
-      startedAt: '2026-04-15T10:00:00.000Z',
-      endedAt: '2026-04-15T10:30:00.000Z',
-      durationSeconds: 1800,
-      progressDelta: null,
-      endProgress: null,
-      format: null,
-    }
     mocks.api
-      .mockResolvedValueOnce(
-        makeResponse({
-          items: [session],
-          total: 5,
-          page: 1,
-          pageSize: 25,
-          stats: { totalSessions: 5, totalSeconds: 0, avgDurationSeconds: 0, firstSessionAt: null, lastSessionAt: null, dailySummary: [] },
-        }),
-      )
+      .mockResolvedValueOnce(makeListResponse([makeSession(1)], 5))
       .mockResolvedValueOnce({ ok: false, status: 404, json: async () => null } as Response)
 
     const bookId = ref(10)
@@ -217,24 +198,103 @@ describe('useBookReadingLog', () => {
     expect(url).toContain('sortDir=asc')
   })
 
-  it('setPage changes page and fetches', async () => {
-    mocks.api.mockResolvedValue(makeListResponse())
+  it('loadMore appends the next page without duplicates', async () => {
+    const firstPage = Array.from({ length: 25 }, (_, i) => makeSession(i + 1))
+    mocks.api.mockResolvedValueOnce(makeListResponse(firstPage, 30))
 
     const bookId = ref(10)
-    const { setPage, page } = useBookReadingLog(bookId)
+    const { sessions, hasMore, loadMore } = useBookReadingLog(bookId)
+    await nextTick()
+    await nextTick()
+
+    expect(sessions.value).toHaveLength(25)
+    expect(hasMore.value).toBe(true)
+
+    mocks.api.mockClear()
+    const secondPage = [makeSession(25), ...Array.from({ length: 5 }, (_, i) => makeSession(i + 26))]
+    mocks.api.mockResolvedValueOnce(makeListResponse(secondPage, 30))
+
+    await loadMore()
+
+    const url = mocks.api.mock.calls[0]?.[0] as string
+    expect(url).toContain('page=2')
+    expect(sessions.value).toHaveLength(30)
+    expect(hasMore.value).toBe(false)
+  })
+
+  it('loadMore is a no-op when everything is loaded', async () => {
+    mocks.api.mockResolvedValueOnce(makeListResponse([makeSession(1)], 1))
+
+    const bookId = ref(10)
+    const { loadMore } = useBookReadingLog(bookId)
     await nextTick()
     await nextTick()
 
     mocks.api.mockClear()
-    mocks.api.mockResolvedValue(makeListResponse())
+    await loadMore()
 
-    setPage(3)
+    expect(mocks.api).not.toHaveBeenCalled()
+  })
+
+  it('addSession posts the payload and refetches from page 1', async () => {
+    mocks.api.mockResolvedValueOnce(makeListResponse())
+
+    const bookId = ref(10)
+    const { addSession } = useBookReadingLog(bookId)
     await nextTick()
     await nextTick()
 
-    expect(page.value).toBe(3)
-    const url = mocks.api.mock.calls[0]?.[0] as string
-    expect(url).toContain('page=3')
+    mocks.api.mockClear()
+    mocks.api
+      .mockResolvedValueOnce(makeResponse({ id: 9, source: 'manual' }, 201))
+      .mockResolvedValueOnce(makeListResponse([makeSession(9, { source: 'manual' })], 1))
+
+    await addSession({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: 50 })
+
+    const [postUrl, postInit] = mocks.api.mock.calls[0] as [string, RequestInit]
+    expect(postUrl).toBe('/api/v1/books/10/sessions')
+    expect(postInit.method).toBe('POST')
+    expect(JSON.parse(postInit.body as string)).toMatchObject({ durationMinutes: 30, endProgress: 50 })
+    const refetchUrl = mocks.api.mock.calls[1]?.[0] as string
+    expect(refetchUrl).toContain('page=1')
+  })
+
+  it('addSession throws with the server message on failure', async () => {
+    mocks.api.mockResolvedValueOnce(makeListResponse())
+
+    const bookId = ref(10)
+    const { addSession } = useBookReadingLog(bookId)
+    await nextTick()
+    await nextTick()
+
+    mocks.api.mockClear()
+    mocks.api.mockResolvedValueOnce(makeResponse({ message: 'startedAt cannot be in the future' }, 400))
+
+    await expect(addSession({ startedAt: '2099-01-01T00:00:00.000Z', durationMinutes: 30 })).rejects.toThrow('startedAt cannot be in the future')
+  })
+
+  it('exportAll pages through the full list at pageSize 100', async () => {
+    mocks.api.mockResolvedValueOnce(makeListResponse())
+
+    const bookId = ref(10)
+    const { exportAll } = useBookReadingLog(bookId)
+    await nextTick()
+    await nextTick()
+
+    mocks.api.mockClear()
+    const pageOne = Array.from({ length: 100 }, (_, i) => makeSession(i + 1))
+    const pageTwo = Array.from({ length: 20 }, (_, i) => makeSession(i + 101))
+    mocks.api.mockResolvedValueOnce(makeListResponse(pageOne, 120)).mockResolvedValueOnce(makeListResponse(pageTwo, 120))
+
+    const items = await exportAll()
+
+    expect(items).toHaveLength(120)
+    expect(mocks.api).toHaveBeenCalledTimes(2)
+    const firstUrl = mocks.api.mock.calls[0]?.[0] as string
+    expect(firstUrl).toContain('pageSize=100')
+    expect(firstUrl).toContain('page=1')
+    const secondUrl = mocks.api.mock.calls[1]?.[0] as string
+    expect(secondUrl).toContain('page=2')
   })
 
   it('loading is true while fetching and false after', async () => {
diff --git a/client/src/features/book/composables/useBookHighlights.test.ts b/client/src/features/book/composables/useBookHighlights.test.ts
index bb04fbaef..7708261ad 100644
--- a/client/src/features/book/composables/useBookHighlights.test.ts
+++ b/client/src/features/book/composables/useBookHighlights.test.ts
@@ -52,8 +52,7 @@ describe('useBookHighlights', () => {
   })
 
   it('fetches highlights on mount', async () => {
-    const response = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(response))
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
     const { items, total, stats, loading } = useBookHighlights(bookId)
 
@@ -77,7 +76,7 @@ describe('useBookHighlights', () => {
     expect(error.value).toBe('HTTP 500')
   })
 
-  it('includes pagination params in URL', async () => {
+  it('includes pagination and sort params in the URL', async () => {
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
     useBookHighlights(bookId)
@@ -92,87 +91,62 @@ describe('useBookHighlights', () => {
     expect(url).toContain('sortDir=asc')
   })
 
-  it('toggleColor adds and removes colors', async () => {
+  it('reloads with the selected colors when the colors filter changes', async () => {
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
-    const { colors, toggleColor } = useBookHighlights(bookId)
+    const { colors } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
     mockFetch.mockClear()
 
-    toggleColor('#FACC15')
-    expect(colors.value).toContain('#FACC15')
+    colors.value = ['#FACC15']
 
     await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
-    const url = mockFetch.mock.calls[0]?.[0] as string
-    expect(url).toContain('colors=%23FACC15')
-
-    mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
-    toggleColor('#FACC15')
-    expect(colors.value).not.toContain('#FACC15')
+    expect(mockFetch.mock.calls[0]?.[0]).toContain('colors=%23FACC15')
   })
 
-  it('setSort changes sort params and resets page', async () => {
+  it('maps the merged sort key to sortBy/sortDir', async () => {
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
-    const { page, sortBy, sortDir, setSort } = useBookHighlights(bookId)
+    const { sortBy, sortDir, sortKey } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
-    mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
-
-    setSort('createdAt', 'desc')
 
+    expect(sortKey.value).toBe('position')
+    sortKey.value = 'newest'
     expect(sortBy.value).toBe('createdAt')
     expect(sortDir.value).toBe('desc')
-    expect(page.value).toBe(1)
+    sortKey.value = 'oldest'
+    expect(sortDir.value).toBe('asc')
   })
 
-  it('setPage changes the page', async () => {
+  it('reloads when the page changes', async () => {
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
-    const { page, setPage } = useBookHighlights(bookId)
+    const { page } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
     mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
 
-    setPage(3)
+    page.value = 3
 
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
     expect(page.value).toBe(3)
+    expect(mockFetch.mock.calls[0]?.[0]).toContain('page=3')
   })
 
-  it('setSearch updates search and resets page', async () => {
+  it('updateNote optimistically patches the item and PATCHes the endpoint', async () => {
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
-    const { search, setSearch } = useBookHighlights(bookId)
-
-    await nextTick()
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
-    mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
-
-    setSearch('freedom')
-
-    expect(search.value).toBe('freedom')
-  })
-
-  it('updateNote patches annotation and updates items', async () => {
-    const initial = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(initial))
-    const bookId = ref(5)
     const { items, updateNote } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(items.value).toHaveLength(1))
     mockFetch.mockClear()
-
-    const updatedItem = { ...initial.items[0], note: 'my note' }
-    mockFetch.mockResolvedValue(mockOkResponse(updatedItem))
+    mockFetch.mockResolvedValue(mockOkResponse({}))
 
     await updateNote(1, 'my note')
 
@@ -180,18 +154,15 @@ describe('useBookHighlights', () => {
     expect(items.value[0]?.note).toBe('my note')
   })
 
-  it('updateColor patches annotation color', async () => {
-    const initial = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(initial))
+  it('updateColor optimistically patches the item color', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
     const { items, updateColor } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(items.value).toHaveLength(1))
     mockFetch.mockClear()
-
-    const updatedItem = { ...initial.items[0], color: '#4ADE80' }
-    mockFetch.mockResolvedValue(mockOkResponse(updatedItem))
+    mockFetch.mockResolvedValue(mockOkResponse({}))
 
     await updateColor(1, '#4ADE80')
 
@@ -199,8 +170,7 @@ describe('useBookHighlights', () => {
   })
 
   it('deleteHighlight removes item optimistically and refetches', async () => {
-    const initial = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(initial))
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
     const { items, deleteHighlight } = useBookHighlights(bookId)
 
@@ -216,8 +186,7 @@ describe('useBookHighlights', () => {
   })
 
   it('deleteHighlight reverts on failure', async () => {
-    const initial = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(initial))
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
     const { items, total, error, deleteHighlight } = useBookHighlights(bookId)
 
@@ -234,46 +203,219 @@ describe('useBookHighlights', () => {
     expect(error.value).toBeTruthy()
   })
 
-  it('resets state when bookId changes', async () => {
-    const initial = makeListResponse()
-    mockFetch.mockResolvedValue(mockOkResponse(initial))
+  it('builds color/date chips and resets all filters', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
     const bookId = ref(5)
-    const { colors, search, chapter, page, toggleColor, setSearch, setChapter, setPage } = useBookHighlights(bookId)
+    const { colors, dateFrom, chapter, search, activeFilterChips, popoverFilterCount, hasActiveFilters, resetAllFilters } = useBookHighlights(bookId)
 
     await nextTick()
     await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
 
-    toggleColor('#FACC15')
-    setSearch('test')
-    setChapter('Chapter 1')
-    setPage(3)
+    colors.value = ['#FACC15']
+    dateFrom.value = '2026-01-10'
+    chapter.value = 'Chapter 1'
+    search.value = 'freedom'
 
+    expect(hasActiveFilters.value).toBe(true)
+    expect(popoverFilterCount.value).toBe(2)
+    expect(activeFilterChips.value.map((chip) => chip.id)).toEqual(['color:#FACC15', 'date'])
+
+    resetAllFilters()
+    expect(colors.value).toEqual([])
+    expect(dateFrom.value).toBe('')
+    expect(chapter.value).toBe('')
+    expect(search.value).toBe('')
+    expect(hasActiveFilters.value).toBe(false)
+  })
+
+  it('bulkTrash returns 0 without calling the API for an empty selection', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { bulkTrash } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+    mockFetch.mockClear()
+
+    expect(await bulkTrash([])).toBe(0)
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+
+  it('bulkTrash posts the trash action, optimistically drops the item, and returns the affected count', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { items, bulkTrash } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(items.value).toHaveLength(1))
+    mockFetch.mockClear()
+    mockFetch
+      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ affected: 1 }) })
+      .mockResolvedValueOnce(mockOkResponse(makeListResponse({ items: [], total: 0 })))
+
+    const affected = await bulkTrash([1])
+
+    expect(affected).toBe(1)
+    const init = mockFetch.mock.calls[0]?.[1] as RequestInit
+    expect(mockFetch.mock.calls[0]?.[0]).toBe('/api/v1/annotations/bulk')
+    expect(JSON.parse(String(init.body))).toEqual({ ids: [1], action: 'trash' })
+  })
+
+  it('bulkTrash reverts items and total when the request fails', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { items, total, error, bulkTrash } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(items.value).toHaveLength(1))
+    mockFetch.mockClear()
+    mockFetch.mockResolvedValue(mockErrorResponse())
+
+    const affected = await bulkTrash([1])
+
+    expect(affected).toBe(0)
+    expect(items.value).toHaveLength(1)
+    expect(total.value).toBe(1)
+    expect(error.value).toBeTruthy()
+  })
+
+  it('bulkRestyle posts the restyle patch and returns the affected count', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { bulkRestyle } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+    mockFetch.mockClear()
+    mockFetch
+      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ affected: 2 }) })
+      .mockResolvedValueOnce(mockOkResponse(makeListResponse()))
+
+    const affected = await bulkRestyle([1, 2], { color: '#4ADE80' })
+
+    expect(affected).toBe(2)
+    const init = mockFetch.mock.calls[0]?.[1] as RequestInit
+    expect(JSON.parse(String(init.body))).toEqual({ ids: [1, 2], action: 'restyle', color: '#4ADE80' })
+  })
+
+  it('bulkRestyle returns 0 for an empty selection and sets an error on failure', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { bulkRestyle, error } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+
+    expect(await bulkRestyle([], { color: '#fff' })).toBe(0)
+
+    mockFetch.mockClear()
+    mockFetch.mockResolvedValue(mockErrorResponse())
+    expect(await bulkRestyle([1], { style: 'underline' })).toBe(0)
+    expect(error.value).toBeTruthy()
+  })
+
+  it('removeFilterChip clears a single color or the whole date range', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { colors, dateFrom, dateTo, removeFilterChip } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+
+    colors.value = ['#FACC15', '#4ADE80']
+    removeFilterChip('color:#FACC15')
+    expect(colors.value).toEqual(['#4ADE80'])
+
+    dateFrom.value = '2026-01-01'
+    dateTo.value = '2026-01-31'
+    removeFilterChip('date')
+    expect(dateFrom.value).toBe('')
+    expect(dateTo.value).toBe('')
+  })
+
+  it('maps the position sort key back to sortBy/sortDir', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { sortKey, sortBy, sortDir } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+
+    sortKey.value = 'newest'
+    expect(sortBy.value).toBe('createdAt')
+
+    sortKey.value = 'position'
+    expect(sortBy.value).toBe('position')
+    expect(sortDir.value).toBe('asc')
+  })
+
+  it('refetches exactly once when a filter changes while on a later page', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { page, colors } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+
+    page.value = 3
+    await nextTick()
+    mockFetch.mockClear()
+
+    colors.value = ['#FACC15']
+    await nextTick()
+
+    expect(page.value).toBe(1)
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('discards a stale fetch when a newer fetch supersedes it', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { total, loading, fetchHighlights } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(loading.value).toBe(false))
+
+    let resolveStale!: (res: unknown) => void
+    const stalePending = new Promise((resolve) => {
+      resolveStale = resolve
+    })
+    mockFetch.mockReset()
+    mockFetch.mockReturnValueOnce(stalePending).mockResolvedValueOnce(mockOkResponse(makeListResponse({ total: 9 })))
+
+    const stale = fetchHighlights()
+    const fresh = fetchHighlights()
+    await fresh
+
+    expect(total.value).toBe(9)
+
+    resolveStale(mockOkResponse(makeListResponse({ total: 1 })))
+    await stale
+
+    expect(total.value).toBe(9)
+    expect(loading.value).toBe(false)
+  })
+
+  it('resets state when bookId changes', async () => {
+    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
+    const bookId = ref(5)
+    const { colors, search, chapter, page } = useBookHighlights(bookId)
+
+    await nextTick()
+    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
+
+    colors.value = ['#FACC15']
+    chapter.value = 'Chapter 1'
+    page.value = 3
     mockFetch.mockClear()
     mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
 
     bookId.value = 10
-
     await nextTick()
 
     expect(colors.value).toEqual([])
     expect(search.value).toBe('')
-    expect(chapter.value).toBeUndefined()
+    expect(chapter.value).toBe('')
     expect(page.value).toBe(1)
   })
-
-  it('setDateRange updates date filters', async () => {
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
-    const bookId = ref(5)
-    const { dateFrom, dateTo, setDateRange } = useBookHighlights(bookId)
-
-    await nextTick()
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalled())
-    mockFetch.mockClear()
-    mockFetch.mockResolvedValue(mockOkResponse(makeListResponse()))
-
-    setDateRange('2026-01-01', '2026-06-01')
-
-    expect(dateFrom.value).toBe('2026-01-01')
-    expect(dateTo.value).toBe('2026-06-01')
-  })
 })
diff --git a/client/src/features/book/composables/useBookHighlights.ts b/client/src/features/book/composables/useBookHighlights.ts
index e76efe751..6fa336784 100644
--- a/client/src/features/book/composables/useBookHighlights.ts
+++ b/client/src/features/book/composables/useBookHighlights.ts
@@ -1,25 +1,66 @@
-import { computed, ref, watch, type Ref } from 'vue'
+import { computed, nextTick, ref, watch, type Ref } from 'vue'
 import type { AnnotationItem, AnnotationListResponse, AnnotationStats } from '@bookorbit/types'
 import { api } from '@/lib/api'
+import { buildFilterChips } from '@/features/annotations/lib/filter-chips'
+import { useAnnotationSelection } from '@/features/annotations/composables/useAnnotationSelection'
+import { useAnnotationMutations } from '@/features/annotations/composables/useAnnotationMutations'
+
+export type BookSortKey = 'position' | 'newest' | 'oldest'
+
+const SEARCH_RELOAD_DEBOUNCE_MS = 300
 
 export function useBookHighlights(bookIdRef: Ref<number>) {
   const items = ref<AnnotationItem[]>([])
   const total = ref(0)
+  const pageSize = ref(25)
+  const page = ref(1)
   const stats = ref<AnnotationStats | null>(null)
   const loading = ref(false)
   const error = ref<string | null>(null)
-  const page = ref(1)
-  const pageSize = ref(25)
+
   const sortBy = ref<'position' | 'createdAt'>('position')
   const sortDir = ref<'asc' | 'desc'>('asc')
   const colors = ref<string[]>([])
   const search = ref('')
-  const chapter = ref<string | undefined>(undefined)
-  const dateFrom = ref<string | undefined>(undefined)
-  const dateTo = ref<string | undefined>(undefined)
+  const chapter = ref('')
+  const dateFrom = ref('')
+  const dateTo = ref('')
+  const hydratingBook = ref(false)
 
+  const selection = useAnnotationSelection(items)
+  const mutations = useAnnotationMutations(items, () => bookIdRef.value)
+
+  const chapters = computed(() => stats.value?.chapters ?? [])
+  const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)))
+  const rangeStart = computed(() => (total.value === 0 ? 0 : Math.min((page.value - 1) * pageSize.value + 1, total.value)))
+  const rangeEnd = computed(() => Math.min(page.value * pageSize.value, total.value))
+
+  const sortKey = computed<BookSortKey>({
+    get() {
+      if (sortBy.value === 'position') return 'position'
+      return sortDir.value === 'desc' ? 'newest' : 'oldest'
+    },
+    set(value) {
+      if (value === 'position') {
+        sortBy.value = 'position'
+        sortDir.value = 'asc'
+      } else {
+        sortBy.value = 'createdAt'
+        sortDir.value = value === 'newest' ? 'desc' : 'asc'
+      }
+    },
+  })
+
+  const activeFilterChips = computed(() => buildFilterChips({ colors: colors.value, dateFrom: dateFrom.value, dateTo: dateTo.value }))
+  const popoverFilterCount = computed(() => activeFilterChips.value.length)
+  const hasActiveFilters = computed(
+    () => search.value.trim() !== '' || colors.value.length > 0 || Boolean(chapter.value) || dateFrom.value !== '' || dateTo.value !== '',
+  )
+
+  let fetchSeq = 0
   async function fetchHighlights() {
     const bookId = bookIdRef.value
+    const seq = ++fetchSeq
     loading.value = true
     error.value = null
     try {
@@ -36,48 +77,49 @@ export function useBookHighlights(bookIdRef: Ref<number>) {
       if (dateTo.value) params.set('dateTo', dateTo.value)
 
       const res = await api(`/api/v1/books/${bookId}/annotations?${params.toString()}`)
+      if (seq !== fetchSeq) return
       if (!res.ok) throw new Error(`HTTP ${res.status}`)
       const data: AnnotationListResponse = await res.json()
+      if (seq !== fetchSeq) return
       items.value = data.items
       total.value = data.total
       stats.value = data.stats
     } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to load highlights'
+      if (seq === fetchSeq) error.value = e instanceof Error ? e.message : 'Failed to load highlights'
     } finally {
-      loading.value = false
+      if (seq === fetchSeq) loading.value = false
     }
   }
 
-  async function updateNote(annotationId: number, note: string | null) {
-    try {
-      const bookId = bookIdRef.value
-      const res = await api(`/api/v1/books/${bookId}/annotations/${annotationId}`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ note }),
-      })
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const updated: AnnotationItem = await res.json()
-      items.value = items.value.map((a) => (a.id === annotationId ? updated : a))
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to update note'
-    }
+  function reloadFromFilterChange() {
+    selection.clearSelection()
+    if (page.value === 1) void fetchHighlights()
+    else page.value = 1
   }
 
-  async function updateColor(annotationId: number, color: string) {
-    try {
-      const bookId = bookIdRef.value
-      const res = await api(`/api/v1/books/${bookId}/annotations/${annotationId}`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ color }),
-      })
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const updated: AnnotationItem = await res.json()
-      items.value = items.value.map((a) => (a.id === annotationId ? updated : a))
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to update color'
+  function clearDates() {
+    dateFrom.value = ''
+    dateTo.value = ''
+  }
+
+  function clearPopoverFilters() {
+    colors.value = []
+    clearDates()
+  }
+
+  function resetAllFilters() {
+    search.value = ''
+    chapter.value = ''
+    clearPopoverFilters()
+  }
+
+  function removeFilterChip(id: string) {
+    if (id.startsWith('color:')) {
+      const hex = id.slice('color:'.length)
+      colors.value = colors.value.filter((value) => value !== hex)
+      return
     }
+    if (id === 'date') clearDates()
   }
 
   async function deleteHighlight(annotationId: number) {
@@ -97,88 +139,125 @@ export function useBookHighlights(bookIdRef: Ref<number>) {
     }
   }
 
-  function setPage(p: number) {
-    page.value = p
-    void fetchHighlights()
-  }
-
-  function setSort(by: typeof sortBy.value, dir: typeof sortDir.value) {
-    sortBy.value = by
-    sortDir.value = dir
-    page.value = 1
-    void fetchHighlights()
-  }
-
-  function toggleColor(color: string) {
-    if (colors.value.includes(color)) {
-      colors.value = colors.value.filter((c) => c !== color)
-    } else {
-      colors.value = [...colors.value, color]
+  async function bulkTrash(annotationIds: number[]): Promise<number> {
+    if (annotationIds.length === 0) return 0
+    const prev = items.value
+    const prevTotal = total.value
+    items.value = items.value.filter((a) => !annotationIds.includes(a.id))
+    total.value = Math.max(0, total.value - annotationIds.length)
+    try {
+      const res = await api('/api/v1/annotations/bulk', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ids: annotationIds, action: 'trash' }),
+      })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const body = (await res.json()) as { affected: number }
+      await fetchHighlights()
+      return body.affected
+    } catch (e) {
+      items.value = prev
+      total.value = prevTotal
+      error.value = e instanceof Error ? e.message : 'Failed to move highlights to trash'
+      return 0
     }
-    page.value = 1
-    void fetchHighlights()
   }
 
-  function setSearch(q: string) {
-    search.value = q
-    page.value = 1
-    void fetchHighlights()
+  async function bulkRestyle(annotationIds: number[], patch: { color?: string; style?: string }): Promise<number> {
+    if (annotationIds.length === 0) return 0
+    try {
+      const res = await api('/api/v1/annotations/bulk', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ids: annotationIds, action: 'restyle', ...patch }),
+      })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const body = (await res.json()) as { affected: number }
+      await fetchHighlights()
+      return body.affected
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to update selected highlights'
+      return 0
+    }
   }
 
-  function setChapter(ch: string | undefined) {
-    chapter.value = ch
-    page.value = 1
+  watch([colors, chapter, dateFrom, dateTo, sortBy, sortDir], () => {
+    if (hydratingBook.value) return
+    reloadFromFilterChange()
+  })
+  let searchDebounce: ReturnType<typeof setTimeout> | null = null
+  watch(search, () => {
+    if (hydratingBook.value) return
+    if (searchDebounce) clearTimeout(searchDebounce)
+    searchDebounce = setTimeout(reloadFromFilterChange, SEARCH_RELOAD_DEBOUNCE_MS)
+  })
+  watch(page, () => {
+    if (hydratingBook.value) return
+    selection.clearSelection()
     void fetchHighlights()
-  }
-
-  function setDateRange(from: string | undefined, to: string | undefined) {
-    dateFrom.value = from
-    dateTo.value = to
-    page.value = 1
-    void fetchHighlights()
-  }
+  })
 
   watch(
     bookIdRef,
     () => {
+      hydratingBook.value = true
       page.value = 1
       colors.value = []
       search.value = ''
-      chapter.value = undefined
-      dateFrom.value = undefined
-      dateTo.value = undefined
+      chapter.value = ''
+      dateFrom.value = ''
+      dateTo.value = ''
+      sortBy.value = 'position'
+      sortDir.value = 'asc'
       void fetchHighlights()
+      void nextTick(() => {
+        hydratingBook.value = false
+      })
     },
     { immediate: true },
   )
 
-  const chapters = computed(() => stats.value?.chapters ?? [])
-
   return {
     items,
     total,
+    page,
+    pageSize,
+    totalPages,
+    rangeStart,
+    rangeEnd,
     stats,
     loading,
     error,
-    page,
-    pageSize,
     sortBy,
     sortDir,
+    sortKey,
     colors,
     search,
     chapter,
     chapters,
     dateFrom,
     dateTo,
+    activeFilterChips,
+    popoverFilterCount,
+    hasActiveFilters,
+    selectedIds: selection.selectedIds,
+    savingIds: mutations.savingIds,
+    hasSelection: selection.hasSelection,
+    allVisibleSelected: selection.allVisibleSelected,
+    selectedItems: selection.selectedItems,
+    toggleSelected: selection.toggleSelected,
+    selectAllOnPage: selection.selectAllOnPage,
+    clearSelection: selection.clearSelection,
+    updateNote: mutations.updateNote,
+    updateColor: mutations.updateColor,
+    updateStyle: mutations.updateStyle,
     fetchHighlights,
-    updateNote,
-    updateColor,
     deleteHighlight,
-    setPage,
-    setSort,
-    toggleColor,
-    setSearch,
-    setChapter,
-    setDateRange,
+    bulkTrash,
+    bulkRestyle,
+    clearPopoverFilters,
+    resetAllFilters,
+    removeFilterChip,
+    clearDates,
   }
 }
diff --git a/client/src/features/book/composables/useBookReadingLog.ts b/client/src/features/book/composables/useBookReadingLog.ts
index ed4737d42..87e50e7e4 100644
--- a/client/src/features/book/composables/useBookReadingLog.ts
+++ b/client/src/features/book/composables/useBookReadingLog.ts
@@ -1,12 +1,23 @@
-import { ref, watch, type Ref } from 'vue'
+import { computed, ref, watch, type Ref } from 'vue'
 import type { BookReadingSession, BookReadingSessionListResponse, BookReadingSessionStats } from '@bookorbit/types'
 import { api } from '@/lib/api'
 
+export interface AddReadingSessionPayload {
+  startedAt: string
+  durationMinutes: number
+  endProgress?: number
+  format?: string
+}
+
+const EXPORT_PAGE_SIZE = 100
+const EXPORT_MAX_PAGES = 50
+
 export function useBookReadingLog(bookIdRef: Ref<number>) {
   const sessions = ref<BookReadingSession[]>([])
   const total = ref(0)
   const stats = ref<BookReadingSessionStats | null>(null)
   const loading = ref(false)
+  const loadingMore = ref(false)
   const error = ref<string | null>(null)
   const page = ref(1)
   const pageSize = ref(25)
@@ -16,30 +27,65 @@ export function useBookReadingLog(bookIdRef: Ref<number>) {
   const dateTo = ref<string | undefined>(undefined)
   const format = ref<string | undefined>(undefined)
 
-  async function fetchSessions() {
+  const hasMore = computed(() => sessions.value.length < total.value)
+
+  function buildParams(overrides?: { page?: number; pageSize?: number }) {
+    const params = new URLSearchParams({
+      page: String(overrides?.page ?? page.value),
+      pageSize: String(overrides?.pageSize ?? pageSize.value),
+      sortBy: sortBy.value,
+      sortDir: sortDir.value,
+    })
+    if (dateFrom.value) params.set('dateFrom', dateFrom.value)
+    if (dateTo.value) params.set('dateTo', dateTo.value)
+    if (format.value) params.set('format', format.value)
+    return params
+  }
+
+  async function fetchSessions(opts?: { append?: boolean }) {
     const bookId = bookIdRef.value
-    loading.value = true
+    const append = opts?.append ?? false
+    if (append) loadingMore.value = true
+    else loading.value = true
     error.value = null
     try {
-      const params = new URLSearchParams({
-        page: String(page.value),
-        pageSize: String(pageSize.value),
-        sortBy: sortBy.value,
-        sortDir: sortDir.value,
-      })
-      if (dateFrom.value) params.set('dateFrom', dateFrom.value)
-      if (dateTo.value) params.set('dateTo', dateTo.value)
-      if (format.value) params.set('format', format.value)
-      const res = await api(`/api/v1/books/${bookId}/sessions?${params.toString()}`)
+      const res = await api(`/api/v1/books/${bookId}/sessions?${buildParams().toString()}`)
       if (!res.ok) throw new Error(`HTTP ${res.status}`)
       const data: BookReadingSessionListResponse = await res.json()
-      sessions.value = data.items
+      if (append) {
+        const seen = new Set(sessions.value.map((s) => s.id))
+        sessions.value = [...sessions.value, ...data.items.filter((item) => !seen.has(item.id))]
+      } else {
+        sessions.value = data.items
+      }
       total.value = data.total
       stats.value = data.stats
     } catch (e) {
       error.value = e instanceof Error ? e.message : 'Failed to load reading sessions'
     } finally {
       loading.value = false
+      loadingMore.value = false
+    }
+  }
+
+  async function loadMore() {
+    if (loading.value || loadingMore.value || !hasMore.value) return
+    // Derive the next page from the accumulated length so a prior delete
+    // (which shifts server page boundaries) cannot skip rows.
+    page.value = Math.floor(sessions.value.length / pageSize.value) + 1
+    await fetchSessions({ append: true })
+  }
+
+  async function refreshStats() {
+    const bookId = bookIdRef.value
+    try {
+      const res = await api(`/api/v1/books/${bookId}/sessions?${buildParams({ page: 1, pageSize: 1 }).toString()}`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data: BookReadingSessionListResponse = await res.json()
+      total.value = data.total
+      stats.value = data.stats
+    } catch {
+      // Stats refresh is best-effort; the optimistic list update already happened.
     }
   }
 
@@ -52,7 +98,7 @@ export function useBookReadingLog(bookIdRef: Ref<number>) {
     try {
       const res = await api(`/api/v1/books/${bookId}/sessions/${sessionId}`, { method: 'DELETE' })
       if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      await fetchSessions()
+      await refreshStats()
     } catch (e) {
       sessions.value = prev
       total.value = prevTotal
@@ -60,9 +106,43 @@ export function useBookReadingLog(bookIdRef: Ref<number>) {
     }
   }
 
-  function setPage(p: number) {
-    page.value = p
-    void fetchSessions()
+  async function addSession(payload: AddReadingSessionPayload) {
+    const bookId = bookIdRef.value
+    const res = await api(`/api/v1/books/${bookId}/sessions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    if (!res.ok) {
+      let message = `HTTP ${res.status}`
+      try {
+        const body = (await res.json()) as { message?: string | string[] }
+        if (body.message) message = Array.isArray(body.message) ? body.message.join(', ') : body.message
+      } catch {
+        // Keep the HTTP status message.
+      }
+      throw new Error(message)
+    }
+    page.value = 1
+    await fetchSessions()
+  }
+
+  async function exportAll(): Promise<BookReadingSession[]> {
+    const bookId = bookIdRef.value
+    const items: BookReadingSession[] = []
+    let expectedTotal = Number.POSITIVE_INFINITY
+    for (let exportPage = 1; exportPage <= EXPORT_MAX_PAGES && items.length < expectedTotal; exportPage += 1) {
+      const params = buildParams({ page: exportPage, pageSize: EXPORT_PAGE_SIZE })
+      params.set('sortBy', 'startedAt')
+      params.set('sortDir', 'desc')
+      const res = await api(`/api/v1/books/${bookId}/sessions?${params.toString()}`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data: BookReadingSessionListResponse = await res.json()
+      items.push(...data.items)
+      expectedTotal = data.total
+      if (data.items.length === 0) break
+    }
+    return items
   }
 
   function setSort(by: typeof sortBy.value, dir: typeof sortDir.value) {
@@ -97,6 +177,7 @@ export function useBookReadingLog(bookIdRef: Ref<number>) {
     total,
     stats,
     loading,
+    loadingMore,
     error,
     page,
     pageSize,
@@ -105,8 +186,11 @@ export function useBookReadingLog(bookIdRef: Ref<number>) {
     dateFrom,
     dateTo,
     format,
+    hasMore,
     deleteSession,
-    setPage,
+    addSession,
+    exportAll,
+    loadMore,
     setSort,
     setFilters,
   }
diff --git a/client/src/features/dashboard/components/widgets/ReadingRhythmWidget.vue b/client/src/features/dashboard/components/widgets/ReadingRhythmWidget.vue
index 3d2f74f38..33ace6523 100644
--- a/client/src/features/dashboard/components/widgets/ReadingRhythmWidget.vue
+++ b/client/src/features/dashboard/components/widgets/ReadingRhythmWidget.vue
@@ -24,6 +24,12 @@ function getDayLabel(dateStr: string): string {
   const d = new Date(dateStr + 'T12:00:00Z')
   return ['S', 'M', 'T', 'W', 'T', 'F', 'S'][d.getUTCDay()]!
 }
+
+const consistencyLabel = computed(() => {
+  if (!data.value) return ''
+  const dayWord = data.value.activeDays === 1 ? 'day' : 'days'
+  return `${data.value.activeDays} active ${dayWord} · ${data.value.consistencyPercent}% consistency`
+})
 </script>
 
 <template>
@@ -33,16 +39,13 @@ function getDayLabel(dateStr: string): string {
       <span class="text-[15px] font-semibold text-foreground">Reading Rhythm</span>
     </div>
 
-    <!-- Loading -->
     <div v-if="loading" class="flex flex-1 flex-col gap-2">
       <div class="flex-1 animate-pulse rounded bg-muted" />
       <div class="h-3 w-20 animate-pulse rounded bg-muted" />
     </div>
 
-    <!-- Error -->
     <div v-else-if="error" class="flex flex-1 items-center justify-center text-sm text-muted-foreground">Failed to load</div>
 
-    <!-- Empty -->
     <div v-else-if="!data || data.activeDays === 0" class="flex flex-1 flex-col items-center justify-center gap-2">
       <div class="flex h-10 w-10 items-center justify-center rounded-full bg-muted">
         <HeartPulse :size="16" class="text-muted-foreground/60" />
@@ -50,9 +53,7 @@ function getDayLabel(dateStr: string): string {
       <p class="text-center text-xs text-muted-foreground">Start reading to see your rhythm take shape</p>
     </div>
 
-    <!-- Rhythm chart -->
     <div v-else class="flex flex-1 flex-col">
-      <!-- Bars area — columns stretch to full height via default align-items:stretch -->
       <div class="flex flex-1 gap-[3px]">
         <div v-for="day in data.days" :key="day.date" class="flex flex-1 flex-col-reverse">
           <div
@@ -63,16 +64,14 @@ function getDayLabel(dateStr: string): string {
         </div>
       </div>
 
-      <!-- Day labels row -->
       <div class="flex gap-[3px] pb-1 pt-0.5">
         <div v-for="day in data.days" :key="day.date + '-lbl'" class="flex flex-1 justify-center">
           <span class="text-[8.5px] text-muted-foreground/70">{{ getDayLabel(day.date) }}</span>
         </div>
       </div>
 
-      <!-- Stats footer -->
-      <div class="flex items-center justify-between border-t border-border/30 pt-1.5">
-        <span class="text-[11px] text-muted-foreground"> {{ data.consistencyPercent }}% consistent </span>
+      <div class="flex flex-wrap items-center justify-between gap-x-2 gap-y-1 border-t border-border/30 pt-1.5">
+        <span class="text-[11px] text-muted-foreground"> {{ consistencyLabel }} </span>
         <span class="text-[11px] text-muted-foreground"> avg {{ formatTime(data.avgSecondsPerDay) }}/day </span>
       </div>
     </div>
diff --git a/client/src/features/kobo/composables/useKoboSettings.ts b/client/src/features/kobo/composables/useKoboSettings.ts
index 3a60f1d07..950d4aa9a 100644
--- a/client/src/features/kobo/composables/useKoboSettings.ts
+++ b/client/src/features/kobo/composables/useKoboSettings.ts
@@ -9,6 +9,7 @@ const settings = ref<KoboSyncSettings>({
   forceEnableHyphenation: false,
   kepubConversionLimitMb: 100,
   twoWayProgressSync: false,
+  syncBookOrbitAnnotationsToKobo: false,
 })
 let fetchPromise: Promise<void> | null = null
 
diff --git a/client/src/features/koreader/composables/__tests__/useKoreaderSync.spec.ts b/client/src/features/koreader/composables/__tests__/useKoreaderSync.spec.ts
index 328a8acb5..8d31728c3 100644
--- a/client/src/features/koreader/composables/__tests__/useKoreaderSync.spec.ts
+++ b/client/src/features/koreader/composables/__tests__/useKoreaderSync.spec.ts
@@ -29,6 +29,10 @@ function makeSyncStatus(overrides: Partial<KoreaderSyncStatus> = {}): KoreaderSy
     ],
     totalSyncedBooks: 14,
     lastSyncAt: '2026-01-02T00:00:00.000Z',
+    latestPluginVersion: '0.5.0',
+    pluginUpdateAvailable: false,
+    sweeps: [],
+    pluginTotals: { matchedBooks: 0, trashedAnnotations: 0, pendingDeletes: 0, failedPositions: 0, pageStatEvents: 0, annotations: 0 },
     ...overrides,
   }
 }
@@ -189,4 +193,42 @@ describe('useKoreaderSync', () => {
 
     expect(getSyncUrl()).toBe(`${window.location.origin}/api/v1/koreader`)
   })
+
+  it('downloadPluginPackage requests the zip with the current origin and triggers a download', async () => {
+    const blob = new Blob(['zip'])
+    apiMock.mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({}), blob: async () => blob } as unknown as Response)
+
+    const originalCreateObjectURL = URL.createObjectURL
+    const originalRevokeObjectURL = URL.revokeObjectURL
+    const createObjectURL = vi.fn<(obj: Blob | MediaSource) => string>(() => 'blob:plugin-zip')
+    const revokeObjectURL = vi.fn<(url: string) => void>()
+    URL.createObjectURL = createObjectURL
+    URL.revokeObjectURL = revokeObjectURL
+    const clickSpy = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+
+    try {
+      const { useKoreaderSync } = await import('../useKoreaderSync')
+      const { downloadPluginPackage } = useKoreaderSync()
+
+      await downloadPluginPackage()
+
+      expect(apiMock).toHaveBeenCalledWith(`/api/v1/koreader/plugin-package?origin=${encodeURIComponent(window.location.origin)}`)
+      expect(createObjectURL).toHaveBeenCalledWith(blob)
+      expect(clickSpy).toHaveBeenCalledTimes(1)
+      expect(revokeObjectURL).toHaveBeenCalledWith('blob:plugin-zip')
+    } finally {
+      URL.createObjectURL = originalCreateObjectURL
+      URL.revokeObjectURL = originalRevokeObjectURL
+      clickSpy.mockRestore()
+    }
+  })
+
+  it('downloadPluginPackage throws the server message on failure', async () => {
+    apiMock.mockResolvedValueOnce(makeResponse({ message: 'Create KOReader sync credentials first' }, { ok: false, status: 404 }))
+
+    const { useKoreaderSync } = await import('../useKoreaderSync')
+    const { downloadPluginPackage } = useKoreaderSync()
+
+    await expect(downloadPluginPackage()).rejects.toThrow('Create KOReader sync credentials first')
+  })
 })
diff --git a/client/src/features/koreader/composables/useKoreaderSync.ts b/client/src/features/koreader/composables/useKoreaderSync.ts
index 6a8cfb8a9..693f6f68b 100644
--- a/client/src/features/koreader/composables/useKoreaderSync.ts
+++ b/client/src/features/koreader/composables/useKoreaderSync.ts
@@ -67,6 +67,17 @@ export function useKoreaderSync() {
     return `${window.location.origin}/api/v1/koreader`
   }
 
+  async function downloadPluginPackage(): Promise<void> {
+    const origin = encodeURIComponent(window.location.origin)
+    const res = await api(`/api/v1/koreader/plugin-package?origin=${origin}`)
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}))
+      throw new Error(body.message || 'Failed to download the plugin')
+    }
+    const blob = await res.blob()
+    triggerBlobDownload(blob, 'bookorbit.koplugin.zip')
+  }
+
   return {
     credentials,
     syncStatus,
@@ -77,5 +88,18 @@ export function useKoreaderSync() {
     deleteCredentials,
     testConnection,
     getSyncUrl,
+    downloadPluginPackage,
   }
 }
+
+function triggerBlobDownload(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = filename
+  anchor.rel = 'noopener'
+  document.body.append(anchor)
+  anchor.click()
+  anchor.remove()
+  URL.revokeObjectURL(url)
+}
diff --git a/client/src/features/reader/ReaderView.vue b/client/src/features/reader/ReaderView.vue
index 02bd51f6a..12d8c6a54 100644
--- a/client/src/features/reader/ReaderView.vue
+++ b/client/src/features/reader/ReaderView.vue
@@ -246,7 +246,7 @@ const {
 
 function handleTextSelected(detail: SelectionDetail) {
   const selCfi = detail.cfi
-  const match = selCfi ? (annotations.annotations.value.find((a) => cfiRangesOverlap(selCfi, a.cfi)) ?? null) : null
+  const match = selCfi ? (annotations.annotations.value.find((a) => a.cfi != null && cfiRangesOverlap(selCfi, a.cfi)) ?? null) : null
   selection.show(detail, match?.id ?? null)
 }
 
@@ -295,11 +295,21 @@ onMounted(async () => {
   sectionFractions.value = getSectionFractions()
   await bookmarks.load(bookId)
   await annotations.load(bookId)
-  if (annotations.annotations.value.length > 0) {
-    addAnnotations(annotations.annotations.value.map((a) => ({ cfi: a.cfi, color: a.color, style: a.style })))
+  const drawableAnnotations = annotations.annotations.value.filter((a): a is typeof a & { cfi: string } => a.cfi != null)
+  if (drawableAnnotations.length > 0) {
+    addAnnotations(drawableAnnotations.map((a) => ({ cfi: a.cfi, color: a.color, style: a.style })))
   }
   void hydrateSidebarLocationMeta()
 
+  const deepLinkCfi = typeof route.query.cfi === 'string' ? route.query.cfi : null
+  if (deepLinkCfi) {
+    try {
+      await goTo(deepLinkCfi)
+    } catch {
+      toast.error('Could not open the linked highlight position')
+    }
+  }
+
   if (hadProgress) {
     const pct = Math.round(progress.percentage.value)
     const label = chapterTitle.value || `Chapter ${sectionIndex.value + 1}`
@@ -381,13 +391,14 @@ async function handleHighlight(color: string, style: string, note?: string) {
   if (!selection.text.value || !annotationCfi) return
   const created = await annotations.create(bookId, {
     cfi: annotationCfi,
+    bookFileId: fileId,
     text: selection.text.value,
     color,
     style,
     note: note ?? null,
     chapterTitle: chapterTitle.value || null,
   })
-  if (created) {
+  if (created?.cfi) {
     addAnnotation(created.cfi, created.color, created.style)
   }
   selection.dismiss()
@@ -402,7 +413,7 @@ async function handleSaveNote(note: string) {
 function handleDeleteAnnotation(id: number) {
   const ann = annotations.annotations.value.find((a) => a.id === id)
   if (ann) {
-    deleteAnnotation(ann.cfi)
+    if (ann.cfi) deleteAnnotation(ann.cfi)
     annotations.remove(bookId, id)
   }
   selection.dismiss()
@@ -411,7 +422,7 @@ function handleDeleteAnnotation(id: number) {
 function handleSidebarDeleteAnnotation(id: number) {
   const ann = annotations.annotations.value.find((a) => a.id === id)
   if (ann) {
-    deleteAnnotation(ann.cfi)
+    if (ann.cfi) deleteAnnotation(ann.cfi)
     annotations.remove(bookId, id)
   }
 }
@@ -504,6 +515,16 @@ async function navigateFromSidebar(cfiTarget: string) {
   showSidebar.value = false
 }
 
+function navigateAnnotationChapterFromSidebar(chapterIndex: number) {
+  const goToPromise = goToSection(chapterIndex)
+  if (!goToPromise) return
+  void Promise.resolve(goToPromise)
+    .then(() => {
+      showSidebar.value = false
+    })
+    .catch(() => undefined)
+}
+
 function navigateChapterFromSidebar(href: string) {
   goTo(href)
   showSidebar.value = false
@@ -617,6 +638,7 @@ watch(
       @navigateChapter="navigateChapterFromSidebar"
       @navigateBookmark="navigateFromSidebar"
       @navigateAnnotation="navigateFromSidebar"
+      @navigateAnnotationChapter="navigateAnnotationChapterFromSidebar"
       @deleteBookmark="handleSidebarDeleteBookmark"
       @deleteAnnotation="handleSidebarDeleteAnnotation"
       @toggleExpand="toggleExpand"
diff --git a/client/src/features/reader/epub/components/ReaderSidebar.vue b/client/src/features/reader/epub/components/ReaderSidebar.vue
index 9d98121ee..4025d20ca 100644
--- a/client/src/features/reader/epub/components/ReaderSidebar.vue
+++ b/client/src/features/reader/epub/components/ReaderSidebar.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, nextTick, ref, watch } from 'vue'
-import { Bookmark, BookOpen, Highlighter, Trash2 } from '@lucide/vue'
+import { Bookmark, BookOpen, Highlighter, Trash2, TriangleAlert } from '@lucide/vue'
+import { ANNOTATION_COLOR_FILTER_OPTIONS } from '@bookorbit/types'
 import type { TocItem } from '../composables/useToc'
 import type { Bookmark as BookmarkType } from '../composables/useBookmarks'
 import type { Annotation } from '../composables/useAnnotations'
@@ -22,6 +23,7 @@ const emit = defineEmits<{
   navigateChapter: [href: string]
   navigateBookmark: [cfi: string]
   navigateAnnotation: [cfi: string]
+  navigateAnnotationChapter: [chapterIndex: number]
   deleteBookmark: [id: number]
   deleteAnnotation: [id: number]
   toggleExpand: [href: string]
@@ -39,27 +41,19 @@ const highlightColorFilter = ref('all')
 const highlightChapterFilter = ref('all')
 const highlightNotesOnly = ref(false)
 
-const HIGHLIGHT_COLOR_META: Record<string, { label: string; sample: string }> = {
-  '#FACC15': { label: 'Yellow', sample: '🟡' },
-  '#4ADE80': { label: 'Green', sample: '🟢' },
-  '#38BDF8': { label: 'Blue', sample: '🔵' },
-  '#F472B6': { label: 'Pink', sample: '🩷' },
-  '#FB923C': { label: 'Orange', sample: '🟠' },
-}
+const HIGHLIGHT_COLOR_META = Object.fromEntries(ANNOTATION_COLOR_FILTER_OPTIONS.map((color) => [color.hex, { label: color.label }])) as Record<
+  string,
+  { label: string }
+>
 
 function getHighlightColorLabel(color: string): string {
   const normalized = color.trim().toUpperCase()
   return HIGHLIGHT_COLOR_META[normalized]?.label ?? `Custom (${normalized})`
 }
 
-function getHighlightColorSample(color: string): string {
-  const normalized = color.trim().toUpperCase()
-  return HIGHLIGHT_COLOR_META[normalized]?.sample ?? '◉'
-}
-
 const highlightColorOptions = computed(() =>
   Array.from(new Set(props.annotations.map((ann) => ann.color)))
-    .map((hex) => ({ hex, label: getHighlightColorLabel(hex), sample: getHighlightColorSample(hex) }))
+    .map((hex) => ({ hex, label: getHighlightColorLabel(hex) }))
     .sort((a, b) => a.label.localeCompare(b.label)),
 )
 const highlightChapterOptions = computed(() =>
@@ -182,9 +176,18 @@ function navigateBookmark(cfi: string | null | undefined) {
   emit('navigateBookmark', cfi)
 }
 
-function navigateAnnotation(cfi: string | null | undefined) {
-  if (!cfi) return
-  emit('navigateAnnotation', cfi)
+function navigateAnnotation(ann: Annotation) {
+  if (ann.cfi) {
+    emit('navigateAnnotation', ann.cfi)
+    return
+  }
+  if (ann.chapterIndex != null) {
+    emit('navigateAnnotationChapter', ann.chapterIndex)
+  }
+}
+
+function isApproximateAnnotation(ann: Annotation): boolean {
+  return ann.cfi == null
 }
 
 function deleteBookmark(id: number) {
@@ -313,7 +316,7 @@ function deleteAnnotation(id: number) {
                   class="h-8 rounded-md border border-border bg-background px-2 text-xs text-muted-foreground outline-none focus:border-primary"
                 >
                   <option value="all">All colors</option>
-                  <option v-for="color in highlightColorOptions" :key="color.hex" :value="color.hex">{{ color.sample }} {{ color.label }}</option>
+                  <option v-for="color in highlightColorOptions" :key="color.hex" :value="color.hex">{{ color.label }}</option>
                 </select>
                 <select
                   v-model="highlightChapterFilter"
@@ -339,11 +342,19 @@ function deleteAnnotation(id: number) {
                 :data-reader-active-row="ann.id === activeAnnotationId ? 'highlight' : undefined"
               >
                 <div class="flex items-start gap-2">
-                  <button type="button" class="flex flex-1 min-w-0 items-start gap-2 text-left cursor-pointer" @click="navigateAnnotation(ann.cfi)">
+                  <button type="button" class="flex flex-1 min-w-0 items-start gap-2 text-left cursor-pointer" @click="navigateAnnotation(ann)">
                     <span class="mt-1.5 w-2.5 h-2.5 rounded-full shrink-0" :style="{ background: ann.color }" />
                     <div class="flex-1 min-w-0">
                       <p class="text-[13px] leading-relaxed line-clamp-3">{{ ann.text }}</p>
-                      <p class="text-[11px] text-muted-foreground mt-1">{{ getHighlightContextLine(ann) }}</p>
+                      <p class="text-[11px] text-muted-foreground mt-1 flex items-center gap-1">
+                        <Tooltip v-if="isApproximateAnnotation(ann)">
+                          <TooltipTrigger as-child>
+                            <TriangleAlert :size="11" class="shrink-0 text-amber-500" />
+                          </TooltipTrigger>
+                          <TooltipContent>Synced from device; exact position unavailable, jumps to the chapter</TooltipContent>
+                        </Tooltip>
+                        <span>{{ getHighlightContextLine(ann) }}</span>
+                      </p>
                       <p class="text-[11px] text-muted-foreground mt-0.5">{{ formatDate(ann.createdAt) }}</p>
                       <p v-if="ann.note" class="text-[11px] text-muted-foreground mt-1 italic">{{ ann.note }}</p>
                     </div>
diff --git a/client/src/features/reader/epub/components/SelectionPopup.vue b/client/src/features/reader/epub/components/SelectionPopup.vue
index 2dc2314c6..ca99baaea 100644
--- a/client/src/features/reader/epub/components/SelectionPopup.vue
+++ b/client/src/features/reader/epub/components/SelectionPopup.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { BookA, Check, Copy, FileText, Highlighter, Languages, Search, Trash2 } from '@lucide/vue'
+import { ANNOTATION_HIGHLIGHT_COLORS } from '@bookorbit/types'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 import { copyToClipboard } from '@/lib/clipboard'
 
@@ -26,13 +27,7 @@ const emit = defineEmits<{
 const showColorPicker = ref(false)
 const copied = ref(false)
 
-const colors = [
-  { hex: '#FACC15', label: 'Yellow' },
-  { hex: '#4ADE80', label: 'Green' },
-  { hex: '#38BDF8', label: 'Blue' },
-  { hex: '#F472B6', label: 'Pink' },
-  { hex: '#FB923C', label: 'Orange' },
-]
+const colors = ANNOTATION_HIGHLIGHT_COLORS
 
 const styles = [
   { id: 'highlight', label: 'H' },
@@ -182,8 +177,11 @@ async function onCopy() {
                 class="w-6 h-6 rounded-full border-2 transition-all hover:scale-110"
                 :class="selectedColor === c.hex ? 'border-foreground scale-110' : 'border-transparent'"
                 :style="{ background: c.hex }"
+                :title="c.label"
                 @click="selectedColor = c.hex"
-              />
+              >
+                <span class="sr-only">{{ c.label }}</span>
+              </button>
             </div>
             <div class="flex gap-1 px-0.5">
               <button
diff --git a/client/src/features/reader/epub/components/__tests__/ReaderSidebar.spec.ts b/client/src/features/reader/epub/components/__tests__/ReaderSidebar.spec.ts
index cc7e4791b..806abfcd8 100644
--- a/client/src/features/reader/epub/components/__tests__/ReaderSidebar.spec.ts
+++ b/client/src/features/reader/epub/components/__tests__/ReaderSidebar.spec.ts
@@ -115,22 +115,32 @@ describe('ReaderSidebar', () => {
             id: 9,
             bookId: 1,
             cfi: 'epubcfi(/6/8)',
+            jumpFileId: 101,
+            pageno: null,
             text: 'Highlight text',
             color: '#FACC15',
             style: 'highlight',
             note: 'note',
             chapterTitle: 'Intro',
+            origin: 'web',
+            positionStatus: 'exact',
+            chapterIndex: null,
             createdAt: '2026-02-14T12:00:00.000Z',
           },
           {
             id: 10,
             bookId: 1,
             cfi: 'epubcfi(/6/12)',
+            jumpFileId: 101,
+            pageno: null,
             text: 'Second highlight',
             color: '#38BDF8',
             style: 'underline',
             note: null,
             chapterTitle: null,
+            origin: 'web',
+            positionStatus: 'exact',
+            chapterIndex: null,
             createdAt: '2026-02-15T12:00:00.000Z',
           },
         ],
@@ -181,22 +191,32 @@ describe('ReaderSidebar', () => {
             id: 11,
             bookId: 1,
             cfi: 'epubcfi(/6/4)',
+            jumpFileId: 101,
+            pageno: null,
             text: 'Alpha quote',
             color: '#FACC15',
             style: 'highlight',
             note: null,
             chapterTitle: null,
+            origin: 'web',
+            positionStatus: 'exact',
+            chapterIndex: null,
             createdAt: '2026-02-13T12:00:00.000Z',
           },
           {
             id: 12,
             bookId: 1,
             cfi: 'epubcfi(/6/10)',
+            jumpFileId: 101,
+            pageno: null,
             text: 'Beta insight',
             color: '#38BDF8',
             style: 'underline',
             note: 'note here',
             chapterTitle: 'Chapter Ten',
+            origin: 'web',
+            positionStatus: 'exact',
+            chapterIndex: null,
             createdAt: '2026-02-16T12:00:00.000Z',
           },
         ],
@@ -282,11 +302,16 @@ describe('ReaderSidebar', () => {
             id: 31,
             bookId: 1,
             cfi: 'epubcfi(/6/8)',
+            jumpFileId: 101,
+            pageno: null,
             text: 'Custom color text',
             color: '#abc123',
             style: 'highlight',
             note: null,
             chapterTitle: null,
+            origin: 'web',
+            positionStatus: 'exact',
+            chapterIndex: null,
             createdAt: '2026-02-11T12:00:00.000Z',
           },
         ],
diff --git a/client/src/features/reader/epub/components/__tests__/SelectionPopup.spec.ts b/client/src/features/reader/epub/components/__tests__/SelectionPopup.spec.ts
index a4b0fc1e1..047b7eaa1 100644
--- a/client/src/features/reader/epub/components/__tests__/SelectionPopup.spec.ts
+++ b/client/src/features/reader/epub/components/__tests__/SelectionPopup.spec.ts
@@ -69,6 +69,28 @@ describe('SelectionPopup', () => {
     expect(wrapper.emitted('highlight')?.[1]).toEqual(['#FACC15', 'highlight'])
   })
 
+  it('shows KOReader-equivalent highlight colors in the picker', async () => {
+    const wrapper = mount(SelectionPopup, {
+      props: {
+        visible: true,
+        position: { x: 100, y: 200 },
+        showBelow: false,
+        selectedText: 'Text',
+        overlappingAnnotationId: null,
+      },
+      global: globalStubs,
+    })
+
+    const highlightButton = wrapper.findAll('button')[1]!
+    await highlightButton.trigger('click')
+
+    expect(wrapper.text()).toContain('Red')
+    expect(wrapper.text()).toContain('Olive')
+    expect(wrapper.text()).toContain('Cyan')
+    expect(wrapper.text()).toContain('Purple')
+    expect(wrapper.text()).toContain('Gray')
+  })
+
   it('shows delete action only when overlapping annotation exists', async () => {
     const withDelete = mount(SelectionPopup, {
       props: {
diff --git a/client/src/features/reader/epub/composables/__tests__/useAnnotations.spec.ts b/client/src/features/reader/epub/composables/__tests__/useAnnotations.spec.ts
index 20f546427..1a8e91cc1 100644
--- a/client/src/features/reader/epub/composables/__tests__/useAnnotations.spec.ts
+++ b/client/src/features/reader/epub/composables/__tests__/useAnnotations.spec.ts
@@ -17,11 +17,16 @@ function makeAnnotation(id: number, cfi = `epubcfi(/6/${id})`): Annotation {
     id,
     bookId: 9,
     cfi,
+    jumpFileId: 33,
+    pageno: null,
     text: `Selection ${id}`,
     color: '#FACC15',
     style: 'highlight',
     note: null,
     chapterTitle: 'Intro',
+    origin: 'web',
+    positionStatus: 'exact',
+    chapterIndex: null,
     createdAt: '2026-01-01T00:00:00.000Z',
   }
 }
@@ -62,11 +67,12 @@ describe('useAnnotations', () => {
 
   it('creates and appends annotation on success', async () => {
     const created = makeAnnotation(3)
+    const createdCfi = created.cfi ?? 'epubcfi(/6/3)'
     apiMock.mockResolvedValueOnce(response(true, created))
 
     const store = useAnnotations()
     const result = await store.create(9, {
-      cfi: created.cfi,
+      cfi: createdCfi,
       text: created.text,
       color: created.color,
       style: created.style,
@@ -78,7 +84,7 @@ describe('useAnnotations', () => {
     expect(url).toBe('/api/v1/books/9/annotations')
     expect(req.method).toBe('POST')
     expect(JSON.parse(String(req.body))).toEqual({
-      cfi: created.cfi,
+      cfi: createdCfi,
       text: created.text,
       color: created.color,
       style: created.style,
diff --git a/client/src/features/reader/epub/composables/useAnnotations.ts b/client/src/features/reader/epub/composables/useAnnotations.ts
index b6b63ab84..8801dcade 100644
--- a/client/src/features/reader/epub/composables/useAnnotations.ts
+++ b/client/src/features/reader/epub/composables/useAnnotations.ts
@@ -1,17 +1,8 @@
 import { ref } from 'vue'
+import type { AnnotationItem } from '@bookorbit/types'
 import { api } from '@/lib/api'
 
-export interface Annotation {
-  id: number
-  bookId: number
-  cfi: string
-  text: string
-  color: string
-  style: string
-  note: string | null
-  chapterTitle: string | null
-  createdAt: string
-}
+export type Annotation = AnnotationItem
 
 export function useAnnotations() {
   const annotations = ref<Annotation[]>([])
@@ -29,7 +20,7 @@ export function useAnnotations() {
 
   async function create(
     bookId: number,
-    data: { cfi: string; text: string; color: string; style: string; note?: string | null; chapterTitle?: string | null },
+    data: { cfi: string; bookFileId?: number; text: string; color: string; style: string; note?: string | null; chapterTitle?: string | null },
   ): Promise<Annotation | null> {
     const res = await api(`/api/v1/books/${bookId}/annotations`, {
       method: 'POST',
diff --git a/client/src/features/reader/epub/composables/useFoliateAnnotations.ts b/client/src/features/reader/epub/composables/useFoliateAnnotations.ts
index 022d44b9f..26e9515c8 100644
--- a/client/src/features/reader/epub/composables/useFoliateAnnotations.ts
+++ b/client/src/features/reader/epub/composables/useFoliateAnnotations.ts
@@ -40,6 +40,21 @@ export function useFoliateAnnotations() {
           }
           return g
         }
+      case 'invert':
+        return (rects: DOMRectList, { color = '#FFFFFF' }: { color?: string } = {}) => {
+          const g = createSVG('g')
+          g.setAttribute('fill', color)
+          ;(g as SVGElement).style.mixBlendMode = 'difference'
+          for (const { left, top, height, width } of Array.from(rects)) {
+            const el = createSVG('rect')
+            el.setAttribute('x', String(left))
+            el.setAttribute('y', String(top))
+            el.setAttribute('height', String(height))
+            el.setAttribute('width', String(width))
+            g.append(el)
+          }
+          return g
+        }
       case 'squiggly':
         return (rects: DOMRectList, { color = 'red' }: { color?: string } = {}) => {
           const g = createSVG('g')
diff --git a/client/src/features/reader/pdf-v4/PdfV4ReaderView.vue b/client/src/features/reader/pdf-v4/PdfV4ReaderView.vue
index b111fcf67..aa7db6959 100644
--- a/client/src/features/reader/pdf-v4/PdfV4ReaderView.vue
+++ b/client/src/features/reader/pdf-v4/PdfV4ReaderView.vue
@@ -128,7 +128,9 @@ async function setupProgressTracking(registry: PluginRegistry) {
 
   unsubLayoutReady = scroll.onLayoutReady(({ isInitial, totalPages }) => {
     if (!isInitial) return
-    const initialPage = progress.pageNumber.value ?? 1
+    const deepLinkQuery = route?.query?.page
+    const deepLinkPage = typeof deepLinkQuery === 'string' ? Number.parseInt(deepLinkQuery, 10) : NaN
+    const initialPage = Number.isFinite(deepLinkPage) && deepLinkPage >= 1 ? deepLinkPage : (progress.pageNumber.value ?? 1)
     currentPageNumber.value = initialPage
     totalPageCount.value = totalPages
     if (initialPage > 1 && initialPage <= totalPages) {
diff --git a/client/src/features/settings/IntegrationsAllSettings.vue b/client/src/features/settings/IntegrationsAllSettings.vue
deleted file mode 100644
index a719b1ec7..000000000
--- a/client/src/features/settings/IntegrationsAllSettings.vue
+++ /dev/null
@@ -1,66 +0,0 @@
-<script setup lang="ts">
-import { computed, ref, watch } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import SettingsPageHeader from './SettingsPageHeader.vue'
-import KoboSettings from './KoboSettings.vue'
-import KoreaderSettings from './KoreaderSettings.vue'
-import HardcoverSettings from '@/features/hardcover/components/HardcoverSettings.vue'
-import { usePermissions } from '@/features/auth/composables/usePermissions'
-import { INTEGRATIONS_TAB_INFO, INTEGRATIONS_TABS, normalizeIntegrationsTab, type IntegrationsTab as Tab } from './lib/integrations-tabs'
-
-const route = useRoute()
-const router = useRouter()
-const { hasPermission } = usePermissions()
-
-const allowedTabs = computed<Tab[]>(() => INTEGRATIONS_TABS.filter((tab) => hasPermission(INTEGRATIONS_TAB_INFO[tab].permission)))
-const activeTab = ref<Tab>(normalizeIntegrationsTab(route.query.tab, allowedTabs.value))
-
-watch(
-  [() => route.query.tab, allowedTabs],
-  ([value, tabs]) => {
-    if (tabs.length === 0) {
-      router.replace({ name: 'settings-appearance' })
-      return
-    }
-    const normalized = normalizeIntegrationsTab(value, tabs)
-    activeTab.value = normalized
-    if (value !== normalized) {
-      router.replace({ name: 'settings-integrations', query: { ...route.query, tab: normalized } })
-    }
-  },
-  { immediate: true },
-)
-
-const tabs = computed(() => allowedTabs.value.map((id) => ({ id, label: INTEGRATIONS_TAB_INFO[id].navLabel })))
-
-function selectTab(tab: Tab) {
-  if (!allowedTabs.value.includes(tab)) return
-  activeTab.value = tab
-  router.replace({ name: 'settings-integrations', query: { ...route.query, tab } })
-}
-</script>
-
-<template>
-  <SettingsPageHeader title="Integrations" subtitle="Configure connections to external devices and services." />
-
-  <div
-    v-if="tabs.length > 0"
-    class="flex gap-1 mb-5 md:mb-6 border-b border-border overflow-x-auto md:overflow-visible md:static sticky top-0 z-20 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/80 snap-x"
-  >
-    <button
-      v-for="tab in tabs"
-      :key="tab.id"
-      class="px-3 py-3 md:py-2 text-sm font-medium shrink-0 border-b-2 -mb-px transition-colors snap-start"
-      :class="
-        activeTab === tab.id ? 'border-primary text-foreground' : 'border-transparent text-muted-foreground hover:text-foreground hover:border-border'
-      "
-      @click="selectTab(tab.id)"
-    >
-      {{ tab.label }}
-    </button>
-  </div>
-
-  <KoboSettings v-if="tabs.length > 0 && activeTab === 'kobo'" embedded />
-  <KoreaderSettings v-else-if="tabs.length > 0 && activeTab === 'koreader'" embedded />
-  <HardcoverSettings v-else-if="tabs.length > 0 && activeTab === 'hardcover'" embedded />
-</template>
diff --git a/client/src/features/settings/KoboSettings.vue b/client/src/features/settings/KoboSettings.vue
index 7e0896bcd..bb79d514b 100644
--- a/client/src/features/settings/KoboSettings.vue
+++ b/client/src/features/settings/KoboSettings.vue
@@ -39,6 +39,7 @@ const convertToKepub = ref(true)
 const forceEnableHyphenation = ref(false)
 const kepubConversionLimitMb = ref(100)
 const twoWayProgressSync = ref(false)
+const syncBookOrbitAnnotationsToKobo = ref(false)
 const savingSettings = ref(false)
 const settingsError = ref<string | null>(null)
 
@@ -49,6 +50,7 @@ function applySettingsToLocal() {
   forceEnableHyphenation.value = settings.value.forceEnableHyphenation
   kepubConversionLimitMb.value = settings.value.kepubConversionLimitMb
   twoWayProgressSync.value = settings.value.twoWayProgressSync
+  syncBookOrbitAnnotationsToKobo.value = settings.value.syncBookOrbitAnnotationsToKobo
 }
 
 function formatLastSeen(date: string | null): string {
@@ -80,6 +82,10 @@ watch(twoWayProgressSync, (enabled) => {
   if (enabled) convertToKepub.value = true
 })
 
+watch(syncBookOrbitAnnotationsToKobo, (enabled) => {
+  if (enabled) convertToKepub.value = true
+})
+
 async function submitCreate() {
   if (!newDeviceName.value.trim()) return
   creating.value = true
@@ -170,6 +176,7 @@ async function saveSettings() {
       forceEnableHyphenation: forceEnableHyphenation.value,
       kepubConversionLimitMb: kepubConversionLimitMb.value,
       twoWayProgressSync: twoWayProgressSync.value,
+      syncBookOrbitAnnotationsToKobo: syncBookOrbitAnnotationsToKobo.value,
     })
     applySettingsToLocal()
     toast.success('Kobo sync settings saved')
@@ -308,7 +315,7 @@ async function saveSettings() {
           <div class="pr-8">
             <p class="settings-label">Two-way progress sync</p>
             <p class="settings-hint">
-              Syncs reading position between BookOrbit and Kobo. For reliable page restore on Kobo, books must be sent as KEPUB.
+              Sync reading position between BookOrbit and Kobo. Requires KEPUB delivery for precise locations and reliable page restore.
             </p>
           </div>
           <ToggleSwitch v-model="twoWayProgressSync" />
@@ -316,13 +323,24 @@ async function saveSettings() {
 
         <div class="flex items-center justify-between px-5 py-4 bg-card">
           <div class="pr-8">
-            <p class="settings-label">Convert to KEPUB</p>
+            <p class="settings-label">Sync BookOrbit highlights to Kobo</p>
             <p class="settings-hint">
-              Required when two-way progress sync is enabled. On the next Kobo sync, affected books are offered again as KEPUB downloads. If Kobo
-              keeps opening an old EPUB copy, remove that book from Kobo and sync again.
+              Send highlights made in BookOrbit or KOReader to your Kobo. Kobo highlights are imported into BookOrbit even when this is off. Linked
+              annotations sync edits and deletes both ways. Requires KEPUB delivery; the book on Kobo must be the KEPUB downloaded from BookOrbit.
             </p>
           </div>
-          <ToggleSwitch v-model="convertToKepub" :disabled="twoWayProgressSync" />
+          <ToggleSwitch v-model="syncBookOrbitAnnotationsToKobo" />
+        </div>
+
+        <div class="flex items-center justify-between px-5 py-4 bg-card">
+          <div class="pr-8">
+            <p class="settings-label">Convert to KEPUB</p>
+            <p class="settings-hint">
+              Send eligible EPUBs as KEPUB. This stays on when progress sync or BookOrbit-to-Kobo highlights are enabled. On the next Kobo sync,
+              affected books are offered again as KEPUB downloads; remove any old EPUB copy if Kobo keeps opening it.
+            </p>
+          </div>
+          <ToggleSwitch v-model="convertToKepub" :disabled="twoWayProgressSync || syncBookOrbitAnnotationsToKobo" />
         </div>
 
         <div v-if="convertToKepub" class="flex items-center justify-between px-5 py-4 bg-card">
diff --git a/client/src/features/settings/KoreaderSettings.vue b/client/src/features/settings/KoreaderSettings.vue
index 8fe533e16..cea90386d 100644
--- a/client/src/features/settings/KoreaderSettings.vue
+++ b/client/src/features/settings/KoreaderSettings.vue
@@ -1,6 +1,22 @@
 <script setup lang="ts">
 import { computed, onMounted, onUnmounted, ref } from 'vue'
-import { Copy, Trash2, BookOpen, Smartphone, Check, Eye, EyeOff, RefreshCw, ChevronDown, ChevronUp } from '@lucide/vue'
+import {
+  AlertTriangle,
+  BookOpen,
+  Calendar,
+  Check,
+  ChevronDown,
+  ChevronUp,
+  Copy,
+  Download,
+  Eye,
+  EyeOff,
+  Library,
+  RefreshCw,
+  Smartphone,
+  Trash2,
+  User,
+} from '@lucide/vue'
 import { toast } from 'vue-sonner'
 import SettingsPageHeader from './SettingsPageHeader.vue'
 import ToggleSwitch from '@/components/ui/ToggleSwitch.vue'
@@ -9,7 +25,17 @@ import { useKoreaderSync } from '@/features/koreader/composables/useKoreaderSync
 
 const props = withDefaults(defineProps<{ embedded?: boolean }>(), { embedded: false })
 
-const { credentials, syncStatus, loading, fetchSyncStatus, createCredentials, updateCredentials, deleteCredentials, getSyncUrl } = useKoreaderSync()
+const {
+  credentials,
+  syncStatus,
+  loading,
+  fetchSyncStatus,
+  createCredentials,
+  updateCredentials,
+  deleteCredentials,
+  getSyncUrl,
+  downloadPluginPackage,
+} = useKoreaderSync()
 
 const error = ref<string | null>(null)
 const showSetupForm = ref(false)
@@ -18,7 +44,7 @@ const newPassword = ref('')
 const creating = ref(false)
 const showPassword = ref(false)
 const deleteConfirmOpen = ref(false)
-const helpOpen = ref(true)
+const helpOpen = ref(false)
 const urlCopied = ref(false)
 
 let urlCopiedTimer: ReturnType<typeof setTimeout> | null = null
@@ -31,6 +57,34 @@ const syncUrl = computed(() => getSyncUrl())
 const hasCredentials = computed(() => !!credentials.value)
 const deviceCount = computed(() => syncStatus.value?.devices.length ?? 0)
 const totalSyncedBooks = computed(() => syncStatus.value?.totalSyncedBooks ?? 0)
+const sweeps = computed(() => syncStatus.value?.sweeps ?? [])
+const pluginTotals = computed(
+  () =>
+    syncStatus.value?.pluginTotals ?? {
+      matchedBooks: 0,
+      pageStatEvents: 0,
+      annotations: 0,
+      trashedAnnotations: 0,
+      pendingDeletes: 0,
+      failedPositions: 0,
+    },
+)
+const latestPluginVersion = computed(() => syncStatus.value?.latestPluginVersion ?? null)
+const pluginUpdateAvailable = computed(() => syncStatus.value?.pluginUpdateAvailable ?? false)
+const latestPluginLabel = computed(() => (latestPluginVersion.value ? `Latest plugin: v${latestPluginVersion.value}` : 'Latest plugin unavailable'))
+const pendingDeletes = computed(() => pluginTotals.value.pendingDeletes)
+const failedPositions = computed(() => pluginTotals.value.failedPositions)
+const hasPluginActivity = computed(
+  () =>
+    sweeps.value.length > 0 ||
+    pluginTotals.value.matchedBooks > 0 ||
+    pluginTotals.value.pageStatEvents > 0 ||
+    pluginTotals.value.annotations > 0 ||
+    pluginTotals.value.trashedAnnotations > 0 ||
+    pendingDeletes.value > 0 ||
+    failedPositions.value > 0,
+)
+const createDisabled = computed(() => creating.value || !newUsername.value || newPassword.value.length < 6)
 
 function formatLastSync(dateStr: string | null): string {
   if (!dateStr) return 'Never'
@@ -46,6 +100,27 @@ function formatLastSync(dateStr: string | null): string {
   return `${diffDays}d ago`
 }
 
+function formatDate(dateStr: string | null | undefined): string {
+  if (!dateStr) return 'Unknown'
+  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).format(new Date(dateStr))
+}
+
+function formatCount(value: number, singular: string, plural = `${singular}s`): string {
+  return `${value} ${value === 1 ? singular : plural}`
+}
+
+function pluginUpdateText(updateAvailable: boolean | null): string {
+  if (updateAvailable === true) return 'Update available'
+  if (updateAvailable === false) return 'Up to date'
+  return 'Version unknown'
+}
+
+function pluginUpdateClass(updateAvailable: boolean | null): string {
+  if (updateAvailable === true) return 'border-primary/40 bg-primary/10 text-primary'
+  if (updateAvailable === false) return 'border-border bg-muted text-muted-foreground'
+  return 'border-border bg-background text-muted-foreground'
+}
+
 onMounted(async () => {
   try {
     await fetchSyncStatus()
@@ -59,6 +134,7 @@ async function handleCreate() {
   try {
     await createCredentials({ username: newUsername.value, password: newPassword.value })
     showSetupForm.value = false
+    helpOpen.value = false
     newUsername.value = ''
     newPassword.value = ''
     toast.success('KOReader sync credentials created')
@@ -136,6 +212,20 @@ async function handleRefresh() {
     toast.error('Failed to refresh')
   }
 }
+
+const downloadingPlugin = ref(false)
+
+async function handleDownloadPlugin() {
+  downloadingPlugin.value = true
+  try {
+    await downloadPluginPackage()
+    toast.success('Plugin downloaded. Copy bookorbit.koplugin from the zip to koreader/plugins/ on your device.')
+  } catch (e) {
+    toast.error(e instanceof Error ? e.message : 'Failed to download the plugin')
+  } finally {
+    downloadingPlugin.value = false
+  }
+}
 </script>
 
 <template>
@@ -143,38 +233,41 @@ async function handleRefresh() {
     v-if="!props.embedded"
     class="hidden md:flex"
     title="KOReader Sync"
-    subtitle="Sync reading progress between KOReader devices and BookOrbit."
+    subtitle="Browse your BookOrbit catalog in KOReader and sync progress, reading activity, highlights, and annotation changes."
   />
   <div v-if="!props.embedded" class="md:hidden px-1">
     <h1 class="text-xl font-semibold tracking-tight text-foreground">KOReader Sync</h1>
     <p
       class="mt-1 text-sm text-muted-foreground leading-5 overflow-hidden text-ellipsis [display:-webkit-box] [-webkit-line-clamp:2] [-webkit-box-orient:vertical]"
     >
-      Sync reading progress between KOReader devices and BookOrbit.
+      Browse your BookOrbit catalog in KOReader and sync progress, reading activity, highlights, and annotation changes.
     </p>
   </div>
 
-  <div v-if="loading" class="mt-5 md:mt-0 text-sm text-muted-foreground">Loading...</div>
-  <div v-else-if="error" class="text-sm text-destructive">{{ error }}</div>
+  <div v-if="loading" class="mt-5 md:mt-0 border border-border rounded-lg px-5 py-8 bg-card text-sm text-muted-foreground shadow-xs">
+    Loading KOReader settings...
+  </div>
+  <div v-else-if="error" class="border border-destructive/30 rounded-lg px-5 py-4 bg-card text-sm text-destructive shadow-xs">{{ error }}</div>
   <template v-else>
-    <!-- No credentials setup -->
     <template v-if="!hasCredentials">
       <div v-if="!showSetupForm" class="border border-border rounded-lg px-5 py-8 bg-card text-center shadow-xs">
-        <BookOpen :size="32" class="mx-auto text-muted-foreground mb-3" />
-        <p class="text-sm font-medium text-foreground mb-1">KOReader sync is not configured</p>
-        <p class="text-xs text-muted-foreground mb-4">Create credentials to sync reading progress with your KOReader devices.</p>
-        <button
-          class="inline-flex items-center gap-1.5 px-4 py-2 text-sm font-medium rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
-          @click="handleShowSetupForm"
-        >
-          Set up KOReader Sync
+        <div class="w-10 h-10 rounded-lg bg-muted flex items-center justify-center mx-auto mb-3">
+          <BookOpen :size="18" class="text-muted-foreground/80" />
+        </div>
+        <p class="text-sm font-medium text-foreground">KOReader sync is not configured</p>
+        <p class="text-xs text-muted-foreground mt-1 mb-4 max-w-sm mx-auto">
+          Create one set of sync credentials, then use them with the BookOrbit KOReader plugin for browsing, downloads, progress, reading events,
+          highlights, and deletes.
+        </p>
+        <button class="settings-btn-primary mx-auto min-h-10 justify-center" @click="handleShowSetupForm">
+          <User :size="13" />
+          Create credentials
         </button>
       </div>
 
-      <!-- Setup form -->
       <div v-else class="border border-border rounded-lg p-4 md:p-5 bg-card space-y-4 shadow-xs">
         <p class="text-sm font-medium text-foreground">Create KOReader Sync Credentials</p>
-        <p class="text-xs text-muted-foreground">These credentials are used by your KOReader device to authenticate with the sync server.</p>
+        <p class="text-xs text-muted-foreground">These credentials authenticate your KOReader devices with BookOrbit.</p>
         <div>
           <label class="block text-xs font-medium text-muted-foreground mb-1.5">Username</label>
           <input v-model="newUsername" type="text" placeholder="e.g. myreader" class="input-field w-full" autocomplete="off" />
@@ -196,27 +289,14 @@ async function handleRefresh() {
           </div>
         </div>
         <div class="hidden md:flex items-center gap-2 pt-1">
-          <button
-            class="px-4 py-2 text-xs font-medium rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors disabled:opacity-50"
-            :disabled="creating || !newUsername || newPassword.length < 6"
-            @click="handleCreate"
-          >
+          <button class="settings-btn-primary" :disabled="createDisabled" @click="handleCreate">
             {{ creating ? 'Creating...' : 'Create' }}
           </button>
-          <button
-            class="px-4 py-2 text-xs font-medium rounded-md border border-border bg-background text-foreground hover:bg-muted transition-colors"
-            @click="handleCancelSetup"
-          >
-            Cancel
-          </button>
+          <button class="settings-btn-outline" @click="handleCancelSetup">Cancel</button>
         </div>
         <div class="md:hidden sticky bottom-2 z-20 border border-border/60 bg-card/95 backdrop-blur rounded-lg px-3 py-2">
           <div class="flex items-center gap-2">
-            <button
-              class="settings-btn-primary flex-1 min-h-10 justify-center"
-              :disabled="creating || !newUsername || newPassword.length < 6"
-              @click="handleCreate"
-            >
+            <button class="settings-btn-primary flex-1 min-h-10 justify-center" :disabled="createDisabled" @click="handleCreate">
               {{ creating ? 'Creating...' : 'Create' }}
             </button>
             <button
@@ -230,107 +310,259 @@ async function handleRefresh() {
       </div>
     </template>
 
-    <!-- Credentials configured -->
     <template v-else>
-      <!-- Sync Toggle -->
-      <div class="mb-6">
-        <p class="settings-group-label">Sync</p>
-        <div class="border border-border rounded-lg overflow-hidden shadow-xs">
-          <div class="flex flex-col gap-3 px-4 py-3.5 bg-card md:flex-row md:items-center md:justify-between md:px-5 md:py-4">
-            <div class="min-w-0">
-              <p class="settings-label">Progress Sync</p>
-              <p class="settings-hint">Automatically sync reading progress between KOReader and BookOrbit</p>
-            </div>
-            <ToggleSwitch :model-value="credentials?.syncEnabled ?? false" class="self-start md:self-auto" @update:model-value="handleToggleSync" />
-          </div>
-        </div>
-      </div>
-
-      <!-- Sync URL -->
-      <div class="mb-6">
-        <p class="settings-group-label">Sync Server URL</p>
-        <div class="border border-border rounded-lg overflow-hidden shadow-xs">
-          <div class="flex flex-col md:flex-row md:items-center gap-2 px-4 py-3.5 md:px-5 md:py-4 bg-card">
-            <BookOpen :size="14" class="text-muted-foreground shrink-0 hidden md:block" />
-            <input
-              :value="syncUrl"
-              readonly
-              class="flex-1 text-sm bg-transparent text-foreground outline-none select-all min-w-0 truncate font-mono"
-            />
-            <button
-              class="w-full md:w-auto flex items-center justify-center gap-1.5 px-3 py-2 md:py-1.5 text-xs font-medium rounded-md border border-border bg-background hover:bg-muted transition-colors shrink-0"
-              @click="handleCopyUrl"
-            >
-              <Check v-if="urlCopied" :size="12" class="text-green-500" />
-              <Copy v-else :size="12" />
-              {{ urlCopied ? 'Copied' : 'Copy' }}
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <!-- Account Info -->
-      <div class="mb-6">
+      <div class="mb-8">
         <div class="flex items-center justify-between mb-3">
-          <p class="settings-group-label mb-0">Account</p>
-          <button
-            class="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md border border-border bg-background text-foreground hover:bg-muted transition-colors"
-            @click="handleRefresh"
-          >
+          <p class="settings-group-label mb-0">KOReader Status</p>
+          <button class="settings-btn-outline" @click="handleRefresh">
             <RefreshCw :size="12" />
             Refresh
           </button>
         </div>
         <div class="border border-border rounded-lg overflow-hidden shadow-xs divide-y divide-border">
-          <div class="flex items-center justify-between px-4 py-3.5 bg-card md:px-5">
-            <div>
+          <div class="flex flex-col gap-3 px-4 py-3.5 bg-card md:flex-row md:items-center md:justify-between md:px-5 md:py-4">
+            <div class="min-w-0">
+              <p class="settings-label">Progress sync</p>
+              <p class="settings-hint">
+                Allow KOReader devices to sync progress, reading activity, highlights, and annotation deletes with BookOrbit.
+              </p>
+            </div>
+            <ToggleSwitch :model-value="credentials?.syncEnabled ?? false" class="self-start md:self-auto" @update:model-value="handleToggleSync" />
+          </div>
+          <div class="grid gap-3 px-4 py-4 bg-card md:grid-cols-2 lg:grid-cols-5 md:px-5">
+            <div class="min-w-0">
               <p class="settings-label">Username</p>
-              <p class="settings-hint font-mono">{{ credentials?.username }}</p>
+              <p class="settings-hint font-mono truncate">{{ credentials?.username }}</p>
             </div>
-          </div>
-          <div class="flex items-center justify-between px-4 py-3.5 bg-card md:px-5">
             <div>
-              <p class="settings-label">Synced Books</p>
-              <p class="settings-hint">{{ totalSyncedBooks }} {{ totalSyncedBooks === 1 ? 'book' : 'books' }}</p>
-            </div>
-          </div>
-          <div class="flex items-center justify-between px-4 py-3.5 bg-card md:px-5">
-            <div>
-              <p class="settings-label">Last Sync</p>
+              <p class="settings-label">Last sync</p>
               <p class="settings-hint">{{ formatLastSync(syncStatus?.lastSyncAt ?? null) }}</p>
             </div>
+            <div>
+              <p class="settings-label">Synced books</p>
+              <p class="settings-hint">{{ formatCount(totalSyncedBooks, 'book') }}</p>
+            </div>
+            <div>
+              <p class="settings-label">Devices</p>
+              <p class="settings-hint">{{ formatCount(deviceCount, 'device') }}</p>
+            </div>
+            <div>
+              <p class="settings-label">Credentials created</p>
+              <p class="settings-hint">{{ formatDate(credentials?.createdAt) }}</p>
+            </div>
           </div>
         </div>
       </div>
 
-      <!-- Devices -->
-      <div v-if="deviceCount > 0" class="mb-6">
-        <p class="settings-group-label">Devices</p>
+      <div class="mb-8">
+        <p class="settings-group-label">Setup</p>
         <div class="border border-border rounded-lg overflow-hidden shadow-xs divide-y divide-border">
-          <div v-for="device in syncStatus?.devices ?? []" :key="device.deviceId" class="flex items-center gap-3 px-4 py-3.5 bg-card md:px-5">
-            <Smartphone :size="16" class="text-muted-foreground shrink-0" />
-            <div class="flex-1 min-w-0">
-              <p class="settings-label truncate">{{ device.device }}</p>
+          <div class="px-4 py-4 bg-card md:px-5">
+            <div class="mb-2 flex items-center gap-2">
+              <BookOpen :size="14" class="text-muted-foreground shrink-0" />
+              <p class="settings-label">Sync server URL</p>
+            </div>
+            <div class="flex flex-col gap-2 md:flex-row md:items-center">
+              <input :value="syncUrl" readonly class="input-field flex-1 min-w-0 font-mono text-xs md:text-sm" />
+              <button class="settings-btn-outline w-full min-h-10 justify-center md:w-auto md:min-h-0" @click="handleCopyUrl">
+                <Check v-if="urlCopied" :size="12" />
+                <Copy v-else :size="12" />
+                {{ urlCopied ? 'Copied' : 'Copy URL' }}
+              </button>
+            </div>
+          </div>
+          <div class="flex flex-col gap-3 px-4 py-4 bg-card md:flex-row md:items-center md:justify-between md:px-5">
+            <div class="min-w-0">
+              <div class="flex flex-wrap items-center gap-2">
+                <p class="settings-label">Preconfigured BookOrbit plugin</p>
+                <span
+                  v-if="pluginUpdateAvailable"
+                  class="rounded-md border border-primary/40 bg-primary/10 px-2 py-0.5 text-[11px] font-medium text-primary"
+                >
+                  Update available
+                </span>
+              </div>
               <p class="settings-hint">
-                Last sync: {{ formatLastSync(device.lastSyncAt)
-                }}<template v-if="device.lastBookTitle"> &middot; {{ device.lastBookTitle }}</template>
+                Download a zip with the server URL and your sync login already configured. The plugin includes catalog browsing and sync. Copy the
+                folder to
+                <span class="font-mono text-foreground/70">koreader/plugins/</span> and restart KOReader.
+              </p>
+              <p class="settings-hint mt-1">{{ latestPluginLabel }}. Device updates run from the BookOrbit menu in KOReader.</p>
+            </div>
+            <button class="settings-btn-primary self-start md:self-auto" :disabled="downloadingPlugin" @click="handleDownloadPlugin">
+              <Download :size="12" />
+              {{ downloadingPlugin ? 'Preparing...' : 'Download Plugin' }}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      <div class="mb-8">
+        <p class="settings-group-label">Devices</p>
+        <div v-if="deviceCount === 0" class="border border-border rounded-lg px-5 py-8 bg-card text-center shadow-xs">
+          <div class="w-10 h-10 rounded-lg bg-muted flex items-center justify-center mx-auto mb-3">
+            <Smartphone :size="18" class="text-muted-foreground/80" />
+          </div>
+          <p class="text-sm font-medium text-foreground">No devices have synced yet</p>
+          <p class="text-xs text-muted-foreground mt-1 max-w-sm mx-auto">
+            Install the BookOrbit plugin for full sync, or configure KOReader's stock progress sync for progress-only updates.
+          </p>
+        </div>
+        <div v-else class="border border-border rounded-lg overflow-hidden shadow-xs divide-y divide-border">
+          <div v-for="device in syncStatus?.devices ?? []" :key="device.deviceId" class="px-4 py-4 bg-card md:px-5">
+            <div class="flex items-start gap-3">
+              <div class="w-9 h-9 rounded-lg bg-muted flex items-center justify-center text-muted-foreground shrink-0 border border-border">
+                <Smartphone :size="16" />
+              </div>
+              <div class="flex-1 min-w-0">
+                <p class="settings-label truncate">{{ device.device }}</p>
+                <div class="mt-1 grid gap-1 text-xs text-muted-foreground sm:grid-cols-2">
+                  <p class="min-w-0">
+                    Last sync: <span class="text-foreground/80">{{ formatLastSync(device.lastSyncAt) }}</span>
+                  </p>
+                  <p class="min-w-0 truncate">
+                    Last book: <span class="text-foreground/80">{{ device.lastBookTitle ?? 'None yet' }}</span>
+                  </p>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div class="mb-8">
+        <p class="settings-group-label">Plugin Activity</p>
+        <div class="border border-border rounded-lg overflow-hidden shadow-xs divide-y divide-border">
+          <div v-if="!hasPluginActivity" class="px-4 py-5 bg-card text-sm text-muted-foreground md:px-5">
+            No plugin activity has been reported yet.
+          </div>
+          <div v-for="sweep in sweeps" :key="sweep.deviceId" class="px-4 py-4 bg-card md:px-5">
+            <div class="flex items-start gap-3">
+              <div class="w-9 h-9 rounded-lg bg-muted flex items-center justify-center text-muted-foreground shrink-0 border border-border">
+                <Smartphone :size="16" />
+              </div>
+              <div class="flex-1 min-w-0">
+                <div class="flex flex-wrap items-center gap-2">
+                  <p class="settings-label truncate">
+                    {{ sweep.deviceModel }}
+                    <span v-if="sweep.pluginVersion" class="font-normal text-muted-foreground"> v{{ sweep.pluginVersion }}</span>
+                  </p>
+                  <span class="rounded-md border px-2 py-0.5 text-[11px] font-medium" :class="pluginUpdateClass(sweep.updateAvailable)">
+                    {{ pluginUpdateText(sweep.updateAvailable) }}
+                  </span>
+                </div>
+                <p class="settings-hint mt-1">
+                  Last full sync: {{ formatLastSync(sweep.lastSweepAt) }}
+                  <span v-if="sweep.updateAvailable === true && sweep.latestPluginVersion"> - latest plugin v{{ sweep.latestPluginVersion }}</span>
+                </p>
+              </div>
+            </div>
+            <div class="mt-4 grid gap-2 text-xs text-muted-foreground sm:grid-cols-3">
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ sweep.lastSweepBooksMatched }}</p>
+                <p>Matched books</p>
+              </div>
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ sweep.lastSweepPageStats }}</p>
+                <p>Reading events</p>
+              </div>
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ sweep.lastSweepAnnotations }}</p>
+                <p>Highlights</p>
+              </div>
+            </div>
+          </div>
+          <div v-if="hasPluginActivity" class="px-4 py-4 bg-card md:px-5">
+            <div class="flex items-center gap-2 mb-3">
+              <Library :size="14" class="text-muted-foreground shrink-0" />
+              <p class="settings-label">Synced totals</p>
+            </div>
+            <div class="grid gap-2 text-xs text-muted-foreground sm:grid-cols-2 lg:grid-cols-4">
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ pluginTotals.matchedBooks }}</p>
+                <p>Matched books</p>
+              </div>
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ pluginTotals.pageStatEvents }}</p>
+                <p>Reading events</p>
+              </div>
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ pluginTotals.annotations }}</p>
+                <p>Highlights</p>
+              </div>
+              <div class="rounded-md border border-border bg-background px-3 py-2">
+                <p class="font-medium text-foreground">{{ pluginTotals.trashedAnnotations }}</p>
+                <p>Trashed highlights</p>
+              </div>
+            </div>
+            <div v-if="pendingDeletes > 0" class="mt-3 flex gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-foreground">
+              <AlertTriangle :size="14" class="mt-0.5 shrink-0 text-muted-foreground" />
+              <p>{{ formatCount(pendingDeletes, 'deleted highlight') }} awaiting KOReader plugin acknowledgement.</p>
+            </div>
+            <div v-if="failedPositions > 0" class="mt-3 flex gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-foreground">
+              <AlertTriangle :size="14" class="mt-0.5 shrink-0 text-muted-foreground" />
+              <p>{{ formatCount(failedPositions, 'highlight position') }} need attention.</p>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div class="mb-8">
+        <p class="settings-group-label">Setup Guide</p>
+        <div class="border border-border rounded-lg bg-card shadow-xs">
+          <button class="w-full flex items-center justify-between gap-2 px-4 py-4 text-left md:px-5" @click="handleToggleHelp">
+            <div class="flex-1 min-w-0">
+              <p class="settings-label">KOReader setup steps</p>
+              <p class="settings-hint">
+                Use the BookOrbit plugin for catalog browsing, downloads, progress, reading events, and highlights. Use the stock plugin for progress
+                only.
+              </p>
+            </div>
+            <ChevronUp v-if="helpOpen" :size="14" class="text-muted-foreground shrink-0" />
+            <ChevronDown v-else :size="14" class="text-muted-foreground shrink-0" />
+          </button>
+          <div v-if="helpOpen" class="border-t border-border px-4 py-4 space-y-4 text-xs text-muted-foreground md:px-5">
+            <div>
+              <p class="font-medium text-foreground/80 mb-2">BookOrbit plugin</p>
+              <ol class="list-decimal list-inside space-y-2 pl-1">
+                <li>Download the preconfigured plugin above.</li>
+                <li>
+                  Unzip it and copy <span class="font-mono text-foreground/70">bookorbit.koplugin</span> to
+                  <span class="font-mono text-foreground/70">koreader/plugins/</span> on your device.
+                </li>
+                <li>Restart KOReader. The server and login are configured automatically.</li>
+                <li>Open <span class="font-mono text-foreground/70">Browse BookOrbit</span> to search, download, and link books to sync.</li>
+              </ol>
+            </div>
+            <div>
+              <p class="font-medium text-foreground/80 mb-2">Stock progress sync plugin</p>
+              <ol class="list-decimal list-inside space-y-2 pl-1">
+                <li>On your KOReader device, go to <span class="font-mono text-foreground/70">Tools &gt; Progress sync</span>.</li>
+                <li>Set the custom sync server to the URL shown above.</li>
+                <li>Enter the username and password you created, then tap Login.</li>
+              </ol>
+            </div>
+            <div class="flex gap-2 rounded-md border border-border bg-muted/40 px-3 py-2">
+              <Calendar :size="14" class="mt-0.5 shrink-0 text-muted-foreground" />
+              <p>
+                BookOrbit saves KOReader-compatible EPUB locations from the web reader. Restore should land close to the same position, though exact
+                line placement can vary by reader and EPUB layout.
               </p>
             </div>
           </div>
         </div>
       </div>
 
-      <!-- Danger Zone -->
       <div class="mb-6">
         <p class="settings-group-label">Danger Zone</p>
         <div class="border border-destructive/30 rounded-lg overflow-hidden shadow-xs">
-          <div class="flex flex-col gap-3 px-4 py-3.5 bg-card md:flex-row md:items-center md:justify-between md:px-5 md:py-4">
+          <div class="flex flex-col gap-3 px-4 py-4 bg-card md:flex-row md:items-center md:justify-between md:px-5">
             <div class="min-w-0">
-              <p class="settings-label">Delete KOReader Credentials</p>
+              <p class="settings-label">Delete KOReader credentials</p>
               <p class="settings-hint">Remove sync credentials and disconnect all devices. Progress data will be retained.</p>
             </div>
             <button
-              class="self-start md:self-auto flex items-center gap-1.5 px-3 py-2 md:py-1.5 text-xs font-medium rounded-md bg-destructive text-destructive-foreground hover:bg-destructive/90 transition-colors shrink-0"
+              class="self-start md:self-auto flex items-center gap-1.5 px-3 py-2 text-xs font-medium rounded-md bg-destructive text-destructive-foreground hover:bg-destructive/90 transition-colors shrink-0"
               @click="handleOpenDeleteConfirm"
             >
               <Trash2 :size="12" />
@@ -339,41 +571,8 @@ async function handleRefresh() {
           </div>
         </div>
       </div>
-
-      <!-- Setup Guide -->
-      <div class="border border-border rounded-lg bg-card/50 shadow-xs">
-        <button class="w-full flex items-center justify-between gap-2 p-4 text-left" @click="handleToggleHelp">
-          <p class="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Setup Guide</p>
-          <ChevronUp v-if="helpOpen" :size="14" class="text-muted-foreground" />
-          <ChevronDown v-else :size="14" class="text-muted-foreground" />
-        </button>
-        <div v-if="helpOpen" class="px-4 pb-4 space-y-3 text-xs text-muted-foreground">
-          <p class="font-medium text-foreground/80">To configure KOReader:</p>
-          <ol class="list-decimal list-inside space-y-2 pl-1">
-            <li>On your KOReader device, go to <span class="font-mono text-foreground/70">Tools > Progress sync</span></li>
-            <li>Set the custom sync server to the URL shown above</li>
-            <li>Enter the username and password you created</li>
-            <li>Tap "Register" (first time) or "Login" to connect</li>
-          </ol>
-          <p class="pt-1">Reading progress will sync automatically when you open and close books.</p>
-        </div>
-      </div>
-
-      <div class="mt-4">
-        <p class="settings-group-label">Sync Accuracy</p>
-        <div class="border border-border rounded-lg overflow-hidden shadow-xs">
-          <div class="px-4 py-3.5 bg-card md:px-5">
-            <p class="settings-label">Cross-reader compatibility</p>
-            <p class="settings-hint">
-              BookOrbit saves KOReader-compatible EPUB locations when progress is saved from the web reader. Restore should land close to the same
-              position in both directions, but exact line placement can still vary between readers and EPUB layouts.
-            </p>
-          </div>
-        </div>
-      </div>
     </template>
 
-    <!-- Delete Confirmation Modal -->
     <div
       v-if="deleteConfirmOpen"
       class="fixed inset-0 z-[70] flex items-end justify-center md:items-center md:px-4"
diff --git a/client/src/features/settings/SettingsHeader.vue b/client/src/features/settings/SettingsHeader.vue
index 35107cd56..70829dea6 100644
--- a/client/src/features/settings/SettingsHeader.vue
+++ b/client/src/features/settings/SettingsHeader.vue
@@ -34,10 +34,6 @@ const sections = computed<Section[]>(() => {
     result.push({ label: 'Metadata', routeName: 'settings-admin-metadata' })
   }
 
-  if (su || perms.includes(Permission.KoboSync) || perms.includes(Permission.KoreaderSync) || perms.includes(Permission.HardcoverSync)) {
-    result.push({ label: 'Integrations', routeName: 'settings-integrations' })
-  }
-
   if (su || perms.includes('email_send') || perms.includes('manage_email')) {
     result.push({ label: 'Email', routeName: 'settings-email' })
   }
@@ -46,6 +42,18 @@ const sections = computed<Section[]>(() => {
     result.push({ label: 'OPDS', routeName: 'settings-opds' })
   }
 
+  if (su || perms.includes(Permission.KoboSync)) {
+    result.push({ label: 'Kobo', routeName: 'settings-kobo' })
+  }
+
+  if (su || perms.includes(Permission.KoreaderSync)) {
+    result.push({ label: 'KOReader', routeName: 'settings-koreader' })
+  }
+
+  if (su || perms.includes(Permission.HardcoverSync)) {
+    result.push({ label: 'Hardcover', routeName: 'settings-hardcover' })
+  }
+
   if (su || perms.includes('manage_users') || perms.includes('manage_app_settings')) {
     result.push({ label: 'Admin', routeName: 'settings-admin' })
   }
diff --git a/client/src/features/settings/__tests__/IntegrationsAllSettings.spec.ts b/client/src/features/settings/__tests__/IntegrationsAllSettings.spec.ts
deleted file mode 100644
index 49180d0ee..000000000
--- a/client/src/features/settings/__tests__/IntegrationsAllSettings.spec.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest'
-import { mount } from '@vue/test-utils'
-import { Permission } from '@bookorbit/types'
-import IntegrationsAllSettings from '../IntegrationsAllSettings.vue'
-
-const permissionState = {
-  isSuperuser: false,
-  permissions: [] as string[],
-}
-
-const routerState = {
-  currentQuery: {} as Record<string, string>,
-  replaceCalls: [] as Array<{ name: string; query?: Record<string, string> }>,
-}
-
-vi.mock('vue-router', () => ({
-  useRoute: () => ({
-    query: routerState.currentQuery,
-  }),
-  useRouter: () => ({
-    replace: vi.fn<(to: { name: string; query?: Record<string, string> }) => void>((to) => {
-      routerState.replaceCalls.push(to)
-    }),
-  }),
-}))
-
-vi.mock('@/features/auth/composables/usePermissions', () => ({
-  usePermissions: () => ({
-    hasPermission: (name: string) => permissionState.isSuperuser || permissionState.permissions.includes(name),
-  }),
-}))
-
-vi.mock('../KoboSettings.vue', () => ({ default: { template: '<div data-testid="kobo-settings" />' } }))
-vi.mock('../KoreaderSettings.vue', () => ({ default: { template: '<div data-testid="koreader-settings" />' } }))
-vi.mock('@/features/hardcover/components/HardcoverSettings.vue', () => ({
-  default: { template: '<div data-testid="hardcover-settings" />' },
-}))
-vi.mock('../SettingsPageHeader.vue', () => ({ default: { template: '<div />' } }))
-
-function mountComponent(opts?: { queryTab?: string; perms?: string[]; su?: boolean }) {
-  permissionState.permissions = opts?.perms ?? []
-  permissionState.isSuperuser = opts?.su ?? false
-  routerState.currentQuery = opts?.queryTab ? { tab: opts.queryTab } : {}
-  routerState.replaceCalls = []
-  return mount(IntegrationsAllSettings)
-}
-
-function labels(wrapper: ReturnType<typeof mount>): string[] {
-  return wrapper.findAll('button').map((button) => button.text())
-}
-
-function lastReplace() {
-  if (routerState.replaceCalls.length === 0) return null
-  return routerState.replaceCalls[routerState.replaceCalls.length - 1] ?? null
-}
-
-describe('IntegrationsAllSettings', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('redirects to appearance when user has no integration permissions', () => {
-    const wrapper = mountComponent()
-    expect(labels(wrapper)).toEqual([])
-    expect(lastReplace()).toEqual({ name: 'settings-appearance' })
-  })
-
-  it('shows only Kobo tab for kobo_sync users and defaults URL to ?tab=kobo', () => {
-    const wrapper = mountComponent({ perms: [Permission.KoboSync] })
-    expect(labels(wrapper)).toEqual(['Kobo'])
-    expect(wrapper.find('[data-testid="kobo-settings"]').exists()).toBe(true)
-    expect(lastReplace()).toEqual({ name: 'settings-integrations', query: { tab: 'kobo' } })
-  })
-
-  it('shows only KOReader tab for koreader_sync users and defaults URL to ?tab=koreader', () => {
-    const wrapper = mountComponent({ perms: [Permission.KoreaderSync] })
-    expect(labels(wrapper)).toEqual(['KOReader'])
-    expect(wrapper.find('[data-testid="koreader-settings"]').exists()).toBe(true)
-    expect(lastReplace()).toEqual({ name: 'settings-integrations', query: { tab: 'koreader' } })
-  })
-
-  it('shows only Hardcover tab for hardcover_sync users and defaults URL to ?tab=hardcover', () => {
-    const wrapper = mountComponent({ perms: [Permission.HardcoverSync] })
-    expect(labels(wrapper)).toEqual(['Hardcover'])
-    expect(wrapper.find('[data-testid="hardcover-settings"]').exists()).toBe(true)
-    expect(lastReplace()).toEqual({ name: 'settings-integrations', query: { tab: 'hardcover' } })
-  })
-
-  it('falls back to the first allowed tab when query tab is not permitted', () => {
-    const wrapper = mountComponent({ queryTab: 'hardcover', perms: [Permission.KoreaderSync] })
-    expect(wrapper.find('[data-testid="koreader-settings"]').exists()).toBe(true)
-    expect(wrapper.find('[data-testid="hardcover-settings"]').exists()).toBe(false)
-    expect(lastReplace()).toEqual({ name: 'settings-integrations', query: { tab: 'koreader' } })
-  })
-
-  it('renders and switches all three tabs when user has all three permissions', async () => {
-    const wrapper = mountComponent({
-      queryTab: 'kobo',
-      perms: [Permission.KoboSync, Permission.KoreaderSync, Permission.HardcoverSync],
-    })
-
-    expect(labels(wrapper)).toEqual(['Kobo', 'KOReader', 'Hardcover'])
-    expect(wrapper.find('[data-testid="kobo-settings"]').exists()).toBe(true)
-
-    const hardcoverButton = wrapper.findAll('button').find((button) => button.text() === 'Hardcover')
-    await hardcoverButton!.trigger('click')
-
-    expect(wrapper.find('[data-testid="hardcover-settings"]').exists()).toBe(true)
-    expect(lastReplace()).toEqual({ name: 'settings-integrations', query: { tab: 'hardcover' } })
-  })
-})
diff --git a/client/src/features/settings/__tests__/KoreaderSettings.spec.ts b/client/src/features/settings/__tests__/KoreaderSettings.spec.ts
new file mode 100644
index 000000000..0ee1a3f32
--- /dev/null
+++ b/client/src/features/settings/__tests__/KoreaderSettings.spec.ts
@@ -0,0 +1,264 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import KoreaderSettings from '../KoreaderSettings.vue'
+import type { KoreaderCredentials, KoreaderSyncStatus } from '@bookorbit/types'
+import { copyToClipboard } from '@/lib/clipboard'
+
+const koreaderMock = vi.hoisted(() => ({
+  credentials: { __v_isRef: true, value: null as KoreaderCredentials | null },
+  syncStatus: { __v_isRef: true, value: null as KoreaderSyncStatus | null },
+  loading: { __v_isRef: true, value: false },
+  fetchSyncStatus: vi.fn<() => Promise<void>>(),
+  createCredentials: vi.fn<() => Promise<void>>(),
+  updateCredentials: vi.fn<() => Promise<void>>(),
+  deleteCredentials: vi.fn<() => Promise<void>>(),
+  getSyncUrl: vi.fn<() => string>(),
+  downloadPluginPackage: vi.fn<() => Promise<void>>(),
+}))
+
+vi.mock('@/features/koreader/composables/useKoreaderSync', () => ({
+  useKoreaderSync: () => koreaderMock,
+}))
+
+vi.mock('vue-sonner', () => ({
+  toast: { success: vi.fn<() => void>(), error: vi.fn<() => void>() },
+}))
+
+vi.mock('@/lib/clipboard', () => ({
+  copyToClipboard: vi.fn<(text: string) => Promise<boolean>>().mockResolvedValue(true),
+}))
+
+vi.mock('../SettingsPageHeader.vue', () => ({
+  default: { template: '<div />' },
+}))
+
+function makeCredentials(overrides: Partial<KoreaderCredentials> = {}): KoreaderCredentials {
+  return {
+    username: 'reader-user',
+    syncEnabled: true,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+function makeSyncStatus(overrides: Partial<KoreaderSyncStatus> = {}): KoreaderSyncStatus {
+  return {
+    credentials: makeCredentials(),
+    devices: [
+      {
+        device: 'Kobo Libra 2',
+        deviceId: 'device-1',
+        lastSyncAt: '2026-01-02T00:00:00.000Z',
+        lastBookTitle: 'Project Hail Mary',
+      },
+    ],
+    totalSyncedBooks: 14,
+    lastSyncAt: '2026-01-02T00:00:00.000Z',
+    latestPluginVersion: '0.5.0',
+    pluginUpdateAvailable: true,
+    sweeps: [
+      {
+        deviceId: 'device-1',
+        deviceModel: 'Kobo Libra 2',
+        pluginVersion: '0.3.0',
+        latestPluginVersion: '0.5.0',
+        updateAvailable: true,
+        lastSweepAt: '2026-01-02T00:00:00.000Z',
+        lastSweepBooksMatched: 12,
+        lastSweepPageStats: 30,
+        lastSweepAnnotations: 8,
+      },
+    ],
+    pluginTotals: { matchedBooks: 12, pageStatEvents: 30, annotations: 8, trashedAnnotations: 1, pendingDeletes: 2, failedPositions: 3 },
+    ...overrides,
+  }
+}
+
+function mountComponent() {
+  return mount(KoreaderSettings, { props: { embedded: true } })
+}
+
+function buttonByText(wrapper: ReturnType<typeof mount>, text: string) {
+  return wrapper.findAll('button').find((button) => button.text().includes(text))
+}
+
+describe('KoreaderSettings', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    koreaderMock.credentials.value = null
+    koreaderMock.syncStatus.value = null
+    koreaderMock.loading.value = false
+    koreaderMock.fetchSyncStatus.mockResolvedValue(undefined)
+    koreaderMock.createCredentials.mockResolvedValue(undefined)
+    koreaderMock.updateCredentials.mockResolvedValue(undefined)
+    koreaderMock.deleteCredentials.mockResolvedValue(undefined)
+    koreaderMock.getSyncUrl.mockReturnValue('https://bookorbit.example/api/v1/koreader')
+    koreaderMock.downloadPluginPackage.mockResolvedValue(undefined)
+  })
+
+  it('shows loading state', () => {
+    koreaderMock.loading.value = true
+
+    const wrapper = mountComponent()
+
+    expect(wrapper.text()).toContain('Loading KOReader settings...')
+  })
+
+  it('shows an error when status loading fails', async () => {
+    koreaderMock.fetchSyncStatus.mockRejectedValue(new Error('Failed to load status'))
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Failed to load status')
+  })
+
+  it('keeps the unconfigured state focused on credential creation', async () => {
+    koreaderMock.syncStatus.value = makeSyncStatus({ credentials: null, devices: [], totalSyncedBooks: 0, lastSyncAt: null, sweeps: [] })
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('KOReader sync is not configured')
+    expect(wrapper.text()).toContain('Create credentials')
+    expect(wrapper.text()).not.toContain('Setup Guide')
+
+    await buttonByText(wrapper, 'Create credentials')!.trigger('click')
+    await wrapper.find('input[type="text"]').setValue('new-reader')
+    await wrapper.find('input[type="password"]').setValue('secret1')
+    await buttonByText(wrapper, 'Create')!.trigger('click')
+
+    expect(koreaderMock.createCredentials).toHaveBeenCalledWith({ username: 'new-reader', password: 'secret1' })
+  })
+
+  it('renders configured status, setup, device, activity, guide, and danger sections', async () => {
+    const status = makeSyncStatus()
+    koreaderMock.credentials.value = status.credentials
+    koreaderMock.syncStatus.value = status
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.findAll('.settings-group-label').map((label) => label.text())).toEqual([
+      'KOReader Status',
+      'Setup',
+      'Devices',
+      'Plugin Activity',
+      'Setup Guide',
+      'Danger Zone',
+    ])
+    expect(wrapper.text()).toContain('reader-user')
+    expect(wrapper.text()).toContain('14 books')
+    expect(wrapper.text()).toContain('1 device')
+    const syncUrlInput = wrapper.find('input[readonly]').element as HTMLInputElement
+    expect(syncUrlInput.value).toBe('https://bookorbit.example/api/v1/koreader')
+    expect(wrapper.text()).toContain('Kobo Libra 2')
+    expect(wrapper.text()).toContain('Project Hail Mary')
+    expect(wrapper.text()).toContain('Latest plugin: v0.5.0')
+    expect(wrapper.text()).toContain('Update available')
+    expect(wrapper.text()).toContain('latest plugin v0.5.0')
+    expect(wrapper.text()).toContain('Matched books')
+    expect(wrapper.text()).toContain('2 deleted highlights awaiting KOReader plugin acknowledgement.')
+    expect(wrapper.text()).toContain('3 highlight positions need attention.')
+    expect(wrapper.text()).not.toContain('Download the preconfigured plugin above.')
+  })
+
+  it('expands the setup guide only when requested', async () => {
+    const status = makeSyncStatus()
+    koreaderMock.credentials.value = status.credentials
+    koreaderMock.syncStatus.value = status
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.text()).not.toContain('Download the preconfigured plugin above.')
+
+    await buttonByText(wrapper, 'KOReader setup steps')!.trigger('click')
+
+    expect(wrapper.text()).toContain('Download the preconfigured plugin above.')
+  })
+
+  it('shows current plugin state without an update warning when reported devices are current', async () => {
+    const status = makeSyncStatus({
+      pluginUpdateAvailable: false,
+      sweeps: [
+        {
+          deviceId: 'device-1',
+          deviceModel: 'Kobo Libra 2',
+          pluginVersion: '0.5.0',
+          latestPluginVersion: '0.5.0',
+          updateAvailable: false,
+          lastSweepAt: '2026-01-02T00:00:00.000Z',
+          lastSweepBooksMatched: 12,
+          lastSweepPageStats: 30,
+          lastSweepAnnotations: 8,
+        },
+      ],
+    })
+    koreaderMock.credentials.value = status.credentials
+    koreaderMock.syncStatus.value = status
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Latest plugin: v0.5.0')
+    expect(wrapper.text()).toContain('Up to date')
+    expect(wrapper.text()).not.toContain('latest plugin v0.5.0')
+  })
+
+  it('keeps plugin update state explicit when the server cannot report the latest version', async () => {
+    const status = makeSyncStatus({
+      latestPluginVersion: null,
+      pluginUpdateAvailable: false,
+      sweeps: [
+        {
+          deviceId: 'device-1',
+          deviceModel: 'Kobo Libra 2',
+          pluginVersion: '0.5.0',
+          latestPluginVersion: null,
+          updateAvailable: null,
+          lastSweepAt: '2026-01-02T00:00:00.000Z',
+          lastSweepBooksMatched: 12,
+          lastSweepPageStats: 30,
+          lastSweepAnnotations: 8,
+        },
+      ],
+    })
+    koreaderMock.credentials.value = status.credentials
+    koreaderMock.syncStatus.value = status
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Latest plugin unavailable')
+    expect(wrapper.text()).toContain('Version unknown')
+    expect(wrapper.text()).not.toContain('Update available')
+  })
+
+  it('calls existing action methods from the refreshed controls', async () => {
+    const status = makeSyncStatus()
+    koreaderMock.credentials.value = status.credentials
+    koreaderMock.syncStatus.value = status
+
+    const wrapper = mountComponent()
+    await flushPromises()
+
+    await buttonByText(wrapper, 'Refresh')!.trigger('click')
+    await wrapper.findComponent({ name: 'ToggleSwitch' }).trigger('click')
+    await buttonByText(wrapper, 'Copy URL')!.trigger('click')
+    await buttonByText(wrapper, 'Download Plugin')!.trigger('click')
+    await buttonByText(wrapper, 'Delete')!.trigger('click')
+    await flushPromises()
+
+    expect(koreaderMock.fetchSyncStatus).toHaveBeenCalledTimes(2)
+    expect(koreaderMock.updateCredentials).toHaveBeenCalledWith({ syncEnabled: false })
+    expect(vi.mocked(copyToClipboard)).toHaveBeenCalledWith('https://bookorbit.example/api/v1/koreader')
+    expect(koreaderMock.downloadPluginPackage).toHaveBeenCalledTimes(1)
+    expect(wrapper.text()).toContain('Delete KOReader credentials?')
+
+    const deleteButtons = wrapper.findAll('button').filter((button) => button.text() === 'Delete')
+    await deleteButtons[deleteButtons.length - 1]!.trigger('click')
+
+    expect(koreaderMock.deleteCredentials).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/client/src/features/settings/__tests__/SettingsHeader.spec.ts b/client/src/features/settings/__tests__/SettingsHeader.spec.ts
index bd49114bf..87136c068 100644
--- a/client/src/features/settings/__tests__/SettingsHeader.spec.ts
+++ b/client/src/features/settings/__tests__/SettingsHeader.spec.ts
@@ -57,48 +57,47 @@ describe('SettingsHeader', () => {
       expect(labels).toContain('Account')
     })
 
-    it('hides Integrations tab when user has no integration permissions', () => {
+    it('hides integration tabs when user has no integration permissions', () => {
       const labels = getTabLabels(mountHeader())
       expect(labels).not.toContain('Integrations')
+      expect(labels).not.toContain('Kobo')
+      expect(labels).not.toContain('KOReader')
+      expect(labels).not.toContain('Hardcover')
+    })
+
+    it('shows Kobo tab for users with kobo_sync', () => {
+      const labels = getTabLabels(mountHeader({ perms: ['kobo_sync'] }))
+      expect(labels).toContain('Kobo')
+      expect(labels).not.toContain('Integrations')
     })
 
-    it('shows Integrations tab for users with kobo_sync', () => {
-      const labels = getTabLabels(mountHeader({ perms: ['kobo_sync'] }))
-      expect(labels).toContain('Integrations')
-    })
-
-    it('shows Integrations tab for users with koreader_sync', () => {
+    it('shows KOReader tab for users with koreader_sync', () => {
       const labels = getTabLabels(mountHeader({ perms: ['koreader_sync'] }))
-      expect(labels).toContain('Integrations')
+      expect(labels).toContain('KOReader')
+      expect(labels).not.toContain('Integrations')
     })
 
-    it('shows Integrations tab for users with hardcover_sync', () => {
+    it('shows Hardcover tab for users with hardcover_sync', () => {
       const labels = getTabLabels(mountHeader({ perms: ['hardcover_sync'] }))
-      expect(labels).toContain('Integrations')
+      expect(labels).toContain('Hardcover')
+      expect(labels).not.toContain('Integrations')
     })
 
-    it('shows Integrations tab for superusers', () => {
+    it('shows integration tabs for superusers', () => {
       const labels = getTabLabels(mountHeader({ su: true }))
-      expect(labels).toContain('Integrations')
+      expect(labels).toContain('Kobo')
+      expect(labels).toContain('KOReader')
+      expect(labels).toContain('Hardcover')
+      expect(labels).not.toContain('Integrations')
+    })
+
+    it('places integration tabs after OPDS', () => {
+      const labels = getTabLabels(mountHeader({ su: true }))
+      expect(labels.slice(labels.indexOf('OPDS'), labels.indexOf('Admin'))).toEqual(['OPDS', 'Kobo', 'KOReader', 'Hardcover'])
     })
   })
 
   describe('tabs removed from top-level navigation', () => {
-    it('does not show a standalone Kobo tab', () => {
-      const labels = getTabLabels(mountHeader({ su: true }))
-      expect(labels).not.toContain('Kobo')
-    })
-
-    it('does not show a standalone KOReader tab', () => {
-      const labels = getTabLabels(mountHeader({ su: true }))
-      expect(labels).not.toContain('KOReader')
-    })
-
-    it('does not show a standalone Hardcover tab', () => {
-      const labels = getTabLabels(mountHeader({ su: true }))
-      expect(labels).not.toContain('Hardcover')
-    })
-
     it('does not show a standalone Users tab', () => {
       const labels = getTabLabels(mountHeader({ su: true }))
       expect(labels).not.toContain('Users')
@@ -229,9 +228,21 @@ describe('SettingsHeader', () => {
       expect(readerBtn?.classes()).toContain('border-transparent')
     })
 
-    it('integrations tab is active when route is settings-integrations', () => {
-      const wrapper = mountHeader({ routeName: 'settings-integrations', perms: ['kobo_sync'] })
-      const btn = wrapper.findAll('button').find((b) => b.text() === 'Integrations')
+    it('kobo tab is active when route is settings-kobo', () => {
+      const wrapper = mountHeader({ routeName: 'settings-kobo', perms: ['kobo_sync'] })
+      const btn = wrapper.findAll('button').find((b) => b.text() === 'Kobo')
+      expect(btn?.classes()).toContain('border-primary')
+    })
+
+    it('KOReader tab is active when route is settings-koreader', () => {
+      const wrapper = mountHeader({ routeName: 'settings-koreader', perms: ['koreader_sync'] })
+      const btn = wrapper.findAll('button').find((b) => b.text() === 'KOReader')
+      expect(btn?.classes()).toContain('border-primary')
+    })
+
+    it('Hardcover tab is active when route is settings-hardcover', () => {
+      const wrapper = mountHeader({ routeName: 'settings-hardcover', perms: ['hardcover_sync'] })
+      const btn = wrapper.findAll('button').find((b) => b.text() === 'Hardcover')
       expect(btn?.classes()).toContain('border-primary')
     })
 
diff --git a/client/src/features/settings/__tests__/integrations-tabs.spec.ts b/client/src/features/settings/__tests__/integrations-tabs.spec.ts
deleted file mode 100644
index f6bf452c4..000000000
--- a/client/src/features/settings/__tests__/integrations-tabs.spec.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Permission } from '@bookorbit/types'
-import { INTEGRATIONS_TABS, INTEGRATIONS_TAB_INFO, normalizeIntegrationsTab } from '../lib/integrations-tabs'
-
-describe('integrations-tabs', () => {
-  describe('INTEGRATIONS_TABS', () => {
-    it('contains exactly kobo, koreader, hardcover', () => {
-      expect(INTEGRATIONS_TABS).toEqual(['kobo', 'koreader', 'hardcover'])
-    })
-
-    it('is readonly (length is 3)', () => {
-      expect(INTEGRATIONS_TABS.length).toBe(3)
-    })
-  })
-
-  describe('INTEGRATIONS_TAB_INFO', () => {
-    it('has an entry for every tab', () => {
-      for (const tab of INTEGRATIONS_TABS) {
-        expect(INTEGRATIONS_TAB_INFO[tab]).toBeDefined()
-      }
-    })
-
-    it('every entry has navLabel, titleLabel, subtitle, and permission', () => {
-      for (const tab of INTEGRATIONS_TABS) {
-        const info = INTEGRATIONS_TAB_INFO[tab]
-        expect(typeof info.navLabel).toBe('string')
-        expect(info.navLabel.length).toBeGreaterThan(0)
-        expect(typeof info.titleLabel).toBe('string')
-        expect(info.titleLabel.length).toBeGreaterThan(0)
-        expect(typeof info.subtitle).toBe('string')
-        expect(info.subtitle.length).toBeGreaterThan(0)
-        expect(typeof info.permission).toBe('string')
-      }
-    })
-
-    it('kobo entry has correct labels', () => {
-      expect(INTEGRATIONS_TAB_INFO.kobo.navLabel).toBe('Kobo')
-      expect(INTEGRATIONS_TAB_INFO.kobo.titleLabel).toBe('Kobo Sync')
-      expect(INTEGRATIONS_TAB_INFO.kobo.permission).toBe(Permission.KoboSync)
-    })
-
-    it('koreader entry has correct labels', () => {
-      expect(INTEGRATIONS_TAB_INFO.koreader.navLabel).toBe('KOReader')
-      expect(INTEGRATIONS_TAB_INFO.koreader.titleLabel).toBe('KOReader Sync')
-      expect(INTEGRATIONS_TAB_INFO.koreader.permission).toBe(Permission.KoreaderSync)
-    })
-
-    it('hardcover entry has correct labels', () => {
-      expect(INTEGRATIONS_TAB_INFO.hardcover.navLabel).toBe('Hardcover')
-      expect(INTEGRATIONS_TAB_INFO.hardcover.titleLabel).toBe('Hardcover')
-      expect(INTEGRATIONS_TAB_INFO.hardcover.permission).toBe(Permission.HardcoverSync)
-    })
-  })
-
-  describe('normalizeIntegrationsTab', () => {
-    it('returns kobo for undefined', () => {
-      expect(normalizeIntegrationsTab(undefined)).toBe('kobo')
-    })
-
-    it('returns kobo for null', () => {
-      expect(normalizeIntegrationsTab(null)).toBe('kobo')
-    })
-
-    it('returns kobo for empty string', () => {
-      expect(normalizeIntegrationsTab('')).toBe('kobo')
-    })
-
-    it('returns kobo for unknown string', () => {
-      expect(normalizeIntegrationsTab('unknown')).toBe('kobo')
-    })
-
-    it('returns kobo for number input', () => {
-      expect(normalizeIntegrationsTab(42)).toBe('kobo')
-    })
-
-    it('returns kobo for object input', () => {
-      expect(normalizeIntegrationsTab({})).toBe('kobo')
-    })
-
-    it('returns kobo when given "kobo"', () => {
-      expect(normalizeIntegrationsTab('kobo')).toBe('kobo')
-    })
-
-    it('returns koreader when given "koreader"', () => {
-      expect(normalizeIntegrationsTab('koreader')).toBe('koreader')
-    })
-
-    it('returns hardcover when given "hardcover"', () => {
-      expect(normalizeIntegrationsTab('hardcover')).toBe('hardcover')
-    })
-
-    it('is case-sensitive (Kobo is not a valid tab)', () => {
-      expect(normalizeIntegrationsTab('Kobo')).toBe('kobo')
-    })
-
-    it('falls back to first allowed tab when current tab is not allowed', () => {
-      expect(normalizeIntegrationsTab('kobo', ['koreader', 'hardcover'])).toBe('koreader')
-    })
-
-    it('returns the allowed tab when current tab is allowed', () => {
-      expect(normalizeIntegrationsTab('hardcover', ['koreader', 'hardcover'])).toBe('hardcover')
-    })
-  })
-})
diff --git a/client/src/features/settings/lib/integrations-tabs.ts b/client/src/features/settings/lib/integrations-tabs.ts
deleted file mode 100644
index 1cc1a6140..000000000
--- a/client/src/features/settings/lib/integrations-tabs.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { Permission } from '@bookorbit/types'
-
-export const INTEGRATIONS_TABS = ['kobo', 'koreader', 'hardcover'] as const
-
-export type IntegrationsTab = (typeof INTEGRATIONS_TABS)[number]
-
-type IntegrationsTabInfo = {
-  navLabel: string
-  titleLabel: string
-  subtitle: string
-  permission: Permission
-}
-
-export const INTEGRATIONS_TAB_INFO: Record<IntegrationsTab, IntegrationsTabInfo> = {
-  kobo: {
-    navLabel: 'Kobo',
-    titleLabel: 'Kobo Sync',
-    subtitle: 'Pair your Kobo device to sync your library.',
-    permission: Permission.KoboSync,
-  },
-  koreader: {
-    navLabel: 'KOReader',
-    titleLabel: 'KOReader Sync',
-    subtitle: 'Sync reading progress between KOReader devices and BookOrbit.',
-    permission: Permission.KoreaderSync,
-  },
-  hardcover: {
-    navLabel: 'Hardcover',
-    titleLabel: 'Hardcover',
-    subtitle: 'Sync your reading progress, status, and ratings to Hardcover.',
-    permission: Permission.HardcoverSync,
-  },
-}
-
-export function normalizeIntegrationsTab(value: unknown, allowedTabs: readonly IntegrationsTab[] = INTEGRATIONS_TABS): IntegrationsTab {
-  const fallback = allowedTabs[0] ?? INTEGRATIONS_TABS[0]
-  if (typeof value === 'string' && allowedTabs.includes(value as IntegrationsTab)) {
-    return value as IntegrationsTab
-  }
-  return fallback
-}
diff --git a/client/src/features/statistics/api/statistics.api.test.ts b/client/src/features/statistics/api/statistics.api.test.ts
index 55e8708f9..417e1c33c 100644
--- a/client/src/features/statistics/api/statistics.api.test.ts
+++ b/client/src/features/statistics/api/statistics.api.test.ts
@@ -437,6 +437,16 @@ describe('fetchUserGoalTrajectory', () => {
     expect(result).toEqual(data)
   })
 
+  it('passes a custom goalBooks value when specified', async () => {
+    mockedApi.mockResolvedValue(mockOkResponse({ goalBooks: 24, points: [] }))
+
+    await fetchUserGoalTrajectory(filters, 24)
+
+    const url = mockedApi.mock.calls[0][0] as string
+    expect(url).toContain('goalBooks=24')
+    expect(url).not.toContain('goalBooks=12')
+  })
+
   it('throws on non-ok response', async () => {
     mockedApi.mockResolvedValue(mockErrorResponse(503))
 
diff --git a/client/src/features/statistics/api/statistics.api.ts b/client/src/features/statistics/api/statistics.api.ts
index f1ee4d86d..133f172b9 100644
--- a/client/src/features/statistics/api/statistics.api.ts
+++ b/client/src/features/statistics/api/statistics.api.ts
@@ -18,6 +18,7 @@ import type {
   UserReadingPacePoint,
   UserReadingSessionTimeline,
   UserReadingSessionTimelineItem,
+  UserReadingSourceDistribution,
   UserSessionArchetypePoint,
   UserStatisticsSummary,
   FormatDistributionItem,
@@ -137,6 +138,12 @@ export async function fetchUserReadingHeatmap(filters: StatisticsFilterConfig):
   return res.json() as Promise<UserDailyReadingStat[]>
 }
 
+export async function fetchUserReadingSourceDistribution(filters: StatisticsFilterConfig): Promise<UserReadingSourceDistribution> {
+  const res = await api(`/api/v1/user-statistics/reading-source-distribution${buildParams(filters, { days: '365' })}`)
+  if (!res.ok) throw new Error(`User reading source distribution request failed: ${res.status}`)
+  return res.json() as Promise<UserReadingSourceDistribution>
+}
+
 export async function fetchUserPeakReadingHours(filters: StatisticsFilterConfig): Promise<UserPeakHourStat[]> {
   const res = await api(`/api/v1/user-statistics/peak-hours${buildParams(filters, { days: '365' })}`)
   if (!res.ok) throw new Error(`User peak hours request failed: ${res.status}`)
@@ -155,8 +162,8 @@ export async function fetchUserCompletionTimeline(filters: StatisticsFilterConfi
   return res.json() as Promise<UserCompletionTimelinePoint[]>
 }
 
-export async function fetchUserGoalTrajectory(filters: StatisticsFilterConfig): Promise<UserGoalTrajectory> {
-  const res = await api(`/api/v1/user-statistics/goal-trajectory${buildParams(filters, { days: '365', goalBooks: '12' })}`)
+export async function fetchUserGoalTrajectory(filters: StatisticsFilterConfig, goalBooks = 12): Promise<UserGoalTrajectory> {
+  const res = await api(`/api/v1/user-statistics/goal-trajectory${buildParams(filters, { days: '365', goalBooks: String(goalBooks) })}`)
   if (!res.ok) throw new Error(`User goal trajectory request failed: ${res.status}`)
   return res.json() as Promise<UserGoalTrajectory>
 }
diff --git a/client/src/features/statistics/components/BreakdownSelect.vue b/client/src/features/statistics/components/BreakdownSelect.vue
new file mode 100644
index 000000000..c1ff4fdd7
--- /dev/null
+++ b/client/src/features/statistics/components/BreakdownSelect.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { BREAKDOWN_OPTIONS, type BreakdownDimension } from '../lib/breakdown'
+
+const model = defineModel<BreakdownDimension>({ required: true })
+</script>
+
+<template>
+  <select
+    v-model="model"
+    class="border-border bg-background text-foreground rounded-md border px-2 py-1 text-xs"
+    aria-label="Break down by source or format"
+  >
+    <option v-for="option in BREAKDOWN_OPTIONS" :key="option.value" :value="option.value">{{ option.label }}</option>
+  </select>
+</template>
diff --git a/client/src/features/statistics/components/StatisticsGrid.vue b/client/src/features/statistics/components/StatisticsGrid.vue
index 3c9287cd9..dfd65892d 100644
--- a/client/src/features/statistics/components/StatisticsGrid.vue
+++ b/client/src/features/statistics/components/StatisticsGrid.vue
@@ -29,6 +29,7 @@ const CHART_COMPONENTS: Record<StatisticsChartId, Component> = {
   'top-series': defineAsyncComponent(() => import('./library/TopSeriesChart.vue')),
   'publication-year-timeline': defineAsyncComponent(() => import('./library/PublicationYearTimelineChart.vue')),
   'reading-heatmap': defineAsyncComponent(() => import('./user/ReadingHeatmapChart.vue')),
+  'reading-source-distribution': defineAsyncComponent(() => import('./user/SourceDistributionChart.vue')),
   'peak-reading-hours': defineAsyncComponent(() => import('./user/PeakReadingHoursChart.vue')),
   'favorite-reading-days': defineAsyncComponent(() => import('./user/FavoriteReadingDaysChart.vue')),
   'completion-timeline': defineAsyncComponent(() => import('./user/CompletionTimelineChart.vue')),
diff --git a/client/src/features/statistics/components/library/LibraryMetadataCompletenessHeatmapChart.vue b/client/src/features/statistics/components/library/LibraryMetadataCompletenessHeatmapChart.vue
index 509c61c50..8701869dd 100644
--- a/client/src/features/statistics/components/library/LibraryMetadataCompletenessHeatmapChart.vue
+++ b/client/src/features/statistics/components/library/LibraryMetadataCompletenessHeatmapChart.vue
@@ -4,7 +4,7 @@ import VChart from 'vue-echarts'
 import { ListChecks } from '@lucide/vue'
 import { useThemeStore } from '@/stores/theme'
 
-import { buildHeatmapPalette } from '../../heatmap-palette'
+import { buildHeatmapPalette } from '@/lib/heatmap-palette'
 import { useLibraryMetadataCompleteness } from '../../composables/useLibraryMetadataCompleteness'
 import ChartCard from '../ChartCard.vue'
 
diff --git a/client/src/features/statistics/components/user/FavoriteReadingDaysChart.vue b/client/src/features/statistics/components/user/FavoriteReadingDaysChart.vue
index 4c7533935..38d13b4bc 100644
--- a/client/src/features/statistics/components/user/FavoriteReadingDaysChart.vue
+++ b/client/src/features/statistics/components/user/FavoriteReadingDaysChart.vue
@@ -1,9 +1,13 @@
 <script setup lang="ts">
-import { computed, shallowRef, watchEffect } from 'vue'
+import { computed, ref, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { CalendarDays } from '@lucide/vue'
+import type { ReadingSessionSourceBucket } from '@bookorbit/types'
 
+import { useThemeStore } from '@/stores/theme'
+import { getBreakdownSeries, type BreakdownDimension } from '../../lib/breakdown'
 import { useUserFavoriteReadingDays } from '../../composables/useUserFavoriteReadingDays'
+import BreakdownSelect from '../BreakdownSelect.vue'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
 
@@ -11,12 +15,14 @@ const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
 const MIN_EVENTS = 14
 const DAYS_WINDOW = 365
 
+const themeStore = useThemeStore()
 const { data, loading, error } = useUserFavoriteReadingDays()
 const option = shallowRef({})
 
 const totalEvents = computed(() => data.value.reduce((sum, item) => sum + item.eventsCount, 0))
 const isEmpty = computed(() => totalEvents.value === 0)
 const lowConfidence = computed(() => totalEvents.value > 0 && totalEvents.value < MIN_EVENTS)
+const dimension = ref<BreakdownDimension>('source')
 
 function weekdayOccurrencesInWindow(days: number): number[] {
   const counts = Array.from({ length: 7 }, () => 0)
@@ -35,28 +41,46 @@ watchEffect(() => {
   if (isEmpty.value || lowConfidence.value || !data.value.length) return
 
   const weekdayCounts = weekdayOccurrencesInWindow(DAYS_WINDOW)
-  const averageMinutesByDay = data.value.map((item, dayOfWeek) => {
-    const denominator = Math.max(1, weekdayCounts[dayOfWeek] ?? 1)
-    return Number((item.readingSeconds / 60 / denominator).toFixed(1))
-  })
+  const denominatorFor = (dayOfWeek: number) => Math.max(1, weekdayCounts[dayOfWeek] ?? 1)
+  const formatKeys = [...new Set(data.value.flatMap((item) => Object.keys(item.byFormat)))].sort()
+  const seriesMeta = getBreakdownSeries(dimension.value, `${themeStore.theme}:${themeStore.accent}`, formatKeys)
+
+  const series = seriesMeta.map((meta) => ({
+    type: 'bar',
+    name: meta.label,
+    stack: 'days',
+    data: data.value.map((item, dayOfWeek) => {
+      const seconds = (dimension.value === 'source' ? item.bySource?.[meta.key as ReadingSessionSourceBucket] : item.byFormat?.[meta.key]) ?? 0
+      return Number((seconds / 60 / denominatorFor(dayOfWeek)).toFixed(1))
+    }),
+    barMaxWidth: 30,
+    itemStyle: { color: meta.color },
+  }))
 
   option.value = {
+    legend: { bottom: 0, itemWidth: 10, itemHeight: 10, textStyle: { fontSize: 11 } },
     tooltip: {
       trigger: 'axis',
-      formatter: (params: Array<{ axisValue: string; data: number; dataIndex: number }>) => {
-        const point = params[0]
-        if (!point) return ''
-        const row = data.value[point.dataIndex]
+      formatter: (params: Array<{ axisValue: string; data: number; dataIndex: number; seriesName: string; marker: string }>) => {
+        const first = params[0]
+        if (!first) return ''
+        const row = data.value[first.dataIndex]
         if (!row) return ''
         const events = row.eventsCount
-        const avgMinuteLabel = point.data === 1 ? 'minute' : 'minutes'
+        const avgTotal = Number(params.reduce((sum, p) => sum + (p.data ?? 0), 0).toFixed(1))
+        const avgMinuteLabel = avgTotal === 1 ? 'minute' : 'minutes'
         const totalMinutes = Math.round(row.readingSeconds / 60)
         const totalMinuteLabel = totalMinutes === 1 ? 'minute' : 'minutes'
         const eventLabel = events === 1 ? 'event' : 'events'
-        return `${point.axisValue}<br/><strong>${point.data}</strong> avg ${avgMinuteLabel}<br/>${totalMinutes} total ${totalMinuteLabel}<br/>${events} ${eventLabel}`
+        const header = `${first.axisValue}<br/><strong>${avgTotal}</strong> avg ${avgMinuteLabel}<br/>${totalMinutes} total ${totalMinuteLabel}<br/>${events} ${eventLabel}`
+        const rows = params
+          .filter((p) => p.data > 0)
+          .map((p) => `${p.marker} ${p.seriesName}: ${p.data} avg min`)
+          .join('<br/>')
+        return rows ? `${header}<br/>${rows}` : header
       },
     },
-    grid: { left: '5%', right: '3%', bottom: '8%', top: '8%', containLabel: true },
+    grid: { left: '5%', right: '3%', bottom: 36, top: '8%', containLabel: true },
     xAxis: {
       type: 'category',
       data: WEEKDAYS,
@@ -70,20 +94,16 @@ watchEffect(() => {
       name: 'Avg min/day',
       nameTextStyle: { fontSize: 11, color: 'var(--muted-foreground)' },
     },
-    series: [
-      {
-        type: 'bar',
-        data: averageMinutesByDay,
-        barMaxWidth: 30,
-        itemStyle: { borderRadius: [4, 4, 0, 0] },
-      },
-    ],
+    series,
   }
 })
 </script>
 
 <template>
   <ChartCard title="Favorite Reading Days" :icon="CalendarDays" :color-index="6" :loading :error :empty="isEmpty">
+    <template #controls>
+      <BreakdownSelect v-model="dimension" />
+    </template>
     <ChartEmptyState
       v-if="lowConfidence"
       :icon="CalendarDays"
diff --git a/client/src/features/statistics/components/user/GenreReadingTimeTreemapChart.vue b/client/src/features/statistics/components/user/GenreReadingTimeTreemapChart.vue
index c5a57989f..ed4b5fbf7 100644
--- a/client/src/features/statistics/components/user/GenreReadingTimeTreemapChart.vue
+++ b/client/src/features/statistics/components/user/GenreReadingTimeTreemapChart.vue
@@ -2,6 +2,7 @@
 import { computed, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { Tag } from '@lucide/vue'
+import { READING_SESSION_SOURCE_BUCKETS, READING_SESSION_SOURCE_BUCKET_LABELS } from '@bookorbit/types'
 
 import { useThemeStore } from '@/stores/theme'
 import { getThemePalette, readCssColor } from '@/lib/echarts'
@@ -26,6 +27,7 @@ watchEffect(() => {
 
   const palette = getThemePalette(themeStore.theme, themeStore.accent, 0.8, 0.8)
   const background = readCssColor('--background')
+  const bySourceByGenre = new Map(data.value.map((item) => [item.genre, item.bySource]))
 
   option.value = {
     tooltip: {
@@ -34,7 +36,14 @@ watchEffect(() => {
       formatter: (params: { name: string; value: number }) => {
         const hours = (params.value / 3600).toFixed(1)
         const pct = totalSeconds.value > 0 ? ((params.value / totalSeconds.value) * 100).toFixed(1) : '0'
-        return `<strong>${params.name}</strong><br/>${hours}h reading time<br/>${pct}% of total`
+        const bySource = bySourceByGenre.get(params.name)
+        const sourceRows = bySource
+          ? READING_SESSION_SOURCE_BUCKETS.filter((bucket) => (bySource[bucket] ?? 0) > 0)
+              .map((bucket) => `${READING_SESSION_SOURCE_BUCKET_LABELS[bucket]}: ${((bySource[bucket] ?? 0) / 3600).toFixed(1)}h`)
+              .join('<br/>')
+          : ''
+        const base = `<strong>${params.name}</strong><br/>${hours}h reading time<br/>${pct}% of total`
+        return sourceRows ? `${base}<br/>${sourceRows}` : base
       },
     },
     series: [
diff --git a/client/src/features/statistics/components/user/PeakReadingHoursChart.vue b/client/src/features/statistics/components/user/PeakReadingHoursChart.vue
index d8b23993f..866a6b093 100644
--- a/client/src/features/statistics/components/user/PeakReadingHoursChart.vue
+++ b/client/src/features/statistics/components/user/PeakReadingHoursChart.vue
@@ -1,16 +1,22 @@
 <script setup lang="ts">
-import { computed, shallowRef, watchEffect } from 'vue'
+import { computed, ref, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { Clock3 } from '@lucide/vue'
+import type { ReadingSessionSourceBucket } from '@bookorbit/types'
 
+import { useThemeStore } from '@/stores/theme'
+import { getBreakdownSeries, type BreakdownDimension } from '../../lib/breakdown'
 import { useUserPeakReadingHours } from '../../composables/useUserPeakReadingHours'
+import BreakdownSelect from '../BreakdownSelect.vue'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
 
 const MIN_EVENTS = 20
 
+const themeStore = useThemeStore()
 const { data, loading, error } = useUserPeakReadingHours()
 const option = shallowRef({})
+const dimension = ref<BreakdownDimension>('source')
 
 const totalEvents = computed(() => data.value.reduce((sum, item) => sum + item.eventsCount, 0))
 const isEmpty = computed(() => totalEvents.value === 0)
@@ -30,19 +36,39 @@ watchEffect(() => {
   option.value = {}
   if (isEmpty.value || lowConfidence.value || !data.value.length) return
 
+  const formatKeys = [...new Set(data.value.flatMap((item) => Object.keys(item.byFormat)))].sort()
+  const seriesMeta = getBreakdownSeries(dimension.value, `${themeStore.theme}:${themeStore.accent}`, formatKeys)
+  const series = seriesMeta.map((meta) => ({
+    type: 'bar',
+    name: meta.label,
+    stack: 'hours',
+    data: data.value.map(
+      (item) => ((dimension.value === 'source' ? item.bySource?.[meta.key as ReadingSessionSourceBucket] : item.byFormat?.[meta.key]) ?? 0) / 60,
+    ),
+    barMaxWidth: 24,
+    itemStyle: { color: meta.color },
+  }))
+
   option.value = {
+    legend: { bottom: 0, itemWidth: 10, itemHeight: 10, textStyle: { fontSize: 11 } },
     tooltip: {
       trigger: 'axis',
-      formatter: (params: Array<{ axisValue: string; data: number; dataIndex: number }>) => {
-        const point = params[0]
-        if (!point) return ''
-        const events = data.value[point.dataIndex]?.eventsCount ?? 0
-        const readingSeconds = data.value[point.dataIndex]?.readingSeconds ?? 0
+      formatter: (params: Array<{ axisValue: string; data: number; dataIndex: number; seriesName: string; marker: string }>) => {
+        const first = params[0]
+        if (!first) return ''
+        const item = data.value[first.dataIndex]
+        const events = item?.eventsCount ?? 0
+        const readingSeconds = item?.readingSeconds ?? 0
         const eventLabel = events === 1 ? 'event' : 'events'
-        return `${point.axisValue}<br/><strong>${formatDuration(readingSeconds)}</strong><br/>${events} ${eventLabel}`
+        const header = `${first.axisValue}<br/><strong>${formatDuration(readingSeconds)}</strong> · ${events} ${eventLabel}`
+        const rows = params
+          .filter((p) => p.data > 0)
+          .map((p) => `${p.marker} ${p.seriesName}: ${formatDuration(p.data * 60)}`)
+          .join('<br/>')
+        return rows ? `${header}<br/>${rows}` : header
       },
     },
-    grid: { left: '3%', right: '3%', bottom: '8%', top: '8%', containLabel: true },
+    grid: { left: '3%', right: '3%', bottom: 36, top: '8%', containLabel: true },
     xAxis: {
       type: 'category',
       data: data.value.map((item) => `${String(item.hour).padStart(2, '0')}:00`),
@@ -56,20 +82,16 @@ watchEffect(() => {
       name: 'Minutes',
       nameTextStyle: { fontSize: 11, color: 'var(--muted-foreground)' },
     },
-    series: [
-      {
-        type: 'bar',
-        data: data.value.map((item) => item.readingSeconds / 60),
-        barMaxWidth: 24,
-        itemStyle: { borderRadius: [4, 4, 0, 0] },
-      },
-    ],
+    series,
   }
 })
 </script>
 
 <template>
   <ChartCard title="Peak Reading Hours" :icon="Clock3" :color-index="5" :loading :error :empty="isEmpty">
+    <template #controls>
+      <BreakdownSelect v-model="dimension" />
+    </template>
     <ChartEmptyState
       v-if="lowConfidence"
       :icon="Clock3"
diff --git a/client/src/features/statistics/components/user/ReadingClockChart.vue b/client/src/features/statistics/components/user/ReadingClockChart.vue
index a2223c509..d54e92027 100644
--- a/client/src/features/statistics/components/user/ReadingClockChart.vue
+++ b/client/src/features/statistics/components/user/ReadingClockChart.vue
@@ -1,11 +1,13 @@
 <script setup lang="ts">
-import { computed, shallowRef, watchEffect } from 'vue'
+import { computed, ref, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { Clock } from '@lucide/vue'
+import type { ReadingSessionSourceBucket } from '@bookorbit/types'
 
 import { useThemeStore } from '@/stores/theme'
-import { getThemePalette } from '@/lib/echarts'
+import { getBreakdownSeries, type BreakdownDimension } from '../../lib/breakdown'
 import { useUserPeakReadingHours } from '../../composables/useUserPeakReadingHours'
+import BreakdownSelect from '../BreakdownSelect.vue'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
 
@@ -26,6 +28,7 @@ const option = shallowRef({})
 const totalEvents = computed(() => data.value.reduce((s, d) => s + d.eventsCount, 0))
 const isEmpty = computed(() => totalEvents.value === 0)
 const lowConfidence = computed(() => totalEvents.value > 0 && totalEvents.value < MIN_EVENTS)
+const dimension = ref<BreakdownDimension>('source')
 
 function formatDuration(seconds: number): string {
   const total = Math.max(0, Math.floor(seconds))
@@ -46,22 +49,23 @@ watchEffect(() => {
   option.value = {}
   if (isEmpty.value || lowConfidence.value || !data.value.length) return
 
-  const palette = getThemePalette(themeStore.theme, themeStore.accent)
+  const formatKeys = [...new Set(data.value.flatMap((d) => Object.keys(d.byFormat)))].sort()
+  const seriesMeta = getBreakdownSeries(dimension.value, `${themeStore.theme}:${themeStore.accent}`, formatKeys)
 
-  const formats = [...new Set(data.value.flatMap((d) => Object.keys(d.byFormat)))].sort()
-
-  const series = formats.map((fmt, i) => ({
+  const series = seriesMeta.map((meta) => ({
     type: 'bar',
-    name: fmt,
-    data: data.value.map((d) => (d.byFormat[fmt] ?? 0) / 60),
+    name: meta.label,
+    data: data.value.map(
+      (d) => ((dimension.value === 'source' ? d.bySource?.[meta.key as ReadingSessionSourceBucket] : d.byFormat?.[meta.key]) ?? 0) / 60,
+    ),
     coordinateSystem: 'polar',
     stack: 'clock',
-    itemStyle: { color: palette[i % palette.length] },
-    emphasis: { focus: 'series' },
+    itemStyle: { color: meta.color },
   }))
 
   option.value = {
-    polar: { radius: ['20%', '80%'] },
+    legend: { bottom: 0, itemWidth: 10, itemHeight: 10, textStyle: { fontSize: 11 } },
+    polar: { radius: ['18%', '74%'], center: ['50%', '46%'] },
     angleAxis: {
       type: 'category',
       data: HOUR_LABELS,
@@ -91,15 +95,15 @@ watchEffect(() => {
         const eventLabel = events === 1 ? 'session' : 'sessions'
         const active = params.filter((p) => p.data > 0)
         const formatRows =
-          active.length > 1
+          active.length > 0
             ? `<div style="border-top:1px solid rgba(128,128,128,0.2);margin-top:5px;padding-top:5px">${active
                 .map((p) => {
-                  const formatSeconds = data.value[idx]?.byFormat[p.seriesName] ?? 0
+                  const sourceSeconds = (p.data ?? 0) * 60
                   return (
                     `<div style="display:flex;align-items:center;gap:6px;margin-top:2px">` +
                     `<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:${p.color};flex-shrink:0"></span>` +
                     `<span style="color:rgba(180,180,180,0.9)">${p.seriesName}</span>` +
-                    `<span style="margin-left:auto;padding-left:12px">${formatDuration(formatSeconds)}</span>` +
+                    `<span style="margin-left:auto;padding-left:12px">${formatDuration(sourceSeconds)}</span>` +
                     `</div>`
                   )
                 })
@@ -120,6 +124,9 @@ watchEffect(() => {
 
 <template>
   <ChartCard title="Reading Clock" :icon="Clock" :color-index="5" :loading :error :empty="isEmpty">
+    <template #controls>
+      <BreakdownSelect v-model="dimension" />
+    </template>
     <ChartEmptyState
       v-if="lowConfidence"
       :icon="Clock"
diff --git a/client/src/features/statistics/components/user/ReadingHeatmapChart.vue b/client/src/features/statistics/components/user/ReadingHeatmapChart.vue
index 59c315a04..e6fa7f2c3 100644
--- a/client/src/features/statistics/components/user/ReadingHeatmapChart.vue
+++ b/client/src/features/statistics/components/user/ReadingHeatmapChart.vue
@@ -2,9 +2,10 @@
 import { computed, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { Calendar } from '@lucide/vue'
+import { READING_SESSION_SOURCE_BUCKETS, READING_SESSION_SOURCE_BUCKET_LABELS } from '@bookorbit/types'
 import { useThemeStore } from '@/stores/theme'
 
-import { buildHeatmapPalette } from '../../heatmap-palette'
+import { buildHeatmapPalette } from '@/lib/heatmap-palette'
 import { useUserReadingHeatmap } from '../../composables/useUserReadingHeatmap'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
@@ -71,7 +72,14 @@ watchEffect(() => {
         const [day, minutes, events] = params.value
         const minuteLabel = minutes === 1 ? 'minute' : 'minutes'
         const eventLabel = events === 1 ? 'event' : 'events'
-        return `${day}<br/><strong>${minutes}</strong> ${minuteLabel}<br/>${events} ${eventLabel}`
+        const bySource = byDay.get(day)?.bySource
+        const sourceRows = bySource
+          ? READING_SESSION_SOURCE_BUCKETS.filter((bucket) => (bySource[bucket] ?? 0) > 0)
+              .map((bucket) => `${READING_SESSION_SOURCE_BUCKET_LABELS[bucket]}: ${Math.round((bySource[bucket] ?? 0) / 60)}m`)
+              .join('<br/>')
+          : ''
+        const base = `${day}<br/><strong>${minutes}</strong> ${minuteLabel}<br/>${events} ${eventLabel}`
+        return sourceRows ? `${base}<br/>${sourceRows}` : base
       },
     },
     visualMap: {
diff --git a/client/src/features/statistics/components/user/ReadingPaceScatterChart.vue b/client/src/features/statistics/components/user/ReadingPaceScatterChart.vue
index 9edb9c97e..4a7bfc5a3 100644
--- a/client/src/features/statistics/components/user/ReadingPaceScatterChart.vue
+++ b/client/src/features/statistics/components/user/ReadingPaceScatterChart.vue
@@ -1,38 +1,53 @@
 <script setup lang="ts">
-import { computed, shallowRef, watchEffect } from 'vue'
+import { computed, ref, shallowRef, watchEffect } from 'vue'
 import VChart from 'vue-echarts'
 import { Zap } from '@lucide/vue'
 
+import { useThemeStore } from '@/stores/theme'
+import { getBreakdownSeries, type BreakdownDimension } from '../../lib/breakdown'
 import { useUserReadingPace } from '../../composables/useUserReadingPace'
+import BreakdownSelect from '../BreakdownSelect.vue'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
 
 const MIN_SESSIONS = 10
 
+const themeStore = useThemeStore()
 const { data, loading, error } = useUserReadingPace()
 
 const isEmpty = computed(() => data.value.length === 0)
 const hasEnoughData = computed(() => data.value.length >= MIN_SESSIONS)
 
 const option = shallowRef({})
+const dimension = ref<BreakdownDimension>('source')
 
 watchEffect(() => {
   option.value = {}
   if (isEmpty.value || !hasEnoughData.value || !data.value.length) return
 
-  const points = data.value
-    .filter((p) => p.durationSeconds > 0 && p.durationSeconds <= 14400 && p.progressDelta > 0 && p.progressDelta <= 100)
-    .map((p) => [+(p.durationSeconds / 60).toFixed(1), +p.progressDelta.toFixed(2)])
+  const visible = data.value.filter((p) => p.durationSeconds > 0 && p.durationSeconds <= 14400 && p.progressDelta > 0 && p.progressDelta <= 100)
+  const formatKeys = [...new Set(visible.map((p) => p.format))].sort()
+  const seriesMeta = getBreakdownSeries(dimension.value, `${themeStore.theme}:${themeStore.accent}`, formatKeys)
+  const series = seriesMeta.map((meta) => ({
+    type: 'scatter',
+    name: meta.label,
+    data: visible
+      .filter((p) => (dimension.value === 'source' ? p.bucket : p.format) === meta.key)
+      .map((p) => [+(p.durationSeconds / 60).toFixed(1), +p.progressDelta.toFixed(2)]),
+    symbolSize: 5,
+    itemStyle: { color: meta.color, opacity: 0.5 },
+  }))
 
   option.value = {
+    legend: { top: 0, itemWidth: 10, itemHeight: 10, textStyle: { fontSize: 11 } },
     tooltip: {
       trigger: 'item',
-      formatter: (params: { data: [number, number] }) => {
+      formatter: (params: { seriesName: string; data: [number, number] }) => {
         const [mins, pct] = params.data
-        return `${mins} min session<br/><strong>${pct}%</strong> progress made`
+        return `${params.seriesName}<br/>${mins} min session<br/><strong>${pct}%</strong> progress made`
       },
     },
-    grid: { left: '3%', right: '5%', bottom: '8%', top: '6%', containLabel: true },
+    grid: { left: '3%', right: '5%', bottom: '8%', top: 30, containLabel: true },
     xAxis: {
       type: 'value',
       name: 'Duration (min)',
@@ -47,20 +62,16 @@ watchEffect(() => {
       nameGap: 40,
       axisLabel: { fontSize: 11 },
     },
-    series: [
-      {
-        type: 'scatter',
-        data: points,
-        symbolSize: 5,
-        itemStyle: { opacity: 0.45 },
-      },
-    ],
+    series,
   }
 })
 </script>
 
 <template>
   <ChartCard title="Reading Pace" :icon="Zap" :color-index="2" :loading :error :empty="isEmpty">
+    <template #controls>
+      <BreakdownSelect v-model="dimension" />
+    </template>
     <ChartEmptyState
       v-if="!hasEnoughData"
       :icon="Zap"
diff --git a/client/src/features/statistics/components/user/ReadingSessionTimelineChart.vue b/client/src/features/statistics/components/user/ReadingSessionTimelineChart.vue
index 2b5d6eaf6..2307cc9c9 100644
--- a/client/src/features/statistics/components/user/ReadingSessionTimelineChart.vue
+++ b/client/src/features/statistics/components/user/ReadingSessionTimelineChart.vue
@@ -3,12 +3,15 @@ import { computed, ref, shallowRef, watch } from 'vue'
 import VChart from 'vue-echarts'
 import { CalendarRange } from '@lucide/vue'
 import { toast } from 'vue-sonner'
-import type { UserReadingSessionTimeline, UserReadingSessionTimelineItem } from '@bookorbit/types'
+import type { UserReadingSessionTimeline, UserReadingSessionTimelineItem, ReadingSessionSourceBucket } from '@bookorbit/types'
+import { READING_SESSION_SOURCE_BUCKET_LABELS } from '@bookorbit/types'
 
+import { useThemeStore } from '@/stores/theme'
 import { useCoverVersions } from '@/features/book/composables/useCoverVersions'
-import { getFormatColor } from '@/features/book/lib/format-colors'
+import { getBreakdownColor, getBreakdownSeries, type BreakdownDimension, type BreakdownSeries } from '../../lib/breakdown'
 import { fetchUserReadingSessionTimeline, updateUserReadingSessionTimelineSession } from '../../api/statistics.api'
 import { useStatisticsConfig } from '../../composables/useStatisticsConfig'
+import BreakdownSelect from '../BreakdownSelect.vue'
 import ChartCard from '../ChartCard.vue'
 import ChartEmptyState from '../ChartEmptyState.vue'
 
@@ -22,6 +25,7 @@ interface SessionSegment {
   bookId: number
   bookTitle: string | null
   bookFormat: string | null
+  bookSource: ReadingSessionSourceBucket
   dayIndex: number
   startMinute: number
   endMinute: number
@@ -54,6 +58,9 @@ interface PointerOffset {
 
 const { filters } = useStatisticsConfig()
 const { coverUrl } = useCoverVersions()
+const themeStore = useThemeStore()
+const themeKey = computed(() => `${themeStore.theme}:${themeStore.accent}`)
+const dimension = ref<BreakdownDimension>('source')
 
 const now = new Date()
 const selectedYear = ref(getIsoWeekYear(now))
@@ -78,6 +85,11 @@ const timeline = ref<UserReadingSessionTimeline>({
 
 const isEmpty = computed(() => timeline.value.items.length === 0)
 
+const legendItems = computed<BreakdownSeries[]>(() => {
+  const formatKeys = [...new Set(timeline.value.items.map((item) => (item.bookFormat ?? 'UNKNOWN').toUpperCase()))].sort()
+  return getBreakdownSeries(dimension.value, themeKey.value, formatKeys)
+})
+
 const weekStartDate = computed(() => parseYmdLocal(timeline.value.weekStart) ?? getIsoWeekStart(selectedYear.value, selectedWeek.value))
 const weekEndExclusive = computed(() => addDays(weekStartDate.value, 7))
 
@@ -127,9 +139,9 @@ watch(dragEnabled, (enabled) => {
 })
 
 watch(
-  [segments, dragPreview, dragEnabled],
+  [segments, dragPreview, dragEnabled, dimension, themeKey],
   () => {
-    option.value = makeOption(segments.value, dragPreview.value)
+    option.value = makeOption(segments.value, dragPreview.value, dimension.value, themeKey.value)
   },
   { immediate: true },
 )
@@ -154,16 +166,17 @@ async function loadTimeline() {
   }
 }
 
-function makeOption(data: SessionSegment[], preview: DragPreview | null) {
+function makeOption(data: SessionSegment[], preview: DragPreview | null, dim: BreakdownDimension, themeKeyValue: string) {
   const seriesData = data.map((segment) => ({
     value: [segment.dayIndex, segment.startMinute, segment.endMinute, segment.track, segment.totalTracks, segment.durationMinutes],
     sessionId: segment.sessionId,
     bookId: segment.bookId,
     bookTitle: segment.bookTitle,
     bookFormat: segment.bookFormat,
+    bookSource: segment.bookSource,
     durationMinutes: segment.durationMinutes,
     itemStyle: {
-      color: getFormatColor(segment.bookFormat),
+      color: getBreakdownColor(dim, dim === 'source' ? segment.bookSource : (segment.bookFormat ?? 'UNKNOWN').toUpperCase(), themeKeyValue),
       opacity: 0.9,
     },
   }))
@@ -206,7 +219,14 @@ function makeOption(data: SessionSegment[], preview: DragPreview | null) {
     tooltip: {
       trigger: 'item',
       formatter: (params: {
-        data: { bookId?: number; bookTitle?: string | null; bookFormat?: string | null; durationMinutes?: number; value: number[] }
+        data: {
+          bookId?: number
+          bookTitle?: string | null
+          bookFormat?: string | null
+          bookSource?: ReadingSessionSourceBucket
+          durationMinutes?: number
+          value: number[]
+        }
       }) => {
         const d = params.data
         if (!d || !d.value) return ''
@@ -215,6 +235,7 @@ function makeOption(data: SessionSegment[], preview: DragPreview | null) {
         const duration = formatDuration(Math.max(0, d.durationMinutes ?? 0))
         const title = escapeHtml(d.bookTitle ?? 'Reading session')
         const format = escapeHtml(d.bookFormat ?? 'Unknown')
+        const source = d.bookSource ? READING_SESSION_SOURCE_BUCKET_LABELS[d.bookSource] : ''
         const cover = d.bookId
           ? `<img src="${coverUrl(d.bookId)}" alt="Cover" style="width:32px;height:48px;object-fit:cover;border-radius:4px;" />`
           : ''
@@ -226,7 +247,7 @@ function makeOption(data: SessionSegment[], preview: DragPreview | null) {
           `<div style="font-weight:600;margin-bottom:2px;">${title}</div>`,
           `<div style="opacity:0.85;">${start} - ${end}</div>`,
           `<div style="opacity:0.85;">${duration}</div>`,
-          `<div style="opacity:0.72;">${format}</div>`,
+          `<div style="opacity:0.72;">${format}${source ? ` · ${source}` : ''}</div>`,
           '</div>',
           '</div>',
         ].join('')
@@ -489,6 +510,7 @@ function buildSegments(items: UserReadingSessionTimelineItem[], weekStart: Date,
         bookId: item.bookId,
         bookTitle: item.bookTitle,
         bookFormat: item.bookFormat,
+        bookSource: item.bookSource,
         dayIndex,
         startMinute,
         endMinute: Math.max(startMinute + 0.5, endMinute),
@@ -664,6 +686,7 @@ function getIsoWeekStart(year: number, week: number): Date {
 <template>
   <ChartCard title="Reading Session Timeline" :icon="CalendarRange" :color-index="11" :loading="loading" :error="error" :empty="false">
     <template #controls>
+      <BreakdownSelect v-model="dimension" />
       <button
         type="button"
         :disabled="persistLoading"
@@ -716,7 +739,15 @@ function getIsoWeekStart(year: number, week: number): Date {
           </select>
         </div>
 
-        <p class="text-muted-foreground text-xs">{{ weekRangeLabel }}</p>
+        <div class="flex items-center gap-3">
+          <div class="flex items-center gap-2">
+            <span v-for="entry in legendItems" :key="entry.key" class="text-muted-foreground flex items-center gap-1 text-xs">
+              <span class="inline-block h-2.5 w-2.5 rounded-full" :style="{ backgroundColor: entry.color }" />
+              {{ entry.label }}
+            </span>
+          </div>
+          <p class="text-muted-foreground text-xs">{{ weekRangeLabel }}</p>
+        </div>
       </div>
 
       <p v-if="dragEnabled" class="text-muted-foreground border-border/60 bg-muted/20 rounded-md border px-2 py-1 text-xs">
diff --git a/client/src/features/statistics/components/user/SourceDistributionChart.vue b/client/src/features/statistics/components/user/SourceDistributionChart.vue
new file mode 100644
index 000000000..38f6d68b5
--- /dev/null
+++ b/client/src/features/statistics/components/user/SourceDistributionChart.vue
@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import { computed, shallowRef, watchEffect } from 'vue'
+import VChart from 'vue-echarts'
+import { MonitorSmartphone } from '@lucide/vue'
+import { READING_SESSION_SOURCE_BUCKET_LABELS } from '@bookorbit/types'
+import { breakpointsTailwind, useBreakpoints } from '@vueuse/core'
+
+import { useThemeStore } from '@/stores/theme'
+import { resolveSourceBucketColors } from '../../lib/source-bucket-colors'
+import { useUserReadingSourceDistribution } from '../../composables/useUserReadingSourceDistribution'
+import ChartCard from '../ChartCard.vue'
+
+const themeStore = useThemeStore()
+const { data, loading, error } = useUserReadingSourceDistribution()
+const { md } = useBreakpoints(breakpointsTailwind)
+
+const isEmpty = computed(() => data.value.slices.length === 0)
+
+function formatDuration(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds))
+  const hours = Math.floor(total / 3600)
+  const mins = Math.floor((total % 3600) / 60)
+  if (hours > 0) return `${hours}h ${mins}m`
+  if (mins > 0) return `${mins}m`
+  return `${total}s`
+}
+
+const option = shallowRef({})
+
+watchEffect(() => {
+  option.value = {}
+  if (isEmpty.value) return
+
+  const colors = resolveSourceBucketColors(`${themeStore.theme}:${themeStore.accent}`)
+
+  option.value = {
+    tooltip: {
+      trigger: 'item',
+      appendToBody: true,
+      formatter: (p: { name: string; value: number; percent: number; color: string }) =>
+        `<div style="font-size:12px;line-height:1.5">` +
+        `<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background:${p.color};margin-right:6px"></span>${p.name}` +
+        `<div><span style="font-weight:600">${formatDuration(p.value)}</span> · ${p.percent}%</div></div>`,
+    },
+    legend: {
+      orient: md.value ? 'vertical' : 'horizontal',
+      right: md.value ? '2%' : 'auto',
+      bottom: md.value ? 'auto' : 0,
+      top: md.value ? 'middle' : 'auto',
+      itemWidth: 10,
+      itemHeight: 10,
+      textStyle: { fontSize: 11 },
+    },
+    series: [
+      {
+        type: 'pie',
+        radius: ['45%', '72%'],
+        center: md.value ? ['38%', '50%'] : ['50%', '44%'],
+        data: data.value.slices.map((slice) => ({
+          name: READING_SESSION_SOURCE_BUCKET_LABELS[slice.bucket],
+          value: slice.readingSeconds,
+          itemStyle: { color: colors[slice.bucket] },
+        })),
+        label: { show: false },
+      },
+    ],
+  }
+})
+</script>
+
+<template>
+  <ChartCard
+    title="Where You Read"
+    :icon="MonitorSmartphone"
+    :color-index="6"
+    :loading
+    :error
+    :empty="isEmpty"
+    empty-title="No reading activity yet"
+    empty-description="Read on the web, KOReader, or Kobo to see your source split."
+  >
+    <VChart :option autoresize style="height: 100%" />
+  </ChartCard>
+</template>
diff --git a/client/src/features/statistics/components/user/__tests__/SourceDistributionChart.spec.ts b/client/src/features/statistics/components/user/__tests__/SourceDistributionChart.spec.ts
new file mode 100644
index 000000000..bf15c0fe4
--- /dev/null
+++ b/client/src/features/statistics/components/user/__tests__/SourceDistributionChart.spec.ts
@@ -0,0 +1,119 @@
+import { mount, flushPromises } from '@vue/test-utils'
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+const apiMock = vi.hoisted(() => vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>())
+
+vi.mock('@/lib/api', () => ({ api: apiMock }))
+
+vi.mock('vue-echarts', () => ({
+  default: { name: 'VChart', props: ['option'], template: '<div class="vchart" />' },
+}))
+
+vi.mock('@/stores/theme', () => ({
+  useThemeStore: () => ({ theme: 'dark', accent: 'blue' }),
+}))
+
+vi.mock('@/features/statistics/composables/useStatisticsConfig', () => ({
+  useStatisticsConfig: () => ({ filters: { value: { libraryIds: [] } } }),
+}))
+
+import SourceDistributionChart from '../SourceDistributionChart.vue'
+
+function makeResponse(data: unknown, options: { ok?: boolean; status?: number } = {}): Response {
+  const { ok = true, status = ok ? 200 : 500 } = options
+  return { ok, status, json: async () => data } as Response
+}
+
+function stubMatchMedia(matches: boolean) {
+  window.matchMedia = vi.fn<(query: string) => unknown>().mockImplementation((query: string) => ({
+    matches,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn<() => void>(),
+    removeEventListener: vi.fn<() => void>(),
+    addListener: vi.fn<() => void>(),
+    removeListener: vi.fn<() => void>(),
+    dispatchEvent: vi.fn<() => void>(),
+  })) as unknown as typeof window.matchMedia
+}
+
+describe('SourceDistributionChart', () => {
+  beforeEach(() => {
+    apiMock.mockReset()
+    stubMatchMedia(false)
+  })
+
+  it('requests the source distribution over a 365-day window', async () => {
+    apiMock.mockResolvedValue(makeResponse({ totalSeconds: 0, slices: [] }))
+    mount(SourceDistributionChart)
+    await flushPromises()
+
+    const url = String(apiMock.mock.calls[0]![0])
+    expect(url).toContain('/api/v1/user-statistics/reading-source-distribution')
+    expect(url).toContain('days=365')
+  })
+
+  it('shows the empty state when no source has reading time', async () => {
+    apiMock.mockResolvedValue(makeResponse({ totalSeconds: 0, slices: [] }))
+    const wrapper = mount(SourceDistributionChart)
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('No reading activity yet')
+    expect(wrapper.findComponent({ name: 'VChart' }).exists()).toBe(false)
+  })
+
+  it('builds a donut series from the source slices', async () => {
+    apiMock.mockResolvedValue(
+      makeResponse({
+        totalSeconds: 4800,
+        slices: [
+          { bucket: 'bookorbit', readingSeconds: 3600 },
+          { bucket: 'kobo', readingSeconds: 1200 },
+        ],
+      }),
+    )
+    const wrapper = mount(SourceDistributionChart)
+    await flushPromises()
+
+    const chart = wrapper.findComponent({ name: 'VChart' })
+    expect(chart.exists()).toBe(true)
+
+    const option = chart.props('option') as {
+      series: { data: { name: string; value: number }[] }[]
+      tooltip: { formatter: (p: { name: string; value: number; percent: number; color: string }) => string }
+    }
+    const data = option.series[0]!.data
+    expect(data.map((d) => d.name)).toEqual(['BookOrbit', 'Kobo'])
+    expect(data.map((d) => d.value)).toEqual([3600, 1200])
+
+    // The tooltip formatter exercises the duration helper across all 3 branches.
+    const fmt = option.tooltip.formatter
+    expect(fmt({ name: 'BookOrbit', value: 3661, percent: 75, color: '#abc' })).toContain('1h 1m')
+    expect(fmt({ name: 'Kobo', value: 120, percent: 20, color: '#def' })).toContain('2m')
+    expect(fmt({ name: 'Kobo', value: 30, percent: 5, color: '#def' })).toContain('30s')
+    expect(fmt({ name: 'BookOrbit', value: 3661, percent: 75, color: '#abc' })).toContain('75%')
+  })
+
+  it('uses the desktop legend and centre layout at >= md width', async () => {
+    stubMatchMedia(true)
+    apiMock.mockResolvedValue(makeResponse({ totalSeconds: 1200, slices: [{ bucket: 'kobo', readingSeconds: 1200 }] }))
+    const wrapper = mount(SourceDistributionChart)
+    await flushPromises()
+
+    const option = wrapper.findComponent({ name: 'VChart' }).props('option') as {
+      legend: { orient: string; right: string }
+      series: { center: string[] }[]
+    }
+    expect(option.legend.orient).toBe('vertical')
+    expect(option.legend.right).toBe('2%')
+    expect(option.series[0]!.center).toEqual(['38%', '50%'])
+  })
+
+  it('shows the error state when the request fails', async () => {
+    apiMock.mockResolvedValue(makeResponse({}, { ok: false, status: 500 }))
+    const wrapper = mount(SourceDistributionChart)
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Failed to load data')
+  })
+})
diff --git a/client/src/features/statistics/composables/useStatisticsQuery.ts b/client/src/features/statistics/composables/useStatisticsQuery.ts
index 99cad7db2..a5ef64ced 100644
--- a/client/src/features/statistics/composables/useStatisticsQuery.ts
+++ b/client/src/features/statistics/composables/useStatisticsQuery.ts
@@ -7,9 +7,10 @@ interface UseStatisticsQueryOptions<T> {
   initialData: T
   fetcher: (filters: StatisticsFilterConfig) => Promise<T>
   watchFilterFields?: Array<(filters: StatisticsFilterConfig) => string | number>
+  extraWatchSources?: Array<() => string | number | null>
 }
 
-export function useStatisticsQuery<T>({ initialData, fetcher, watchFilterFields = [] }: UseStatisticsQueryOptions<T>) {
+export function useStatisticsQuery<T>({ initialData, fetcher, watchFilterFields = [], extraWatchSources = [] }: UseStatisticsQueryOptions<T>) {
   const data = ref<T>(initialData)
   const loading = ref(true)
   const error = ref(false)
@@ -35,9 +36,10 @@ export function useStatisticsQuery<T>({ initialData, fetcher, watchFilterFields
     }
   }
 
-  const watchSources: Array<() => string | number> = [
+  const watchSources: Array<() => string | number | null> = [
     () => filters.value.libraryIds.join(','),
     ...watchFilterFields.map((selector) => () => selector(filters.value)),
+    ...extraWatchSources,
   ]
 
   watch(watchSources, load)
diff --git a/client/src/features/statistics/composables/useUserGoalTrajectory.ts b/client/src/features/statistics/composables/useUserGoalTrajectory.ts
index f616ab4ed..077d8e374 100644
--- a/client/src/features/statistics/composables/useUserGoalTrajectory.ts
+++ b/client/src/features/statistics/composables/useUserGoalTrajectory.ts
@@ -1,16 +1,24 @@
-import type { UserGoalTrajectory } from '@bookorbit/types'
+import { computed } from 'vue'
+import type { DashboardConfig, UserGoalTrajectory } from '@bookorbit/types'
 
+import { useAuth } from '@/features/auth/composables/useAuth'
 import { fetchUserGoalTrajectory } from '../api/statistics.api'
 import { useStatisticsQuery } from './useStatisticsQuery'
 
+const DEFAULT_GOAL = 12
+
 const EMPTY: UserGoalTrajectory = {
-  goalBooks: 12,
+  goalBooks: DEFAULT_GOAL,
   points: [],
 }
 
 export function useUserGoalTrajectory() {
+  const { user } = useAuth()
+  const readingGoal = computed(() => (user.value?.settings?.dashboardConfig as DashboardConfig | undefined)?.readingGoal ?? DEFAULT_GOAL)
+
   return useStatisticsQuery({
     initialData: EMPTY,
-    fetcher: fetchUserGoalTrajectory,
+    fetcher: (filters) => fetchUserGoalTrajectory(filters, readingGoal.value),
+    extraWatchSources: [() => readingGoal.value],
   })
 }
diff --git a/client/src/features/statistics/composables/useUserReadingSourceDistribution.ts b/client/src/features/statistics/composables/useUserReadingSourceDistribution.ts
new file mode 100644
index 000000000..d2592daa3
--- /dev/null
+++ b/client/src/features/statistics/composables/useUserReadingSourceDistribution.ts
@@ -0,0 +1,13 @@
+import type { UserReadingSourceDistribution } from '@bookorbit/types'
+
+import { fetchUserReadingSourceDistribution } from '../api/statistics.api'
+import { useStatisticsQuery } from './useStatisticsQuery'
+
+const EMPTY: UserReadingSourceDistribution = { totalSeconds: 0, slices: [] }
+
+export function useUserReadingSourceDistribution() {
+  return useStatisticsQuery({
+    initialData: EMPTY,
+    fetcher: fetchUserReadingSourceDistribution,
+  })
+}
diff --git a/client/src/features/statistics/lib/breakdown.test.ts b/client/src/features/statistics/lib/breakdown.test.ts
new file mode 100644
index 000000000..92e1c5fde
--- /dev/null
+++ b/client/src/features/statistics/lib/breakdown.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/echarts', () => ({
+  readCssColor: (varName: string) => `rgb(${varName})`,
+  oklchToHex: () => '#000000',
+}))
+
+import { getBreakdownColor, getBreakdownSeries } from './breakdown'
+
+describe('breakdown', () => {
+  it('returns the three source buckets for the source dimension', () => {
+    const series = getBreakdownSeries('source', 'theme:violet', [])
+    expect(series.map((s) => s.key)).toEqual(['bookorbit', 'koreader', 'kobo'])
+    expect(series.map((s) => s.label)).toEqual(['BookOrbit', 'KOReader', 'Kobo'])
+  })
+
+  it('returns one series per format key for the format dimension', () => {
+    expect(getBreakdownSeries('format', 'theme:violet', ['EPUB', 'PDF'])).toEqual([
+      { key: 'EPUB', label: 'EPUB', color: '#16a34a' },
+      { key: 'PDF', label: 'PDF', color: '#dc2626' },
+    ])
+  })
+
+  it('resolves a per-item colour for each dimension', () => {
+    expect(getBreakdownColor('format', 'EPUB', 'theme:violet')).toBe('#16a34a')
+    expect(getBreakdownColor('source', 'koreader', 'theme:violet')).toBe('rgb(--pill-koreader)')
+  })
+})
diff --git a/client/src/features/statistics/lib/breakdown.ts b/client/src/features/statistics/lib/breakdown.ts
new file mode 100644
index 000000000..7fc8ca3c9
--- /dev/null
+++ b/client/src/features/statistics/lib/breakdown.ts
@@ -0,0 +1,37 @@
+import { READING_SESSION_SOURCE_BUCKETS, READING_SESSION_SOURCE_BUCKET_LABELS, type ReadingSessionSourceBucket } from '@bookorbit/types'
+
+import { getFormatColor } from '@/features/book/lib/format-colors'
+import { resolveSourceBucketColors } from './source-bucket-colors'
+
+export type BreakdownDimension = 'source' | 'format'
+
+export const BREAKDOWN_OPTIONS: { value: BreakdownDimension; label: string }[] = [
+  { value: 'source', label: 'Source' },
+  { value: 'format', label: 'Format' },
+]
+
+export interface BreakdownSeries {
+  key: string
+  label: string
+  color: string
+}
+
+// Ordered series descriptors for charts that stack/colour by the chosen dimension.
+// `formatKeys` (uppercase, e.g. EPUB/PDF/UNKNOWN) is only consulted for the format dimension.
+export function getBreakdownSeries(dimension: BreakdownDimension, themeKey: string, formatKeys: string[]): BreakdownSeries[] {
+  if (dimension === 'source') {
+    const colors = resolveSourceBucketColors(themeKey)
+    return READING_SESSION_SOURCE_BUCKETS.map((bucket) => ({
+      key: bucket,
+      label: READING_SESSION_SOURCE_BUCKET_LABELS[bucket],
+      color: colors[bucket],
+    }))
+  }
+  return formatKeys.map((key) => ({ key, label: key, color: getFormatColor(key) }))
+}
+
+// Colour for a single item keyed by the chosen dimension (used by per-item charts).
+export function getBreakdownColor(dimension: BreakdownDimension, key: string, themeKey: string): string {
+  if (dimension === 'source') return resolveSourceBucketColors(themeKey)[key as ReadingSessionSourceBucket]
+  return getFormatColor(key)
+}
diff --git a/client/src/features/statistics/lib/source-bucket-colors.test.ts b/client/src/features/statistics/lib/source-bucket-colors.test.ts
new file mode 100644
index 000000000..810e3c686
--- /dev/null
+++ b/client/src/features/statistics/lib/source-bucket-colors.test.ts
@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  readCssColor: vi.fn<(varName: string) => string>(
+    (varName: string) =>
+      (
+        ({
+          '--pill-web': 'oklch(0.72 0.14 245)',
+          '--pill-koreader': 'oklch(0.72 0.17 295)',
+          '--pill-kobo': 'oklch(0.74 0.1 195)',
+        }) as Record<string, string>
+      )[varName] ?? 'oklch(0.5 0.1 0)',
+  ),
+  oklchToHex: vi.fn<() => string>(() => '#abcdef'),
+}))
+
+vi.mock('@/lib/echarts', () => ({ readCssColor: mocks.readCssColor, oklchToHex: mocks.oklchToHex }))
+
+import { resolveSourceBucketColors, SOURCE_BUCKET_COLOR_TOKENS } from './source-bucket-colors'
+
+describe('source-bucket-colors', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('maps each bucket to its pill token (bookorbit reuses the web hue)', () => {
+    expect(SOURCE_BUCKET_COLOR_TOKENS).toEqual({
+      bookorbit: '--pill-web',
+      koreader: '--pill-koreader',
+      kobo: '--pill-kobo',
+    })
+  })
+
+  it('converts oklch tokens to a zrender-parseable hex so bars do not vanish on hover', () => {
+    const colors = resolveSourceBucketColors('dark:violet')
+
+    expect(colors).toEqual({ bookorbit: '#abcdef', koreader: '#abcdef', kobo: '#abcdef' })
+    expect(mocks.readCssColor).toHaveBeenCalledWith('--pill-web')
+    expect(mocks.readCssColor).toHaveBeenCalledWith('--pill-koreader')
+    expect(mocks.readCssColor).toHaveBeenCalledWith('--pill-kobo')
+    expect(mocks.oklchToHex).toHaveBeenCalledTimes(3)
+  })
+
+  it('passes through values that are already rgb/hex', () => {
+    mocks.readCssColor.mockReturnValueOnce('rgb(1, 2, 3)')
+    const colors = resolveSourceBucketColors('passthrough-rgb')
+    expect(colors.bookorbit).toBe('rgb(1, 2, 3)')
+
+    mocks.readCssColor.mockReturnValueOnce('#123456')
+    const hexColors = resolveSourceBucketColors('passthrough-hex')
+    expect(hexColors.bookorbit).toBe('#123456')
+  })
+
+  it('converts percentage lightness and chroma to fractional oklch components', () => {
+    mocks.readCssColor.mockReturnValueOnce('oklch(72% 50% 245)')
+
+    resolveSourceBucketColors('percentage-key')
+
+    expect(mocks.oklchToHex).toHaveBeenCalledWith(0.72, 0.2, 245)
+  })
+
+  it('ignores the optional alpha component after the slash', () => {
+    mocks.readCssColor.mockReturnValueOnce('oklch(0.72 0.14 245 / 0.5)')
+
+    resolveSourceBucketColors('alpha-key')
+
+    expect(mocks.oklchToHex).toHaveBeenCalledWith(0.72, 0.14, 245)
+  })
+
+  it('returns the raw value when the oklch components are not finite', () => {
+    mocks.readCssColor.mockReturnValueOnce('oklch(not a color)')
+
+    const colors = resolveSourceBucketColors('malformed-key')
+
+    expect(colors.bookorbit).toBe('oklch(not a color)')
+  })
+
+  it('caches resolved colors per theme key', () => {
+    const first = resolveSourceBucketColors('light:violet')
+    const second = resolveSourceBucketColors('light:violet')
+    expect(first).toBe(second)
+  })
+})
diff --git a/client/src/features/statistics/lib/source-bucket-colors.ts b/client/src/features/statistics/lib/source-bucket-colors.ts
new file mode 100644
index 000000000..548a7e831
--- /dev/null
+++ b/client/src/features/statistics/lib/source-bucket-colors.ts
@@ -0,0 +1,47 @@
+import { oklchToHex, readCssColor } from '@/lib/echarts'
+import type { ReadingSessionSourceBucket } from '@bookorbit/types'
+
+// The 3 reading-source buckets reuse the existing pill tokens (light + dark variants
+// live in client/src/assets/theme/tokens.css). bookorbit shares the "web" hue.
+export const SOURCE_BUCKET_COLOR_TOKENS: Record<ReadingSessionSourceBucket, string> = {
+  bookorbit: '--pill-web',
+  koreader: '--pill-koreader',
+  kobo: '--pill-kobo',
+}
+
+const cache = new Map<string, Record<ReadingSessionSourceBucket, string>>()
+
+// The pill tokens are authored in oklch(), and getComputedStyle serializes them back as
+// oklch() strings. The browser paints `fill: oklch(...)` fine, but zrender cannot parse
+// oklch when it derives the hover/emphasis color, which makes the hovered bar vanish.
+// Convert to a hex string zrender can parse, mirroring how getThemePalette() emits hex.
+function toParseableColor(input: string): string {
+  const value = input.trim()
+  if (value.startsWith('#') || value.startsWith('rgb')) return value
+
+  const match = /^oklch\(([^)]+)\)/i.exec(value)
+  const inside = match?.[1]
+  if (inside) {
+    const [lRaw, cRaw, hRaw] = inside.split('/')[0]!.trim().split(/\s+/)
+    const l = lRaw?.endsWith('%') ? parseFloat(lRaw) / 100 : parseFloat(lRaw ?? '')
+    const c = cRaw?.endsWith('%') ? (parseFloat(cRaw) / 100) * 0.4 : parseFloat(cRaw ?? '')
+    const h = parseFloat(hRaw ?? '')
+    if (Number.isFinite(l) && Number.isFinite(c) && Number.isFinite(h)) return oklchToHex(l, c, h)
+  }
+  return value
+}
+
+// `themeKey` (e.g. `${theme}:${accent}`) is supplied by the caller so a computed re-resolves
+// colors when the active theme changes; the CSS variables themselves already encode the theme.
+export function resolveSourceBucketColors(themeKey: string): Record<ReadingSessionSourceBucket, string> {
+  const cached = cache.get(themeKey)
+  if (cached) return cached
+
+  const colors: Record<ReadingSessionSourceBucket, string> = {
+    bookorbit: toParseableColor(readCssColor(SOURCE_BUCKET_COLOR_TOKENS.bookorbit)),
+    koreader: toParseableColor(readCssColor(SOURCE_BUCKET_COLOR_TOKENS.koreader)),
+    kobo: toParseableColor(readCssColor(SOURCE_BUCKET_COLOR_TOKENS.kobo)),
+  }
+  cache.set(themeKey, colors)
+  return colors
+}
diff --git a/client/src/features/statistics/statistics-chart-meta.ts b/client/src/features/statistics/statistics-chart-meta.ts
index d07887672..4dc8f886e 100644
--- a/client/src/features/statistics/statistics-chart-meta.ts
+++ b/client/src/features/statistics/statistics-chart-meta.ts
@@ -15,6 +15,7 @@ import {
   HardDrive,
   Layers,
   ListChecks,
+  MonitorSmartphone,
   PieChart,
   Rabbit,
   ShieldCheck,
@@ -158,6 +159,12 @@ export const STATISTICS_CHART_META: Record<StatisticsChartId, StatisticsChartMet
     size: '2x1',
     category: 'user',
   },
+  'reading-source-distribution': {
+    label: 'Where You Read',
+    icon: MonitorSmartphone,
+    size: '1x1',
+    category: 'user',
+  },
   'peak-reading-hours': {
     label: 'Peak Reading Hours',
     icon: Clock3,
diff --git a/client/src/lib/echarts.ts b/client/src/lib/echarts.ts
index 39feba39b..a622a005b 100644
--- a/client/src/lib/echarts.ts
+++ b/client/src/lib/echarts.ts
@@ -79,7 +79,7 @@ const THEME_MODES: ProjectxThemeMode[] = ['light', 'dark']
 // Staggered hue offsets so adjacent chart series have more contrast.
 const HUE_OFFSETS = [0, 72, 144, 216, 288, 36, 108, 180, 252, 324]
 
-function oklchToHex(L: number, C: number, H: number): string {
+export function oklchToHex(L: number, C: number, H: number): string {
   const h = (H * Math.PI) / 180
   const a = C * Math.cos(h)
   const b = C * Math.sin(h)
diff --git a/client/src/features/statistics/heatmap-palette.ts b/client/src/lib/heatmap-palette.ts
similarity index 100%
rename from client/src/features/statistics/heatmap-palette.ts
rename to client/src/lib/heatmap-palette.ts
diff --git a/client/src/router/index.ts b/client/src/router/index.ts
index e4d2b5284..c14d4863e 100644
--- a/client/src/router/index.ts
+++ b/client/src/router/index.ts
@@ -2,7 +2,6 @@ import { createRouter, createWebHistory, type RouteLocationNormalizedLoaded, typ
 import { EMAIL_TAB_LABELS, normalizeEmailTab } from '@/features/email/lib/email-tabs'
 import { METADATA_TAB_INFO, normalizeMetadataTab } from '@/features/settings/lib/metadata-tabs'
 import { READER_TAB_TITLE_LABELS, normalizeReaderTab } from '@/features/settings/lib/reader-tabs'
-import { INTEGRATIONS_TAB_INFO, normalizeIntegrationsTab } from '@/features/settings/lib/integrations-tabs'
 import { ADMIN_TAB_INFO, normalizeAdminTab } from '@/features/settings/lib/admin-tabs'
 import { SYSTEM_TAB_INFO, normalizeSystemTab } from '@/features/settings/lib/system-tabs'
 import { ACCOUNT_TAB_INFO, normalizeAccountTab } from '@/features/settings/lib/account-tabs'
@@ -48,11 +47,6 @@ function resolveMetadataTitle(to: RouteLocationNormalizedLoaded): string {
   return METADATA_TAB_INFO[tab].titleLabel
 }
 
-function resolveIntegrationsTitle(to: RouteLocationNormalizedLoaded): string {
-  const tab = normalizeIntegrationsTab(to.query.tab)
-  return INTEGRATIONS_TAB_INFO[tab].titleLabel
-}
-
 function resolveAdminTitle(to: RouteLocationNormalizedLoaded): string {
   const tab = normalizeAdminTab(to.query.tab)
   return ADMIN_TAB_INFO[tab].titleLabel
@@ -72,6 +66,18 @@ function resolveStatisticsTitle(): string {
   return 'Statistics'
 }
 
+function resolveLegacyIntegrationsRoute(tab: unknown): string {
+  switch (firstText(tab)) {
+    case 'koreader':
+      return 'settings-koreader'
+    case 'hardcover':
+      return 'settings-hardcover'
+    case 'kobo':
+    default:
+      return 'settings-kobo'
+  }
+}
+
 export const routes: RouteRecordRaw[] = [
   {
     path: '/',
@@ -120,23 +126,25 @@ export const routes: RouteRecordRaw[] = [
           {
             path: 'integrations',
             name: 'settings-integrations',
-            component: () => import('@/features/settings/IntegrationsAllSettings.vue'),
-            meta: { maxWidth: 'max-w-3xl', title: resolveIntegrationsTitle },
+            redirect: (to) => ({ name: resolveLegacyIntegrationsRoute(to.query.tab) }),
           },
           {
             path: 'kobo',
             name: 'settings-kobo',
-            redirect: () => ({ name: 'settings-integrations', query: { tab: 'kobo' } }),
+            component: () => import('@/features/settings/KoboSettings.vue'),
+            meta: { maxWidth: 'max-w-4xl', title: 'Kobo Sync' },
           },
           {
             path: 'koreader',
             name: 'settings-koreader',
-            redirect: () => ({ name: 'settings-integrations', query: { tab: 'koreader' } }),
+            component: () => import('@/features/settings/KoreaderSettings.vue'),
+            meta: { maxWidth: 'max-w-4xl', title: 'KOReader Sync' },
           },
           {
             path: 'hardcover',
             name: 'settings-hardcover',
-            redirect: () => ({ name: 'settings-integrations', query: { tab: 'hardcover' } }),
+            component: () => import('@/features/hardcover/components/HardcoverSettings.vue'),
+            meta: { maxWidth: 'max-w-3xl', title: 'Hardcover' },
           },
           {
             path: 'email',
@@ -238,6 +246,12 @@ export const routes: RouteRecordRaw[] = [
         component: () => import('@/features/whats-new/WhatsNewView.vue'),
         meta: { title: "What's New" },
       },
+      {
+        path: '/annotations',
+        name: 'annotations',
+        component: () => import('@/features/annotations/views/AnnotationsHubView.vue'),
+        meta: { title: 'Annotations' },
+      },
       {
         path: '/statistics',
         name: 'statistics',
diff --git a/client/src/views/BookDetailView.vue b/client/src/views/BookDetailView.vue
index 0c5599634..c9dca81d6 100644
--- a/client/src/views/BookDetailView.vue
+++ b/client/src/views/BookDetailView.vue
@@ -99,7 +99,7 @@ function onCoverChanged(source: 'extracted' | 'custom' | null) {
           @cover-changed="onCoverChanged"
         />
         <FilesTab v-else-if="tab === 'files'" :book="detail" @refetch="fetch(detail.id)" />
-        <ReadingLogTab v-else-if="tab === 'reading-log'" :book="detail" />
+        <ReadingLogTab v-else-if="tab === 'reading-log'" :book="detail" @saved="onMetadataSaved" />
         <HighlightsTab v-else-if="tab === 'highlights'" :book="detail" />
       </div>
 
@@ -133,13 +133,14 @@ function onCoverChanged(source: 'extracted' | 'custom' | null) {
           <div v-for="i in 3" :key="i" class="h-16 rounded-md bg-muted animate-shimmer" />
         </div>
         <div v-else-if="tab === 'reading-log'" class="space-y-4">
+          <div class="h-32 rounded-lg bg-muted animate-shimmer" />
           <div class="flex gap-2">
             <div v-for="i in 4" :key="i" class="h-8 w-24 rounded-md bg-muted animate-shimmer" />
           </div>
-          <div class="grid grid-cols-2 sm:grid-cols-5 gap-3">
-            <div v-for="i in 5" :key="i" class="h-16 rounded-lg bg-muted animate-shimmer" />
+          <div class="grid grid-cols-1 gap-4 lg:grid-cols-5">
+            <div class="h-64 rounded-lg bg-muted animate-shimmer lg:col-span-3" />
+            <div class="h-64 rounded-lg bg-muted animate-shimmer lg:col-span-2" />
           </div>
-          <div class="h-16 rounded-md bg-muted animate-shimmer" />
           <div class="space-y-2">
             <div v-for="i in 5" :key="i" class="h-12 rounded-md bg-muted animate-shimmer" />
           </div>
diff --git a/koreader-plugin/README.md b/koreader-plugin/README.md
new file mode 100644
index 000000000..f81bcdf36
--- /dev/null
+++ b/koreader-plugin/README.md
@@ -0,0 +1,119 @@
+# BookOrbit Sync plugin for KOReader
+
+Syncs your KOReader reading life into BookOrbit:
+
+- Native BookOrbit catalog browsing from KOReader: "Continue reading", recently added books, libraries, collections, SmartScopes, authors, series, all books, "On device" and scoped or global search. Browse as a cover mosaic or a detailed list, with read-status, reading-progress bars and on-device indicators, read-status and format filters, a configurable grid, persisted view/sort/grid, recent-search history, loading feedback, download progress and inline retry on failures. Navigation runs off the UI thread (cancellable, no freeze) and the next page's covers are prefetched. The detail page shows genres, tags, page count and an expandable full description, and can set read status and star rating directly (synced back like any other status/rating change). Series open as an ordered read-through view with a "read N/total" header. Authors and series lists are paginated with a filter-within box. Downloads are linked to BookOrbit sync after the file is saved, and books already on the device offer a "Read" action that opens the local file. The thumbnail cache is bounded and evicts the oldest covers.
+- Live reading progress of the open book (pull on open with conflict prompt, optional periodic push every N page turns, push on close and suspend), compatible with the kosync flow BookOrbit already speaks.
+- Reading statistics: the raw per-page time events from KOReader's statistics database. BookOrbit turns them into reading sessions and daily stats, so they show up in the existing dashboards.
+- Highlights and notes, two ways: device highlights appear in the BookOrbit web reader as native highlights, and highlights, note edits and deletions made in BookOrbit come back to the device.
+- Book status (reading / complete / abandoned) and star ratings, with newest-change-wins conflict handling.
+
+The open book is captured from live memory when it is closed, on suspend, and via "Sync this book now", so highlights and status made mid-session sync without reopening the book. The full-library sweep ("Sync all books now") is manual-only.
+
+Only books that BookOrbit already knows are synced. Matching uses the same partial-MD5 file hash KOReader uses internally, which BookOrbit's scanner computes for every file. Books on the device that are not in any BookOrbit library are skipped and re-checked automatically when your library changes.
+
+## Install (preconfigured, recommended)
+
+1. In BookOrbit web settings, open Settings, KOReader and create sync credentials (username + password). The KOReader sync permission must be enabled for your account.
+2. Click "Download preconfigured plugin". The zip is generated by your server with the server address and your sync credentials already embedded (`bookorbit_provision.lua` inside the plugin folder).
+3. Unzip and copy the `bookorbit.koplugin/` folder to the `koreader/plugins/` directory on your device.
+4. Restart KOReader. The plugin configures itself on startup (a confirmation message appears) and removes the embedded credentials file.
+
+Re-downloading later (for example after changing the sync password or server address) and reinstalling applies the new configuration, even over an existing login. Reinstalling an old zip after a logout does not log back in: every download carries a generation stamp and the plugin only applies a configuration it has not applied before.
+
+## Install (manual)
+
+1. Copy the `bookorbit.koplugin/` folder from the repository to the `koreader/plugins/` directory on your device.
+2. Restart KOReader.
+3. In BookOrbit web settings, open Settings, KOReader and create sync credentials (username + password). The KOReader sync permission must be enabled for your account.
+4. On the device, open the main menu, Tools tab: "BookOrbit sync" sits directly below "Calibre" on the first page.
+   - Set the BookOrbit server address (e.g. `https://bookorbit.example.com`; the `/api/v1` suffix is added automatically).
+   - Login with the credentials from step 3.
+   - Use "Browse BookOrbit" to browse and download books from the same account.
+
+## Setup
+
+1. In the "BookOrbit sync" menu, enable "Auto sync this book" if you want the open book synced automatically. Leave the stock "Progress sync" plugin unconfigured to avoid double syncing.
+2. Optional: tune "Periodically sync every # pages" (default 10, 0 disables mid-session pushes).
+3. Optional: assign the "BookOrbit: sync this book" and "BookOrbit: sync all books" actions to gestures.
+
+Menu placement note: the plugin generates `settings/reader_menu_order.lua` and `settings/filemanager_menu_order.lua` to pin its entry below Calibre, and keeps them up to date across KOReader updates. Delete those files to reset the menu order. If you maintain your own menu order files, only the single `bookorbit_sync` entry is inserted (a one-time rewrite normalizes formatting and strips comments).
+
+## Two-way highlight sync
+
+Plugin 0.4 exchanges highlights instead of only uploading them (server 0.4+; against an older server the plugin falls back to upload-only automatically):
+
+- Device to web: highlights upload as before. BookOrbit converts their crengine positions (xpointers) to reader positions (CFIs), verifying every conversion against the highlighted text, so they render as native highlights in the web reader where you can edit notes, recolor and delete them.
+- Web to device: on book open (with "Auto sync this book" on), after "Sync this book now", and during the full sweep for closed books, the plugin applies web-created highlights, edits and deletions. For the open book they are verified against the rendering engine first; a position that does not match its text is re-anchored by searching the text, and the corrected position is reported back to the server. For closed books they are merged into the sidecar the same way KOHighlights does, and KOReader re-validates them on next open.
+- Deletions go both ways: deleting in the web moves nothing until the device confirms; deleting on the device moves the highlight to the BookOrbit trash, where it can be restored (a restore pushes it back to devices).
+- Identity is the highlight's creation datetime plus position, so extending a highlight on the device is recognized as a move, never as a delete-and-recreate.
+- Styles map across: highlight/underline/strikethrough map 1:1, BookOrbit's squiggly renders as underline on the device (and stays squiggly on the web), KOReader's invert renders inverted on the web. Colors map between KOReader's named palette and hex.
+- "Two-way highlight sync" in the plugin settings turns the apply direction off; uploads continue either way.
+
+## How syncing works
+
+- With "Auto sync this book" on: progress is pulled when a book opens (with conflict prompts), pushed every N page turns (10 seconds after you stop turning pages, 25 second debounce, silently skipped when offline), and the whole book (progress, highlights, status, rating, reading time) is snapshotted from live memory and uploaded when the book is closed and on suspend.
+- "Sync this book now" (menu item or gesture) does the same per-book snapshot on demand, including a forced statistics flush, so a highlight made seconds ago syncs immediately. If the book is not in any BookOrbit library it tells you so.
+- "Sync all books now" runs the full-library sweep: match new books, upload reading time for every matched book, then highlights, statuses and bulk progress. It never runs automatically. If a book is open when it starts, that book's sidecar and statistics are flushed first, so the sweep sees current data.
+- Everything is incremental: page-stat events are uploaded past a per-book watermark that only advances after the server acknowledges them, sidecars are only parsed when their modification time changed, and unmatched books are only re-checked when BookOrbit's library actually changed. An interrupted sync resumes where it left off; resends are server-side no-ops.
+- Local plugin state lives in `settings/bookorbit_sync_state.lua` next to your other KOReader settings. Deleting it is safe: the next sync re-uploads everything and the server deduplicates.
+
+## First sync on a device with lots of history
+
+Years of statistics upload in batches of 500 events. Roughly 200k events means about 400 requests, a few minutes of background work. The UI stays usable; progress is kept on every acknowledged batch, so you can suspend or lose wifi mid-way without losing anything.
+
+## Limitations
+
+- Web-side highlight changes reach a closed book's sidecar only through the manual sweep (and only when that book's sidecar changed since the last sweep) or on the next open of the book.
+- Web-created PDF highlights are not supported; device PDF highlights sync up and are listed (and jump to the page) in BookOrbit, but are not drawn over the PDF.
+- Books with reading statistics but no sidecar path in the reading history sync reading time only (no highlights/status/progress); the full sweep covers them.
+- Position-only bookmarks (no highlighted text) are not synced.
+- Device clocks far in the past can delay edit detection for highlights that were last modified from the web (the device edit must carry a newer timestamp than the applied one).
+- The full-library sweep is manual-only by design; books you never open again only sync when you press "Sync all books now".
+- A cloned device with a different KOReader `device_id` re-uploads its history under the new device identity, which double-counts reading time. Clones that keep the same `device_id` deduplicate naturally.
+
+## Hand-test checklist
+
+- Menu placement: "BookOrbit sync" appears on the Tools first page directly below Calibre, in both the file manager and the reader; `settings/reader_menu_order.lua` and `settings/filemanager_menu_order.lua` exist with the bookorbit marker line; a restart does not rewrite them.
+- Catalog browser: "Browse BookOrbit" appears in the Tools menu after login. "Continue reading", recently added books, libraries, collections, SmartScopes, authors, series, all books and "On device" load through the BookOrbit JSON API, with page navigation, scoped/global search and sorting.
+- Catalog search: on the root and browse screens the title-bar left button is a magnifier that opens global search; on a book page it becomes the actions menu (which still offers "Search in this scope"). Search is no longer a row in the root list.
+- Catalog view and filters (actions menu, title-bar left button on a book page): toggle mosaic/list view, change the mosaic grid size, filter by read status (all/unread/reading/finished) and by format, sort, and reverse the sort direction (asc/desc). View mode, sort and grid size persist across sessions; the active sort, direction and filters show in the page subtitle.
+- Catalog responsiveness: tapping any section, book page or detail shows a dismissable loading message and does not freeze the reader (network runs in a subprocess); tapping the loading message cancels the request. The next page's covers are prefetched a second after a page settles, so paging forward shows covers immediately.
+- Catalog detail edits (detail page actions menu): "Set read status" and "Set rating" write straight to BookOrbit and update the page in place; against an older server without these endpoints the action reports it is unsupported instead of erroring. "Full description" opens the complete text, "All genres"/"All tags" list every value (the detail page itself only shows the first few with a "+N more" hint).
+- Catalog series view: opening a series shows its books in series order with a "Read N/total" header.
+- Catalog authors/series lists: a "Filter..." row narrows the list as you type and "Next/Previous page" rows move through large libraries.
+- Catalog manual refresh: the actions menu "Refresh" re-fetches the current scope and retries any covers that failed.
+- Catalog indicators: each card/row shows reading progress, read status and an "On device" badge when a matching file already exists locally. "On device" lists those matched books via a single `?ids=` lookup.
+- Catalog search history: the search dialog offers a "Recent" button to re-run one of the last searches (stored locally).
+- Catalog feedback: section/page/detail fetches show a loading message; failures show an inline "Retry" dialog; downloads show throttled byte/percent progress.
+- Catalog download: open a book detail, choose a file format, change folder/name if needed, confirm overwrite, watch the download progress, then accept "Open now". The downloaded file is matched by partial MD5 and linked in `bookorbit_sync_state.lua`; the "On device" badge refreshes after a successful link.
+- Catalog read vs download: when a book is already on the device, the detail page shows a primary "Read" button that opens the local file. "Download" is shown next to it only when there are formats not yet on the device, and is hidden once every supported format is downloaded. The file chooser marks already-downloaded formats as "Open" instead of "Download". On-device state is refreshed when the detail opens.
+- Custom menu order: remove the marker line and shuffle the tools list; on restart only the `bookorbit_sync` id is re-inserted, the rest is preserved. A syntactically broken file is left untouched (warning in the log).
+- Login: wrong password shows a login error; server URL with and without trailing `/` and with `/api/v1` already appended all work.
+- Preconfigured install: download the zip from web settings, install, restart; the "set up for ... as ..." message appears once, the server URL and login are filled in, `bookorbit_provision.lua` is gone from the plugin folder, and a second restart shows no message.
+- Provision after logout: logout in the plugin menu, reinstall the SAME zip, restart; still logged out. Download a FRESH zip, reinstall, restart; logged in again.
+- Provision over existing login: with a working login, install a fresh zip with different credentials and restart; the new credentials win and the message appears.
+- Open a book that another device read further: pull prompt appears (with "Prompt" strategy); accepting jumps to the newer location.
+- Periodic push: with "Auto sync this book" on and the period set to 3, turn 3 pages and stop; about 10 seconds later one progress request hits the server. Turning 3 more pages within 25 seconds gets debounced. Toggling auto sync off cancels a pending push.
+- Mid-session highlight, then "Sync this book now": the highlight appears in BookOrbit immediately, no reopen needed.
+- Close a book after highlighting and changing status/rating: reading time, highlights, status, rating and progress all land in BookOrbit; reopening and closing again uploads nothing new.
+- "Sync this book now" on a book that is not in BookOrbit: shows "not in your BookOrbit library"; closing such a book stays silent.
+- Manual "Sync all books now": summary message shows matched books / events / highlights; settings page in BookOrbit shows the sweep. Running it with a freshly annotated book still open includes that book's data.
+- Re-running the manual sync immediately: all uploads are no-ops, counts stay stable.
+- Add a previously unmatched device book to BookOrbit, rescan the library, run a manual sync: its history backfills.
+- Suspend with a book open: the snapshot uploads before wifi drops (where the platform allows); suspend mid-sweep, resume, sync again: no duplicates, sweep completes.
+- Airplane mode: manual syncs report the server as unreachable; automatic ones stay silent.
+- Gestures: "BookOrbit: sync this book" is assignable from the file manager gesture settings and works inside the reader.
+- With the statistics plugin actively recording (book open), a sweep still reads the stats database without errors.
+
+Two-way highlight checks:
+
+- Web highlight on a device-matched book, then open the book on the device: the highlight appears (notification shows the count), with the right color/style and note.
+- Edit the note and color of that highlight in the web reader, reopen the book (or "Sync this book now"): the device copy updates.
+- Delete a highlight in the web reader; on next device sync it disappears from the book and the bookmark list.
+- Delete a highlight on the device; after the book closes (or a sweep), it appears under Annotations, Trash in the web. Restoring it brings it back to the device on the next sync.
+- Extend an existing highlight on the device: the web copy moves, no duplicate and nothing lands in trash.
+- Create a squiggly highlight on the web: it arrives as underline on the device, and stays squiggly in the web after the device re-syncs it.
+- Create an invert highlight on the device: it renders inverted in the web reader.
+- Kill KOReader mid-sync and sync again: no duplicates, no lost highlights (acks make re-delivery idempotent).
+- Closed-book sweep with pending web highlights: the sidecar gains them with `annotations_externally_modified` set; opening the book shows them sorted and valid.
diff --git a/koreader-plugin/bookorbit.koplugin/_meta.lua b/koreader-plugin/bookorbit.koplugin/_meta.lua
new file mode 100644
index 000000000..b0364cad9
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/_meta.lua
@@ -0,0 +1,5 @@
+local _ = require("gettext")
+return {
+    fullname = _("BookOrbit Sync"),
+    description = _([[Browse and download your BookOrbit library from KOReader, then synchronize reading progress, book status, ratings, reading statistics and highlights to BookOrbit. Highlights sync two ways: notes, edits and deletions made in the BookOrbit web reader appear on this device and vice versa.]]),
+}
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_annotations.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_annotations.lua
new file mode 100644
index 000000000..32af9bbbf
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_annotations.lua
@@ -0,0 +1,454 @@
+--[[--
+Two-way annotation exchange with BookOrbit.
+
+Uploads local highlight changes, applies server-side changes (web-created
+highlights, note/style edits, deletions) and reports back an acknowledgment so
+the server only marks entries delivered once they really landed on-device.
+
+Apply modes:
+- live: the book is open; entries are verified against crengine
+  (isXPointerInDocument + getTextFromXPointers) and repaired through
+  findAllText when the server-generated xpointer does not resolve to the
+  highlighted text. crengine has the final word; corrected positions are sent
+  back in the ack so the server stores them.
+- sidecar: the book is closed; entries are merged into the sidecar annotations
+  table and annotations_externally_modified is set, the same path KOHighlights
+  uses, so KOReader re-validates and re-sorts on next open.
+- skip: upload-only (suspend path); pending server changes stay queued because
+  no ack is sent for them.
+]]
+
+local DocSettings = require("docsettings")
+local Event = require("ui/event")
+local UIManager = require("ui/uimanager")
+local logger = require("logger")
+local md5 = require("ffi/sha2").md5
+local util = require("util")
+
+local BookOrbitSidecar = require("bookorbit_sidecar")
+
+local MAX_KEYS_PER_BOOK = 5000
+local MAX_PULL_ROUNDS = 10
+
+local BookOrbitAnnotations = {}
+
+function BookOrbitAnnotations.buildKey(datetime, pos0)
+    return md5(datetime .. "|" .. pos0)
+end
+
+-- Returns the stored upload watermark, resetting it when it sits in the
+-- device's future: bad data there (e.g. a server that minted UTC datetimes)
+-- would swallow every new annotation. The re-upload is a server-side no-op.
+function BookOrbitAnnotations.readWatermark(book, device_now)
+    local watermark = book.annWatermark or ""
+    if watermark > device_now then
+        watermark = ""
+        book.annWatermark = ""
+    end
+    return watermark
+end
+
+-- Advances the watermark, capped at the device clock so a future-dated entry
+-- cannot freeze it; such an entry just re-uploads until time passes it.
+function BookOrbitAnnotations.advanceWatermark(book, ann_max_datetime, device_now)
+    if not ann_max_datetime or ann_max_datetime == "" then return end
+    local advance = ann_max_datetime
+    if advance > device_now then
+        advance = device_now
+    end
+    if advance > (book.annWatermark or "") then
+        book.annWatermark = advance
+    end
+end
+
+-- Key list for deletion detection, built from normalized entries so the
+-- serialized pos0 matches what the server hashed at upload time.
+function BookOrbitAnnotations.collectKeys(normalized)
+    local keys = {}
+    for _, a in ipairs(normalized) do
+        table.insert(keys, { k = BookOrbitAnnotations.buildKey(a.datetime, a.pos0), dt = a.datetime })
+    end
+    return keys
+end
+
+local function normalizeText(text)
+    if type(text) ~= "string" then return "" end
+    return util.trim(text:gsub("%s+", " "))
+end
+
+local function findByDatetime(annotations, datetime)
+    for index, a in ipairs(annotations or {}) do
+        if a.datetime == datetime then
+            return index, a
+        end
+    end
+end
+
+-- crengine verification: both endpoints must resolve and, when the server
+-- knows the highlighted text, the extracted range must match it.
+local function verifyRange(document, pos0, pos1, text)
+    if type(pos0) ~= "string" or type(pos1) ~= "string" then return false end
+    local ok0, in0 = pcall(document.isXPointerInDocument, document, pos0)
+    local ok1, in1 = pcall(document.isXPointerInDocument, document, pos1)
+    if not (ok0 and in0 and ok1 and in1) then return false end
+    local wanted = normalizeText(text)
+    if wanted == "" then return true end
+    local ok, extracted = pcall(document.getTextFromXPointers, document, pos0, pos1)
+    return ok and type(extracted) == "string" and normalizeText(extracted) == wanted
+end
+
+-- Re-anchors an entry by searching its highlighted text, picking the hit
+-- nearest to the page the broken xpointer pointed at (when derivable).
+local function repairRange(document, entry)
+    local needle = type(entry.text) == "string" and util.trim(entry.text) or ""
+    if needle == "" or not document.findAllText then return nil end
+
+    local page_hint
+    if type(entry.pos0) == "string" then
+        local ok, page = pcall(document.getPageFromXPointer, document, entry.pos0)
+        if ok and type(page) == "number" then page_hint = page end
+    end
+
+    local ok, hits = pcall(document.findAllText, document, needle, true, 0, 20, false)
+    pcall(document.clearSelection, document)
+    if not ok or type(hits) ~= "table" or #hits == 0 then return nil end
+
+    local best = hits[1]
+    if page_hint and #hits > 1 then
+        local best_distance = math.huge
+        for _, hit in ipairs(hits) do
+            local okp, page = pcall(document.getPageFromXPointer, document, hit.start)
+            if okp and type(page) == "number" then
+                local distance = math.abs(page - page_hint)
+                if distance < best_distance then
+                    best_distance = distance
+                    best = hit
+                end
+            end
+        end
+    end
+    if verifyRange(document, best.start, best["end"], entry.text) then
+        return best.start, best["end"]
+    end
+    return nil
+end
+
+local function ackApplied(entry, opts)
+    return {
+        serverId = entry.serverId,
+        version = entry.version,
+        status = opts.failed and "failed" or "applied",
+        verified = opts.verified or false,
+        corrected = opts.corrected or false,
+        pos0 = opts.pos0,
+        pos1 = opts.pos1,
+        pageno = opts.pageno,
+        datetimeUpdated = entry.datetimeUpdated,
+    }
+end
+
+local function applyEditFields(annotation, entry)
+    annotation.drawer = entry.drawer or annotation.drawer
+    annotation.color = entry.color or annotation.color
+    if entry.text and entry.text ~= "" then annotation.text = entry.text end
+    annotation.note = entry.note
+    if entry.chapter then annotation.chapter = entry.chapter end
+    if entry.datetimeUpdated then annotation.datetime_updated = entry.datetimeUpdated end
+end
+
+-- Applies server changes to the OPEN book through ReaderAnnotation, so the
+-- view, footer and bookmark list stay coherent. Returns ack tables.
+function BookOrbitAnnotations.applyLive(ui, to_apply)
+    local applied, deleted = {}, {}
+    local document = ui.document
+    local annotations = ui.annotation.annotations
+    local touched = 0
+
+    for _, entry in ipairs(to_apply.add or {}) do
+        local existing_index = findByDatetime(annotations, entry.datetime)
+        if existing_index then
+            -- Idempotent retry of an earlier apply that lost its ack.
+            table.insert(applied, ackApplied(entry, { verified = true, pos0 = entry.pos0, pos1 = entry.pos1 }))
+        elseif entry.posFormat ~= "xpointer" or not ui.rolling then
+            -- PDF adds from the web are out of scope; never expected here.
+            table.insert(applied, ackApplied(entry, { failed = true }))
+        else
+            local pos0, pos1 = entry.pos0, entry.pos1
+            local verified = verifyRange(document, pos0, pos1, entry.text)
+            local corrected = false
+            if not verified then
+                local repaired0, repaired1 = repairRange(document, entry)
+                if repaired0 then
+                    pos0, pos1 = repaired0, repaired1
+                    verified = true
+                    corrected = true
+                end
+            end
+            if not verified then
+                logger.dbg("BookOrbit: annotation apply failed, no verifiable position:", entry.serverId)
+                table.insert(applied, ackApplied(entry, { failed = true }))
+            else
+                local item = {
+                    datetime = entry.datetime,
+                    datetime_updated = entry.datetimeUpdated,
+                    drawer = entry.drawer,
+                    color = entry.color,
+                    text = entry.text,
+                    note = entry.note,
+                    chapter = entry.chapter,
+                    page = pos0,
+                    pos0 = pos0,
+                    pos1 = pos1,
+                }
+                ui.annotation:addItem(item)
+                ui:handleEvent(Event:new("AnnotationsModified", { item, nb_highlights_added = 1 }))
+                touched = touched + 1
+                table.insert(applied, ackApplied(entry, {
+                    verified = true,
+                    corrected = corrected,
+                    pos0 = pos0,
+                    pos1 = pos1,
+                    pageno = type(item.pageno) == "number" and item.pageno or nil,
+                }))
+            end
+        end
+    end
+
+    for _, entry in ipairs(to_apply.edit or {}) do
+        local index, annotation = findByDatetime(annotations, entry.datetime)
+        if not index then
+            logger.dbg("BookOrbit: annotation edit target missing:", entry.serverId)
+            table.insert(applied, ackApplied(entry, { failed = true }))
+        else
+            applyEditFields(annotation, entry)
+            ui:handleEvent(Event:new("AnnotationsModified", { annotation, index_modified = index }))
+            touched = touched + 1
+            table.insert(applied, ackApplied(entry, { verified = true }))
+        end
+    end
+
+    for _, entry in ipairs(to_apply.delete or {}) do
+        local index, annotation = findByDatetime(annotations, entry.datetime)
+        if index then
+            if ui.paging then
+                pcall(ui.highlight.writePdfAnnotation, ui.highlight, "delete", annotation)
+            end
+            ui.bookmark:removeItemByIndex(index)
+            touched = touched + 1
+        end
+        -- Missing entries were already deleted locally; ack either way.
+        table.insert(deleted, { serverId = entry.serverId, status = "applied" })
+    end
+
+    if touched > 0 then
+        UIManager:setDirty("all", "ui")
+    end
+    return applied, deleted, touched
+end
+
+-- Merges server changes into the sidecar of a CLOSED book and raises
+-- annotations_externally_modified so KOReader re-validates and sorts on open.
+function BookOrbitAnnotations.applySidecar(file, to_apply)
+    local applied, deleted = {}, {}
+    local doc_settings = DocSettings:open(file)
+    local annotations = doc_settings:readSetting("annotations") or {}
+    local touched = 0
+
+    for _, entry in ipairs(to_apply.add or {}) do
+        if entry.posFormat ~= "xpointer" then
+            table.insert(applied, ackApplied(entry, { failed = true }))
+        else
+            local existing = findByDatetime(annotations, entry.datetime)
+            if not existing then
+                table.insert(annotations, {
+                    datetime = entry.datetime,
+                    datetime_updated = entry.datetimeUpdated,
+                    drawer = entry.drawer,
+                    color = entry.color,
+                    text = entry.text,
+                    note = entry.note,
+                    chapter = entry.chapter,
+                    pageno = entry.pageno,
+                    page = entry.pos0,
+                    pos0 = entry.pos0,
+                    pos1 = entry.pos1,
+                })
+                touched = touched + 1
+            end
+            -- Unverified until the book is opened; the server keeps it pending.
+            table.insert(applied, ackApplied(entry, { pos0 = entry.pos0, pos1 = entry.pos1, pageno = entry.pageno }))
+        end
+    end
+
+    for _, entry in ipairs(to_apply.edit or {}) do
+        local index, annotation = findByDatetime(annotations, entry.datetime)
+        if not index then
+            table.insert(applied, ackApplied(entry, { failed = true }))
+        else
+            applyEditFields(annotation, entry)
+            touched = touched + 1
+            table.insert(applied, ackApplied(entry, {}))
+        end
+    end
+
+    for _, entry in ipairs(to_apply.delete or {}) do
+        local index = findByDatetime(annotations, entry.datetime)
+        if index then
+            table.remove(annotations, index)
+            touched = touched + 1
+        end
+        table.insert(deleted, { serverId = entry.serverId, status = "applied" })
+    end
+
+    if touched > 0 then
+        doc_settings:saveSetting("annotations", annotations)
+        doc_settings:makeTrue("annotations_externally_modified")
+        doc_settings:flush()
+    end
+    return applied, deleted, touched
+end
+
+local function hasPending(to_apply)
+    return to_apply and (#(to_apply.add or {}) > 0 or #(to_apply.edit or {}) > 0 or #(to_apply.delete or {}) > 0)
+end
+
+--[[--
+Full annotation exchange for one matched book. Blocking; callers run it from a
+step machine or a scheduled task.
+
+opts:
+- client: BookOrbitApi instance
+- state: BookOrbitState instance (book must already be matched)
+- digest: partial md5 of the book file
+- annotations: normalized annotation list (live or sidecar source)
+- ann_max_datetime: max effective datetime of that list
+- apply_mode: "live" | "sidecar" | "skip"
+- ui: ReaderUI (required for apply_mode "live")
+- file: book file path (required for apply_mode "sidecar")
+
+Returns a result table { uploaded, applied, deleted, failed, had_errors } or
+nil, err for auth/network level failures.
+]]
+function BookOrbitAnnotations.exchangeBook(opts)
+    local book = opts.state:getBook(opts.digest)
+    if not book then return nil, "unmatched" end
+
+    local keys = BookOrbitAnnotations.collectKeys(opts.annotations)
+    local keys_complete = #keys <= MAX_KEYS_PER_BOOK
+    if not keys_complete then keys = {} end
+
+    local device_now = os.date("%Y-%m-%d %H:%M:%S")
+    local watermark = BookOrbitAnnotations.readWatermark(book, device_now)
+    local delta = {}
+    for _, annotation in ipairs(opts.annotations) do
+        local effective = annotation.datetimeUpdated or annotation.datetime
+        if effective > watermark then
+            table.insert(delta, annotation)
+        end
+    end
+
+    local result = { uploaded = 0, applied = 0, deleted = 0, failed = 0, had_errors = false }
+    local response
+    local first_request = true
+    local upload_failed = false
+
+    repeat
+        local chunk = {}
+        while #delta > 0 and #chunk < 50 do
+            table.insert(chunk, table.remove(delta, 1))
+        end
+        local body, err = opts.client:exchangeAnnotations({
+            {
+                hash = opts.digest,
+                keys = first_request and keys or {},
+                keysComplete = first_request and keys_complete or false,
+                changes = chunk,
+            },
+        })
+        if not body then
+            if err == 401 or err == 403 then return nil, "auth" end
+            if err == 404 then return nil, "unsupported_server" end
+            if type(err) ~= "number" then return nil, "network" end
+            logger.dbg("BookOrbit: annotation exchange failed:", err)
+            result.had_errors = true
+            upload_failed = true
+            break
+        end
+        for _, hash in ipairs(body.unmatched or {}) do
+            if hash == opts.digest then
+                opts.state:setUnmatched(opts.digest)
+                return nil, "unmatched"
+            end
+        end
+        response = body.results and body.results[1] or nil
+        result.uploaded = result.uploaded + #chunk
+        first_request = false
+    until #delta == 0
+
+    if not upload_failed then
+        BookOrbitAnnotations.advanceWatermark(book, opts.ann_max_datetime, device_now)
+    end
+
+    if opts.apply_mode == "skip" then
+        return result
+    end
+
+    local rounds = 0
+    while response and hasPending(response.toApply) and rounds < MAX_PULL_ROUNDS do
+        rounds = rounds + 1
+        local applied, deleted, touched
+        if opts.apply_mode == "live" and opts.ui and opts.ui.document then
+            applied, deleted, touched = BookOrbitAnnotations.applyLive(opts.ui, response.toApply)
+        elseif opts.apply_mode == "sidecar" and opts.file then
+            applied, deleted, touched = BookOrbitAnnotations.applySidecar(opts.file, response.toApply)
+        else
+            break
+        end
+
+        result.applied = result.applied + touched
+        for _, entry in ipairs(applied) do
+            if entry.status == "failed" then result.failed = result.failed + 1 end
+        end
+
+        local ack_body, ack_err = opts.client:exchangeAck({
+            { hash = opts.digest, applied = applied, deleted = deleted },
+        })
+        if not ack_body then
+            logger.dbg("BookOrbit: annotation exchange ack failed:", ack_err)
+            result.had_errors = true
+            break
+        end
+
+        if not response.more then break end
+        local body, err = opts.client:exchangeAnnotations({
+            { hash = opts.digest, keys = {}, keysComplete = false, changes = {} },
+        })
+        if not body then
+            logger.dbg("BookOrbit: annotation exchange follow-up failed:", err)
+            result.had_errors = true
+            break
+        end
+        response = body.results and body.results[1] or nil
+    end
+
+    return result
+end
+
+-- Convenience wrapper for the open book: collects live annotations, exchanges
+-- and applies in place. Used by the reader-ready pull and the manual sync.
+function BookOrbitAnnotations.exchangeOpenBook(opts)
+    local ui = opts.ui
+    if not ui or not ui.document then return nil, "no_document" end
+    local annotations, ann_max = BookOrbitSidecar.normalizeAnnotations(ui.annotation and ui.annotation.annotations)
+    return BookOrbitAnnotations.exchangeBook({
+        client = opts.client,
+        state = opts.state,
+        digest = opts.digest,
+        annotations = annotations,
+        ann_max_datetime = ann_max,
+        apply_mode = "live",
+        ui = ui,
+    })
+end
+
+return BookOrbitAnnotations
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_api.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_api.lua
new file mode 100644
index 000000000..b67f4e058
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_api.lua
@@ -0,0 +1,294 @@
+--[[--
+HTTP client for the BookOrbit server.
+
+Speaks the kosync-compatible progress endpoints plus the BookOrbit plugin
+endpoints. All requests are blocking; callers keep them short and chunked.
+]]
+
+local http = require("socket.http")
+local ltn12 = require("ltn12")
+local rapidjson = require("rapidjson")
+local socket = require("socket")
+local socketutil = require("socketutil")
+local logger = require("logger")
+local util = require("util")
+
+local MAX_BODY_BYTES = 900 * 1024 -- stays under the server's 1 MiB body limit
+
+-- Plain empty Lua tables would encode as {} and fail the server's array
+-- validation; every empty table in our payloads is semantically an array.
+local ENCODE_OPTIONS = { empty_table_as_array = true }
+
+-- JSON null decodes to the rapidjson.null lightuserdata, which is truthy in
+-- Lua and would leak into sidecars and truthiness checks; treat it as absent.
+local function scrubNulls(value)
+    if value == rapidjson.null then return nil end
+    if type(value) == "table" then
+        for key, item in pairs(value) do
+            value[key] = scrubNulls(item)
+        end
+    end
+    return value
+end
+
+local BookOrbitApi = {}
+BookOrbitApi.__index = BookOrbitApi
+
+-- Normalizes a user-entered server address to the API base, e.g.
+-- "https://books.example.com/" -> "https://books.example.com/api/v1".
+function BookOrbitApi.normalizeServerUrl(input)
+    if not input then return nil end
+    local url = util.trim(input)
+    if url == "" then return nil end
+    url = url:gsub("/+$", "")
+    if not url:match("/api/v1$") then
+        url = url .. "/api/v1"
+    end
+    return url
+end
+
+function BookOrbitApi.new(opts)
+    return setmetatable({
+        server_url = opts.server_url,
+        username = opts.username,
+        userkey = opts.userkey,
+        device_id = opts.device_id,
+        device_model = opts.device_model,
+        plugin_version = opts.plugin_version,
+    }, BookOrbitApi)
+end
+
+function BookOrbitApi:isConfigured()
+    return self.server_url ~= nil and self.username ~= nil and self.userkey ~= nil
+end
+
+-- Returns decoded_body on success, or nil, err_code, decoded_error_body.
+-- err_code is a number for HTTP errors and a string for transport errors.
+function BookOrbitApi:request(method, path, body)
+    local sink = {}
+    local request = {
+        url = self.server_url .. path,
+        method = method,
+        sink = ltn12.sink.table(sink),
+        headers = {
+            ["accept"] = "application/json",
+            ["x-auth-user"] = self.username,
+            ["x-auth-key"] = self.userkey,
+        },
+    }
+
+    if body then
+        local body_json, encode_err = rapidjson.encode(body, ENCODE_OPTIONS)
+        if not body_json then
+            return nil, "encode_error: " .. tostring(encode_err)
+        end
+        if #body_json > MAX_BODY_BYTES then
+            return nil, "body_too_large"
+        end
+        request.source = ltn12.source.string(body_json)
+        request.headers["Content-Type"] = "application/json"
+        request.headers["Content-Length"] = #body_json
+    end
+
+    socketutil:set_timeout(socketutil.LARGE_BLOCK_TIMEOUT, socketutil.LARGE_TOTAL_TIMEOUT)
+    local code, _, status = socket.skip(1, http.request(request))
+    socketutil:reset_timeout()
+
+    if type(code) ~= "number" then
+        logger.dbg("BookOrbit: network error:", status or code)
+        return nil, tostring(status or code or "network_error")
+    end
+
+    local decoded = nil
+    if sink[1] then
+        decoded = scrubNulls(rapidjson.decode(table.concat(sink)))
+    end
+
+    if code < 200 or code >= 300 then
+        return nil, code, decoded
+    end
+
+    return decoded or {}
+end
+
+function BookOrbitApi:query(path, params)
+    if not params then return path end
+
+    local keys = {}
+    for key, value in pairs(params) do
+        if value ~= nil and value ~= "" then
+            table.insert(keys, key)
+        end
+    end
+    table.sort(keys)
+    if #keys == 0 then return path end
+
+    local parts = {}
+    for _, key in ipairs(keys) do
+        table.insert(parts, util.urlEncode(key) .. "=" .. util.urlEncode(tostring(params[key])))
+    end
+    return path .. "?" .. table.concat(parts, "&")
+end
+
+function BookOrbitApi:download(path, local_path, accept, progress_cb)
+    local out, open_err = io.open(local_path, "w")
+    if not out then
+        return nil, tostring(open_err or "open_error")
+    end
+
+    local file_sink = ltn12.sink.file(out)
+    local sink = file_sink
+    if progress_cb then
+        local received = 0
+        sink = function(chunk, err)
+            if chunk and chunk ~= "" then
+                received = received + #chunk
+                progress_cb(received)
+            end
+            return file_sink(chunk, err)
+        end
+    end
+
+    local request = {
+        url = self.server_url .. path,
+        method = "GET",
+        sink = sink,
+        headers = {
+            ["accept"] = accept or "application/octet-stream",
+            ["Accept-Encoding"] = "identity",
+            ["x-auth-user"] = self.username,
+            ["x-auth-key"] = self.userkey,
+        },
+    }
+
+    socketutil:set_timeout(socketutil.FILE_BLOCK_TIMEOUT, socketutil.FILE_TOTAL_TIMEOUT)
+    local code, _, status = socket.skip(1, http.request(request))
+    socketutil:reset_timeout()
+
+    if code == 200 then
+        return true
+    end
+
+    util.removeFile(local_path)
+    if type(code) ~= "number" then
+        return nil, tostring(status or code or "network_error")
+    end
+    return nil, code
+end
+
+function BookOrbitApi:withDevice(body)
+    body.deviceId = self.device_id
+    body.deviceModel = self.device_model
+    body.pluginVersion = self.plugin_version
+    -- KOReader datetimes are local wall clock with no timezone; the server
+    -- needs our clock to mint device datetimes that are not in our future.
+    body.deviceTime = os.date("%Y-%m-%d %H:%M:%S")
+    return body
+end
+
+-- kosync-compatible endpoints (existing BookOrbit API, snake_case wire format)
+
+function BookOrbitApi:auth()
+    return self:request("GET", "/koreader/users/auth")
+end
+
+function BookOrbitApi:getProgress(digest)
+    return self:request("GET", "/koreader/syncs/progress/" .. digest)
+end
+
+function BookOrbitApi:updateProgress(digest, percentage, progress, timestamp)
+    return self:request("PUT", "/koreader/syncs/progress", {
+        document = digest,
+        percentage = percentage,
+        progress = progress,
+        device = self.device_model,
+        device_id = self.device_id,
+        timestamp = timestamp,
+    })
+end
+
+-- BookOrbit plugin endpoints (camelCase wire format)
+
+function BookOrbitApi:matchCheck(hashes)
+    return self:request("POST", "/koreader/plugin/match-check", self:withDevice({ hashes = hashes }))
+end
+
+function BookOrbitApi:uploadPageStats(books)
+    return self:request("POST", "/koreader/plugin/page-stats", self:withDevice({ books = books }))
+end
+
+-- Deprecated one-way upload, kept as fallback for pre-0.4 servers.
+function BookOrbitApi:uploadAnnotations(books)
+    return self:request("POST", "/koreader/plugin/annotations", self:withDevice({ books = books }))
+end
+
+function BookOrbitApi:exchangeAnnotations(books)
+    return self:request("POST", "/koreader/plugin/annotations/exchange", self:withDevice({ books = books }))
+end
+
+function BookOrbitApi:exchangeAck(books)
+    return self:request("POST", "/koreader/plugin/annotations/exchange-ack", self:withDevice({ books = books }))
+end
+
+function BookOrbitApi:uploadBookStates(books)
+    return self:request("POST", "/koreader/plugin/book-states", self:withDevice({ books = books }))
+end
+
+function BookOrbitApi:bulkProgress(items)
+    return self:request("POST", "/koreader/plugin/progress", self:withDevice({ items = items }))
+end
+
+function BookOrbitApi:sweepComplete(counts)
+    return self:request("POST", "/koreader/plugin/sweeps", self:withDevice({
+        booksMatched = counts.books_matched or 0,
+        pageStatsUploaded = counts.page_stats or 0,
+        annotationsUpserted = counts.annotations or 0,
+    }))
+end
+
+-- BookOrbit catalog endpoints
+
+function BookOrbitApi:catalogRoot()
+    return self:request("GET", "/koreader/plugin/catalog/root")
+end
+
+function BookOrbitApi:catalogSection(section, params)
+    return self:request("GET", self:query("/koreader/plugin/catalog/sections/" .. util.urlEncode(section), params))
+end
+
+function BookOrbitApi:catalogSetReadStatus(book_id, status)
+    return self:request("PUT", "/koreader/plugin/catalog/books/" .. tostring(book_id) .. "/read-status", { status = status })
+end
+
+function BookOrbitApi:catalogSetRating(book_id, rating)
+    if rating == nil then rating = rapidjson.null end
+    return self:request("PUT", "/koreader/plugin/catalog/books/" .. tostring(book_id) .. "/rating", { rating = rating })
+end
+
+function BookOrbitApi:catalogBooks(params)
+    return self:request("GET", self:query("/koreader/plugin/catalog/books", params))
+end
+
+function BookOrbitApi:catalogBook(book_id)
+    return self:request("GET", "/koreader/plugin/catalog/books/" .. tostring(book_id))
+end
+
+function BookOrbitApi:downloadCatalogFile(file_id, local_path, progress_cb)
+    return self:download("/koreader/plugin/catalog/files/" .. tostring(file_id) .. "/download", local_path, nil, progress_cb)
+end
+
+function BookOrbitApi:downloadCatalogThumbnail(book_id, local_path)
+    return self:download("/koreader/plugin/catalog/books/" .. tostring(book_id) .. "/thumbnail", local_path, "image/jpeg,image/*")
+end
+
+-- Plugin self-update endpoints
+
+function BookOrbitApi:getPluginVersion()
+    return self:request("GET", "/koreader/plugin/version")
+end
+
+function BookOrbitApi:downloadPluginUpdate(local_path, progress_cb)
+    return self:download("/koreader/plugin/package", local_path, "application/zip", progress_cb)
+end
+
+return BookOrbitApi
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_book_sync.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_book_sync.lua
new file mode 100644
index 000000000..5e64d6e53
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_book_sync.lua
@@ -0,0 +1,445 @@
+--[[--
+Per-book snapshot sync: pushes progress, highlights, status/rating and page
+stats for ONE book, sourced from live memory instead of the sidecar file, so
+mid-session data is never stale.
+
+capture() runs synchronously while the ReaderUI is alive and returns plain
+tables only; run() uploads afterwards and never touches reader objects, so the
+close path can finish after the document is gone. Watermarks share the exact
+ack-gated semantics of the full sweep, and both write the same state file
+under mutual exclusion, so sweep and snapshot never double-upload.
+]]
+
+local InfoMessage = require("ui/widget/infomessage")
+local Notification = require("ui/widget/notification")
+local UIManager = require("ui/uimanager")
+local logger = require("logger")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local BookOrbitAnnotations = require("bookorbit_annotations")
+local BookOrbitApi = require("bookorbit_api")
+local BookOrbitSidecar = require("bookorbit_sidecar")
+local BookOrbitState = require("bookorbit_state")
+local BookOrbitStatsReader = require("bookorbit_stats_reader")
+local BookOrbitSweep = require("bookorbit_sweep")
+
+local STEP_DELAY = 0.1
+local STATS_BATCH = 500
+local ANN_BATCH_TOTAL = 50
+
+local BookOrbitBookSync = {
+    running = false,
+}
+
+function BookOrbitBookSync.isRunning()
+    return BookOrbitBookSync.running
+end
+
+-- Synchronous snapshot of the open book from live memory. The statistics
+-- flush writes pending page stats to statistics.sqlite3, which run() reads
+-- later; the DB outlives the document.
+function BookOrbitBookSync.capture(plugin)
+    local ui = plugin.ui
+    if not ui or not ui.document then return nil end
+
+    local digest = plugin:getDocumentDigest()
+    if not digest then return nil end
+
+    local annotations, ann_max = BookOrbitSidecar.normalizeAnnotations(ui.annotation and ui.annotation.annotations)
+    local summary = BookOrbitSidecar.normalizeSummary(ui.doc_settings:readSetting("summary"))
+
+    local stats = ui.statistics
+    if stats and stats.settings and stats.settings.is_enabled then
+        pcall(stats.insertDB, stats)
+    end
+
+    local file = ui.document.file
+    return {
+        digest = digest,
+        file = file,
+        percentage = plugin:getLastPercent(),
+        progress = plugin:getLastProgress(),
+        status = summary.status,
+        status_modified = summary.status_modified,
+        rating = summary.rating,
+        annotations = annotations,
+        ann_count = #annotations,
+        ann_max_datetime = ann_max,
+        mtime_at_capture = file and BookOrbitSidecar.sidecarMtime(file) or nil,
+        ts = os.time(),
+    }
+end
+
+local function isAuthError(err)
+    return err == 401 or err == 403
+end
+
+-- Numbers are HTTP statuses (server reachable, keep going); anything else is
+-- a transport failure, where firing more doomed requests would just stack
+-- timeouts, which the synchronous suspend path cannot afford.
+local function isTransportError(err)
+    return type(err) ~= "number"
+end
+
+local function isUnmatched(body, md5)
+    for _, hash in ipairs(body.unmatched or {}) do
+        if hash == md5 then return true end
+    end
+    return false
+end
+
+local function finish(ctx, err)
+    BookOrbitBookSync.running = false
+
+    -- The sidecar-clean marker is only safe on the close path: ReaderUI
+    -- flushed the sidecar before our handler captured, so memory equals disk
+    -- unless the book was reopened mid-upload (mtime check guards that).
+    if not err and not ctx.had_errors and ctx.reason == "close"
+            and ctx.snap.file and ctx.snap.mtime_at_capture then
+        local book = ctx.state:getBook(ctx.snap.digest)
+        if book and BookOrbitSidecar.sidecarMtime(ctx.snap.file) == ctx.snap.mtime_at_capture then
+            book.sidecarMtime = ctx.snap.mtime_at_capture
+        end
+    end
+
+    ctx.state:flush()
+
+    if err == "auth" then
+        if ctx.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync: login failed. Check your credentials."), timeout = 4 })
+        else
+            Notification:notify(_("BookOrbit sync: login failed"))
+        end
+    elseif err == "network" then
+        if ctx.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync: server not reachable."), timeout = 4 })
+        end
+        logger.dbg("BookOrbit: book sync aborted, server not reachable")
+    elseif err == "unmatched" then
+        if ctx.interactive then
+            UIManager:show(InfoMessage:new{ text = _("This book is not in your BookOrbit library."), timeout = 4 })
+        end
+        logger.dbg("BookOrbit: book sync skipped, book unmatched:", ctx.snap.digest)
+    else
+        if ctx.interactive then
+            local text = T(_("BookOrbit: book synced. %1 reading events, %2 highlights up, %3 applied."),
+                ctx.counts.page_stats, ctx.counts.annotations, ctx.counts.ann_applied or 0)
+            if ctx.had_errors then
+                text = text .. "\n" .. _("Some uploads failed and will retry on the next sync.")
+            end
+            UIManager:show(InfoMessage:new{ text = text, timeout = 4 })
+        end
+        logger.info(string.format(
+            "BookOrbit: book sync done reason=%s pageStats=%d annotations=%d applied=%d errors=%s",
+            ctx.reason, ctx.counts.page_stats, ctx.counts.annotations, ctx.counts.ann_applied or 0, tostring(ctx.had_errors)))
+    end
+
+    if ctx.on_finish then
+        pcall(ctx.on_finish)
+    end
+end
+
+-- In synchronous mode (suspend path) the steps run inline as tail calls under
+-- one pcall in run(); otherwise they are chained through UIManager:scheduleIn
+-- so the UI stays responsive.
+local function step(ctx, fn)
+    if ctx.synchronous then
+        return fn(ctx)
+    end
+    UIManager:scheduleIn(STEP_DELAY, function()
+        local ok, err = pcall(fn, ctx)
+        if not ok then
+            logger.err("BookOrbit: book sync step failed:", err)
+            ctx.had_errors = true
+            finish(ctx)
+        end
+    end)
+end
+
+local stepMatch, stepStats, stepAnnotations, stepAnnotationsLegacy, stepState, stepProgress
+
+stepMatch = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if book then
+        if ctx.snap.file and not book.file then
+            book.file = ctx.snap.file
+        end
+        return step(ctx, stepStats)
+    end
+
+    local body, err = ctx.client:matchCheck({ ctx.snap.digest })
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        return finish(ctx, "network")
+    end
+
+    for _, match in ipairs(body.matches or {}) do
+        if match.hash == ctx.snap.digest then
+            ctx.state:setMatched(match.hash, match.bookFileId, match.bookId, ctx.snap.file)
+            return step(ctx, stepStats)
+        end
+    end
+
+    ctx.state:setUnmatched(ctx.snap.digest)
+    return finish(ctx, "unmatched")
+end
+
+stepStats = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if not book then return finish(ctx, "unmatched") end
+
+    if ctx.stat_ids == nil then
+        ctx.stat_ids = BookOrbitStatsReader.getBookIds(ctx.snap.digest)
+    end
+    if #ctx.stat_ids == 0 then
+        return step(ctx, stepAnnotations)
+    end
+
+    local watermark = book.statsWatermark or 0
+    local events = BookOrbitStatsReader.getEventsAfter(ctx.stat_ids, watermark, STATS_BATCH)
+    if not events or #events == 0 then
+        return step(ctx, stepAnnotations)
+    end
+
+    local body, err = ctx.client:uploadPageStats({ { hash = ctx.snap.digest, events = events } })
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        ctx.had_errors = true
+        if isTransportError(err) then return finish(ctx, "network") end
+        logger.dbg("BookOrbit: book sync page stats upload failed:", err)
+        return step(ctx, stepAnnotations)
+    end
+    if isUnmatched(body, ctx.snap.digest) then
+        ctx.state:setUnmatched(ctx.snap.digest)
+        return finish(ctx, "unmatched")
+    end
+
+    local more = BookOrbitState.applyStatsAck(book, events, body, ctx.snap.digest, STATS_BATCH, watermark)
+    ctx.counts.page_stats = ctx.counts.page_stats + #events
+    if more then
+        return step(ctx, stepStats)
+    end
+    return step(ctx, stepAnnotations)
+end
+
+-- Two-way exchange: uploads the local delta, reports the full key set for
+-- deletion detection, applies server-side changes (live for the manual sync
+-- while the book is open, sidecar on the close path) and acks them.
+stepAnnotations = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if not book then return finish(ctx, "unmatched") end
+
+    local apply_mode = "skip"
+    if ctx.annotation_sync then
+        if ctx.reason == "close" then
+            apply_mode = "sidecar"
+        elseif ctx.reason == "manual" and ctx.plugin and ctx.plugin.ui and ctx.plugin.ui.document then
+            apply_mode = "live"
+        end
+    end
+
+    local result, err = BookOrbitAnnotations.exchangeBook({
+        client = ctx.client,
+        state = ctx.state,
+        digest = ctx.snap.digest,
+        annotations = ctx.snap.annotations,
+        ann_max_datetime = ctx.snap.ann_max_datetime,
+        apply_mode = apply_mode,
+        ui = apply_mode == "live" and ctx.plugin.ui or nil,
+        file = ctx.snap.file,
+    })
+    if not result then
+        if err == "auth" then return finish(ctx, "auth") end
+        if err == "network" then
+            ctx.had_errors = true
+            return finish(ctx, "network")
+        end
+        if err == "unmatched" then return finish(ctx, "unmatched") end
+        if err == "unsupported_server" then
+            return step(ctx, stepAnnotationsLegacy)
+        end
+        ctx.had_errors = true
+        return step(ctx, stepState)
+    end
+
+    if result.had_errors then ctx.had_errors = true end
+    ctx.counts.annotations = ctx.counts.annotations + result.uploaded
+    ctx.counts.ann_applied = (ctx.counts.ann_applied or 0) + result.applied
+    if not result.had_errors then
+        book.annCount = ctx.snap.ann_count
+    end
+    return step(ctx, stepState)
+end
+
+-- One-way upload for servers without the 0.4 exchange endpoint.
+stepAnnotationsLegacy = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if not book then return finish(ctx, "unmatched") end
+
+    if ctx.ann_delta == nil then
+        ctx.ann_delta = {}
+        ctx.ann_failed = false
+        local watermark = BookOrbitAnnotations.readWatermark(book, os.date("%Y-%m-%d %H:%M:%S"))
+        for _, annotation in ipairs(ctx.snap.annotations) do
+            local effective = annotation.datetimeUpdated or annotation.datetime
+            if effective > watermark then
+                table.insert(ctx.ann_delta, annotation)
+            end
+        end
+    end
+
+    if #ctx.ann_delta == 0 then
+        if not ctx.ann_failed then
+            BookOrbitAnnotations.advanceWatermark(book, ctx.snap.ann_max_datetime, os.date("%Y-%m-%d %H:%M:%S"))
+            book.annCount = ctx.snap.ann_count
+        end
+        return step(ctx, stepState)
+    end
+
+    local chunk = {}
+    while #ctx.ann_delta > 0 and #chunk < ANN_BATCH_TOTAL do
+        table.insert(chunk, table.remove(ctx.ann_delta, 1))
+    end
+
+    local body, err = ctx.client:uploadAnnotations({ { hash = ctx.snap.digest, annotations = chunk } })
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        ctx.had_errors = true
+        ctx.ann_failed = true
+        ctx.ann_delta = {}
+        if isTransportError(err) then return finish(ctx, "network") end
+        logger.dbg("BookOrbit: book sync annotations upload failed:", err)
+        return step(ctx, stepState)
+    end
+    if isUnmatched(body, ctx.snap.digest) then
+        ctx.state:setUnmatched(ctx.snap.digest)
+        return finish(ctx, "unmatched")
+    end
+
+    ctx.counts.annotations = ctx.counts.annotations + #chunk
+    return step(ctx, stepAnnotationsLegacy)
+end
+
+stepState = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if not book then return finish(ctx, "unmatched") end
+
+    if ctx.snap.status == nil and ctx.snap.rating == nil then
+        return step(ctx, stepProgress)
+    end
+    local status_changed = ctx.snap.status ~= nil
+        and (ctx.snap.status_modified or "") ~= (book.statusSyncedModified or "")
+    local rating_changed = (ctx.snap.rating or 0) ~= (book.ratingSynced or 0)
+    if not status_changed and not rating_changed then
+        return step(ctx, stepProgress)
+    end
+
+    local body, err = ctx.client:uploadBookStates({
+        {
+            hash = ctx.snap.digest,
+            status = ctx.snap.status,
+            statusModified = ctx.snap.status_modified,
+            rating = ctx.snap.rating,
+        },
+    })
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        ctx.had_errors = true
+        if isTransportError(err) then return finish(ctx, "network") end
+        logger.dbg("BookOrbit: book sync state upload failed:", err)
+        return step(ctx, stepProgress)
+    end
+    if isUnmatched(body, ctx.snap.digest) then
+        ctx.state:setUnmatched(ctx.snap.digest)
+        return finish(ctx, "unmatched")
+    end
+
+    -- A server-kept tie still counts as synced: the device value was considered.
+    book.statusSyncedModified = ctx.snap.status_modified or book.statusSyncedModified
+    book.ratingSynced = ctx.snap.rating or book.ratingSynced
+    return step(ctx, stepProgress)
+end
+
+stepProgress = function(ctx)
+    local book = ctx.state:getBook(ctx.snap.digest)
+    if not book then return finish(ctx, "unmatched") end
+
+    local pct = ctx.snap.percentage
+    if type(pct) ~= "number" then
+        return finish(ctx)
+    end
+    local pushed = book.progressPushedPct or -1
+    if math.abs(pct - pushed) <= 0.001 and not ctx.interactive then
+        return finish(ctx)
+    end
+
+    -- The live PUT carries device/device_id/timestamp, which is what the
+    -- pull-conflict logic on other devices consumes; the bulk endpoint is the
+    -- sweep's many-books channel with sidecar freshness semantics.
+    local body, err = ctx.client:updateProgress(ctx.snap.digest, pct, ctx.snap.progress, ctx.snap.ts)
+    if ctx.plugin then
+        ctx.plugin.push_timestamp = UIManager:getElapsedTimeSinceBoot()
+    end
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        logger.dbg("BookOrbit: book sync progress push failed:", err)
+        ctx.had_errors = true
+        return finish(ctx)
+    end
+
+    book.progressPushedPct = pct
+    return finish(ctx)
+end
+
+function BookOrbitBookSync.run(opts)
+    if BookOrbitBookSync.running or BookOrbitSweep.isRunning() then
+        if opts.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync is already running."), timeout = 2 })
+        end
+        return
+    end
+
+    local snap = opts.snap
+    if not snap then return end
+
+    local client = BookOrbitApi.new(opts.api)
+    if not client:isConfigured() then
+        if opts.interactive then
+            UIManager:show(InfoMessage:new{ text = _("Please configure the BookOrbit server and login first."), timeout = 3 })
+        end
+        return
+    end
+
+    BookOrbitBookSync.running = true
+
+    local ctx = {
+        client = client,
+        state = BookOrbitState.open(),
+        snap = snap,
+        reason = opts.reason or "manual",
+        interactive = opts.interactive or false,
+        synchronous = opts.synchronous or false,
+        annotation_sync = opts.annotation_sync ~= false,
+        plugin = opts.plugin,
+        on_finish = opts.on_finish,
+        counts = { page_stats = 0, annotations = 0, ann_applied = 0 },
+        had_errors = false,
+    }
+
+    ctx.state:rememberFile(snap.file, snap.digest)
+    logger.dbg("BookOrbit: book sync started, reason:", ctx.reason)
+
+    if ctx.synchronous then
+        local ok, err = pcall(step, ctx, stepMatch)
+        if not ok then
+            logger.err("BookOrbit: book sync failed:", err)
+            ctx.had_errors = true
+            finish(ctx)
+        end
+    else
+        step(ctx, stepMatch)
+    end
+end
+
+return BookOrbitBookSync
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_catalog.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog.lua
new file mode 100644
index 000000000..605fc2eda
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog.lua
@@ -0,0 +1,2040 @@
+--[[--
+Native BookOrbit catalog browser.
+
+Uses BookOrbit's KOReader-authenticated JSON catalog endpoints. Book result
+pages render as KOReader-style menu pages with a cover mosaic and progressive
+thumbnail loading.
+
+The controller is split across modules: bookorbit_catalog_util (constants and
+pure helpers), bookorbit_catalog_widgets (cover and item widgets) and
+bookorbit_catalog_download (download manager mixin). Navigation fetches run off
+the UI thread via Trapper so taps never freeze the reader.
+]]
+
+local BD = require("ui/bidi")
+local Button = require("ui/widget/button")
+local ButtonDialog = require("ui/widget/buttondialog")
+local CenterContainer = require("ui/widget/container/centercontainer")
+local DataStorage = require("datastorage")
+local Device = require("device")
+local Font = require("ui/font")
+local FrameContainer = require("ui/widget/container/framecontainer")
+local Geom = require("ui/geometry")
+local HorizontalGroup = require("ui/widget/horizontalgroup")
+local HorizontalSpan = require("ui/widget/horizontalspan")
+local InfoMessage = require("ui/widget/infomessage")
+local InputDialog = require("ui/widget/inputdialog")
+local Menu = require("ui/widget/menu")
+local NetworkMgr = require("ui/network/manager")
+local Size = require("ui/size")
+local TextBoxWidget = require("ui/widget/textboxwidget")
+local TextViewer = require("ui/widget/textviewer")
+local Trapper = require("ui/trapper")
+local UIManager = require("ui/uimanager")
+local VerticalGroup = require("ui/widget/verticalgroup")
+local VerticalSpan = require("ui/widget/verticalspan")
+local lfs = require("libs/libkoreader-lfs")
+local logger = require("logger")
+local util = require("util")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local BookOrbitApi = require("bookorbit_api")
+local BookOrbitState = require("bookorbit_state")
+local CatalogUtil = require("bookorbit_catalog_util")
+local CatalogWidgets = require("bookorbit_catalog_widgets")
+local CatalogDownload = require("bookorbit_catalog_download")
+
+local Screen = Device.screen
+
+local DEFAULT_GRID_COLUMNS = CatalogUtil.DEFAULT_GRID_COLUMNS
+local DEFAULT_GRID_ROWS = CatalogUtil.DEFAULT_GRID_ROWS
+local THUMBNAIL_BATCH_SIZE = CatalogUtil.THUMBNAIL_BATCH_SIZE
+local MAX_RECENT_SEARCHES = CatalogUtil.MAX_RECENT_SEARCHES
+local ON_DEVICE_MAX_IDS = CatalogUtil.ON_DEVICE_MAX_IDS
+local SORTS = CatalogUtil.SORTS
+local SORT_LABELS = CatalogUtil.SORT_LABELS
+local NATURAL_ORDER = CatalogUtil.NATURAL_ORDER
+local SORT_KIND = CatalogUtil.SORT_KIND
+local DIRECTION_LABELS = CatalogUtil.DIRECTION_LABELS
+local READ_STATUS_FILTERS = CatalogUtil.READ_STATUS_FILTERS
+local READ_STATUS_LABELS = CatalogUtil.READ_STATUS_LABELS
+local SETTABLE_READ_STATUSES = CatalogUtil.SETTABLE_READ_STATUSES
+local COMMON_FORMATS = CatalogUtil.COMMON_FORMATS
+local GRID_PRESETS = CatalogUtil.GRID_PRESETS
+
+local isAuthError = CatalogUtil.isAuthError
+local cloneParams = CatalogUtil.cloneParams
+local formatBytes = CatalogUtil.formatBytes
+local formatDuration = CatalogUtil.formatDuration
+local formatProgress = CatalogUtil.formatProgress
+local formatRating = CatalogUtil.formatRating
+local isSupportedFormat = CatalogUtil.isSupportedFormat
+local shortText = CatalogUtil.shortText
+local joinNames = CatalogUtil.joinNames
+local cleanInlineText = CatalogUtil.cleanInlineText
+local cleanDescriptionText = CatalogUtil.cleanDescriptionText
+local formatSeries = CatalogUtil.formatSeries
+local firstAuthor = CatalogUtil.firstAuthor
+local coverLabel = CatalogUtil.coverLabel
+local buildCoverWidget = CatalogWidgets.buildCoverWidget
+local BookOrbitMosaicItem = CatalogWidgets.MosaicItem
+local BookOrbitListItem = CatalogWidgets.ListItem
+
+-- Max genres/tags shown inline on the detail page before a "+N more" expander.
+local DETAIL_TAGS_INLINE = 6
+-- Soft cap on the catalog thumbnail cache (cache/bookorbit). Oldest covers are
+-- evicted past this many files so the cache cannot grow without bound.
+local THUMBNAIL_CACHE_MAX_FILES = 600
+
+local function showError(err)
+    local text
+    if isAuthError(err) then
+        text = _("BookOrbit login failed. Check your KOReader credentials.")
+    elseif err then
+        text = T(_("Could not reach the BookOrbit server: %1"), tostring(err))
+    else
+        text = _("Could not reach the BookOrbit server.")
+    end
+    UIManager:show(InfoMessage:new{ text = text, timeout = 4 })
+end
+
+local BookOrbitCatalog = Menu:extend{
+    title = _("BookOrbit"),
+    title_shrink_font_to_fit = true,
+    title_bar_left_icon = "appbar.menu",
+}
+
+CatalogDownload.install(BookOrbitCatalog)
+
+local Menu_recalculateDimen = Menu._recalculateDimen
+local Menu_updateItems = Menu.updateItems
+local Menu_onGotoPage = Menu.onGotoPage
+local Menu_onNextPage = Menu.onNextPage
+local Menu_onPrevPage = Menu.onPrevPage
+local Menu_onFirstPage = Menu.onFirstPage
+local Menu_onLastPage = Menu.onLastPage
+
+function BookOrbitCatalog:init()
+    self.client = BookOrbitApi.new(self.api)
+    self.stack = {}
+    self.thumbnail_cache_dir = DataStorage:getDataDir() .. "/cache/bookorbit"
+    self.thumbnail_generation = 0
+    self.thumbnail_failures = {}
+    self.settings = self.settings or {}
+    self.view_mode = self.settings.catalog_view_mode == "list" and "list" or "mosaic"
+    self.grid_cols = self:sanitizeGridValue(self.settings.catalog_grid_cols, DEFAULT_GRID_COLUMNS)
+    self.grid_rows = self:sanitizeGridValue(self.settings.catalog_grid_rows, DEFAULT_GRID_ROWS)
+    self.default_sort = self.settings.catalog_sort or "recently_added"
+    self.list_rows = self:computeListRows()
+    self.on_device = {}
+    self.on_device_files = {}
+    self:refreshOnDevice()
+    self.current_context = { kind = "root", title = self.title }
+    self.item_table = self:rootItems()
+    self.is_borderless = true
+    self.title_bar_fm_style = true
+    Menu.init(self)
+    self:updateLeftIcon()
+    self.paths = self.stack
+    UIManager:nextTick(function()
+        self:cleanLegacyThumbnails()
+        self:pruneThumbnailCache()
+    end)
+end
+
+-- Removes pre-versioning cache files ("<id>.jpg"). They were keyed by book id
+-- only, so after a library rescan reassigned ids they showed the wrong cover.
+function BookOrbitCatalog:cleanLegacyThumbnails()
+    local dir = self.thumbnail_cache_dir
+    if not dir or lfs.attributes(dir, "mode") ~= "directory" then return end
+    for name in lfs.dir(dir) do
+        if name:match("^%d+%.jpg$") then
+            os.remove(dir .. "/" .. name)
+        end
+    end
+end
+
+function BookOrbitCatalog:refreshCurrent()
+    self.thumbnail_failures = {}
+    local context = self.current_context or {}
+    if context.kind == "books" then
+        self:evictCachedCovers(context.books)
+        local params = cloneParams(context.params or {})
+        params.page = context.page or 1
+        self:loadBooks(params, context.title or _("Books"), false)
+    elseif context.kind == "section" then
+        self:loadSection(context.section, { page = context.page, q = context.q, replace = true })
+    elseif context.kind == "detail" and context.detail then
+        self:evictCachedCovers({ context.detail })
+        self:runConnected(function()
+            local detail, err = self:fetch(_("Refreshing..."), function()
+                return self.client:catalogBook(context.detail.id)
+            end)
+            if not detail then
+                if err ~= "cancelled" then self:showWriteError(err) end
+                return
+            end
+            self:cancelThumbnailJobs()
+            context.detail = detail
+            context.supported_files = self:supportedFiles(detail)
+            self:refreshOnDevice()
+            self:updateItems()
+            self:scheduleThumbnailDownloads({ detail })
+        end)
+    end
+end
+
+-- Deletes cached covers for the given books so a refresh re-downloads them,
+-- guaranteeing fresh covers even if the cover changed without a new version.
+function BookOrbitCatalog:evictCachedCovers(books)
+    for _, book in ipairs(books or {}) do
+        local path = self:thumbnailPath(book)
+        if path then os.remove(path) end
+    end
+end
+
+function BookOrbitCatalog:sanitizeGridValue(value, fallback)
+    value = tonumber(value)
+    if not value then return fallback end
+    value = math.floor(value)
+    if value < 1 then return 1 end
+    if value > 6 then return 6 end
+    return value
+end
+
+function BookOrbitCatalog:computeListRows()
+    local row_h = Screen:scaleBySize(64)
+    local usable = Screen:getHeight() * 0.82
+    return math.max(5, math.floor(usable / row_h))
+end
+
+function BookOrbitCatalog:itemsPerPage()
+    if self.view_mode == "list" then
+        return self.list_rows or 8
+    end
+    return self.grid_cols * self.grid_rows
+end
+
+function BookOrbitCatalog:persistSetting(key, value)
+    self.settings[key] = value
+    if self.save_settings then
+        self.save_settings()
+    end
+end
+
+function BookOrbitCatalog:refreshOnDevice()
+    local ok, state = pcall(function()
+        return BookOrbitState.open()
+    end)
+    if ok and state then
+        self.on_device = state:matchedByBookId()
+        self.on_device_files = state:matchedByBookFileId()
+    else
+        self.on_device = {}
+        self.on_device_files = {}
+    end
+end
+
+function BookOrbitCatalog:isOnDevice(book)
+    return book ~= nil and book.id ~= nil and self.on_device[book.id] ~= nil
+end
+
+function BookOrbitCatalog:onDeviceFilePath(file)
+    return file ~= nil and file.id ~= nil and self.on_device_files and self.on_device_files[file.id] or nil
+end
+
+function BookOrbitCatalog:detailReadPath(detail)
+    local fallback
+    for _, file in ipairs(self:supportedFiles(detail)) do
+        local path = self:onDeviceFilePath(file)
+        if path then
+            if string.lower(file.format or "") == "epub" then
+                return path
+            end
+            fallback = fallback or path
+        end
+    end
+    if fallback then return fallback end
+    return detail ~= nil and detail.id ~= nil and self.on_device[detail.id] or nil
+end
+
+function BookOrbitCatalog:readStatusLabel(book)
+    return book and book.readStatus and READ_STATUS_LABELS[book.readStatus] or nil
+end
+
+function BookOrbitCatalog:bookMetaLine(book)
+    local meta = {}
+    local progress = formatProgress(book.progressPercentage)
+    if progress then table.insert(meta, progress) end
+    local status = self:readStatusLabel(book)
+    if status then table.insert(meta, status) end
+    if self:isOnDevice(book) then table.insert(meta, _("On device")) end
+    if #meta == 0 and book.formats and book.formats[1] then
+        table.insert(meta, table.concat(book.formats, ", "))
+    end
+    return #meta > 0 and table.concat(meta, " - ") or nil
+end
+
+function BookOrbitCatalog:cellLabel(book)
+    local parts = { shortText(book.title or _("Untitled"), 30) }
+    local author = firstAuthor(book)
+    if author then
+        table.insert(parts, shortText(author, 24))
+    end
+    local meta = self:bookMetaLine(book)
+    if meta then table.insert(parts, meta) end
+    return table.concat(parts, "\n")
+end
+
+function BookOrbitCatalog:listText(book)
+    local lines = { shortText(book.title or _("Untitled"), 48) }
+    local author = firstAuthor(book)
+    if author then
+        table.insert(lines, shortText(author, 44))
+    end
+    local series = formatSeries(book)
+    if series then
+        table.insert(lines, shortText(series, 44))
+    end
+    local meta = self:bookMetaLine(book)
+    if meta then table.insert(lines, meta) end
+    return table.concat(lines, "\n")
+end
+
+function BookOrbitCatalog:rootItems()
+    local body, err = self:fetch(_("Loading..."), function()
+        return self.client:catalogRoot()
+    end)
+    if not body then
+        if err ~= "cancelled" then
+            showError(err)
+        end
+        return {}
+    end
+
+    local items = {}
+    for _, section in ipairs(body.sections or {}) do
+        if section.section == "search" then
+            -- Search is exposed through the title-bar magnifier on the root, not a list row.
+        elseif section.section == "recent" then
+            table.insert(items, {
+                text = section.title,
+                kind = "books",
+                params = { sort = "recently_added" },
+            })
+        elseif section.section == "continue-reading" then
+            table.insert(items, {
+                text = section.title,
+                kind = "books",
+                params = { sort = "recently_read", readStatus = "reading" },
+            })
+        elseif section.section == "all-books" then
+            table.insert(items, {
+                text = section.title,
+                kind = "books",
+                params = { sort = "title" },
+            })
+        else
+            table.insert(items, {
+                text = section.title,
+                kind = "section",
+                section = section.section,
+            })
+        end
+    end
+
+    local on_device_count = 0
+    for _ in pairs(self.on_device or {}) do
+        on_device_count = on_device_count + 1
+    end
+    table.insert(items, {
+        text = _("On device"),
+        mandatory = on_device_count > 0 and tostring(on_device_count) or nil,
+        kind = "on-device",
+    })
+
+    return items
+end
+
+function BookOrbitCatalog:updateReturnPath()
+    self.paths = self.stack
+end
+
+function BookOrbitCatalog:cancelThumbnailJobs()
+    self.thumbnail_generation = self.thumbnail_generation + 1
+end
+
+function BookOrbitCatalog:switchTo(title, item_table, context, push)
+    self:cancelThumbnailJobs()
+    if push and self.current_context then
+        table.insert(self.stack, {
+            title = self.current_context.title,
+            subtitle = self.current_context.subtitle,
+            item_table = self.item_table,
+            context = self.current_context,
+        })
+    end
+    self:updateReturnPath()
+    self.current_context = context
+    self:switchItemTable(title, item_table, nil, nil, context.subtitle or "")
+    self:updateLeftIcon()
+    if context.kind == "books" then
+        self:scheduleThumbnailDownloads(context.books or {})
+    elseif context.kind == "detail" then
+        self:scheduleThumbnailDownloads({ context.detail })
+    end
+end
+
+-- Runs the blocking request fn() off the UI thread when possible, so the
+-- reader stays responsive and the loading message can be tapped to cancel.
+-- fn must return (body, err, errbody); they are marshalled back through the
+-- subprocess. Returns nil, "cancelled" when the user dismisses the request.
+function BookOrbitCatalog:fetch(text, fn)
+    if not Trapper:isWrapped() then
+        local info = InfoMessage:new{ text = text or _("Loading...") }
+        UIManager:show(info)
+        UIManager:forceRePaint()
+        local body, err, errbody = fn()
+        UIManager:close(info)
+        return body, err, errbody
+    end
+    local completed, result = Trapper:dismissableRunInSubprocess(function()
+        local ok, body, err, errbody = pcall(fn)
+        if not ok then
+            return { err = tostring(body) }
+        end
+        return { body = body, err = err, errbody = errbody }
+    end, text or _("Loading..."))
+    if not completed then
+        return nil, "cancelled"
+    end
+    result = result or {}
+    return result.body, result.err, result.errbody
+end
+
+-- Wraps a connected job in a Trapper coroutine so self:fetch can run network
+-- calls in a dismissable subprocess.
+function BookOrbitCatalog:runConnected(fn)
+    NetworkMgr:runWhenConnected(function()
+        Trapper:wrap(fn)
+    end)
+end
+
+function BookOrbitCatalog:errorText(err)
+    if isAuthError(err) then
+        return _("BookOrbit login failed. Check your KOReader credentials.")
+    elseif type(err) == "number" then
+        return T(_("BookOrbit server error (%1)."), err)
+    end
+    return _("Could not reach the BookOrbit server. Check your connection.")
+end
+
+function BookOrbitCatalog:emptyEntriesText(section)
+    if section == "libraries" then return _("No libraries you can access.") end
+    if section == "collections" then return _("No collections yet.") end
+    if section == "smart-scopes" then return _("No SmartScopes yet.") end
+    if section == "authors" then return _("No authors found.") end
+    if section == "series" then return _("No series found.") end
+    return _("Nothing here yet.")
+end
+
+function BookOrbitCatalog:emptyBooksText()
+    local context = self.current_context or {}
+    local params = context.params or {}
+    if params.q then
+        return T(_("No books match \"%1\"."), tostring(params.q))
+    end
+    if params.readStatus or params.format then
+        return _("No books match these filters.")
+    end
+    return _("No books here yet.")
+end
+
+function BookOrbitCatalog:showRetry(err, retry_fn)
+    local dialog
+    dialog = ButtonDialog:new{
+        title = self:errorText(err),
+        buttons = {
+            {
+                {
+                    text = _("Retry"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        retry_fn()
+                    end,
+                },
+            },
+            {
+                {
+                    text = _("Cancel"),
+                    callback = function()
+                        UIManager:close(dialog)
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:loadSection(section, opts)
+    opts = opts or {}
+    local paged = (section == "authors" or section == "series")
+    self:runConnected(function()
+        local params
+        if paged then
+            params = {}
+            if opts.page and opts.page > 1 then params.page = opts.page end
+            if opts.q and opts.q ~= "" then params.q = opts.q end
+        end
+        local body, err = self:fetch(_("Loading..."), function()
+            return self.client:catalogSection(section, params)
+        end)
+        if not body then
+            if err ~= "cancelled" then
+                self:showRetry(err, function()
+                    self:loadSection(section, opts)
+                end)
+            end
+            return
+        end
+
+        local page = body.page or opts.page or 1
+        local q = body.query or opts.q
+        local item_table = {}
+
+        if paged then
+            table.insert(item_table, {
+                text = q and T(_("Filter: %1"), q) or _("Filter..."),
+                kind = "section-filter",
+                section = section,
+                q = q,
+            })
+            if page > 1 then
+                table.insert(item_table, {
+                    text = T(_("< Previous page (%1)"), page - 1),
+                    kind = "section-page",
+                    section = section,
+                    section_page = page - 1,
+                    q = q,
+                })
+            end
+            if body.hasNext then
+                table.insert(item_table, {
+                    text = T(_("Next page (%1) >"), page + 1),
+                    kind = "section-page",
+                    section = section,
+                    section_page = page + 1,
+                    q = q,
+                })
+            end
+        end
+
+        for _, entry in ipairs(body.items or {}) do
+            local entry_params = self:paramsForEntry(section, entry)
+            table.insert(item_table, {
+                text = entry.title,
+                mandatory = entry.count and tostring(entry.count) or nil,
+                kind = "books",
+                params = entry_params,
+            })
+        end
+
+        if #item_table == 0 then
+            table.insert(item_table, { text = self:emptyEntriesText(section), enabled = false })
+        end
+        local title = self:titleForSection(section)
+        local push = not opts.replace
+        self:switchTo(title, item_table, { kind = "section", title = title, section = section, page = page, q = q }, push)
+    end)
+end
+
+function BookOrbitCatalog:promptSectionFilter(section, current_q)
+    local dialog
+    dialog = InputDialog:new{
+        title = _("Filter"),
+        input = current_q or "",
+        input_hint = _("Type to filter"),
+        buttons = {
+            {
+                {
+                    text = _("Cancel"),
+                    id = "close",
+                    callback = function()
+                        UIManager:close(dialog)
+                    end,
+                },
+                {
+                    text = _("Clear"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:loadSection(section, { page = 1, q = nil, replace = true })
+                    end,
+                },
+                {
+                    text = _("Filter"),
+                    is_enter_default = true,
+                    callback = function()
+                        local value = util.trim(dialog:getInputText() or "")
+                        UIManager:close(dialog)
+                        self:loadSection(section, { page = 1, q = value ~= "" and value or nil, replace = true })
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+    dialog:onShowKeyboard()
+end
+
+function BookOrbitCatalog:titleForSection(section)
+    if section == "libraries" then return _("Libraries") end
+    if section == "collections" then return _("Collections") end
+    if section == "smart-scopes" then return _("SmartScopes") end
+    if section == "authors" then return _("Authors") end
+    if section == "series" then return _("Series") end
+    return _("BookOrbit")
+end
+
+function BookOrbitCatalog:paramsForEntry(section, entry)
+    local params = { sort = "title" }
+    if section == "libraries" then
+        params.libraryId = tonumber(entry.id)
+    elseif section == "collections" then
+        params.collectionId = tonumber(entry.id)
+    elseif section == "smart-scopes" then
+        params.smartScopeId = tonumber(entry.id)
+    elseif section == "authors" then
+        params.author = entry.id
+    elseif section == "series" then
+        params.series = entry.id
+        params.sort = "series"
+    end
+    return params
+end
+
+function BookOrbitCatalog:loadBooks(params, title, push)
+    self:runConnected(function()
+        local query = cloneParams(params)
+        query.page = query.page or 1
+        query.size = self:itemsPerPage()
+        query.sort = query.sort or self.default_sort or "recently_added"
+        query.order = self:effectiveOrder(query)
+
+        local body, err = self:fetch(_("Loading books..."), function()
+            return self.client:catalogBooks(query)
+        end)
+        if not body then
+            if err ~= "cancelled" then
+                self:showRetry(err, function()
+                    self:loadBooks(params, title, push)
+                end)
+            end
+            return
+        end
+
+        self:showBookPage(body, query, title or _("Books"), push ~= false)
+    end)
+end
+
+function BookOrbitCatalog:loadOnDevice()
+    self:refreshOnDevice()
+    local ids = {}
+    for book_id in pairs(self.on_device) do
+        table.insert(ids, book_id)
+    end
+    if #ids == 0 then
+        UIManager:show(InfoMessage:new{ text = _("No downloaded books are linked on this device yet."), timeout = 3 })
+        return
+    end
+    table.sort(ids)
+    local capped = {}
+    for i = 1, math.min(#ids, ON_DEVICE_MAX_IDS) do
+        capped[i] = ids[i]
+    end
+    self:loadBooks({ ids = table.concat(capped, ","), sort = "title" }, _("On device"), true)
+end
+
+function BookOrbitCatalog:scopeParams(query)
+    local params = cloneParams(query)
+    params.page = nil
+    params.size = nil
+    params.q = nil
+    return params
+end
+
+function BookOrbitCatalog:recordRecentSearch(q)
+    local recents = self.settings.catalog_recent_searches or {}
+    local next_list = { q }
+    for _, prev in ipairs(recents) do
+        if prev ~= q and #next_list < MAX_RECENT_SEARCHES then
+            table.insert(next_list, prev)
+        end
+    end
+    self:persistSetting("catalog_recent_searches", next_list)
+end
+
+function BookOrbitCatalog:runSearch(params, q)
+    q = util.trim(q or "")
+    if q == "" then return end
+    self:recordRecentSearch(q)
+    local query = cloneParams(params)
+    query.q = q
+    query.page = 1
+    query.sort = query.sort or "title"
+    self:loadBooks(query, T(_("Search: %1"), q), true)
+end
+
+function BookOrbitCatalog:showRecentSearches(params)
+    local recents = self.settings.catalog_recent_searches or {}
+    if #recents == 0 then
+        UIManager:show(InfoMessage:new{ text = _("No recent searches yet."), timeout = 2 })
+        return
+    end
+    local dialog
+    local buttons = {}
+    for _, q in ipairs(recents) do
+        table.insert(buttons, {
+            {
+                text = q,
+                callback = function()
+                    UIManager:close(dialog)
+                    self:runSearch(params, q)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{
+        title = _("Recent searches"),
+        buttons = buttons,
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:promptSearch(params)
+    local has_recents = #(self.settings.catalog_recent_searches or {}) > 0
+    local dialog
+    dialog = InputDialog:new{
+        title = _("Search BookOrbit"),
+        input_hint = _("Title, author, series, ISBN"),
+        buttons = {
+            {
+                {
+                    text = _("Cancel"),
+                    id = "close",
+                    callback = function()
+                        UIManager:close(dialog)
+                    end,
+                },
+                {
+                    text = _("Recent"),
+                    enabled = has_recents,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showRecentSearches(params)
+                    end,
+                },
+                {
+                    text = _("Search"),
+                    is_enter_default = true,
+                    callback = function()
+                        local q = util.trim(dialog:getInputText() or "")
+                        if q == "" then return end
+                        UIManager:close(dialog)
+                        self:runSearch(params, q)
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+    dialog:onShowKeyboard()
+end
+
+function BookOrbitCatalog:filterSummary(query)
+    local parts = {}
+    if query.readStatus then
+        for _, f in ipairs(READ_STATUS_FILTERS) do
+            if f.id == query.readStatus then
+                table.insert(parts, f.text)
+                break
+            end
+        end
+    end
+    if query.format then
+        table.insert(parts, string.upper(query.format))
+    end
+    return #parts > 0 and table.concat(parts, ", ") or nil
+end
+
+function BookOrbitCatalog:showBookPage(body, query, title, push)
+    local items = body.items or {}
+    local page = body.page or query.page or 1
+    local size = body.size or query.size or self:itemsPerPage()
+    local total = body.total or 0
+    local page_count = math.max(1, math.ceil(total / size))
+    local filters = self:filterSummary(query)
+    local sort_label = T(_("%1 (%2)"), self:sortLabel(query.sort), self:directionLabel(query))
+    local subtitle
+    if total > 0 then
+        subtitle = T(_("%1 books - Sort: %2"), total, sort_label)
+    else
+        subtitle = T(_("Sort: %1"), sort_label)
+    end
+    if filters then
+        subtitle = subtitle .. T(_(" - Filter: %1"), filters)
+    end
+    if body.seriesSummary then
+        subtitle = T(_("Read %1/%2 - %3"), body.seriesSummary.finished or 0, body.seriesSummary.total or total, subtitle)
+    end
+    local item_table = {}
+
+    for _, book in ipairs(items) do
+        table.insert(item_table, {
+            text = coverLabel(book),
+            kind = "book",
+            book_id = book.id,
+            book = book,
+        })
+    end
+
+    self:switchTo(title, item_table, {
+        kind = "books",
+        title = title,
+        subtitle = subtitle,
+        params = query,
+        books = items,
+        page = page,
+        page_count = page_count,
+        total = total,
+    }, push)
+
+    if page < page_count then
+        self:prefetchNextPage(query, page + 1)
+    end
+end
+
+-- Cover cache files are versioned by the book's updatedAt so a server-side
+-- cover change or a library rescan (which reassigns book ids) invalidates the
+-- cached image instead of showing the previous book's cover.
+local function coverToken(book)
+    local value = book and book.updatedAt
+    if not value then return "0" end
+    local token = tostring(value):gsub("%D", "")
+    return token ~= "" and token or "0"
+end
+
+function BookOrbitCatalog:thumbnailPath(book)
+    if not book or not book.hasCover then return nil end
+    if not util.makePath(self.thumbnail_cache_dir) then return nil end
+    return self.thumbnail_cache_dir .. "/" .. tostring(book.id) .. "_" .. coverToken(book) .. ".jpg"
+end
+
+function BookOrbitCatalog:cachedThumbnailPath(book)
+    local path = self:thumbnailPath(book)
+    if path and lfs.attributes(path, "mode") == "file" then
+        return path
+    end
+    return nil
+end
+
+function BookOrbitCatalog:thumbnailState(book)
+    if not book or not book.hasCover then return "missing" end
+    if self:cachedThumbnailPath(book) then return "ready" end
+    if self.thumbnail_failures[tostring(book.id)] then return "failed" end
+    return "loading"
+end
+
+function BookOrbitCatalog:scheduleThumbnailDownloads(items)
+    local queue = {}
+    for _, book in ipairs(items or {}) do
+        if book.hasCover and not self:cachedThumbnailPath(book) and not self.thumbnail_failures[tostring(book.id)] then
+            table.insert(queue, book)
+        end
+    end
+    if #queue == 0 then return end
+
+    local generation = self.thumbnail_generation
+    local function step()
+        if generation ~= self.thumbnail_generation then return end
+
+        for _ = 1, THUMBNAIL_BATCH_SIZE do
+            local book = table.remove(queue, 1)
+            if not book then break end
+
+            local path = self:thumbnailPath(book)
+            if path then
+                local ok, err = self.client:downloadCatalogThumbnail(book.id, path)
+                if ok then
+                    self.thumbnail_failures[tostring(book.id)] = nil
+                else
+                    self.thumbnail_failures[tostring(book.id)] = true
+                    logger.dbg("BookOrbit: thumbnail download failed", book.id, err)
+                end
+            end
+        end
+
+        if generation == self.thumbnail_generation then
+            self:updateItems(nil, true)
+            if #queue > 0 then
+                UIManager:scheduleIn(0.05, step)
+            else
+                self:pruneThumbnailCache()
+            end
+        end
+    end
+
+    UIManager:scheduleIn(0.15, step)
+end
+
+-- Downloads covers for a future page into the disk cache without repainting the
+-- current view, so paging forward shows covers immediately.
+function BookOrbitCatalog:prefetchThumbnails(items, generation)
+    local queue = {}
+    for _, book in ipairs(items or {}) do
+        if book.hasCover and not self:cachedThumbnailPath(book) and not self.thumbnail_failures[tostring(book.id)] then
+            table.insert(queue, book)
+        end
+    end
+    if #queue == 0 then return end
+
+    local function step()
+        if generation ~= self.thumbnail_generation then return end
+        local book = table.remove(queue, 1)
+        if not book then
+            self:pruneThumbnailCache()
+            return
+        end
+        local path = self:thumbnailPath(book)
+        if path then
+            local ok = self.client:downloadCatalogThumbnail(book.id, path)
+            if not ok then
+                self.thumbnail_failures[tostring(book.id)] = true
+            end
+        end
+        UIManager:scheduleIn(0.08, step)
+    end
+    UIManager:scheduleIn(0.08, step)
+end
+
+-- Fetches the next page's book list off the UI thread and warms its covers.
+function BookOrbitCatalog:prefetchNextPage(query, next_page)
+    if not next_page then return end
+    local generation = self.thumbnail_generation
+    UIManager:scheduleIn(1.0, function()
+        if generation ~= self.thumbnail_generation then return end
+        NetworkMgr:runWhenConnected(function()
+            if generation ~= self.thumbnail_generation then return end
+            Trapper:wrap(function()
+                local q = cloneParams(query)
+                q.page = next_page
+                local completed, result = Trapper:dismissableRunInSubprocess(function()
+                    local ok, body = pcall(function()
+                        return self.client:catalogBooks(q)
+                    end)
+                    return { body = ok and body or nil }
+                end, true)
+                if not completed or generation ~= self.thumbnail_generation then return end
+                local body = result and result.body
+                if body and body.items then
+                    self:prefetchThumbnails(body.items, generation)
+                end
+            end)
+        end)
+    end)
+end
+
+-- Evicts the oldest cached covers once the cache exceeds its soft file cap.
+function BookOrbitCatalog:pruneThumbnailCache()
+    local dir = self.thumbnail_cache_dir
+    if not dir or lfs.attributes(dir, "mode") ~= "directory" then return end
+    local files = {}
+    for name in lfs.dir(dir) do
+        if name:match("%.jpg$") then
+            local path = dir .. "/" .. name
+            local mtime = lfs.attributes(path, "modification")
+            if mtime then
+                table.insert(files, { path = path, mtime = mtime })
+            end
+        end
+    end
+    if #files <= THUMBNAIL_CACHE_MAX_FILES then return end
+    table.sort(files, function(a, b) return a.mtime < b.mtime end)
+    for i = 1, #files - THUMBNAIL_CACHE_MAX_FILES do
+        os.remove(files[i].path)
+    end
+end
+
+function BookOrbitCatalog:showSortDialog(item)
+    local dialog
+    local buttons = {}
+    for _, sort in ipairs(SORTS) do
+        table.insert(buttons, {
+            {
+                text = sort.text .. (item.current_sort == sort.id and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    local params = cloneParams(item.params)
+                    params.sort = sort.id
+                    params.order = nil
+                    params.page = 1
+                    self.default_sort = sort.id
+                    self:persistSetting("catalog_sort", sort.id)
+                    self:loadBooks(params, item.title or _("Books"), false)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{
+        title = _("Sort books"),
+        buttons = buttons,
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:reverseOrder()
+    self:applyToCurrentBooks(function(params)
+        local current = self:effectiveOrder(params)
+        params.order = current == "asc" and "desc" or "asc"
+    end)
+end
+
+function BookOrbitCatalog:sortLabel(sort_id)
+    return SORT_LABELS[sort_id] or _("Recently added")
+end
+
+function BookOrbitCatalog:effectiveOrder(query)
+    local sort = query.sort or "recently_added"
+    return query.order or NATURAL_ORDER[sort] or "asc"
+end
+
+function BookOrbitCatalog:directionLabel(query)
+    local sort = query.sort or "recently_added"
+    local kind = SORT_KIND[sort] or "alpha"
+    local order = self:effectiveOrder(query)
+    return DIRECTION_LABELS[kind][order]
+end
+
+function BookOrbitCatalog:applyToCurrentBooks(mutator)
+    local context = self.current_context or {}
+    if context.kind ~= "books" then return false end
+    local params = cloneParams(context.params or {})
+    if mutator then mutator(params) end
+    params.page = 1
+    self:loadBooks(params, context.title or _("Books"), false)
+    return true
+end
+
+function BookOrbitCatalog:reloadCurrentBooks()
+    return self:applyToCurrentBooks(nil)
+end
+
+function BookOrbitCatalog:setViewMode(mode)
+    if mode ~= "list" and mode ~= "mosaic" then return end
+    if self.view_mode == mode then return end
+    self.view_mode = mode
+    self:persistSetting("catalog_view_mode", mode)
+    if self:bookMode() then
+        self:reloadCurrentBooks()
+    end
+end
+
+function BookOrbitCatalog:setGrid(cols, rows)
+    self.grid_cols = self:sanitizeGridValue(cols, DEFAULT_GRID_COLUMNS)
+    self.grid_rows = self:sanitizeGridValue(rows, DEFAULT_GRID_ROWS)
+    self:persistSetting("catalog_grid_cols", self.grid_cols)
+    self:persistSetting("catalog_grid_rows", self.grid_rows)
+    if self:bookMode() and self.view_mode == "mosaic" then
+        self:reloadCurrentBooks()
+    end
+end
+
+function BookOrbitCatalog:showGridDialog()
+    local dialog
+    local grid_label = _("%1 x %2")
+    local buttons = {}
+    for _, preset in ipairs(GRID_PRESETS) do
+        local cols, rows = preset[1], preset[2]
+        local is_current = cols == self.grid_cols and rows == self.grid_rows
+        table.insert(buttons, {
+            {
+                text = T(grid_label, cols, rows) .. (is_current and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:setGrid(cols, rows)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{
+        title = _("Grid (columns x rows)"),
+        buttons = buttons,
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showReadStatusDialog()
+    local context = self.current_context or {}
+    local current = (context.params or {}).readStatus
+    local dialog
+    local buttons = {}
+    for _, filter in ipairs(READ_STATUS_FILTERS) do
+        table.insert(buttons, {
+            {
+                text = filter.text .. (current == filter.id and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:applyToCurrentBooks(function(params)
+                        params.readStatus = filter.id
+                    end)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{
+        title = _("Read status"),
+        buttons = buttons,
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showFormatDialog()
+    local context = self.current_context or {}
+    local current = (context.params or {}).format
+    local dialog
+    local buttons = {
+        {
+            {
+                text = _("All") .. (current == nil and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:applyToCurrentBooks(function(params)
+                        params.format = nil
+                    end)
+                end,
+            },
+        },
+    }
+    for _, fmt in ipairs(COMMON_FORMATS) do
+        if isSupportedFormat(fmt) then
+            table.insert(buttons, {
+                {
+                    text = string.upper(fmt) .. (current == fmt and " *" or ""),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:applyToCurrentBooks(function(params)
+                            params.format = fmt
+                        end)
+                    end,
+                },
+            })
+        end
+    end
+    dialog = ButtonDialog:new{
+        title = _("Format"),
+        buttons = buttons,
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showBookActions()
+    local context = self.current_context or {}
+    local in_books = context.kind == "books"
+    local params = in_books and self:scopeParams(context.params or {}) or {}
+    local view_label = self.view_mode == "list" and _("View: List") or _("View: Mosaic")
+    local dialog
+    dialog = ButtonDialog:new{
+        title = _("BookOrbit"),
+        buttons = {
+            {
+                {
+                    text = _("Search in this scope"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:promptSearch(params)
+                    end,
+                },
+                {
+                    text = _("Refresh"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:refreshCurrent()
+                    end,
+                },
+            },
+            {
+                {
+                    text = in_books
+                        and T(_("Sort: %1 (%2)"), self:sortLabel((context.params or {}).sort), self:directionLabel(context.params or {}))
+                        or _("Sort books"),
+                    enabled = in_books,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showSortDialog({
+                            params = params,
+                            current_sort = (context.params or {}).sort,
+                            title = context.title,
+                        })
+                    end,
+                },
+                {
+                    text = _("Reverse"),
+                    enabled = in_books,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:reverseOrder()
+                    end,
+                },
+            },
+            {
+                {
+                    text = _("Read status"),
+                    enabled = in_books,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showReadStatusDialog()
+                    end,
+                },
+                {
+                    text = _("Format"),
+                    enabled = in_books,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showFormatDialog()
+                    end,
+                },
+            },
+            {
+                {
+                    text = view_label,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:setViewMode(self.view_mode == "list" and "mosaic" or "list")
+                    end,
+                },
+                {
+                    text = _("Grid size"),
+                    enabled = self.view_mode == "mosaic",
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showGridDialog()
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showDetailActions()
+    local detail = (self.current_context or {}).detail
+    if not detail then return end
+    local has_genres = detail.genres and #detail.genres > 0
+    local has_tags = detail.tags and #detail.tags > 0
+    local dialog
+    dialog = ButtonDialog:new{
+        title = detail.title or _("Book"),
+        buttons = {
+            {
+                {
+                    text = _("Set read status"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showSetStatusDialog(detail)
+                    end,
+                },
+                {
+                    text = _("Set rating"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showSetRatingDialog(detail)
+                    end,
+                },
+            },
+            {
+                {
+                    text = _("Full description"),
+                    enabled = cleanDescriptionText(detail.description) ~= nil,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showFullText(_("Description"), detail.description)
+                    end,
+                },
+            },
+            {
+                {
+                    text = _("All genres"),
+                    enabled = has_genres,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showFullList(_("Genres"), detail.genres)
+                    end,
+                },
+                {
+                    text = _("All tags"),
+                    enabled = has_tags,
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:showFullList(_("Tags"), detail.tags)
+                    end,
+                },
+            },
+            {
+                {
+                    text = _("Refresh"),
+                    callback = function()
+                        UIManager:close(dialog)
+                        self:refreshCurrent()
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showSetStatusDialog(detail)
+    local dialog
+    local buttons = {}
+    for _, status in ipairs(SETTABLE_READ_STATUSES) do
+        table.insert(buttons, {
+            {
+                text = status.text .. (detail.readStatus == status.id and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:applyReadStatus(detail, status.id)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{ title = _("Set read status"), buttons = buttons }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:showSetRatingDialog(detail)
+    local dialog
+    local buttons = {
+        {
+            {
+                text = _("Clear rating") .. (detail.rating == nil and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:applyRating(detail, nil)
+                end,
+            },
+        },
+    }
+    for star = 1, 5 do
+        table.insert(buttons, {
+            {
+                text = formatRating(star) .. (detail.rating == star and " *" or ""),
+                callback = function()
+                    UIManager:close(dialog)
+                    self:applyRating(detail, star)
+                end,
+            },
+        })
+    end
+    dialog = ButtonDialog:new{ title = _("Set rating"), buttons = buttons }
+    UIManager:show(dialog)
+end
+
+function BookOrbitCatalog:refreshDetailView()
+    if self:detailMode() then
+        self:updateItems()
+    end
+end
+
+function BookOrbitCatalog:showWriteError(err)
+    local text
+    if err == 404 or err == 405 then
+        text = _("This BookOrbit server does not support catalog edits.")
+    elseif isAuthError(err) then
+        text = _("BookOrbit login failed. Check your KOReader credentials.")
+    else
+        text = self:errorText(err)
+    end
+    UIManager:show(InfoMessage:new{ text = text, timeout = 3 })
+end
+
+function BookOrbitCatalog:applyReadStatus(detail, status)
+    self:runConnected(function()
+        local body, err = self:fetch(_("Saving..."), function()
+            return self.client:catalogSetReadStatus(detail.id, status)
+        end)
+        if not body then
+            if err ~= "cancelled" then self:showWriteError(err) end
+            return
+        end
+        detail.readStatus = body.readStatus or status
+        self:refreshDetailView()
+        UIManager:show(InfoMessage:new{ text = _("Read status updated"), timeout = 1 })
+    end)
+end
+
+function BookOrbitCatalog:applyRating(detail, rating)
+    self:runConnected(function()
+        local body, err = self:fetch(_("Saving..."), function()
+            return self.client:catalogSetRating(detail.id, rating)
+        end)
+        if not body then
+            if err ~= "cancelled" then self:showWriteError(err) end
+            return
+        end
+        detail.rating = body.rating
+        self:refreshDetailView()
+        UIManager:show(InfoMessage:new{ text = _("Rating updated"), timeout = 1 })
+    end)
+end
+
+function BookOrbitCatalog:contextUsesActions()
+    local kind = self.current_context and self.current_context.kind
+    return kind == "books" or kind == "detail"
+end
+
+function BookOrbitCatalog:updateLeftIcon()
+    if not self.title_bar then return end
+    self.title_bar:setLeftIcon(self:contextUsesActions() and "appbar.menu" or "appbar.search")
+end
+
+function BookOrbitCatalog:onLeftButtonTap()
+    if self:detailMode() then
+        self:showDetailActions()
+    elseif self:contextUsesActions() then
+        self:showBookActions()
+    else
+        self:promptSearch({})
+    end
+    return true
+end
+
+function BookOrbitCatalog:loadBookDetail(book_id)
+    self:runConnected(function()
+        local detail, err = self:fetch(_("Loading book..."), function()
+            return self.client:catalogBook(book_id)
+        end)
+        if not detail then
+            if err ~= "cancelled" then
+                self:showRetry(err, function()
+                    self:loadBookDetail(book_id)
+                end)
+            end
+            return
+        end
+        self:showBookDetail(detail)
+    end)
+end
+
+function BookOrbitCatalog:supportedFiles(detail)
+    local files = {}
+    for _, file in ipairs(detail.files or {}) do
+        if isSupportedFormat(file.format) then
+            table.insert(files, file)
+        end
+    end
+    return files
+end
+
+function BookOrbitCatalog:fileLabel(file, show_support)
+    local label = string.upper(file.format or "file")
+    local extras = {}
+    local size = formatBytes(file.sizeBytes)
+    if size ~= "" then table.insert(extras, size) end
+    local duration = formatDuration(file.durationSeconds)
+    if duration then table.insert(extras, duration) end
+    if show_support and not isSupportedFormat(file.format) then
+        table.insert(extras, _("unsupported"))
+    end
+    if #extras > 0 then
+        label = label .. " - " .. table.concat(extras, ", ")
+    end
+    return label
+end
+
+function BookOrbitCatalog:fileMetadataValue(detail)
+    local files = detail.files or {}
+    if #files == 0 then return nil end
+
+    local labels = {}
+    for index, file in ipairs(files) do
+        if index > 3 then break end
+        table.insert(labels, self:fileLabel(file, true))
+    end
+    if #files > 3 then
+        table.insert(labels, "...")
+    end
+    return table.concat(labels, "; ")
+end
+
+function BookOrbitCatalog:cappedListText(items)
+    if not items or #items == 0 then return nil end
+    local shown = {}
+    for i = 1, math.min(#items, DETAIL_TAGS_INLINE) do
+        table.insert(shown, items[i])
+    end
+    local text = table.concat(shown, ", ")
+    if #items > DETAIL_TAGS_INLINE then
+        text = text .. T(_(" +%1 more"), #items - DETAIL_TAGS_INLINE)
+    end
+    return text
+end
+
+function BookOrbitCatalog:detailFactLines(detail)
+    local lines = {}
+    local function add(label, value)
+        value = cleanInlineText(value)
+        if value then
+            table.insert(lines, T(_("%1: %2"), label, value))
+        end
+    end
+
+    add(_("Series"), formatSeries(detail))
+    add(_("Year"), detail.publishedYear and tostring(detail.publishedYear) or nil)
+    add(_("Publisher"), detail.publisher)
+    add(_("Pages"), detail.pageCount and tostring(detail.pageCount) or nil)
+    add(_("Rating"), formatRating(detail.rating))
+    add(_("ISBN"), detail.isbn13 or detail.isbn10)
+    add(_("Progress"), formatProgress(detail.progressPercentage))
+    add(_("Status"), self:readStatusLabel(detail) or detail.readStatus)
+    add(_("Library"), detail.libraryName)
+    add(_("Genres"), self:cappedListText(detail.genres))
+    add(_("Tags"), self:cappedListText(detail.tags))
+    add(#(detail.files or {}) == 1 and _("File") or _("Files"), self:fileMetadataValue(detail))
+    return lines
+end
+
+function BookOrbitCatalog:detailOverviewLines(detail)
+    local lines = {}
+    local description = cleanDescriptionText(detail.description)
+    if description then
+        table.insert(lines, _("Description"))
+        table.insert(lines, shortText(description, 360))
+        if #description > 360 then
+            table.insert(lines, _("(tap the menu for the full description)"))
+        end
+    end
+
+    if #lines == 0 then
+        table.insert(lines, _("No description available."))
+    end
+    return lines
+end
+
+function BookOrbitCatalog:showFullText(title, text)
+    text = cleanDescriptionText(text) or _("Nothing to show.")
+    UIManager:show(TextViewer:new{
+        title = title,
+        text = text,
+    })
+end
+
+function BookOrbitCatalog:showFullList(title, items)
+    if not items or #items == 0 then
+        UIManager:show(InfoMessage:new{ text = _("None."), timeout = 2 })
+        return
+    end
+    UIManager:show(TextViewer:new{
+        title = title,
+        text = table.concat(items, "\n"),
+    })
+end
+
+function BookOrbitCatalog:showBookDetail(detail)
+    self:refreshOnDevice()
+    local supported_files = self:supportedFiles(detail)
+    self:switchTo(detail.title or _("Book details"), {
+        {
+            text = detail.title or _("Book details"),
+            kind = "detail",
+            detail = detail,
+        },
+    }, {
+        kind = "detail",
+        title = detail.title or _("Book details"),
+        subtitle = "",
+        detail = detail,
+        supported_files = supported_files,
+    }, true)
+end
+
+function BookOrbitCatalog:bookMode()
+    return self.current_context and self.current_context.kind == "books"
+end
+
+function BookOrbitCatalog:detailMode()
+    return self.current_context and self.current_context.kind == "detail"
+end
+
+function BookOrbitCatalog:_recalculateDimen(no_recalculate_dimen)
+    if self:bookMode() then
+        if self.view_mode == "list" then
+            return self:recalculateListDimen()
+        end
+        return self:recalculateMosaicDimen()
+    elseif self:detailMode() then
+        return self:recalculateDetailDimen()
+    end
+    return Menu_recalculateDimen(self, no_recalculate_dimen)
+end
+
+function BookOrbitCatalog:menuChromeHeight()
+    local top_height = 0
+    if self.title_bar and not self.no_title then
+        top_height = self.title_bar:getHeight()
+    end
+    local bottom_height = 0
+    if self.page_return_arrow and self.page_info_text then
+        bottom_height = math.max(self.page_return_arrow:getSize().h, self.page_info_text:getSize().h)
+            + Size.padding.button
+    end
+    return top_height, bottom_height
+end
+
+function BookOrbitCatalog:recalculateMosaicDimen()
+    self.perpage = self.grid_cols * self.grid_rows
+    self.page = self.current_context.page or 1
+    self.page_num = self.current_context.page_count or 1
+    local top_height, bottom_height = self:menuChromeHeight()
+    self.available_height = self.inner_dimen.h - top_height - bottom_height
+    self.item_margin = Screen:scaleBySize(10)
+    self.item_height = math.floor((self.available_height - (self.grid_rows + 1) * self.item_margin) / self.grid_rows)
+    self.item_width = math.floor((self.inner_dimen.w - (self.grid_cols + 1) * self.item_margin) / self.grid_cols)
+    self.item_dimen = Geom:new{
+        x = 0,
+        y = 0,
+        w = self.item_width,
+        h = self.item_height,
+    }
+end
+
+function BookOrbitCatalog:recalculateDetailDimen()
+    self.perpage = 1
+    self.page = 1
+    self.page_num = 1
+    local top_height, bottom_height = self:menuChromeHeight()
+    self.available_height = self.inner_dimen.h - top_height - bottom_height
+    self.item_dimen = Geom:new{
+        x = 0,
+        y = 0,
+        w = self.inner_dimen.w,
+        h = self.available_height,
+    }
+end
+
+function BookOrbitCatalog:updateItems(select_number, no_recalculate_dimen)
+    if self:bookMode() then
+        if self.view_mode == "list" then
+            return self:updateListItems(select_number, no_recalculate_dimen)
+        end
+        return self:updateMosaicItems(select_number, no_recalculate_dimen)
+    elseif self:detailMode() then
+        return self:updateDetailItems(select_number, no_recalculate_dimen)
+    end
+    return Menu_updateItems(self, select_number, no_recalculate_dimen)
+end
+
+function BookOrbitCatalog:prepareCustomUpdate(no_recalculate_dimen)
+    local old_dimen = self.dimen and self.dimen:copy()
+    self.layout = {}
+    self.item_group:clear()
+    self.page_info:resetLayout()
+    self.return_button:resetLayout()
+    self.content_group:resetLayout()
+    self:_recalculateDimen(no_recalculate_dimen)
+    return old_dimen
+end
+
+function BookOrbitCatalog:finishCustomUpdate(old_dimen, select_number)
+    self:updatePageInfo(select_number)
+    Menu.mergeTitleBarIntoLayout(self)
+    UIManager:setDirty(self.show_parent, function()
+        local refresh_dimen = old_dimen and old_dimen:combine(self.dimen) or self.dimen
+        return "ui", refresh_dimen
+    end)
+end
+
+function BookOrbitCatalog:updateMosaicItems(select_number, no_recalculate_dimen)
+    local old_dimen = self:prepareCustomUpdate(no_recalculate_dimen)
+    local items = self.item_table or {}
+    local selected_number = select_number
+
+    if #items == 0 then
+        table.insert(self.item_group, VerticalSpan:new{ width = math.floor(self.available_height * 0.38) })
+        table.insert(self.item_group, CenterContainer:new{
+            dimen = Geom:new{ w = self.inner_dimen.w, h = Screen:scaleBySize(80) },
+            TextBoxWidget:new{
+                text = self:emptyBooksText(),
+                width = self.inner_dimen.w - 2 * Size.padding.large,
+                alignment = "center",
+                face = Font:getFace("infofont"),
+            },
+        })
+        self:finishCustomUpdate(old_dimen, selected_number)
+        return
+    end
+
+    for row = 1, self.grid_rows do
+        local line_layout = {}
+        table.insert(self.item_group, VerticalSpan:new{ width = self.item_margin })
+        local row_group = HorizontalGroup:new{}
+        table.insert(row_group, HorizontalSpan:new{ width = self.item_margin })
+        for col = 1, self.grid_cols do
+            local slot = (row - 1) * self.grid_cols + col
+            local entry = items[slot]
+            if entry then
+                entry.idx = slot
+                local item = BookOrbitMosaicItem:new{
+                    entry = entry,
+                    text = entry.text,
+                    dimen = self.item_dimen:copy(),
+                    menu = self,
+                }
+                if entry.idx == self.itemnumber then
+                    selected_number = slot
+                end
+                table.insert(row_group, item)
+                table.insert(line_layout, item)
+            else
+                table.insert(row_group, CenterContainer:new{
+                    dimen = Geom:new{ w = self.item_width, h = self.item_height },
+                    HorizontalSpan:new{ width = 0 },
+                })
+            end
+            table.insert(row_group, HorizontalSpan:new{ width = self.item_margin })
+        end
+        table.insert(self.item_group, CenterContainer:new{
+            dimen = Geom:new{ w = self.inner_dimen.w, h = self.item_height },
+            row_group,
+        })
+        if #line_layout > 0 then
+            table.insert(self.layout, line_layout)
+        end
+    end
+    table.insert(self.item_group, VerticalSpan:new{ width = self.item_margin })
+    self:finishCustomUpdate(old_dimen, selected_number)
+end
+
+function BookOrbitCatalog:recalculateListDimen()
+    self.perpage = self.list_rows
+    self.page = self.current_context.page or 1
+    self.page_num = self.current_context.page_count or 1
+    local top_height, bottom_height = self:menuChromeHeight()
+    self.available_height = self.inner_dimen.h - top_height - bottom_height
+    self.item_margin = Screen:scaleBySize(4)
+    self.item_height = math.floor((self.available_height - (self.list_rows + 1) * self.item_margin) / self.list_rows)
+    self.item_width = self.inner_dimen.w - 2 * self.item_margin
+    self.item_dimen = Geom:new{
+        x = 0,
+        y = 0,
+        w = self.item_width,
+        h = self.item_height,
+    }
+end
+
+function BookOrbitCatalog:updateListItems(select_number, no_recalculate_dimen)
+    local old_dimen = self:prepareCustomUpdate(no_recalculate_dimen)
+    local items = self.item_table or {}
+    local selected_number = select_number
+
+    if #items == 0 then
+        table.insert(self.item_group, VerticalSpan:new{ width = math.floor(self.available_height * 0.38) })
+        table.insert(self.item_group, CenterContainer:new{
+            dimen = Geom:new{ w = self.inner_dimen.w, h = Screen:scaleBySize(80) },
+            TextBoxWidget:new{
+                text = self:emptyBooksText(),
+                width = self.inner_dimen.w - 2 * Size.padding.large,
+                alignment = "center",
+                face = Font:getFace("infofont"),
+            },
+        })
+        self:finishCustomUpdate(old_dimen, selected_number)
+        return
+    end
+
+    for idx = 1, self.list_rows do
+        local entry = items[idx]
+        table.insert(self.item_group, VerticalSpan:new{ width = self.item_margin })
+        if entry then
+            entry.idx = idx
+            local item = BookOrbitListItem:new{
+                entry = entry,
+                dimen = self.item_dimen:copy(),
+                menu = self,
+            }
+            if entry.idx == self.itemnumber then
+                selected_number = idx
+            end
+            table.insert(self.item_group, CenterContainer:new{
+                dimen = Geom:new{ w = self.inner_dimen.w, h = self.item_height },
+                item,
+            })
+            table.insert(self.layout, { item })
+        else
+            table.insert(self.item_group, CenterContainer:new{
+                dimen = Geom:new{ w = self.inner_dimen.w, h = self.item_height },
+                HorizontalSpan:new{ width = 0 },
+            })
+        end
+    end
+    table.insert(self.item_group, VerticalSpan:new{ width = self.item_margin })
+    self:finishCustomUpdate(old_dimen, selected_number)
+end
+
+function BookOrbitCatalog:detailCoverDimensions(header_h)
+    local max_cover_h = math.max(1, header_h - 2 * Size.padding.tiny)
+    local min_cover_h = math.min(Screen:scaleBySize(120), max_cover_h)
+    local cover_h = math.max(min_cover_h, math.min(max_cover_h, Screen:scaleBySize(340)))
+    local cover_w = math.floor(cover_h * 0.68)
+    local max_cover_w = math.floor(self.inner_dimen.w * 0.42)
+    if cover_w > max_cover_w then
+        cover_w = max_cover_w
+        cover_h = math.floor(cover_w / 0.68)
+    end
+    return cover_w, cover_h
+end
+
+function BookOrbitCatalog:buildDetailHeader(detail, width, height)
+    local supported_files = self.current_context.supported_files or {}
+    local cover_w, cover_h = self:detailCoverDimensions(height)
+    local frame_padding = Size.padding.default
+    local gap = Size.span.horizontal_default
+    local text_w = math.max(1, width - 2 * frame_padding - cover_w - gap)
+    local inner_h = math.max(1, height - 2 * frame_padding)
+    local row_gap = Size.span.vertical_large
+    local button_h = math.min(Screen:scaleBySize(44), math.max(Screen:scaleBySize(34), math.floor(inner_h * 0.16)))
+    local author_h = math.min(Screen:scaleBySize(56), math.max(Screen:scaleBySize(34), math.floor(inner_h * 0.20)))
+    local facts_h = math.min(Screen:scaleBySize(170),
+        math.max(Screen:scaleBySize(68), inner_h - author_h - button_h - 2 * row_gap))
+    local button_w = text_w
+    local path = self:cachedThumbnailPath(detail)
+    local state = self:thumbnailState(detail)
+
+    local read_path = self:detailReadPath(detail)
+    local undownloaded = 0
+    for _, file in ipairs(supported_files) do
+        if not self:onDeviceFilePath(file) then
+            undownloaded = undownloaded + 1
+        end
+    end
+    local show_read = read_path ~= nil
+    local show_download = (not show_read) or undownloaded > 0
+    local both = show_read and show_download
+    local half_w = math.floor((button_w - gap) / 2)
+
+    self.detail_read_button = nil
+    self.detail_download_button = nil
+    local buttons_row = HorizontalGroup:new{}
+
+    if show_read then
+        self.detail_read_button = Button:new{
+            text = _("Read"),
+            width = both and half_w or button_w,
+            height = button_h,
+            text_font_size = 16,
+            callback = function()
+                self:openDownloadedFile(read_path)
+            end,
+        }
+        table.insert(buttons_row, self.detail_read_button)
+    end
+    if both then
+        table.insert(buttons_row, HorizontalSpan:new{ width = gap })
+    end
+    if show_download then
+        self.detail_download_button = Button:new{
+            text = _("Download"),
+            width = both and (button_w - half_w - gap) or button_w,
+            height = button_h,
+            enabled = #supported_files > 0,
+            text_font_size = 16,
+            callback = function()
+                self:showFileChoices(detail)
+            end,
+        }
+        table.insert(buttons_row, self.detail_download_button)
+    end
+
+    local facts = self:detailFactLines(detail)
+    local author = joinNames(detail.authors) or _("Unknown author")
+
+    local right = VerticalGroup:new{ align = "left" }
+    table.insert(right, TextBoxWidget:new{
+        text = BD.auto(author),
+        width = text_w,
+        height = author_h,
+        face = Font:getFace("smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+    table.insert(right, VerticalSpan:new{ width = row_gap })
+    table.insert(right, TextBoxWidget:new{
+        text = table.concat(facts, "\n"),
+        width = text_w,
+        height = facts_h,
+        face = Font:getFace("x_smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+    table.insert(right, VerticalSpan:new{ width = row_gap })
+    table.insert(right, buttons_row)
+
+    return FrameContainer:new{
+        width = width,
+        height = height,
+        margin = 0,
+        padding = frame_padding,
+        bordersize = 0,
+        HorizontalGroup:new{
+            buildCoverWidget(detail, cover_w, cover_h, path, state),
+            HorizontalSpan:new{ width = gap },
+            right,
+        },
+    }
+end
+
+function BookOrbitCatalog:updateDetailItems(select_number, no_recalculate_dimen)
+    local old_dimen = self:prepareCustomUpdate(no_recalculate_dimen)
+    local detail = self.current_context.detail
+    local header_h = math.min(Screen:scaleBySize(360), math.floor(self.available_height * 0.48))
+    local info_h = math.max(Screen:scaleBySize(80), self.available_height - header_h - Size.span.vertical_large)
+
+    table.insert(self.item_group, self:buildDetailHeader(detail, self.inner_dimen.w, header_h))
+    table.insert(self.item_group, VerticalSpan:new{ width = Size.span.vertical_large })
+    table.insert(self.item_group, FrameContainer:new{
+        width = self.inner_dimen.w,
+        height = info_h,
+        margin = 0,
+        padding = Size.padding.large,
+        bordersize = 0,
+        TextBoxWidget:new{
+            text = table.concat(self:detailOverviewLines(detail), "\n"),
+            width = self.inner_dimen.w - 2 * Size.padding.large,
+            height = math.max(Screen:scaleBySize(40), info_h - 2 * Size.padding.large),
+            face = Font:getFace("x_smallinfofont"),
+            height_overflow_show_ellipsis = true,
+        },
+    })
+    local focus_row = {}
+    if self.detail_read_button then table.insert(focus_row, self.detail_read_button) end
+    if self.detail_download_button then table.insert(focus_row, self.detail_download_button) end
+    self.layout = { focus_row }
+    self:finishCustomUpdate(old_dimen, select_number)
+end
+
+function BookOrbitCatalog:onGotoPage(page)
+    if self:bookMode() then
+        local context = self.current_context
+        if page < 1 or page > (context.page_count or 1) or page == context.page then
+            return true
+        end
+        local params = cloneParams(context.params)
+        params.page = page
+        self:loadBooks(params, context.title, false)
+        return true
+    elseif self:detailMode() then
+        return true
+    end
+    return Menu_onGotoPage(self, page)
+end
+
+function BookOrbitCatalog:onNextPage()
+    if self:bookMode() then
+        local context = self.current_context
+        if context.page < context.page_count then
+            return self:onGotoPage(context.page + 1)
+        end
+        return true
+    elseif self:detailMode() then
+        return true
+    end
+    return Menu_onNextPage(self)
+end
+
+function BookOrbitCatalog:onPrevPage()
+    if self:bookMode() then
+        local context = self.current_context
+        if context.page > 1 then
+            return self:onGotoPage(context.page - 1)
+        end
+        return true
+    elseif self:detailMode() then
+        return true
+    end
+    return Menu_onPrevPage(self)
+end
+
+function BookOrbitCatalog:onFirstPage()
+    if self:bookMode() then
+        return self:onGotoPage(1)
+    elseif self:detailMode() then
+        return true
+    end
+    return Menu_onFirstPage(self)
+end
+
+function BookOrbitCatalog:onLastPage()
+    if self:bookMode() then
+        return self:onGotoPage(self.current_context.page_count or 1)
+    elseif self:detailMode() then
+        return true
+    end
+    return Menu_onLastPage(self)
+end
+
+function BookOrbitCatalog:onMenuSelect(item)
+    if item.kind == "section" then
+        self:loadSection(item.section)
+    elseif item.kind == "section-filter" then
+        self:promptSectionFilter(item.section, item.q)
+    elseif item.kind == "section-page" then
+        self:loadSection(item.section, { page = item.section_page, q = item.q, replace = true })
+    elseif item.kind == "on-device" then
+        self:loadOnDevice()
+    elseif item.kind == "books" then
+        self:loadBooks(item.params or {}, item.list_title or item.text)
+    elseif item.kind == "book" then
+        self:loadBookDetail(item.book_id)
+    elseif item.kind == "sort" then
+        self:showSortDialog(item)
+    end
+    return true
+end
+
+function BookOrbitCatalog:onReturn()
+    self:cancelThumbnailJobs()
+    local previous = table.remove(self.stack)
+    if previous then
+        self.current_context = previous.context
+        self:updateReturnPath()
+        self:switchItemTable(previous.title, previous.item_table, nil, nil, previous.subtitle or "")
+        if self.current_context.kind == "books" then
+            self:scheduleThumbnailDownloads(self.current_context.books or {})
+        elseif self.current_context.kind == "detail" then
+            self:scheduleThumbnailDownloads({ self.current_context.detail })
+        end
+    else
+        self.item_table = self:rootItems()
+        self.current_context = { kind = "root", title = self.title }
+        self:updateReturnPath()
+        self:switchItemTable(self.title, self.item_table, nil, nil, "")
+    end
+    self:updateLeftIcon()
+    return true
+end
+
+function BookOrbitCatalog:onHoldReturn()
+    self:cancelThumbnailJobs()
+    self.stack = {}
+    self:updateReturnPath()
+    self.item_table = self:rootItems()
+    self.current_context = { kind = "root", title = self.title }
+    self:switchItemTable(self.title, self.item_table, nil, nil, "")
+    self:updateLeftIcon()
+    return true
+end
+
+function BookOrbitCatalog:onCloseWidget()
+    self:cancelThumbnailJobs()
+    return Menu.onCloseWidget(self)
+end
+
+return BookOrbitCatalog
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_download.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_download.lua
new file mode 100644
index 000000000..ff3ef4cd9
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_download.lua
@@ -0,0 +1,289 @@
+--[[--
+Download manager mixin for the BookOrbit catalog browser.
+
+Installs the file-choice, download, link-to-sync and open-file methods onto the
+catalog controller. Downloads stay foreground with live byte/percent progress
+(a deliberate user action), unlike navigation which runs off the UI thread.
+]]
+
+local BD = require("ui/bidi")
+local ButtonDialog = require("ui/widget/buttondialog")
+local ConfirmBox = require("ui/widget/confirmbox")
+local InfoMessage = require("ui/widget/infomessage")
+local InputDialog = require("ui/widget/inputdialog")
+local Notification = require("ui/widget/notification")
+local UIManager = require("ui/uimanager")
+local lfs = require("libs/libkoreader-lfs")
+local logger = require("logger")
+local util = require("util")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local BookOrbitState = require("bookorbit_state")
+local CatalogUtil = require("bookorbit_catalog_util")
+
+local formatBytes = CatalogUtil.formatBytes
+local safeFilenameBase = CatalogUtil.safeFilenameBase
+
+local CatalogDownload = {}
+
+function CatalogDownload.install(Catalog)
+    function Catalog:showFileChoices(detail)
+        local files = self:supportedFiles(detail)
+
+        if #files == 0 then
+            UIManager:show(InfoMessage:new{ text = _("No KOReader-supported file found."), timeout = 3 })
+            return
+        end
+        if #files == 1 then
+            local path = self:onDeviceFilePath(files[1])
+            if path then
+                self:openDownloadedFile(path)
+            else
+                self:showDownloadDialog(detail, files[1])
+            end
+            return
+        end
+
+        local dialog
+        local buttons = {}
+        local open_tpl = _("Open - %1")
+        local download_tpl = _("Download - %1")
+        for _, file in ipairs(files) do
+            local path = self:onDeviceFilePath(file)
+            local label = self:fileLabel(file, false)
+            table.insert(buttons, {
+                {
+                    text = path and T(open_tpl, label) or T(download_tpl, label),
+                    callback = function()
+                        UIManager:close(dialog)
+                        if path then
+                            self:openDownloadedFile(path)
+                        else
+                            self:showDownloadDialog(detail, file)
+                        end
+                    end,
+                },
+            })
+        end
+        dialog = ButtonDialog:new{
+            title = _("Choose file"),
+            buttons = buttons,
+        }
+        UIManager:show(dialog)
+    end
+
+    function Catalog:getCurrentDownloadDir()
+        return G_reader_settings:readSetting("download_dir") or G_reader_settings:readSetting("lastdir")
+    end
+
+    function Catalog:getLocalDownloadPath(filename, filetype)
+        local download_dir = self:getCurrentDownloadDir()
+        filename = filename .. "." .. string.lower(filetype or "bin")
+        filename = util.getSafeFilename(filename, download_dir)
+        return (download_dir ~= "/" and download_dir or "") .. "/" .. filename
+    end
+
+    function Catalog:showDownloadDialog(detail, file)
+        local filename = safeFilenameBase(detail)
+        local filetype = string.lower(file.format or "bin")
+
+        local function createTitle(path, name)
+            return T(_("Download folder:\n%1\n\nDownload filename:\n%2\n\nDownload file type:\n%3"),
+                BD.dirpath(path), name, string.upper(filetype))
+        end
+
+        local dialog
+        dialog = ButtonDialog:new{
+            title = createTitle(self:getCurrentDownloadDir(), filename),
+            buttons = {
+                {
+                    {
+                        text = _("Download"),
+                        callback = function()
+                            UIManager:close(dialog)
+                            local local_path = self:getLocalDownloadPath(filename, filetype)
+                            self:checkDownloadFile(local_path, detail, file)
+                        end,
+                    },
+                },
+                {},
+                {
+                    {
+                        text = _("Choose folder"),
+                        callback = function()
+                            UIManager:close(dialog)
+                            require("ui/downloadmgr"):new{
+                                onConfirm = function(path)
+                                    logger.dbg("BookOrbit: download folder set to", path)
+                                    if self._manager and self._manager.ui and self._manager.ui.folder_shortcuts then
+                                        self._manager.ui.folder_shortcuts:updateShortcut("download_dir", path)
+                                    end
+                                    G_reader_settings:saveSetting("download_dir", path)
+                                    UIManager:nextTick(function()
+                                        self:showDownloadDialog(detail, file)
+                                    end)
+                                end,
+                            }:chooseDir(self:getCurrentDownloadDir())
+                        end,
+                    },
+                    {
+                        text = _("Change filename"),
+                        callback = function()
+                            local input_dialog
+                            input_dialog = InputDialog:new{
+                                title = _("Enter filename"),
+                                input = filename,
+                                buttons = {
+                                    {
+                                        {
+                                            text = _("Cancel"),
+                                            id = "close",
+                                            callback = function()
+                                                UIManager:close(input_dialog)
+                                            end,
+                                        },
+                                        {
+                                            text = _("Set filename"),
+                                            is_enter_default = true,
+                                            callback = function()
+                                                local value = util.trim(input_dialog:getInputText() or "")
+                                                if value ~= "" then filename = value end
+                                                UIManager:close(input_dialog)
+                                                dialog:setTitle(createTitle(self:getCurrentDownloadDir(), filename))
+                                            end,
+                                        },
+                                    },
+                                },
+                            }
+                            UIManager:show(input_dialog)
+                            input_dialog:onShowKeyboard()
+                        end,
+                    },
+                },
+            },
+        }
+        UIManager:show(dialog)
+    end
+
+    function Catalog:checkDownloadFile(local_path, detail, file)
+        local function download()
+            UIManager:nextTick(function()
+                self:downloadFile(local_path, detail, file)
+            end)
+        end
+
+        if lfs.attributes(local_path) then
+            UIManager:show(ConfirmBox:new{
+                text = T(_("The file %1 already exists. Do you want to overwrite it?"), BD.filepath(local_path)),
+                ok_text = _("Overwrite"),
+                ok_callback = download,
+            })
+        else
+            download()
+        end
+    end
+
+    function Catalog:downloadFile(local_path, detail, file)
+        local total = file.sizeBytes
+        local info = InfoMessage:new{ text = _("Downloading...") }
+        UIManager:show(info)
+        UIManager:forceRePaint()
+
+        local last_bucket = -1
+        local function on_progress(received)
+            local text, bucket
+            if total and total > 0 then
+                local pct = math.min(100, math.floor(received / total * 100))
+                bucket = math.floor(pct / 5)
+                if bucket == last_bucket then return end
+                text = T(_("Downloading... %1"), pct .. "%")
+            else
+                bucket = math.floor(received / (256 * 1024))
+                if bucket == last_bucket then return end
+                text = T(_("Downloading... %1"), formatBytes(received))
+            end
+            last_bucket = bucket
+            UIManager:close(info)
+            info = InfoMessage:new{ text = text }
+            UIManager:show(info)
+            UIManager:forceRePaint()
+        end
+
+        local ok, err = self.client:downloadCatalogFile(file.id, local_path, on_progress)
+        UIManager:close(info)
+        if not ok then
+            self:showRetry(err, function()
+                self:downloadFile(local_path, detail, file)
+            end)
+            return
+        end
+
+        local linked = self:linkDownloadedFile(local_path)
+        if linked then
+            self:refreshOnDevice()
+        end
+        self:showDownloadedDialog(local_path, linked)
+    end
+
+    function Catalog:linkDownloadedFile(local_path)
+        local ok, digest = pcall(util.partialMD5, local_path)
+        if not ok or not digest then
+            logger.warn("BookOrbit: downloaded file partial MD5 failed", local_path)
+            return false
+        end
+
+        local body, err = self.client:matchCheck({ digest })
+        if not body then
+            logger.warn("BookOrbit: downloaded file match-check failed", err)
+            return false
+        end
+
+        local state = BookOrbitState.open()
+        state:rememberFile(local_path, digest)
+        for _, match in ipairs(body.matches or {}) do
+            if match.hash == digest then
+                state:setMatched(digest, match.bookFileId, match.bookId, local_path)
+                state:flush()
+                return true
+            end
+        end
+        state:setUnmatched(digest)
+        state:flush()
+        return false
+    end
+
+    function Catalog:showDownloadedDialog(local_path, linked)
+        local message = linked and _("File saved and linked to BookOrbit sync:\n%1\n\nOpen now?")
+            or _("File saved:\n%1\n\nOpen now?")
+        UIManager:nextTick(function()
+            UIManager:show(ConfirmBox:new{
+                text = T(message, BD.filepath(local_path)),
+                ok_text = _("Open now"),
+                cancel_text = _("Close"),
+                ok_callback = function()
+                    self:openDownloadedFile(local_path)
+                end,
+            })
+        end)
+    end
+
+    function Catalog:openDownloadedFile(local_path)
+        if self.close_callback then
+            self.close_callback()
+        else
+            UIManager:close(self)
+        end
+        if self._manager and self._manager.ui then
+            if self._manager.ui.document then
+                self._manager.ui:switchDocument(local_path)
+            else
+                self._manager.ui:openFile(local_path)
+            end
+        else
+            Notification:notify(T(_("Downloaded to %1"), local_path))
+        end
+    end
+end
+
+return CatalogDownload
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_util.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_util.lua
new file mode 100644
index 000000000..5a3ee40c9
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_util.lua
@@ -0,0 +1,278 @@
+--[[--
+Pure helpers and constants for the BookOrbit catalog browser.
+
+No widget construction and no dependency on the catalog instance; everything
+here is stateless text/data formatting plus the shared lookup tables. Kept in
+its own module so the catalog controller and its widgets can share it without
+duplicating logic.
+]]
+
+local DocumentRegistry = require("document/documentregistry")
+local util = require("util")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local CatalogUtil = {}
+
+CatalogUtil.DEFAULT_GRID_COLUMNS = 3
+CatalogUtil.DEFAULT_GRID_ROWS = 3
+CatalogUtil.THUMBNAIL_BATCH_SIZE = 2
+CatalogUtil.MAX_RECENT_SEARCHES = 8
+CatalogUtil.ON_DEVICE_MAX_IDS = 200
+
+CatalogUtil.SORTS = {
+    { id = "title", text = _("Title") },
+    { id = "author", text = _("Author") },
+    { id = "recently_added", text = _("Recently added") },
+    { id = "recently_updated", text = _("Recently updated") },
+    { id = "recently_read", text = _("Recently read") },
+    { id = "series", text = _("Series order") },
+}
+
+CatalogUtil.SORT_LABELS = {
+    title = _("Title"),
+    author = _("Author"),
+    recently_added = _("Recently added"),
+    recently_updated = _("Recently updated"),
+    recently_read = _("Recently read"),
+    series = _("Series order"),
+}
+
+CatalogUtil.NATURAL_ORDER = {
+    title = "asc",
+    author = "asc",
+    series = "asc",
+    recently_added = "desc",
+    recently_updated = "desc",
+    recently_read = "desc",
+}
+
+CatalogUtil.SORT_KIND = {
+    title = "alpha",
+    author = "alpha",
+    series = "alpha",
+    recently_added = "time",
+    recently_updated = "time",
+    recently_read = "time",
+}
+
+CatalogUtil.DIRECTION_LABELS = {
+    alpha = { asc = _("A-Z"), desc = _("Z-A") },
+    time = { asc = _("oldest first"), desc = _("newest first") },
+}
+
+CatalogUtil.READ_STATUS_FILTERS = {
+    { id = nil, text = _("All") },
+    { id = "unread", text = _("Unread") },
+    { id = "reading", text = _("Reading") },
+    { id = "finished", text = _("Finished") },
+}
+
+CatalogUtil.READ_STATUS_LABELS = {
+    unread = _("Unread"),
+    want_to_read = _("To read"),
+    reading = _("Reading"),
+    on_hold = _("On hold"),
+    rereading = _("Rereading"),
+    read = _("Read"),
+    skimmed = _("Skimmed"),
+    abandoned = _("Abandoned"),
+}
+
+-- Read statuses the user can set from the catalog detail page. Kept in sync
+-- with the server's manual read-status enum.
+CatalogUtil.SETTABLE_READ_STATUSES = {
+    { id = "want_to_read", text = _("To read") },
+    { id = "reading", text = _("Reading") },
+    { id = "on_hold", text = _("On hold") },
+    { id = "read", text = _("Read") },
+    { id = "abandoned", text = _("Abandoned") },
+}
+
+CatalogUtil.COMMON_FORMATS = { "epub", "pdf", "cbz", "cbr", "mobi", "azw3", "fb2", "djvu", "txt" }
+
+CatalogUtil.GRID_PRESETS = {
+    { 2, 2 }, { 2, 3 }, { 3, 3 }, { 3, 4 }, { 4, 4 }, { 4, 5 },
+}
+
+function CatalogUtil.isAuthError(err)
+    return err == 401 or err == 403
+end
+
+function CatalogUtil.cloneParams(params)
+    local copy = {}
+    for key, value in pairs(params or {}) do
+        copy[key] = value
+    end
+    return copy
+end
+
+function CatalogUtil.formatBytes(bytes)
+    if not bytes then return "" end
+    if bytes >= 1024 * 1024 then
+        return string.format("%.1f MB", bytes / 1024 / 1024)
+    elseif bytes >= 1024 then
+        return string.format("%.0f KB", bytes / 1024)
+    end
+    return tostring(bytes) .. " B"
+end
+
+function CatalogUtil.formatDuration(seconds)
+    if not seconds then return nil end
+    local minutes = math.floor(seconds / 60 + 0.5)
+    if minutes < 60 then
+        return T(_("%1 min"), minutes)
+    end
+    local hours = math.floor(minutes / 60)
+    local remaining = minutes - hours * 60
+    if remaining == 0 then
+        return T(_("%1 h"), hours)
+    end
+    return T(_("%1 h %2 min"), hours, remaining)
+end
+
+function CatalogUtil.formatProgress(value)
+    if not value then return nil end
+    return tostring(math.floor(value + 0.5)) .. "%"
+end
+
+function CatalogUtil.formatRating(value)
+    if not value then return nil end
+    if value == math.floor(value) then
+        return tostring(value) .. "/5"
+    end
+    return string.format("%.1f/5", value)
+end
+
+function CatalogUtil.isSupportedFormat(format)
+    return format and DocumentRegistry:hasProvider("dummy." .. string.lower(format))
+end
+
+function CatalogUtil.shortText(text, max_len)
+    text = tostring(text or "")
+    if #text <= max_len then return text end
+    return util.fixUtf8(text:sub(1, max_len - 3), "?") .. "..."
+end
+
+function CatalogUtil.joinNames(items, key)
+    local names = {}
+    for _, item in ipairs(items or {}) do
+        table.insert(names, key and item[key] or item)
+    end
+    return #names > 0 and table.concat(names, ", ") or nil
+end
+
+local HTML_ENTITIES = {
+    amp = "&",
+    apos = "'",
+    bull = "*",
+    eacute = "e",
+    hellip = "...",
+    ldquo = "\"",
+    lsquo = "'",
+    lt = "<",
+    mdash = " - ",
+    nbsp = " ",
+    ndash = " - ",
+    quot = "\"",
+    rdquo = "\"",
+    gt = ">",
+    rsquo = "'",
+}
+
+local NUMERIC_ENTITIES = {
+    [160] = " ",
+    [8211] = " - ",
+    [8212] = " - ",
+    [8216] = "'",
+    [8217] = "'",
+    [8220] = "\"",
+    [8221] = "\"",
+    [8226] = "*",
+    [8230] = "...",
+}
+
+local function decodeHtmlEntity(entity)
+    local named = HTML_ENTITIES[entity:lower()]
+    if named then return named end
+
+    local code = entity:match("^#(%d+)$")
+    if code then
+        code = tonumber(code)
+    else
+        local hex_code = entity:match("^#x(%x+)$") or entity:match("^#X(%x+)$")
+        code = hex_code and tonumber(hex_code, 16) or nil
+    end
+    if not code then return "&" .. entity .. ";" end
+
+    local replacement = NUMERIC_ENTITIES[code]
+    if replacement then return replacement end
+    if code >= 32 and code <= 126 then
+        return string.char(code)
+    end
+    return ""
+end
+
+function CatalogUtil.decodeHtmlEntities(text)
+    return text:gsub("&(#?[xX]?%w+);", decodeHtmlEntity)
+end
+
+function CatalogUtil.cleanInlineText(text)
+    text = tostring(text or "")
+    text = text:gsub("%s+", " "):gsub("^%s+", ""):gsub("%s+$", "")
+    return text ~= "" and text or nil
+end
+
+function CatalogUtil.cleanDescriptionText(text)
+    text = tostring(text or "")
+    text = CatalogUtil.decodeHtmlEntities(text)
+    text = text:gsub("\r\n", "\n"):gsub("\r", "\n")
+    text = text:gsub("<%s*[Bb][Rr]%s*/?%s*>", "\n")
+    text = text:gsub("<%s*/%s*[Pp]%s*>", "\n\n")
+    text = text:gsub("<%s*[Pp][^>]*>", "")
+    text = text:gsub("<%s*/%s*[Dd][Ii][Vv]%s*>", "\n\n")
+    text = text:gsub("<%s*[Dd][Ii][Vv][^>]*>", "")
+    text = text:gsub("<%s*/%s*[Ll][Ii]%s*>", "\n")
+    text = text:gsub("<%s*[Ll][Ii][^>]*>", "* ")
+    text = text:gsub("<[^>]+>", "")
+    text = CatalogUtil.decodeHtmlEntities(text)
+    text = text:gsub("[ \t]+", " ")
+    text = text:gsub(" *\n *", "\n")
+    text = text:gsub("\n\n\n+", "\n\n")
+    text = text:gsub("^%s+", ""):gsub("%s+$", "")
+    return text ~= "" and text or nil
+end
+
+function CatalogUtil.formatSeries(book)
+    if not book.seriesName then return nil end
+    if book.seriesIndex then
+        return book.seriesName .. " #" .. tostring(book.seriesIndex)
+    end
+    return book.seriesName
+end
+
+function CatalogUtil.firstAuthor(book)
+    return book.authors and book.authors[1] or nil
+end
+
+function CatalogUtil.safeFilenameBase(detail)
+    local title = detail.title or ("book-" .. tostring(detail.id))
+    local author = CatalogUtil.firstAuthor(detail)
+    local base = author and (title .. " - " .. author) or title
+    base = base:gsub("[\"\\/:*?<>|]+", " "):gsub("%s+", " "):gsub("^%s+", ""):gsub("%s+$", "")
+    if base == "" then base = "book-" .. tostring(detail.id) end
+    return base
+end
+
+function CatalogUtil.coverLabel(book)
+    local lines = {}
+    local title = book and book.title or _("Untitled")
+    table.insert(lines, CatalogUtil.shortText(title, 34))
+    local author = book and CatalogUtil.firstAuthor(book)
+    if author then
+        table.insert(lines, CatalogUtil.shortText(author, 28))
+    end
+    return table.concat(lines, "\n")
+end
+
+return CatalogUtil
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_widgets.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_widgets.lua
new file mode 100644
index 000000000..6de64f50f
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_catalog_widgets.lua
@@ -0,0 +1,280 @@
+--[[--
+Cover and book-item widgets for the BookOrbit catalog browser.
+
+`buildCoverWidget`/`buildFakeCover` render a real cover image or a text
+placeholder. `MosaicItem`/`ListItem` are the tappable cells the catalog Menu
+lays out; they read cached thumbnails and labels back from the owning menu.
+]]
+
+local BD = require("ui/bidi")
+local Blitbuffer = require("ffi/blitbuffer")
+local CenterContainer = require("ui/widget/container/centercontainer")
+local Device = require("device")
+local Font = require("ui/font")
+local FrameContainer = require("ui/widget/container/framecontainer")
+local Geom = require("ui/geometry")
+local GestureRange = require("ui/gesturerange")
+local HorizontalGroup = require("ui/widget/horizontalgroup")
+local HorizontalSpan = require("ui/widget/horizontalspan")
+local ImageWidget = require("ui/widget/imagewidget")
+local InputContainer = require("ui/widget/container/inputcontainer")
+local ProgressWidget = require("ui/widget/progresswidget")
+local Size = require("ui/size")
+local TextBoxWidget = require("ui/widget/textboxwidget")
+local VerticalGroup = require("ui/widget/verticalgroup")
+local VerticalSpan = require("ui/widget/verticalspan")
+local _ = require("gettext")
+
+local CatalogUtil = require("bookorbit_catalog_util")
+
+local Screen = Device.screen
+local shortText = CatalogUtil.shortText
+local firstAuthor = CatalogUtil.firstAuthor
+
+local PROGRESS_BAR_HEIGHT = Screen:scaleBySize(5)
+
+local CatalogWidgets = {}
+
+local function hasProgress(book)
+    return book and book.progressPercentage and book.progressPercentage > 0
+end
+
+-- A slim solid progress bar, e-ink friendly (no animation), used to visualize
+-- reading progress on cards and rows.
+function CatalogWidgets.buildProgressBar(percentage, width)
+    if not percentage or percentage <= 0 then return nil end
+    local bar = ProgressWidget:new{
+        width = width,
+        height = PROGRESS_BAR_HEIGHT,
+        percentage = math.min(1, percentage / 100),
+        margin_h = 0,
+        margin_v = 0,
+        bordersize = Size.border.thin,
+        bgcolor = Blitbuffer.COLOR_WHITE,
+        fillcolor = Blitbuffer.COLOR_BLACK,
+    }
+    return bar
+end
+
+function CatalogWidgets.buildFakeCover(book, width, height, footer)
+    local inner_w = math.max(1, width - 2 * Size.padding.default - 2 * Size.border.thin)
+    local inner_h = math.max(1, height - 2 * Size.padding.default - 2 * Size.border.thin)
+    local title_h = math.floor(inner_h * 0.58)
+    local author_h = math.floor(inner_h * 0.22)
+    local footer_h = math.max(1, inner_h - title_h - author_h)
+    local author = book and firstAuthor(book) or nil
+
+    local content = VerticalGroup:new{ align = "center" }
+    table.insert(content, VerticalSpan:new{ width = Size.span.vertical_default })
+    table.insert(content, TextBoxWidget:new{
+        text = BD.auto(shortText(book and book.title or _("Untitled"), 60)),
+        width = inner_w,
+        height = title_h,
+        alignment = "center",
+        face = Font:getFace("smallinfofont", 16),
+        height_overflow_show_ellipsis = true,
+    })
+    table.insert(content, TextBoxWidget:new{
+        text = author and BD.auto(shortText(author, 44)) or "",
+        width = inner_w,
+        height = author_h,
+        alignment = "center",
+        face = Font:getFace("x_smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+    table.insert(content, TextBoxWidget:new{
+        text = footer or "",
+        width = inner_w,
+        height = footer_h,
+        alignment = "center",
+        face = Font:getFace("xx_smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+
+    return FrameContainer:new{
+        width = width,
+        height = height,
+        margin = 0,
+        padding = Size.padding.default,
+        bordersize = Size.border.thin,
+        background = Blitbuffer.COLOR_WHITE,
+        CenterContainer:new{
+            dimen = Geom:new{ w = inner_w, h = inner_h },
+            content,
+        },
+    }
+end
+
+function CatalogWidgets.buildCoverWidget(book, width, height, path, state)
+    if path then
+        return CenterContainer:new{
+            dimen = Geom:new{ w = width, h = height },
+            FrameContainer:new{
+                margin = 0,
+                padding = 0,
+                bordersize = Size.border.thin,
+                ImageWidget:new{
+                    file = path,
+                    width = width,
+                    height = height,
+                    scale_factor = 0,
+                },
+            },
+        }
+    end
+
+    local footer
+    if state == "loading" then
+        footer = _("Loading cover")
+    elseif state == "failed" then
+        footer = _("Cover unavailable")
+    else
+        footer = _("No cover")
+    end
+    return CatalogWidgets.buildFakeCover(book, width, height, footer)
+end
+
+local MosaicItem = InputContainer:extend{
+    entry = nil,
+    dimen = nil,
+    menu = nil,
+    text = nil,
+}
+
+function MosaicItem:init()
+    self.ges_events = {
+        TapSelect = {
+            GestureRange:new{
+                ges = "tap",
+                range = self.dimen,
+            },
+        },
+        HoldSelect = {
+            GestureRange:new{
+                ges = "hold",
+                range = self.dimen,
+            },
+        },
+    }
+
+    local book = self.entry.book
+    local bar_reserve = hasProgress(book) and (PROGRESS_BAR_HEIGHT + Size.span.vertical_default) or 0
+    local label_h = math.max(Screen:scaleBySize(44), math.floor(self.dimen.h * 0.24))
+    local cover_h = math.max(Screen:scaleBySize(60), self.dimen.h - label_h - Size.span.vertical_default - bar_reserve)
+    local cover_w = math.min(self.dimen.w - 2 * Size.padding.default, math.floor(cover_h * 0.68))
+    cover_h = math.min(cover_h, self.dimen.h - label_h - Size.span.vertical_default - bar_reserve)
+
+    local path = self.menu:cachedThumbnailPath(book)
+    local state = self.menu:thumbnailState(book)
+    local content = VerticalGroup:new{ align = "center" }
+    table.insert(content, CatalogWidgets.buildCoverWidget(book, cover_w, cover_h, path, state))
+    local bar = CatalogWidgets.buildProgressBar(book and book.progressPercentage, cover_w)
+    if bar then
+        table.insert(content, VerticalSpan:new{ width = Size.span.vertical_default })
+        table.insert(content, bar)
+    end
+    table.insert(content, VerticalSpan:new{ width = Size.span.vertical_default })
+    table.insert(content, TextBoxWidget:new{
+        text = self.menu:cellLabel(book),
+        width = self.dimen.w - 2 * Size.padding.tiny,
+        height = label_h,
+        alignment = "center",
+        face = Font:getFace("x_smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+
+    self[1] = CenterContainer:new{
+        dimen = Geom:new{ w = self.dimen.w, h = self.dimen.h },
+        content,
+    }
+end
+
+function MosaicItem:onTapSelect()
+    self.menu:onMenuSelect(self.entry)
+    return true
+end
+
+function MosaicItem:onHoldSelect()
+    self.menu:onMenuSelect(self.entry)
+    return true
+end
+
+local ListItem = InputContainer:extend{
+    entry = nil,
+    dimen = nil,
+    menu = nil,
+}
+
+function ListItem:init()
+    self.ges_events = {
+        TapSelect = {
+            GestureRange:new{
+                ges = "tap",
+                range = self.dimen,
+            },
+        },
+        HoldSelect = {
+            GestureRange:new{
+                ges = "hold",
+                range = self.dimen,
+            },
+        },
+    }
+
+    local book = self.entry.book
+    local pad = Size.padding.default
+    local inner_h = math.max(1, self.dimen.h - 2 * Size.border.thin)
+    local cover_h = math.max(Screen:scaleBySize(40), inner_h - 2 * Size.padding.small)
+    local cover_w = math.floor(cover_h * 0.68)
+    local text_w = math.max(1, self.dimen.w - cover_w - 3 * pad)
+    local bar_reserve = hasProgress(book) and (PROGRESS_BAR_HEIGHT + Size.span.vertical_default) or 0
+
+    local path = self.menu:cachedThumbnailPath(book)
+    local state = self.menu:thumbnailState(book)
+
+    local text_col = VerticalGroup:new{ align = "left" }
+    table.insert(text_col, TextBoxWidget:new{
+        text = self.menu:listText(book),
+        width = text_w,
+        height = math.max(1, inner_h - 2 * Size.padding.small - bar_reserve),
+        alignment = "left",
+        face = Font:getFace("smallinfofont"),
+        height_overflow_show_ellipsis = true,
+    })
+    local bar = CatalogWidgets.buildProgressBar(book and book.progressPercentage, text_w)
+    if bar then
+        table.insert(text_col, VerticalSpan:new{ width = Size.span.vertical_default })
+        table.insert(text_col, bar)
+    end
+
+    local row = HorizontalGroup:new{ align = "center" }
+    table.insert(row, HorizontalSpan:new{ width = pad })
+    table.insert(row, CatalogWidgets.buildCoverWidget(book, cover_w, cover_h, path, state))
+    table.insert(row, HorizontalSpan:new{ width = pad })
+    table.insert(row, text_col)
+
+    self[1] = FrameContainer:new{
+        width = self.dimen.w,
+        height = self.dimen.h,
+        margin = 0,
+        padding = 0,
+        bordersize = Size.border.thin,
+        background = Blitbuffer.COLOR_WHITE,
+        row,
+    }
+end
+
+function ListItem:onTapSelect()
+    self.menu:onMenuSelect(self.entry)
+    return true
+end
+
+function ListItem:onHoldSelect()
+    self.menu:onMenuSelect(self.entry)
+    return true
+end
+
+CatalogWidgets.MosaicItem = MosaicItem
+CatalogWidgets.ListItem = ListItem
+
+return CatalogWidgets
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_menu_pin.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_menu_pin.lua
new file mode 100644
index 000000000..b4263ee23
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_menu_pin.lua
@@ -0,0 +1,160 @@
+--[[--
+Pins the BookOrbit menu entry onto the first page of the Tools menu, right
+below calibre, by maintaining user menu-order override files.
+
+KOReader merges <settings_dir>/<prefix>_menu_order.lua over the bundled order
+tables per top-level key, so the generated files must carry the complete tools
+list. Files created here start with a marker comment and are regenerated from
+the bundled order on every startup, so KOReader updates never drift. A
+hand-maintained file only ever gets old BookOrbit ids replaced by the current
+one.
+]]
+
+local DataStorage = require("datastorage")
+local dump = require("dump")
+local lfs = require("libs/libkoreader-lfs")
+local logger = require("logger")
+local util = require("util")
+
+local MARKER = "-- bookorbit-menu-pin v2 (generated; delete this file to reset menu order)"
+local OLD_MARKERS = {
+    "-- bookorbit-sync-pin v1 (generated; delete this file to reset menu order)",
+}
+local MENU_ID = "bookorbit"
+local OLD_MENU_IDS = {
+    "bookorbit_browse",
+    "bookorbit_sync",
+}
+
+local PREFIXES = {
+    { prefix = "reader", order_module = "ui/elements/reader_menu_order" },
+    { prefix = "filemanager", order_module = "ui/elements/filemanager_menu_order" },
+}
+
+local BookOrbitMenuPin = {
+    done = false,
+}
+
+local function removeId(tools, menu_id)
+    local removed = false
+    for i = #tools, 1, -1 do
+        if tools[i] == menu_id then
+            table.remove(tools, i)
+            removed = true
+        end
+    end
+    return removed
+end
+
+local function removeOldIds(tools)
+    local removed = false
+    for _, menu_id in ipairs(OLD_MENU_IDS) do
+        removed = removeId(tools, menu_id) or removed
+    end
+    return removed
+end
+
+local function normalizeBookOrbitIds(tools)
+    removeOldIds(tools)
+    removeId(tools, MENU_ID)
+
+    local insert_at = #tools
+    for i, id in ipairs(tools) do
+        if id == "calibre" then
+            insert_at = i
+            break
+        end
+    end
+
+    table.insert(tools, insert_at + 1, MENU_ID)
+end
+
+local function desiredTools(order_module)
+    local bundled = require(order_module)
+    if type(bundled) ~= "table" or type(bundled.tools) ~= "table" then
+        return nil
+    end
+    local tools = {}
+    for _, id in ipairs(bundled.tools) do
+        table.insert(tools, id)
+    end
+    normalizeBookOrbitIds(tools)
+    return tools
+end
+
+local function serializeOurs(tools)
+    return MARKER .. "\nreturn " .. dump({ tools = tools }, nil, true) .. "\n"
+end
+
+local function isGeneratedByUs(existing)
+    if existing:sub(1, #MARKER) == MARKER then
+        return true
+    end
+    for _, marker in ipairs(OLD_MARKERS) do
+        if existing:sub(1, #marker) == marker then
+            return true
+        end
+    end
+    return false
+end
+
+local function ensureOne(prefix, order_module)
+    local tools = desiredTools(order_module)
+    if not tools then return end
+
+    local path = DataStorage:getSettingsDir() .. "/" .. prefix .. "_menu_order.lua"
+
+    if not lfs.attributes(path) then
+        local ok, err = util.writeToFile(serializeOurs(tools), path, true)
+        if not ok then
+            logger.warn("BookOrbit: cannot write menu order file", path, err)
+        end
+        return
+    end
+
+    local existing = util.readFromFile(path, "r")
+    if not existing then
+        logger.warn("BookOrbit: cannot read menu order file, leaving it alone:", path)
+        return
+    end
+
+    if isGeneratedByUs(existing) then
+        local content = serializeOurs(tools)
+        if content ~= existing then
+            local ok, err = util.writeToFile(content, path, true)
+            if not ok then
+                logger.warn("BookOrbit: cannot update menu order file", path, err)
+            end
+        end
+        return
+    end
+
+    -- Hand-maintained file: replace stale BookOrbit ids without touching other entries.
+    local parsed, user = pcall(dofile, path)
+    if not parsed or type(user) ~= "table" then
+        logger.warn("BookOrbit: cannot parse user menu order file, leaving it alone:", path)
+        return
+    end
+    if type(user.tools) == "table" then
+        normalizeBookOrbitIds(user.tools)
+    else
+        user.tools = tools
+    end
+    local ok, err = util.writeToFile(dump(user, nil, true), path, true, true)
+    if not ok then
+        logger.warn("BookOrbit: cannot update user menu order file", path, err)
+    end
+end
+
+function BookOrbitMenuPin.ensure()
+    if BookOrbitMenuPin.done then return end
+    BookOrbitMenuPin.done = true
+    for _, entry in ipairs(PREFIXES) do
+        local ok, err = pcall(ensureOne, entry.prefix, entry.order_module)
+        if not ok then
+            logger.warn("BookOrbit: menu pin failed for", entry.prefix, err)
+        end
+    end
+end
+
+return BookOrbitMenuPin
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_sidecar.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_sidecar.lua
new file mode 100644
index 000000000..27b5726a5
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_sidecar.lua
@@ -0,0 +1,140 @@
+--[[--
+Extracts syncable data from a book's sidecar without opening the document.
+
+The normalizers are shared with the per-book snapshot sync, which feeds them
+the live in-memory annotation list and summary table instead of sidecar data
+(both have the same shape), so server-side annotation keys stay stable no
+matter which path uploaded them.
+]]
+
+local DocSettings = require("docsettings")
+local lfs = require("libs/libkoreader-lfs")
+
+local ALLOWED_DRAWERS = {
+    lighten = true,
+    underscore = true,
+    strikeout = true,
+    invert = true,
+}
+
+local ALLOWED_STATUSES = {
+    reading = true,
+    complete = true,
+    abandoned = true,
+}
+
+local BookOrbitSidecar = {}
+
+function BookOrbitSidecar.sidecarMtime(file)
+    local sidecar_file = DocSettings:findSidecarFile(file)
+    if not sidecar_file then return nil end
+    return lfs.attributes(sidecar_file, "modification")
+end
+
+local function isDeviceDatetime(value)
+    return type(value) == "string" and value:match("^%d%d%d%d%-%d%d%-%d%d %d%d:%d%d:%d%d$") ~= nil
+end
+
+local function isDateOnly(value)
+    return type(value) == "string" and value:match("^%d%d%d%d%-%d%d%-%d%d$") ~= nil
+end
+
+local function truncate(value, max_len)
+    if type(value) ~= "string" then return nil end
+    if #value > max_len then
+        return value:sub(1, max_len)
+    end
+    return value
+end
+
+-- PDF positions are tables; serialize them canonically by hand so the
+-- server-side annotation key (md5 of datetime|pos0) stays stable across syncs.
+local function serializePos(pos)
+    if type(pos) == "string" then
+        return pos, "xpointer"
+    end
+    if type(pos) == "table" and type(pos.page) == "number" then
+        return string.format('{"page":%d,"x":%.2f,"y":%.2f}', pos.page, tonumber(pos.x) or 0, tonumber(pos.y) or 0), "pdf"
+    end
+    return nil
+end
+
+-- Returns normalized annotations plus the max effective datetime; accepts the
+-- raw sidecar list or the live ui.annotation.annotations array.
+function BookOrbitSidecar.normalizeAnnotations(raw)
+    local annotations = {}
+    local max_datetime = ""
+    for _, a in ipairs(raw or {}) do
+        -- drawer == nil marks a position-only bookmark; those are skipped in v1.
+        if ALLOWED_DRAWERS[a.drawer] and isDeviceDatetime(a.datetime) then
+            local pos0, pos_format = serializePos(a.pos0)
+            if pos0 then
+                local pos1 = serializePos(a.pos1)
+                local entry = {
+                    datetime = a.datetime,
+                    datetimeUpdated = isDeviceDatetime(a.datetime_updated) and a.datetime_updated or nil,
+                    drawer = a.drawer,
+                    color = truncate(a.color, 30),
+                    text = truncate(a.text, 10000),
+                    note = truncate(a.note, 5000),
+                    chapter = truncate(a.chapter, 500),
+                    pageno = type(a.pageno) == "number" and math.floor(a.pageno) or nil,
+                    posFormat = pos_format,
+                    pos0 = truncate(pos0, 4000),
+                    pos1 = truncate(pos1, 4000),
+                }
+                table.insert(annotations, entry)
+                local effective = entry.datetimeUpdated or entry.datetime
+                if effective > max_datetime then
+                    max_datetime = effective
+                end
+            end
+        end
+    end
+    return annotations, max_datetime
+end
+
+-- Validates a summary table (sidecar or live doc_settings reference) into a
+-- fresh plain table; never returns the input reference.
+function BookOrbitSidecar.normalizeSummary(summary)
+    if type(summary) ~= "table" then summary = {} end
+    local rating = nil
+    if type(summary.rating) == "number" and summary.rating >= 1 and summary.rating <= 5 then
+        rating = math.floor(summary.rating)
+    end
+    return {
+        status = ALLOWED_STATUSES[summary.status] and summary.status or nil,
+        status_modified = isDateOnly(summary.modified) and summary.modified or nil,
+        rating = rating,
+    }
+end
+
+function BookOrbitSidecar.extract(file)
+    if not DocSettings:hasSidecarFile(file) then return nil end
+
+    local doc_settings = DocSettings:open(file)
+    local summary = BookOrbitSidecar.normalizeSummary(doc_settings:readSetting("summary"))
+    local annotations, max_datetime = BookOrbitSidecar.normalizeAnnotations(doc_settings:readSetting("annotations"))
+
+    local last_position = doc_settings:readSetting("last_xpointer")
+    if not last_position then
+        local last_page = doc_settings:readSetting("last_page")
+        if last_page then
+            last_position = tostring(last_page)
+        end
+    end
+
+    return {
+        md5 = doc_settings:readSetting("partial_md5_checksum"),
+        percent_finished = doc_settings:readSetting("percent_finished"),
+        last_position = last_position,
+        status = summary.status,
+        status_modified = summary.status_modified,
+        rating = summary.rating,
+        annotations = annotations,
+        annotations_count = #annotations,
+        annotations_max_datetime = max_datetime,
+    }
+end
+
+return BookOrbitSidecar
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_state.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_state.lua
new file mode 100644
index 000000000..f2ef0c238
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_state.lua
@@ -0,0 +1,113 @@
+--[[--
+Persistent local sync state for the BookOrbit plugin.
+
+This LuaSettings file is the plugin's only local database. Matched books carry
+full watermark records, unmatched hashes only a last-checked timestamp, so
+thousands of unmatched books stay cheap. statistics.sqlite3 is never written.
+]]
+
+local DataStorage = require("datastorage")
+local LuaSettings = require("luasettings")
+local lfs = require("libs/libkoreader-lfs")
+
+local STATE_FILE = "bookorbit_sync_state.lua"
+
+local BookOrbitState = {}
+BookOrbitState.__index = BookOrbitState
+
+function BookOrbitState.open()
+    local settings = LuaSettings:open(DataStorage:getSettingsDir() .. "/" .. STATE_FILE)
+    local self = setmetatable({ settings = settings }, BookOrbitState)
+    -- readSetting with a default persists the returned live table on flush.
+    self.books = settings:readSetting("books", {})
+    self.unmatched = settings:readSetting("unmatched", {})
+    self.files = settings:readSetting("files", {})
+    self.global = settings:readSetting("global", {})
+    return self
+end
+
+function BookOrbitState:getBook(md5)
+    return self.books[md5]
+end
+
+-- Maps BookOrbit bookId -> local file path for every matched book whose file is
+-- still present on disk. Powers the catalog "on device" badges and shortcut.
+function BookOrbitState:matchedByBookId()
+    local result = {}
+    for _, book in pairs(self.books) do
+        if book.bookId and book.file and lfs.attributes(book.file, "mode") == "file" then
+            result[book.bookId] = book.file
+        end
+    end
+    return result
+end
+
+function BookOrbitState:matchedByBookFileId()
+    local result = {}
+    for _, book in pairs(self.books) do
+        if book.fileId and book.file and lfs.attributes(book.file, "mode") == "file" then
+            result[book.fileId] = book.file
+        end
+    end
+    return result
+end
+
+function BookOrbitState:setMatched(md5, book_file_id, book_id, file)
+    local book = self.books[md5] or {}
+    book.fileId = book_file_id
+    book.bookId = book_id
+    book.file = file or book.file
+    book.statsWatermark = book.statsWatermark or 0
+    book.annWatermark = book.annWatermark or ""
+    book.annCount = book.annCount or 0
+    self.books[md5] = book
+    self.unmatched[md5] = nil
+end
+
+function BookOrbitState:setUnmatched(md5)
+    self.books[md5] = nil
+    self.unmatched[md5] = os.time()
+end
+
+function BookOrbitState:rememberFile(file, md5)
+    if file and md5 then
+        self.files[file] = md5
+        local book = self.books[md5]
+        if book and not book.file then
+            book.file = file
+        end
+    end
+end
+
+function BookOrbitState:flush()
+    self.settings:flush()
+end
+
+-- Shared ack-gated stats watermark advance used by the sweep and the per-book
+-- sync. Returns true when a full batch went out and more events may remain.
+function BookOrbitState.applyStatsAck(book, events, body, md5, batch_size, old_watermark)
+    local server_watermark = old_watermark
+    for _, result in ipairs(body.results or {}) do
+        if result.hash == md5 and result.watermark then
+            server_watermark = result.watermark
+        end
+    end
+
+    if #events == batch_size then
+        -- A full batch may have been cut inside a one-second group of events;
+        -- back off by one second so the remainder is fetched next round
+        -- (duplicates are server-side no-ops).
+        local max_start = events[#events].startTime
+        local next_watermark = max_start - 1
+        if next_watermark <= old_watermark then
+            next_watermark = server_watermark
+        end
+        book.statsWatermark = next_watermark
+        return true
+    end
+
+    book.statsWatermark = server_watermark
+    return false
+end
+
+return BookOrbitState
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_stats_reader.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_stats_reader.lua
new file mode 100644
index 000000000..0b2a7dc9d
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_stats_reader.lua
@@ -0,0 +1,111 @@
+--[[--
+Read-only access to KOReader's statistics.sqlite3.
+
+Connections are short-lived and opened in read-only mode; the statistics
+plugin owns all writes to this database.
+]]
+
+local DataStorage = require("datastorage")
+local SQ3 = require("lua-ljsqlite3/init")
+local logger = require("logger")
+
+local BookOrbitStatsReader = {}
+
+local function dbPath()
+    return DataStorage:getSettingsDir() .. "/statistics.sqlite3"
+end
+
+local function withConn(fn)
+    local ok_open, conn = pcall(SQ3.open, dbPath(), "ro")
+    if not ok_open or not conn then
+        logger.dbg("BookOrbit: cannot open statistics.sqlite3:", conn)
+        return nil, "open_failed"
+    end
+    local ok, result = pcall(fn, conn)
+    pcall(conn.close, conn)
+    if not ok then
+        logger.dbg("BookOrbit: statistics query failed:", result)
+        return nil, "query_failed"
+    end
+    return result
+end
+
+-- Returns an array of { md5, ids = {stat book row ids}, last_open, title }.
+-- Multiple stats rows can share one md5 (the stats unique key is
+-- title+authors+md5), so rows are grouped per md5 here.
+function BookOrbitStatsReader.getBooks()
+    return withConn(function(conn)
+        local res = conn:exec("SELECT id, md5, title, last_open FROM book WHERE md5 IS NOT NULL AND md5 != '';")
+        local by_md5 = {}
+        local list = {}
+        if res then
+            for i = 1, #res[1] do
+                local md5 = res[2][i]
+                local entry = by_md5[md5]
+                if not entry then
+                    entry = { md5 = md5, ids = {}, last_open = 0, title = res[3][i] }
+                    by_md5[md5] = entry
+                    table.insert(list, entry)
+                end
+                table.insert(entry.ids, tonumber(res[1][i]))
+                local last_open = tonumber(res[4][i]) or 0
+                if last_open > entry.last_open then
+                    entry.last_open = last_open
+                end
+            end
+        end
+        return list
+    end)
+end
+
+-- Returns the stat book row ids sharing one md5 (the stats unique key is
+-- title+authors+md5, so a single file can map to several rows).
+function BookOrbitStatsReader.getBookIds(md5)
+    if type(md5) ~= "string" or not md5:match("^%x+$") then return {} end
+    local result = withConn(function(conn)
+        local res = conn:exec(string.format("SELECT id FROM book WHERE md5 = '%s';", md5))
+        local ids = {}
+        if res then
+            for i = 1, #res[1] do
+                table.insert(ids, tonumber(res[1][i]))
+            end
+        end
+        return ids
+    end)
+    return result or {}
+end
+
+-- Returns events newer than the watermark across all stat row ids of a book,
+-- ordered by start_time. The caller handles batching via the limit.
+function BookOrbitStatsReader.getEventsAfter(ids, watermark, limit)
+    if not ids or #ids == 0 then return {} end
+    return withConn(function(conn)
+        local id_list = {}
+        for _, id in ipairs(ids) do
+            table.insert(id_list, string.format("%d", id))
+        end
+        local sql = string.format(
+            "SELECT page, start_time, duration, total_pages FROM page_stat_data"
+                .. " WHERE id_book IN (%s) AND start_time > %d AND total_pages > 0"
+                .. " ORDER BY start_time, page LIMIT %d;",
+            table.concat(id_list, ","),
+            watermark or 0,
+            limit
+        )
+        local res = conn:exec(sql)
+        local events = {}
+        if res then
+            for i = 1, #res[1] do
+                table.insert(events, {
+                    page = tonumber(res[1][i]) or 0,
+                    startTime = tonumber(res[2][i]) or 0,
+                    durationSeconds = math.min(tonumber(res[3][i]) or 0, 86400),
+                    totalPages = tonumber(res[4][i]) or 1,
+                })
+            end
+        end
+        return events
+    end)
+end
+
+return BookOrbitStatsReader
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_sweep.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_sweep.lua
new file mode 100644
index 000000000..743582006
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_sweep.lua
@@ -0,0 +1,732 @@
+--[[--
+Full-library sweep: pushes reading statistics, annotations, book states and
+bulk progress for all matched books to BookOrbit. Manual-only; the open book
+is covered day to day by the per-book snapshot sync.
+
+The sweep is a module-level singleton driven by small steps chained through
+UIManager:scheduleIn so the UI stays responsive. It holds no references to a
+ReaderUI/FileManager plugin instance and therefore survives document close.
+Per-book sync state advances only after the server acknowledges an upload, so
+an interrupted sweep resumes exactly where it left off.
+]]
+
+local DocSettings = require("docsettings")
+local InfoMessage = require("ui/widget/infomessage")
+local Notification = require("ui/widget/notification")
+local ReadHistory = require("readhistory")
+local UIManager = require("ui/uimanager")
+local logger = require("logger")
+local util = require("util")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local BookOrbitAnnotations = require("bookorbit_annotations")
+local BookOrbitApi = require("bookorbit_api")
+local BookOrbitSidecar = require("bookorbit_sidecar")
+local BookOrbitState = require("bookorbit_state")
+local BookOrbitStatsReader = require("bookorbit_stats_reader")
+
+local STEP_DELAY = 0.1
+local MATCH_BATCH = 500
+local STATS_BATCH = 500
+local ANN_BATCH_BOOKS = 20
+local ANN_BATCH_TOTAL = 50
+local STATES_BATCH = 200
+local PROGRESS_BATCH = 100
+
+local BookOrbitSweep = {
+    running = false,
+}
+
+function BookOrbitSweep.isRunning()
+    return BookOrbitSweep.running
+end
+
+function BookOrbitSweep.syncStatus()
+    local state = BookOrbitState.open()
+    local matched, unmatched = 0, 0
+    for _ in pairs(state.books) do matched = matched + 1 end
+    for _ in pairs(state.unmatched) do unmatched = unmatched + 1 end
+    return {
+        lastSweepAt = state.global.lastSweepAt or 0,
+        matched = matched,
+        unmatched = unmatched,
+    }
+end
+
+local function isAuthError(err)
+    return err == 401 or err == 403
+end
+
+local PROGRESS_THROTTLE = 2
+
+-- Interactive-only progress toast for the sweep, reused across phases. Identical
+-- text never redraws, and changing text redraws at most every PROGRESS_THROTTLE
+-- seconds, so a long first run stays legible without flooding the e-ink screen.
+local function setProgress(ctx, text, force)
+    if not ctx.interactive then return end
+    if not force then
+        if text == ctx.progress_shown_text then return end
+        if ctx.progress_msg and os.time() - (ctx.progress_shown_at or 0) < PROGRESS_THROTTLE then
+            return
+        end
+    end
+    ctx.progress_shown_text = text
+    ctx.progress_shown_at = os.time()
+    if ctx.progress_msg then UIManager:close(ctx.progress_msg) end
+    ctx.progress_msg = InfoMessage:new{ text = text }
+    UIManager:show(ctx.progress_msg)
+end
+
+local function finish(ctx, err)
+    BookOrbitSweep.running = false
+    if ctx.progress_msg then
+        UIManager:close(ctx.progress_msg)
+        ctx.progress_msg = nil
+    end
+    ctx.state:flush()
+    if ctx.on_finish then
+        pcall(ctx.on_finish, err)
+    end
+
+    if err == "auth" then
+        if ctx.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync: login failed. Check your credentials."), timeout = 4 })
+        else
+            Notification:notify(_("BookOrbit sync: login failed"))
+        end
+        return
+    end
+
+    if err == "network" then
+        if ctx.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync: server not reachable."), timeout = 4 })
+        end
+        logger.dbg("BookOrbit: sweep aborted, server not reachable")
+        return
+    end
+
+    if ctx.interactive then
+        local text = T(_("BookOrbit sync done: %1 books matched, %2 reading events, %3 highlights."),
+            ctx.counts.books_matched, ctx.counts.page_stats, ctx.counts.annotations)
+        if ctx.had_errors then
+            text = text .. "\n" .. _("Some books failed and will retry on the next sync.")
+        end
+        UIManager:show(InfoMessage:new{ text = text, timeout = 5 })
+    end
+    logger.info(string.format(
+        "BookOrbit: sweep done matched=%d pageStats=%d annotations=%d errors=%s",
+        ctx.counts.books_matched, ctx.counts.page_stats, ctx.counts.annotations, tostring(ctx.had_errors)))
+end
+
+local function step(ctx, fn)
+    UIManager:scheduleIn(STEP_DELAY, function()
+        local ok, err = pcall(fn, ctx)
+        if not ok then
+            logger.err("BookOrbit: sweep step failed:", err)
+            ctx.had_errors = true
+            finish(ctx)
+        end
+    end)
+end
+
+-- Phase 1: enumerate candidate books from the stats database (primary source,
+-- has md5 directly) and ReadHistory (provides file paths for sidecar data).
+local function stepEnumerate(ctx)
+    ctx.candidates = {}
+
+    local stats_books = BookOrbitStatsReader.getBooks()
+    for _, entry in ipairs(stats_books or {}) do
+        ctx.candidates[entry.md5] = { stat_ids = entry.ids, last_open = entry.last_open }
+    end
+
+    for _, item in ipairs(ReadHistory.hist or {}) do
+        local file = item.file
+        if file then
+            local md5 = ctx.state.files[file]
+            if not md5 and DocSettings:hasSidecarFile(file) then
+                local doc_settings = DocSettings:open(file)
+                md5 = doc_settings:readSetting("partial_md5_checksum")
+                if not md5 then
+                    local ok, computed = pcall(util.partialMD5, file)
+                    if ok then md5 = computed end
+                end
+                ctx.state:rememberFile(file, md5)
+            end
+            if md5 then
+                local cand = ctx.candidates[md5] or {}
+                cand.file = file
+                if (item.time or 0) > (cand.last_open or 0) then
+                    cand.last_open = item.time
+                end
+                ctx.candidates[md5] = cand
+                local book = ctx.state:getBook(md5)
+                if book and not book.file then
+                    book.file = file
+                end
+            end
+        end
+    end
+
+    step(ctx, ctx.steps.match)
+end
+
+-- Phase 2: ask the server which hashes it knows. Only never-seen hashes,
+-- unmatched hashes with new activity, and (when the library version token
+-- changed or on manual sync) the whole unmatched backlog are checked.
+local function stepMatch(ctx)
+    local to_check = {}
+    local queued = {}
+    local function queue(md5)
+        if not queued[md5] then
+            queued[md5] = true
+            table.insert(to_check, md5)
+        end
+    end
+
+    for md5, cand in pairs(ctx.candidates) do
+        if not ctx.state:getBook(md5) then
+            local last_check = ctx.state.unmatched[md5]
+            if not last_check then
+                queue(md5)
+            elseif (cand.last_open or 0) > last_check then
+                queue(md5)
+            end
+        end
+    end
+
+    if ctx.full_recheck then
+        for md5 in pairs(ctx.state.unmatched) do
+            queue(md5)
+        end
+    end
+
+    ctx.match_queue = {}
+    for i = 1, #to_check, MATCH_BATCH do
+        local batch = {}
+        for j = i, math.min(i + MATCH_BATCH - 1, #to_check) do
+            table.insert(batch, to_check[j])
+        end
+        table.insert(ctx.match_queue, batch)
+    end
+
+    step(ctx, ctx.steps.matchNext)
+end
+
+local function stepMatchNext(ctx)
+    local batch = table.remove(ctx.match_queue, 1)
+    if not batch then
+        for md5 in pairs(ctx.candidates) do
+            if ctx.state:getBook(md5) then
+                ctx.counts.books_matched = ctx.counts.books_matched + 1
+            end
+        end
+        ctx.state:flush()
+        ctx.stats_queue = {}
+        for md5, cand in pairs(ctx.candidates) do
+            if cand.stat_ids and ctx.state:getBook(md5) then
+                table.insert(ctx.stats_queue, { md5 = md5, ids = cand.stat_ids })
+            end
+        end
+        ctx.stats_total = #ctx.stats_queue
+        step(ctx, ctx.steps.statsNext)
+        return
+    end
+
+    setProgress(ctx, _("BookOrbit sync: matching books..."))
+    local body, err = ctx.client:matchCheck(batch)
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        return finish(ctx, "network")
+    end
+
+    local matched = {}
+    for _, match in ipairs(body.matches or {}) do
+        matched[match.hash] = true
+        local cand = ctx.candidates[match.hash]
+        ctx.state:setMatched(match.hash, match.bookFileId, match.bookId, cand and cand.file or nil)
+    end
+    for _, md5 in ipairs(batch) do
+        if not matched[md5] then
+            ctx.state:setUnmatched(md5)
+        end
+    end
+    if body.libraryVersion then
+        ctx.server_library_version = body.libraryVersion
+    end
+
+    step(ctx, ctx.steps.matchNext)
+end
+
+-- Phase 3: upload page stat events per matched book, batched and watermarked.
+local function stepStatsNext(ctx)
+    local item = ctx.current_stats or table.remove(ctx.stats_queue, 1)
+    ctx.current_stats = nil
+    if not item then
+        step(ctx, ctx.steps.sidecars)
+        return
+    end
+
+    if ctx.stats_total and ctx.stats_total > 0 then
+        setProgress(ctx, T(_("BookOrbit sync: uploading reading data (%1/%2)"),
+            ctx.stats_total - #ctx.stats_queue, ctx.stats_total))
+    end
+
+    local book = ctx.state:getBook(item.md5)
+    if not book then
+        step(ctx, ctx.steps.statsNext)
+        return
+    end
+
+    local watermark = book.statsWatermark or 0
+    local events = BookOrbitStatsReader.getEventsAfter(item.ids, watermark, STATS_BATCH)
+    if not events or #events == 0 then
+        step(ctx, ctx.steps.statsNext)
+        return
+    end
+
+    local body, err = ctx.client:uploadPageStats({ { hash = item.md5, events = events } })
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        logger.dbg("BookOrbit: page stats upload failed for", item.md5, err)
+        ctx.had_errors = true
+        step(ctx, ctx.steps.statsNext)
+        return
+    end
+
+    for _, unmatched in ipairs(body.unmatched or {}) do
+        if unmatched == item.md5 then
+            ctx.state:setUnmatched(item.md5)
+            step(ctx, ctx.steps.statsNext)
+            return
+        end
+    end
+
+    local more = BookOrbitState.applyStatsAck(book, events, body, item.md5, STATS_BATCH, watermark)
+    ctx.counts.page_stats = ctx.counts.page_stats + #events
+    if more then
+        ctx.current_stats = item
+    end
+
+    step(ctx, ctx.steps.statsNext)
+end
+
+-- Phase 4: read sidecars of matched books with known paths, mtime-gated, and
+-- queue annotation/state/progress deltas.
+local function stepSidecars(ctx)
+    ctx.pending_books = {}
+    ctx.ann_queue = {}
+    ctx.ann_chunks = {}
+    ctx.states_items = {}
+    ctx.progress_items = {}
+
+    for md5, book in pairs(ctx.state.books) do
+        if book.file then
+            local mtime = BookOrbitSidecar.sidecarMtime(book.file)
+            if mtime and mtime ~= book.sidecarMtime then
+                local extract = BookOrbitSidecar.extract(book.file)
+                if extract then
+                    local pending = {
+                        md5 = md5,
+                        mtime = mtime,
+                        ann_count = extract.annotations_count,
+                        ann_max_datetime = extract.annotations_max_datetime,
+                        ann_done = false,
+                        failed = false,
+                        need_state = false,
+                        need_progress = false,
+                    }
+
+                    -- Every changed sidecar goes through the exchange, even with
+                    -- no new local highlights: the full key set is what lets the
+                    -- server detect on-device deletions.
+                    table.insert(ctx.ann_queue, {
+                        md5 = md5,
+                        file = book.file,
+                        annotations = extract.annotations,
+                        ann_max_datetime = extract.annotations_max_datetime,
+                    })
+
+                    if extract.status or extract.rating then
+                        local state_changed = extract.status ~= nil
+                            and (extract.status_modified or "") ~= (book.statusSyncedModified or "")
+                        local rating_changed = (extract.rating or 0) ~= (book.ratingSynced or 0)
+                        if state_changed or rating_changed then
+                            pending.need_state = true
+                            pending.status_modified = extract.status_modified
+                            pending.rating = extract.rating
+                            table.insert(ctx.states_items, {
+                                hash = md5,
+                                status = extract.status,
+                                statusModified = extract.status_modified,
+                                rating = extract.rating,
+                            })
+                        end
+                    end
+
+                    if extract.percent_finished then
+                        local pushed = book.progressPushedPct or -1
+                        if math.abs(extract.percent_finished - pushed) > 0.001 then
+                            pending.need_progress = true
+                            pending.percentage = extract.percent_finished
+                            local cand = ctx.candidates[md5]
+                            table.insert(ctx.progress_items, {
+                                hash = md5,
+                                percentage = extract.percent_finished,
+                                progress = extract.last_position,
+                                timestamp = cand and cand.last_open or nil,
+                            })
+                        end
+                    end
+
+                    ctx.pending_books[md5] = pending
+                end
+            end
+        end
+    end
+
+    ctx.ann_total = #ctx.ann_queue
+    step(ctx, ctx.steps.annotationsNext)
+end
+
+local buildLegacyAnnotationChunks
+
+local function currentlyOpenFile()
+    local ok, ReaderUI = pcall(require, "apps/reader/readerui")
+    if ok and ReaderUI and ReaderUI.instance and ReaderUI.instance.document then
+        return ReaderUI.instance.document.file
+    end
+end
+
+-- Phase 5: per-book annotation exchange. Uploads the local delta, reports the
+-- key set for deletion detection and applies server-side changes into the
+-- sidecar of closed books. Falls back to the legacy one-way upload when the
+-- server has no exchange endpoint.
+local function stepAnnotationsNext(ctx)
+    if ctx.use_legacy_annotations then
+        return step(ctx, ctx.steps.annotationsLegacyNext)
+    end
+    local entry = table.remove(ctx.ann_queue, 1)
+    if not entry then
+        step(ctx, ctx.steps.statesNext)
+        return
+    end
+
+    if ctx.ann_total and ctx.ann_total > 0 then
+        setProgress(ctx, T(_("BookOrbit sync: syncing highlights (%1/%2)"),
+            ctx.ann_total - #ctx.ann_queue, ctx.ann_total))
+    end
+
+    local pending = ctx.pending_books[entry.md5]
+    local apply_mode = "skip"
+    if ctx.annotation_sync and entry.file ~= currentlyOpenFile() then
+        apply_mode = "sidecar"
+    end
+
+    local result, err = BookOrbitAnnotations.exchangeBook({
+        client = ctx.client,
+        state = ctx.state,
+        digest = entry.md5,
+        annotations = entry.annotations,
+        ann_max_datetime = entry.ann_max_datetime,
+        apply_mode = apply_mode,
+        file = entry.file,
+    })
+    if not result then
+        if isAuthError(err) or err == "auth" then return finish(ctx, "auth") end
+        if err == "unsupported_server" then
+            -- Re-queue everything, including this entry, for the legacy path.
+            table.insert(ctx.ann_queue, 1, entry)
+            ctx.use_legacy_annotations = true
+            buildLegacyAnnotationChunks(ctx)
+            return step(ctx, ctx.steps.annotationsLegacyNext)
+        end
+        ctx.had_errors = true
+        if pending then pending.failed = true end
+        logger.dbg("BookOrbit: annotation exchange failed for", entry.md5, err)
+        return step(ctx, ctx.steps.annotationsNext)
+    end
+
+    if result.had_errors then
+        ctx.had_errors = true
+        if pending then pending.failed = true end
+    elseif pending then
+        pending.ann_done = true
+    end
+    ctx.counts.annotations = ctx.counts.annotations + result.uploaded
+    ctx.counts.ann_applied = (ctx.counts.ann_applied or 0) + result.applied
+    return step(ctx, ctx.steps.annotationsNext)
+end
+
+-- Legacy phase 5: one-way chunk upload, packing several books per request
+-- while respecting both the per-request book and annotation caps.
+buildLegacyAnnotationChunks = function(ctx)
+    local device_now = os.date("%Y-%m-%d %H:%M:%S")
+    for _, entry in ipairs(ctx.ann_queue) do
+        local book = ctx.state:getBook(entry.md5)
+        local ann_watermark = book and BookOrbitAnnotations.readWatermark(book, device_now) or ""
+        local delta = {}
+        for _, annotation in ipairs(entry.annotations) do
+            local effective = annotation.datetimeUpdated or annotation.datetime
+            if effective > ann_watermark then
+                table.insert(delta, annotation)
+            end
+        end
+        local pending = ctx.pending_books[entry.md5]
+        if pending then pending.ann_chunks_left = 0 end
+        for i = 1, #delta, ANN_BATCH_TOTAL do
+            local chunk = {}
+            for j = i, math.min(i + ANN_BATCH_TOTAL - 1, #delta) do
+                table.insert(chunk, delta[j])
+            end
+            table.insert(ctx.ann_chunks, { md5 = entry.md5, annotations = chunk })
+            if pending then pending.ann_chunks_left = pending.ann_chunks_left + 1 end
+        end
+    end
+    ctx.ann_queue = {}
+end
+
+local function stepAnnotationsLegacyNext(ctx)
+    if #ctx.ann_chunks == 0 then
+        step(ctx, ctx.steps.statesNext)
+        return
+    end
+
+    local books = {}
+    local total = 0
+    while #ctx.ann_chunks > 0 and #books < ANN_BATCH_BOOKS do
+        local next_chunk = ctx.ann_chunks[1]
+        if total + #next_chunk.annotations > ANN_BATCH_TOTAL then break end
+        table.remove(ctx.ann_chunks, 1)
+        table.insert(books, { hash = next_chunk.md5, annotations = next_chunk.annotations })
+        total = total + #next_chunk.annotations
+    end
+
+    local body, err = ctx.client:uploadAnnotations(books)
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        logger.dbg("BookOrbit: annotations upload failed:", err)
+        ctx.had_errors = true
+        for _, book in ipairs(books) do
+            local pending = ctx.pending_books[book.hash]
+            if pending then pending.failed = true end
+        end
+        step(ctx, ctx.steps.annotationsLegacyNext)
+        return
+    end
+
+    local unmatched = {}
+    for _, hash in ipairs(body.unmatched or {}) do
+        unmatched[hash] = true
+    end
+
+    for _, book in ipairs(books) do
+        local pending = ctx.pending_books[book.hash]
+        if unmatched[book.hash] then
+            ctx.state:setUnmatched(book.hash)
+            if pending then pending.failed = true end
+        elseif pending then
+            pending.ann_chunks_left = pending.ann_chunks_left - 1
+            ctx.counts.annotations = ctx.counts.annotations + #book.annotations
+        end
+    end
+
+    step(ctx, ctx.steps.annotationsLegacyNext)
+end
+
+-- Phase 6: book status + rating, batched.
+local function stepStatesNext(ctx)
+    if #ctx.states_items == 0 then
+        step(ctx, ctx.steps.progressNext)
+        return
+    end
+
+    local batch = {}
+    while #ctx.states_items > 0 and #batch < STATES_BATCH do
+        table.insert(batch, table.remove(ctx.states_items, 1))
+    end
+
+    local body, err = ctx.client:uploadBookStates(batch)
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        logger.dbg("BookOrbit: book states upload failed:", err)
+        ctx.had_errors = true
+        for _, item in ipairs(batch) do
+            local pending = ctx.pending_books[item.hash]
+            if pending then pending.failed = true end
+        end
+        step(ctx, ctx.steps.statesNext)
+        return
+    end
+
+    local unmatched = {}
+    for _, hash in ipairs(body.unmatched or {}) do
+        unmatched[hash] = true
+    end
+
+    for _, item in ipairs(batch) do
+        local pending = ctx.pending_books[item.hash]
+        if unmatched[item.hash] then
+            ctx.state:setUnmatched(item.hash)
+            if pending then pending.failed = true end
+        elseif pending then
+            -- A server-kept tie still counts as synced: the device value was considered.
+            pending.state_acked = true
+        end
+    end
+
+    step(ctx, ctx.steps.statesNext)
+end
+
+-- Phase 7: bulk progress for matched books whose sidecar percent changed.
+local function stepProgressNext(ctx)
+    if #ctx.progress_items == 0 then
+        step(ctx, ctx.steps.done)
+        return
+    end
+
+    local batch = {}
+    while #ctx.progress_items > 0 and #batch < PROGRESS_BATCH do
+        table.insert(batch, table.remove(ctx.progress_items, 1))
+    end
+
+    local body, err = ctx.client:bulkProgress(batch)
+    if not body then
+        if isAuthError(err) then return finish(ctx, "auth") end
+        logger.dbg("BookOrbit: bulk progress upload failed:", err)
+        ctx.had_errors = true
+        for _, item in ipairs(batch) do
+            local pending = ctx.pending_books[item.hash]
+            if pending then pending.failed = true end
+        end
+        step(ctx, ctx.steps.progressNext)
+        return
+    end
+
+    local unmatched = {}
+    for _, hash in ipairs(body.unmatched or {}) do
+        unmatched[hash] = true
+    end
+
+    for _, item in ipairs(batch) do
+        local pending = ctx.pending_books[item.hash]
+        if unmatched[item.hash] then
+            ctx.state:setUnmatched(item.hash)
+            if pending then pending.failed = true end
+        elseif pending then
+            pending.progress_acked = true
+        end
+    end
+
+    step(ctx, ctx.steps.progressNext)
+end
+
+-- Phase 8: commit per-book sidecar watermarks for fully acked books, record
+-- the sweep server-side and store the fresh library version token.
+local function stepDone(ctx)
+    local device_now = os.date("%Y-%m-%d %H:%M:%S")
+    for md5, pending in pairs(ctx.pending_books) do
+        local book = ctx.state:getBook(md5)
+        if book and not pending.failed then
+            local ann_done = pending.ann_done or (pending.ann_chunks_left ~= nil and pending.ann_chunks_left <= 0)
+            local state_done = not pending.need_state or pending.state_acked
+            local progress_done = not pending.need_progress or pending.progress_acked
+            if ann_done and state_done and progress_done then
+                book.sidecarMtime = pending.mtime
+                book.annCount = pending.ann_count
+                BookOrbitAnnotations.advanceWatermark(book, pending.ann_max_datetime, device_now)
+                if state_done and pending.need_state then
+                    book.statusSyncedModified = pending.status_modified or book.statusSyncedModified
+                    book.ratingSynced = pending.rating or book.ratingSynced
+                end
+                if progress_done and pending.need_progress then
+                    book.progressPushedPct = pending.percentage
+                end
+            end
+        end
+    end
+
+    local body = ctx.client:sweepComplete(ctx.counts)
+    if body and body.libraryVersion then
+        ctx.server_library_version = body.libraryVersion
+    end
+
+    if ctx.server_library_version then
+        local known = ctx.state.global.libraryVersion
+        if ctx.full_recheck or known == nil then
+            ctx.state.global.needsFullRecheck = false
+        elseif ctx.server_library_version ~= known then
+            -- The library changed; the next sweep rechecks the unmatched backlog.
+            ctx.state.global.needsFullRecheck = true
+        end
+        ctx.state.global.libraryVersion = ctx.server_library_version
+    end
+
+    ctx.state.global.lastSweepAt = os.time()
+    finish(ctx)
+end
+
+function BookOrbitSweep.run(opts)
+    if BookOrbitSweep.running then
+        if opts.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit sync is already running."), timeout = 2 })
+        end
+        return
+    end
+
+    local BookOrbitBookSync = require("bookorbit_book_sync")
+    if BookOrbitBookSync.isRunning() then
+        if opts.interactive then
+            UIManager:show(InfoMessage:new{ text = _("BookOrbit is syncing the current book, try again shortly."), timeout = 2 })
+        end
+        return
+    end
+
+    local client = BookOrbitApi.new(opts.api)
+    if not client:isConfigured() then
+        if opts.interactive then
+            UIManager:show(InfoMessage:new{ text = _("Please configure the BookOrbit server and login first."), timeout = 3 })
+        end
+        return
+    end
+
+    BookOrbitSweep.running = true
+
+    -- Flush the open book (sidecar + statistics DB) so a mid-session sweep
+    -- sees current annotations, summary and reading time.
+    local rdr = require("apps/reader/readerui").instance
+    if rdr then
+        pcall(rdr.saveSettings, rdr)
+    end
+
+    local state = BookOrbitState.open()
+    local ctx = {
+        client = client,
+        state = state,
+        interactive = opts.interactive or false,
+        annotation_sync = opts.annotation_sync ~= false,
+        full_recheck = opts.interactive or state.global.needsFullRecheck or false,
+        on_finish = opts.on_finish,
+        counts = { books_matched = 0, page_stats = 0, annotations = 0, ann_applied = 0 },
+        had_errors = false,
+    }
+    ctx.steps = {
+        enumerate = stepEnumerate,
+        match = stepMatch,
+        matchNext = stepMatchNext,
+        statsNext = stepStatsNext,
+        sidecars = stepSidecars,
+        annotationsNext = stepAnnotationsNext,
+        annotationsLegacyNext = stepAnnotationsLegacyNext,
+        statesNext = stepStatesNext,
+        progressNext = stepProgressNext,
+        done = stepDone,
+    }
+
+    setProgress(ctx, _("Syncing to BookOrbit. This may take a while on first run."), true)
+    logger.info("BookOrbit: sweep started, interactive:", ctx.interactive)
+
+    step(ctx, ctx.steps.enumerate)
+end
+
+return BookOrbitSweep
diff --git a/koreader-plugin/bookorbit.koplugin/bookorbit_updater.lua b/koreader-plugin/bookorbit.koplugin/bookorbit_updater.lua
new file mode 100644
index 000000000..f98080742
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/bookorbit_updater.lua
@@ -0,0 +1,103 @@
+--[[--
+Self-update support for the BookOrbit KOReader plugin.
+
+Compares semver strings and, when an update is confirmed by the user, downloads
+the plugin zip from the BookOrbit server and atomically replaces the current
+plugin directory. KOReader must be restarted for the new files to load.
+]]
+
+local lfs = require("libs/libkoreader-lfs")
+
+local BookOrbitUpdater = {}
+
+-- Returns true if `candidate` is strictly newer than `current` (semver, optional "v" prefix).
+function BookOrbitUpdater.isNewer(candidate, current)
+    local function parse(v)
+        if type(v) ~= "string" then return nil end
+        local a, b, c = v:match("^v?(%d+)%.(%d+)%.(%d+)")
+        if not a then return nil end
+        return { tonumber(a), tonumber(b), tonumber(c) }
+    end
+    local c = parse(candidate)
+    local cur = parse(current)
+    if not c or not cur then return false end
+    if c[1] ~= cur[1] then return c[1] > cur[1] end
+    if c[2] ~= cur[2] then return c[2] > cur[2] end
+    return c[3] > cur[3]
+end
+
+-- Wraps a path in POSIX single quotes, escaping any embedded single quotes.
+local function sq(path)
+    return "'" .. path:gsub("'", "'\\''") .. "'"
+end
+
+-- Downloads the plugin zip from the server and atomically replaces `plugin_dir`.
+--
+-- Strategy: extract into a staging directory, backup the current plugin dir,
+-- rename the new one into place, then clean up. On any failure after the backup
+-- the original is restored so the user always has a working plugin.
+--
+-- `api`         BookOrbitApi instance (must be logged in)
+-- `plugin_dir`  Absolute path of the running plugin directory
+-- `progress_cb` Optional function(bytes_received) called during download
+--
+-- Returns true on success, or nil + error string on failure.
+function BookOrbitUpdater.apply(api, plugin_dir, progress_cb)
+    local dir = plugin_dir:gsub("/+$", "")
+    local parent_dir = dir:match("^(.*)/[^/]+$")
+    local plugin_name = dir:match("([^/]+)$")
+
+    if not parent_dir or parent_dir == "" or not plugin_name then
+        return nil, "cannot determine plugin parent directory"
+    end
+
+    local tmp_zip  = parent_dir .. "/bookorbit-update.zip"
+    local staging  = parent_dir .. "/" .. plugin_name .. ".update"
+    local backup   = parent_dir .. "/" .. plugin_name .. ".bak"
+
+    -- Remove any leftover staging dir from a previous failed attempt.
+    os.execute("rm -rf " .. sq(staging))
+
+    local ok, err = api:downloadPluginUpdate(tmp_zip, progress_cb)
+    if not ok then
+        return nil, tostring(err or "download failed")
+    end
+
+    -- Extract into a staging directory so a partial unzip never touches the
+    -- live plugin directory.
+    local ret = os.execute("unzip -o " .. sq(tmp_zip) .. " -d " .. sq(staging))
+    os.remove(tmp_zip)
+
+    if ret ~= 0 then
+        os.execute("rm -rf " .. sq(staging))
+        return nil, "unzip failed with exit code " .. tostring(ret)
+    end
+
+    -- The zip must contain exactly the plugin folder as its top-level entry.
+    local extracted = staging .. "/" .. plugin_name
+    if lfs.attributes(extracted, "mode") ~= "directory" then
+        os.execute("rm -rf " .. sq(staging))
+        return nil, "update zip does not contain expected directory: " .. plugin_name
+    end
+
+    -- Atomic-ish swap (all paths share the same filesystem):
+    --   1. backup current plugin
+    --   2. move new plugin into place
+    --   3. clean up backup and staging
+    os.execute("rm -rf " .. sq(backup))
+    if not os.rename(dir, backup) then
+        os.execute("rm -rf " .. sq(staging))
+        return nil, "could not create plugin backup"
+    end
+    if not os.rename(extracted, dir) then
+        -- Restore backup so the plugin remains usable.
+        os.rename(backup, dir)
+        os.execute("rm -rf " .. sq(staging))
+        return nil, "could not install updated plugin"
+    end
+
+    os.execute("rm -rf " .. sq(backup) .. " " .. sq(staging))
+    return true
+end
+
+return BookOrbitUpdater
diff --git a/koreader-plugin/bookorbit.koplugin/main.lua b/koreader-plugin/bookorbit.koplugin/main.lua
new file mode 100644
index 000000000..0fd845cd9
--- /dev/null
+++ b/koreader-plugin/bookorbit.koplugin/main.lua
@@ -0,0 +1,1214 @@
+--[[--
+BookOrbit Sync plugin.
+
+Live progress sync mirrors the stock kosync plugin (pull on open with
+conflict strategies, periodic push every N page turns, push on close and
+suspend, 25 second debounce) against BookOrbit's kosync-compatible endpoints.
+Closing or suspending additionally snapshots the open book from live memory
+(progress, highlights, status/rating, page stats) and uploads it per book.
+The full-library sweep is manual-only.
+]]
+
+local ConfirmBox = require("ui/widget/confirmbox")
+local Device = require("device")
+local Dispatcher = require("dispatcher")
+local Event = require("ui/event")
+local InfoMessage = require("ui/widget/infomessage")
+local InputDialog = require("ui/widget/inputdialog")
+local Math = require("optmath")
+local MultiInputDialog = require("ui/widget/multiinputdialog")
+local NetworkMgr = require("ui/network/manager")
+local Notification = require("ui/widget/notification")
+local UIManager = require("ui/uimanager")
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+local logger = require("logger")
+local md5 = require("ffi/sha2").md5
+local time = require("ui/time")
+local util = require("util")
+local T = require("ffi/util").template
+local _ = require("gettext")
+
+local BookOrbitAnnotations = require("bookorbit_annotations")
+local BookOrbitApi = require("bookorbit_api")
+local BookOrbitBookSync = require("bookorbit_book_sync")
+local BookOrbitCatalog = require("bookorbit_catalog")
+local BookOrbitState = require("bookorbit_state")
+local BookOrbitMenuPin = require("bookorbit_menu_pin")
+local BookOrbitSweep = require("bookorbit_sweep")
+local BookOrbitUpdater = require("bookorbit_updater")
+
+local PLUGIN_VERSION = "0.1.0"
+
+local SYNC_STRATEGY = {
+    PROMPT = 1,
+    SILENT = 2,
+    DISABLE = 3,
+}
+
+local API_CALL_DEBOUNCE_DELAY = time.s(25)
+local UPDATE_CHECK_INTERVAL = 24 * 60 * 60
+
+local BookOrbit = WidgetContainer:extend{
+    name = "bookorbit",
+    title = _("Login to BookOrbit"),
+
+    push_timestamp = nil,
+    pull_timestamp = nil,
+    last_page = nil,
+    last_page_turn_timestamp = nil,
+
+    settings = nil,
+}
+
+BookOrbit.default_settings = {
+    settings_version = 1,
+    server_url = nil,
+    username = nil,
+    userkey = nil,
+    auto_sync = false,
+    annotation_sync = true,
+    pages_before_update = 10,
+    sync_forward = SYNC_STRATEGY.PROMPT,
+    sync_backward = SYNC_STRATEGY.DISABLE,
+    catalog_view_mode = "mosaic",
+    catalog_sort = "recently_added",
+    catalog_grid_cols = 3,
+    catalog_grid_rows = 3,
+    catalog_recent_searches = {},
+    update_check_last_at = 0,
+}
+
+function BookOrbit:init()
+    self.push_timestamp = 0
+    self.pull_timestamp = 0
+    self.last_page = -1
+    self.last_page_turn_timestamp = 0
+    self.page_update_counter = 0
+    self.periodic_push_scheduled = false
+    self.periodic_push_task = function()
+        self.periodic_push_scheduled = false
+        self.page_update_counter = 0
+        -- Push only, no pull, no network nagging: relies on the connection
+        -- being already up, like the stock kosync periodic push.
+        if self.settings.auto_sync and (self.settings.pages_before_update or 0) > 0 then
+            self:updateProgress(false, false)
+        end
+    end
+
+    self.settings = G_reader_settings:readSetting("bookorbit", self.default_settings)
+    self.device_id = G_reader_settings:readSetting("device_id")
+
+    -- Detect settings from the old bookorbit-koplugin, which used the same
+    -- "bookorbit" key but a different structure. Reset behavior keys to
+    -- defaults while preserving any existing credentials so users aren't
+    -- logged out.
+    if not self.settings.settings_version then
+        local server_url = self.settings.server_url
+        local username = self.settings.username
+        local userkey = self.settings.userkey
+        local provision_fingerprint = self.settings.provision_fingerprint
+        self.settings = {}
+        for k, v in pairs(self.default_settings) do
+            self.settings[k] = type(v) == "table" and {} or v
+        end
+        self.settings.server_url = server_url
+        self.settings.username = username
+        self.settings.userkey = userkey
+        self.settings.provision_fingerprint = provision_fingerprint
+        G_reader_settings:saveSetting("bookorbit", self.settings)
+        G_reader_settings:flush()
+        logger.info("BookOrbit: migrated settings from previous schema")
+    end
+
+    -- v1 settings cleanup: full sweeps are manual-only since 0.2.0.
+    self.settings.sweep_on_close = nil
+    self.settings.sweep_on_suspend = nil
+    if self.settings.pages_before_update == nil then
+        self.settings.pages_before_update = 10
+    end
+    if self.settings.annotation_sync == nil then
+        self.settings.annotation_sync = true
+    end
+    if self.settings.update_check_last_at == nil then
+        self.settings.update_check_last_at = 0
+    end
+
+    self:applyProvision()
+
+    if self.settings.auto_sync and Device:hasSeamlessWifiToggle() and G_reader_settings:readSetting("wifi_enable_action") ~= "turn_on" then
+        self.settings.auto_sync = false
+        logger.warn("BookOrbit: auto sync disabled because wifi_enable_action is not turn_on")
+    end
+
+    pcall(BookOrbitMenuPin.ensure)
+    self:onDispatcherRegisterActions()
+    self.ui.menu:registerToMainMenu(self)
+    UIManager:scheduleIn(5, function()
+        self:maybeCheckForUpdate(false)
+    end)
+end
+
+local PROVISION_FILE = "bookorbit_provision.lua"
+
+-- Applies the connection settings bundled by "Download preconfigured plugin"
+-- in BookOrbit web settings. The fingerprint ties one download to one apply:
+-- a freshly generated zip always (re)configures, while reinstalling an old
+-- one never overrides a logout.
+function BookOrbit:applyProvision()
+    if not self.path then return end
+    local provision_path = self.path .. "/" .. PROVISION_FILE
+    local chunk = loadfile(provision_path)
+    if not chunk then return end
+
+    setfenv(chunk, {})
+    local ok, provision = pcall(chunk)
+    if not ok or type(provision) ~= "table" then
+        logger.warn("BookOrbit: ignoring unreadable provision file", provision_path)
+        return
+    end
+
+    local server_url = BookOrbitApi.normalizeServerUrl(provision.server_url)
+    if not server_url or type(provision.username) ~= "string" or type(provision.userkey) ~= "string" then
+        logger.warn("BookOrbit: ignoring incomplete provision file", provision_path)
+        return
+    end
+
+    local fingerprint = md5(table.concat({
+        server_url, provision.username, provision.userkey, tostring(provision.generated_at),
+    }, "\0"))
+    if self.settings.provision_fingerprint ~= fingerprint then
+        self.settings.server_url = server_url
+        self.settings.username = provision.username
+        self.settings.userkey = provision.userkey
+        self.settings.provision_fingerprint = fingerprint
+        G_reader_settings:flush()
+        logger.info("BookOrbit: applied provision file for", provision.username)
+        UIManager:nextTick(function()
+            UIManager:show(InfoMessage:new{
+                text = T(_("BookOrbit sync is set up for %1 as %2."), provision.server_url, provision.username),
+                timeout = 5,
+            })
+        end)
+    end
+    os.remove(provision_path)
+end
+
+function BookOrbit:apiOpts()
+    return {
+        server_url = self.settings.server_url,
+        username = self.settings.username,
+        userkey = self.settings.userkey,
+        device_id = self.device_id,
+        device_model = Device.model,
+        plugin_version = PLUGIN_VERSION,
+    }
+end
+
+function BookOrbit:newClient()
+    return BookOrbitApi.new(self:apiOpts())
+end
+
+function BookOrbit:isLoggedIn()
+    return self.settings.server_url ~= nil and self.settings.username ~= nil and self.settings.userkey ~= nil
+end
+
+local function showSyncError()
+    UIManager:show(InfoMessage:new{
+        text = _("Something went wrong when syncing to BookOrbit, please check your network connection and try again later."),
+        timeout = 3,
+    })
+end
+
+local function promptLogin()
+    UIManager:show(InfoMessage:new{
+        text = _("Please configure the BookOrbit server and login first."),
+        timeout = 3,
+    })
+end
+
+function BookOrbit:onDispatcherRegisterActions()
+    Dispatcher:registerAction("bookorbit_sync_now",
+        { category = "none", event = "BookOrbitSyncNow", title = _("BookOrbit: sync all books"), general = true })
+    Dispatcher:registerAction("bookorbit_sync_book",
+        { category = "none", event = "BookOrbitSyncBook", title = _("BookOrbit: sync this book"), reader = true })
+    Dispatcher:registerAction("bookorbit_push_progress",
+        { category = "none", event = "BookOrbitPushProgress", title = _("BookOrbit: push progress"), reader = true })
+    Dispatcher:registerAction("bookorbit_pull_progress",
+        { category = "none", event = "BookOrbitPullProgress", title = _("BookOrbit: pull progress"), reader = true, separator = true })
+end
+
+function BookOrbit:onReaderReady()
+    if self.settings.auto_sync then
+        UIManager:nextTick(function()
+            self:getProgress(true, false)
+        end)
+        if self.settings.annotation_sync then
+            UIManager:scheduleIn(2, function()
+                self:exchangeAnnotationsForOpenBook()
+            end)
+        end
+    end
+    self:registerEvents()
+
+    self.last_page = self.ui:getCurrentPage()
+end
+
+-- Two-way annotation pull/push for the open book. Runs once per book open;
+-- safe to call again manually, guarded against concurrent syncs.
+function BookOrbit:exchangeAnnotationsForOpenBook()
+    if self.annotation_exchange_running then return end
+    if not self:isLoggedIn() or not self.ui or not self.ui.document then return end
+    if BookOrbitBookSync.isRunning() or BookOrbitSweep.isRunning() then return end
+
+    local digest = self:getDocumentDigest()
+    if not digest then return end
+    local state = BookOrbitState.open()
+    if not state:getBook(digest) then
+        -- Unknown or unmatched book: the close-path snapshot sync matches it.
+        return
+    end
+
+    self.annotation_exchange_running = true
+    local ok, result, err = pcall(BookOrbitAnnotations.exchangeOpenBook, {
+        client = self:newClient(),
+        state = state,
+        digest = digest,
+        ui = self.ui,
+    })
+    state:flush()
+    self.annotation_exchange_running = false
+
+    if not ok then
+        logger.err("BookOrbit: annotation exchange error:", result)
+    elseif result then
+        local touched = (result.applied or 0) + (result.deleted or 0)
+        if touched > 0 then
+            Notification:notify(T(_("BookOrbit: %1 highlight(s) updated"), touched))
+        end
+    elseif err and err ~= "unmatched" and err ~= "unsupported_server" and err ~= "network" then
+        logger.dbg("BookOrbit: annotation exchange skipped:", err)
+    end
+end
+
+-- Menu
+
+local function getNameStrategy(strategy)
+    if strategy == SYNC_STRATEGY.PROMPT then
+        return _("Prompt")
+    elseif strategy == SYNC_STRATEGY.SILENT then
+        return _("Silently")
+    else
+        return _("Never")
+    end
+end
+
+function BookOrbit:strategyMenu(getter, setter)
+    local function item(text, value)
+        return {
+            text = text,
+            checked_func = function() return getter() == value end,
+            callback = function() setter(value) end,
+        }
+    end
+    return {
+        item(_("Silently"), SYNC_STRATEGY.SILENT),
+        item(_("Prompt"), SYNC_STRATEGY.PROMPT),
+        item(_("Never"), SYNC_STRATEGY.DISABLE),
+    }
+end
+
+function BookOrbit:hasKnownUpdate()
+    return BookOrbitUpdater.isNewer(self.settings.update_latest_version, PLUGIN_VERSION) == true
+end
+
+function BookOrbit:updateCheckMenuText()
+    if self:hasKnownUpdate() then
+        return T(_("Plugin update available: v%1 -> v%2"), PLUGIN_VERSION, self.settings.update_latest_version)
+    end
+    if self:isLoggedIn() then
+        return T(_("Installed plugin: v%1 (Check for update)"), PLUGIN_VERSION)
+    end
+    return T(_("Installed plugin: v%1 (Login required)"), PLUGIN_VERSION)
+end
+
+function BookOrbit:addToMainMenu(menu_items)
+    menu_items.bookorbit = {
+        text = _("BookOrbit"),
+        -- Fallback placement only: BookOrbitMenuPin normally pins this entry
+        -- right below calibre on the first page of the Tools menu.
+        sorting_hint = "tools",
+        sub_item_table = {
+            {
+                text = _("BookOrbit server address"),
+                keep_menu_open = true,
+                callback = function()
+                    self:setServerAddress()
+                end,
+            },
+            {
+                text_func = function()
+                    return self.settings.userkey and _("Logout") or _("Login")
+                end,
+                enabled_func = function()
+                    return self.settings.server_url ~= nil
+                end,
+                keep_menu_open = true,
+                callback_func = function()
+                    if self.settings.userkey then
+                        return function(menu)
+                            self:logout(menu)
+                        end
+                    else
+                        return function(menu)
+                            self:login(menu)
+                        end
+                    end
+                end,
+                separator = true,
+            },
+            {
+                text = _("Browse library"),
+                enabled_func = function()
+                    return self:isLoggedIn()
+                end,
+                callback = function()
+                    self:browseCatalog()
+                end,
+                separator = true,
+            },
+            {
+                text = _("Auto sync this book"),
+                checked_func = function() return self.settings.auto_sync end,
+                help_text = _([[Pulls progress when a book is opened; pushes progress, highlights, status, rating and reading time when it is closed and on suspend.]]),
+                callback = function()
+                    self:onBookOrbitToggleAutoSync(nil, true)
+                end,
+            },
+            {
+                text = _("Two-way highlight sync"),
+                checked_func = function() return self.settings.annotation_sync end,
+                help_text = _([[Also applies highlights, notes and deletions made in BookOrbit to this device: on book open, after the manual book sync, and during the full sweep for closed books. Turning this off keeps uploads only.]]),
+                callback = function()
+                    self.settings.annotation_sync = not self.settings.annotation_sync
+                end,
+            },
+            {
+                text_func = function()
+                    return T(_("Periodically sync every # pages (%1)"), self:getSyncPeriod())
+                end,
+                enabled_func = function() return self.settings.auto_sync end,
+                keep_menu_open = true,
+                callback = function(touchmenu_instance)
+                    local SpinWidget = require("ui/widget/spinwidget")
+                    local items = SpinWidget:new{
+                        text = _([[This value determines how many page turns it takes to push book progress.
+If set to 0, updating progress based on page turns will be disabled.]]),
+                        value = self.settings.pages_before_update or 0,
+                        value_min = 0,
+                        value_max = 999,
+                        value_step = 1,
+                        value_hold_step = 10,
+                        ok_text = _("Set"),
+                        title_text = _("Number of pages before update"),
+                        default_value = 10,
+                        callback = function(spin)
+                            self:setPagesBeforeUpdate(spin.value)
+                            if touchmenu_instance then touchmenu_instance:updateItems() end
+                        end,
+                    }
+                    UIManager:show(items)
+                end,
+            },
+            {
+                text = _("Sync behavior"),
+                sub_item_table = {
+                    {
+                        text_func = function()
+                            return T(_("Sync to a newer state (%1)"), getNameStrategy(self.settings.sync_forward))
+                        end,
+                        sub_item_table = self:strategyMenu(
+                            function() return self.settings.sync_forward end,
+                            function(value) self.settings.sync_forward = value end
+                        ),
+                    },
+                    {
+                        text_func = function()
+                            return T(_("Sync to an older state (%1)"), getNameStrategy(self.settings.sync_backward))
+                        end,
+                        sub_item_table = self:strategyMenu(
+                            function() return self.settings.sync_backward end,
+                            function(value) self.settings.sync_backward = value end
+                        ),
+                    },
+                },
+            },
+            {
+                text = _("Sync this book now"),
+                enabled_func = function()
+                    return self:isLoggedIn() and self.ui.document ~= nil
+                        and not BookOrbitSweep.isRunning() and not BookOrbitBookSync.isRunning()
+                end,
+                callback = function()
+                    self:onBookOrbitSyncBook()
+                end,
+            },
+            {
+                text = _("Sync all books now"),
+                enabled_func = function()
+                    return self:isLoggedIn() and not BookOrbitSweep.isRunning() and not BookOrbitBookSync.isRunning()
+                end,
+                callback = function()
+                    self:startSweep()
+                end,
+                separator = true,
+            },
+            {
+                text_func = function()
+                    return self:updateCheckMenuText()
+                end,
+                enabled_func = function()
+                    return self:isLoggedIn()
+                        and not BookOrbitSweep.isRunning()
+                        and not BookOrbitBookSync.isRunning()
+                end,
+                keep_menu_open = true,
+                callback = function()
+                    self:checkForUpdate()
+                end,
+                separator = true,
+            },
+            {
+                text_func = function()
+                    local status = BookOrbitSweep.syncStatus()
+                    local when = (status.lastSweepAt == 0) and _("never")
+                        or os.date("%Y-%m-%d %H:%M", status.lastSweepAt)
+                    if status.unmatched > 0 then
+                        return T(_("Last sync: %1 (%2 linked, %3 unmatched)"), when, status.matched, status.unmatched)
+                    elseif status.matched > 0 then
+                        return T(_("Last sync: %1 (%2 linked)"), when, status.matched)
+                    end
+                    return T(_("Last sync: %1"), when)
+                end,
+                enabled = false,
+                separator = true,
+            },
+        },
+    }
+end
+
+function BookOrbit:browseCatalog()
+    if not self:isLoggedIn() then
+        promptLogin()
+        return
+    end
+
+    NetworkMgr:runWhenConnected(function()
+        self.catalog_browser = BookOrbitCatalog:new{
+            title = _("BookOrbit"),
+            api = self:apiOpts(),
+            settings = self.settings,
+            save_settings = function()
+                G_reader_settings:flush()
+            end,
+            _manager = self,
+            close_callback = function()
+                UIManager:close(self.catalog_browser)
+                self.catalog_browser = nil
+            end,
+        }
+        UIManager:show(self.catalog_browser)
+    end)
+end
+
+function BookOrbit:setServerAddress()
+    local dialog
+    dialog = InputDialog:new{
+        title = _("BookOrbit server address"),
+        input = self.settings.server_url or "https://",
+        input_hint = "https://bookorbit.example.com",
+        buttons = {
+            {
+                {
+                    text = _("Cancel"),
+                    id = "close",
+                    callback = function()
+                        UIManager:close(dialog)
+                    end,
+                },
+                {
+                    text = _("OK"),
+                    is_enter_default = true,
+                    callback = function()
+                        local normalized = BookOrbitApi.normalizeServerUrl(dialog:getInputText())
+                        self.settings.server_url = normalized
+                        UIManager:close(dialog)
+                        if normalized then
+                            Notification:notify(T(_("BookOrbit server set to %1"), normalized))
+                        end
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+    dialog:onShowKeyboard()
+end
+
+function BookOrbit:login(menu)
+    if NetworkMgr:willRerunWhenOnline(function() self:login(menu) end) then
+        return
+    end
+
+    local dialog
+    dialog = MultiInputDialog:new{
+        title = self.title,
+        fields = {
+            {
+                text = self.settings.username,
+                hint = "username",
+            },
+            {
+                hint = "password",
+                text_type = "password",
+            },
+        },
+        description = _("Credentials are created in BookOrbit web settings under Settings, KOReader."),
+        buttons = {
+            {
+                {
+                    text = _("Cancel"),
+                    id = "close",
+                    callback = function()
+                        UIManager:close(dialog)
+                    end,
+                },
+                {
+                    text = _("Login"),
+                    is_enter_default = true,
+                    callback = function()
+                        local username, password = unpack(dialog:getFields())
+                        username = util.trim(username or "")
+                        if username == "" or not password or password == "" then
+                            UIManager:show(InfoMessage:new{ text = _("Please enter a username and password."), timeout = 2 })
+                            return
+                        end
+                        UIManager:close(dialog)
+                        UIManager:scheduleIn(0.5, function()
+                            self:doLogin(username, password, menu)
+                        end)
+                        UIManager:show(InfoMessage:new{ text = _("Logging in. Please wait."), timeout = 1 })
+                    end,
+                },
+            },
+        },
+    }
+    UIManager:show(dialog)
+    dialog:onShowKeyboard()
+end
+
+function BookOrbit:doLogin(username, password, menu)
+    Device:setIgnoreInput(true)
+    local userkey = md5(password)
+    local client = BookOrbitApi.new{
+        server_url = self.settings.server_url,
+        username = username,
+        userkey = userkey,
+        device_id = self.device_id,
+        device_model = Device.model,
+        plugin_version = PLUGIN_VERSION,
+    }
+    local body, err = client:auth()
+    Device:setIgnoreInput(false)
+
+    if body then
+        self.settings.username = username
+        self.settings.userkey = userkey
+        if menu then menu:updateItems() end
+        UIManager:show(InfoMessage:new{ text = _("Logged in to BookOrbit.") })
+        UIManager:scheduleIn(1, function()
+            self:maybeCheckForUpdate(false)
+        end)
+    elseif err == 401 or err == 403 then
+        UIManager:show(InfoMessage:new{
+            text = _("Login failed. Create or check your KOReader credentials in BookOrbit web settings."),
+        })
+    else
+        UIManager:show(InfoMessage:new{ text = T(_("Could not reach the BookOrbit server: %1"), tostring(err)) })
+    end
+end
+
+function BookOrbit:logout(menu)
+    self.settings.userkey = nil
+    if menu then menu:updateItems() end
+end
+
+function BookOrbit:getSyncPeriod()
+    if not self.settings.auto_sync then
+        return _("Not available")
+    end
+    local period = self.settings.pages_before_update
+    if period and period > 0 then
+        return period
+    end
+    return _("Never")
+end
+
+function BookOrbit:setPagesBeforeUpdate(value)
+    self.settings.pages_before_update = value
+end
+
+function BookOrbit:schedulePeriodicPush()
+    UIManager:unschedule(self.periodic_push_task)
+    -- A sizable delay debounces nicely while skimming.
+    UIManager:scheduleIn(10, self.periodic_push_task)
+    self.periodic_push_scheduled = true
+end
+
+-- Live progress sync (kosync mirror)
+
+function BookOrbit:getLastPercent()
+    if self.ui.document.info.has_pages then
+        return Math.roundPercent(self.ui.paging:getLastPercent())
+    else
+        return Math.roundPercent(self.ui.rolling:getLastPercent())
+    end
+end
+
+function BookOrbit:getLastProgress()
+    if self.ui.document.info.has_pages then
+        return self.ui.paging:getLastProgress()
+    else
+        return self.ui.rolling:getLastProgress()
+    end
+end
+
+-- Always the binary partial MD5: BookOrbit matches on the scanner-computed
+-- partial MD5 of the file, so the filename checksum method does not exist here.
+function BookOrbit:getDocumentDigest()
+    local digest = self.ui.doc_settings:readSetting("partial_md5_checksum")
+    if digest then return digest end
+
+    local file = self.ui.document.file
+    if not file then return nil end
+    local ok, computed = pcall(util.partialMD5, file)
+    if not ok or not computed then return nil end
+    self.ui.doc_settings:saveSetting("partial_md5_checksum", computed)
+    return computed
+end
+
+function BookOrbit:syncToProgress(progress)
+    logger.dbg("BookOrbit: syncing to progress", progress)
+    if self.ui.document.info.has_pages then
+        self.ui:handleEvent(Event:new("GotoPage", tonumber(progress)))
+    else
+        self.ui:handleEvent(Event:new("GotoXPointer", progress))
+    end
+end
+
+function BookOrbit:updateProgress(ensure_networking, interactive, on_suspend)
+    if not self:isLoggedIn() then
+        if interactive then promptLogin() end
+        return
+    end
+    if not self.ui or not self.ui.document then return end
+
+    local now = UIManager:getElapsedTimeSinceBoot()
+    if not interactive and now - self.push_timestamp <= API_CALL_DEBOUNCE_DELAY then
+        logger.dbg("BookOrbit: push debounced")
+        return
+    end
+
+    if ensure_networking and NetworkMgr:willRerunWhenOnline(function() self:updateProgress(ensure_networking, interactive, on_suspend) end) then
+        return
+    end
+
+    local digest = self:getDocumentDigest()
+    if not digest then return end
+
+    local client = self:newClient()
+    local body, err = client:updateProgress(digest, self:getLastPercent(), self:getLastProgress(), os.time())
+    if interactive then
+        if body then
+            UIManager:show(InfoMessage:new{ text = _("Progress has been pushed to BookOrbit."), timeout = 3 })
+            if not on_suspend then self:maybeCheckForUpdate(false) end
+        else
+            showSyncError()
+        end
+    elseif not body then
+        logger.dbg("BookOrbit: push failed:", err)
+    elseif not on_suspend then
+        self:maybeCheckForUpdate(false)
+    end
+
+    if on_suspend and Device:hasWifiManager() then
+        NetworkMgr:disableWifi()
+    end
+
+    self.push_timestamp = now
+end
+
+function BookOrbit:getProgress(ensure_networking, interactive)
+    if not self:isLoggedIn() then
+        if interactive then promptLogin() end
+        return
+    end
+    if not self.ui or not self.ui.document then return end
+
+    local now = UIManager:getElapsedTimeSinceBoot()
+    if not interactive and now - self.pull_timestamp <= API_CALL_DEBOUNCE_DELAY then
+        logger.dbg("BookOrbit: pull debounced")
+        return
+    end
+
+    if ensure_networking and NetworkMgr:willRerunWhenOnline(function() self:getProgress(ensure_networking, interactive) end) then
+        return
+    end
+
+    local digest = self:getDocumentDigest()
+    if not digest then return end
+
+    local client = self:newClient()
+    local body, err = client:getProgress(digest)
+    self.pull_timestamp = now
+
+    if not body then
+        if interactive then showSyncError() end
+        logger.dbg("BookOrbit: pull failed:", err)
+        return
+    end
+    self:maybeCheckForUpdate(false)
+
+    if not body.percentage then
+        if interactive then
+            UIManager:show(InfoMessage:new{ text = _("No progress found for this document."), timeout = 3 })
+        end
+        return
+    end
+
+    if body.device == Device.model and body.device_id == self.device_id then
+        if interactive then
+            UIManager:show(InfoMessage:new{ text = _("Latest progress is coming from this device."), timeout = 3 })
+        end
+        return
+    end
+
+    body.percentage = Math.roundPercent(body.percentage)
+    local progress = self:getLastProgress()
+    local percentage = self:getLastPercent()
+
+    if percentage == body.percentage or body.progress == progress then
+        if interactive then
+            UIManager:show(InfoMessage:new{ text = _("The progress has already been synchronized."), timeout = 3 })
+        end
+        return
+    end
+
+    if interactive then
+        self:syncToProgress(body.progress)
+        UIManager:show(InfoMessage:new{ text = _("Progress has been synchronized."), timeout = 3 })
+        return
+    end
+
+    local self_older
+    if body.timestamp ~= nil then
+        self_older = (body.timestamp > self.last_page_turn_timestamp)
+    else
+        self_older = (body.percentage > percentage)
+    end
+
+    local strategy = self_older and self.settings.sync_forward or self.settings.sync_backward
+    if strategy == SYNC_STRATEGY.SILENT then
+        self:syncToProgress(body.progress)
+        UIManager:show(InfoMessage:new{ text = _("Progress has been synchronized."), timeout = 3 })
+    elseif strategy == SYNC_STRATEGY.PROMPT then
+        local template = self_older and _("Sync to latest location %1% from device '%2'?")
+            or _("Sync to previous location %1% from device '%2'?")
+        UIManager:show(ConfirmBox:new{
+            text = T(template, Math.round(body.percentage * 100), body.device),
+            ok_callback = function()
+                self:syncToProgress(body.progress)
+            end,
+        })
+    end
+end
+
+-- Manual sync triggers
+
+function BookOrbit:startSweep()
+    if not self:isLoggedIn() then
+        promptLogin()
+        return
+    end
+    if BookOrbitBookSync.isRunning() then
+        UIManager:show(InfoMessage:new{ text = _("BookOrbit is syncing the current book, try again shortly."), timeout = 2 })
+        return
+    end
+
+    local sweep_opts = {
+        api = self:apiOpts(),
+        interactive = true,
+        annotation_sync = self.settings.annotation_sync,
+        on_finish = function(err)
+            if not err then self:maybeCheckForUpdate(false) end
+        end,
+    }
+    if NetworkMgr:willRerunWhenOnline(function() BookOrbitSweep.run(sweep_opts) end) then
+        return
+    end
+    BookOrbitSweep.run(sweep_opts)
+end
+
+function BookOrbit:onBookOrbitSyncBook()
+    if not self:isLoggedIn() then
+        promptLogin()
+        return
+    end
+    if not self.ui or not self.ui.document then
+        UIManager:show(InfoMessage:new{ text = _("Open a book to sync it."), timeout = 2 })
+        return
+    end
+    if BookOrbitSweep.isRunning() or BookOrbitBookSync.isRunning() then
+        UIManager:show(InfoMessage:new{ text = _("BookOrbit sync is already running."), timeout = 2 })
+        return
+    end
+
+    local snap = BookOrbitBookSync.capture(self)
+    if not snap then
+        UIManager:show(InfoMessage:new{ text = _("Could not read this book's data."), timeout = 2 })
+        return
+    end
+
+    local api_opts = self:apiOpts()
+    local run = function()
+        BookOrbitBookSync.run{ api = api_opts, snap = snap, reason = "manual", interactive = true, plugin = self,
+            annotation_sync = self.settings.annotation_sync }
+    end
+    if NetworkMgr:willRerunWhenOnline(run) then
+        return
+    end
+    run()
+end
+
+-- Events
+
+function BookOrbit:_onCloseDocument()
+    logger.dbg("BookOrbit: onCloseDocument")
+    self.onResume = nil
+    self.onSuspend = nil
+    UIManager:unschedule(self.periodic_push_task)
+    self.periodic_push_scheduled = false
+
+    if BookOrbitSweep.isRunning() or BookOrbitBookSync.isRunning() then
+        logger.dbg("BookOrbit: close sync skipped, another sync is running")
+        return
+    end
+
+    -- Snapshot now: reader objects die after this handler returns. ReaderUI
+    -- already flushed the sidecar and statistics before broadcasting
+    -- CloseDocument, so memory, sidecar and stats DB agree at this point.
+    local snap = BookOrbitBookSync.capture(self)
+    if not snap then return end
+
+    local api_opts = self:apiOpts()
+    NetworkMgr:goOnlineToRun(function()
+        BookOrbitBookSync.run{ api = api_opts, snap = snap, reason = "close", interactive = false,
+            annotation_sync = self.settings.annotation_sync }
+    end)
+end
+
+function BookOrbit:_onPageUpdate(page)
+    if page == nil then return end
+    if self.last_page ~= page then
+        self.last_page = page
+        self.last_page_turn_timestamp = os.time()
+        self.page_update_counter = self.page_update_counter + 1
+        -- A pending periodic push is re-delayed on every page turn so it
+        -- only fires once the reader is actually idle.
+        if self.periodic_push_scheduled
+                or (self.settings.pages_before_update or 0) > 0 and self.page_update_counter >= self.settings.pages_before_update then
+            self:schedulePeriodicPush()
+        end
+    end
+end
+
+function BookOrbit:_onResume()
+    logger.dbg("BookOrbit: onResume")
+    if Device:hasWifiRestore() and NetworkMgr.wifi_was_on and G_reader_settings:isTrue("auto_restore_wifi") then
+        return
+    end
+    UIManager:scheduleIn(1, function()
+        self:getProgress(true, false)
+    end)
+end
+
+function BookOrbit:_onSuspend()
+    logger.dbg("BookOrbit: onSuspend")
+    UIManager:unschedule(self.periodic_push_task)
+    self.periodic_push_scheduled = false
+
+    if not self:isLoggedIn() then return end
+    if BookOrbitSweep.isRunning() or BookOrbitBookSync.isRunning() then return end
+
+    local snap = BookOrbitBookSync.capture(self)
+    if not snap then return end
+
+    local on_finish
+    if Device:hasWifiManager() then
+        on_finish = function() NetworkMgr:disableWifi() end
+    end
+    local api_opts = self:apiOpts()
+    -- Synchronous: the device is about to sleep, so the uploads must not be
+    -- parked on the scheduler (they would run after resume and then kill
+    -- wifi mid-read via on_finish).
+    local run = function()
+        BookOrbitBookSync.run{
+            api = api_opts, snap = snap, reason = "suspend",
+            interactive = false, synchronous = true, plugin = self, on_finish = on_finish,
+            annotation_sync = self.settings.annotation_sync,
+        }
+    end
+    if NetworkMgr:willRerunWhenOnline(run) then
+        return
+    end
+    run()
+end
+
+function BookOrbit:_onNetworkConnected()
+    logger.dbg("BookOrbit: onNetworkConnected")
+    UIManager:scheduleIn(0.5, function()
+        self:getProgress(false, false)
+        self:maybeCheckForUpdate(false)
+    end)
+end
+
+function BookOrbit:_onNetworkDisconnecting()
+    logger.dbg("BookOrbit: onNetworkDisconnecting")
+    self:updateProgress(false, false)
+end
+
+function BookOrbit:onBookOrbitPushProgress()
+    self:updateProgress(true, true)
+end
+
+function BookOrbit:onBookOrbitPullProgress()
+    self:getProgress(true, true)
+end
+
+function BookOrbit:onBookOrbitSyncNow()
+    self:startSweep()
+end
+
+function BookOrbit:onBookOrbitToggleAutoSync(toggle, from_menu)
+    if toggle == self.settings.auto_sync then
+        return true
+    end
+    if not self.settings.auto_sync
+            and Device:hasSeamlessWifiToggle()
+            and G_reader_settings:readSetting("wifi_enable_action") ~= "turn_on" then
+        UIManager:show(InfoMessage:new{
+            text = _("You will have to switch the 'Action when Wi-Fi is off' Network setting to 'turn on' to be able to enable this feature!"),
+        })
+        return true
+    end
+    self.settings.auto_sync = not self.settings.auto_sync
+    self:registerEvents()
+
+    if self.settings.auto_sync then
+        self:getProgress(true, true)
+    else
+        UIManager:unschedule(self.periodic_push_task)
+        self.periodic_push_scheduled = false
+        self.page_update_counter = 0
+        if from_menu then
+            self:updateProgress(true, true)
+        end
+    end
+
+    if not from_menu then
+        Notification:notify(self.settings.auto_sync and _("BookOrbit auto progress sync: on") or _("BookOrbit auto progress sync: off"))
+    end
+    return true
+end
+
+function BookOrbit:registerEvents()
+    if self.settings.auto_sync then
+        self.onCloseDocument = self._onCloseDocument
+        self.onPageUpdate = self._onPageUpdate
+        self.onResume = self._onResume
+        self.onSuspend = self._onSuspend
+        self.onNetworkConnected = self._onNetworkConnected
+        self.onNetworkDisconnecting = self._onNetworkDisconnecting
+    else
+        self.onCloseDocument = nil
+        self.onPageUpdate = nil
+        self.onResume = nil
+        self.onSuspend = nil
+        self.onNetworkConnected = nil
+        self.onNetworkDisconnecting = nil
+    end
+end
+
+function BookOrbit:onCloseWidget()
+    if self.periodic_push_task then
+        UIManager:unschedule(self.periodic_push_task)
+        self.periodic_push_task = nil
+    end
+end
+
+function BookOrbit:checkForUpdate()
+    if not self:isLoggedIn() then
+        promptLogin()
+        return
+    end
+    NetworkMgr:runWhenConnected(function()
+        self:doCheckForUpdate()
+    end)
+end
+
+function BookOrbit:maybeCheckForUpdate(interactive)
+    if not self:isLoggedIn() or self._checking_update or self._updating then return end
+    if BookOrbitSweep.isRunning() or BookOrbitBookSync.isRunning() then return end
+
+    local now = os.time()
+    if not interactive and now - (self.settings.update_check_last_at or 0) < UPDATE_CHECK_INTERVAL then
+        return
+    end
+
+    self._checking_update = true
+    local body, err = self:newClient():getPluginVersion()
+    self._checking_update = false
+
+    if not body then
+        if interactive then
+            UIManager:show(InfoMessage:new{
+                text = T(_("Could not check for update: %1"), tostring(err or "network error")),
+                timeout = 4,
+            })
+        else
+            logger.dbg("BookOrbit: plugin update check failed:", err)
+        end
+        return
+    end
+
+    self:handleUpdateVersionResponse(body, interactive, interactive or self.catalog_browser == nil)
+end
+
+function BookOrbit:doCheckForUpdate()
+    local checking = InfoMessage:new{ text = _("Checking for update...") }
+    UIManager:show(checking)
+
+    local body, err = self:newClient():getPluginVersion()
+    UIManager:close(checking)
+
+    if not body then
+        UIManager:show(InfoMessage:new{
+            text = T(_("Could not check for update: %1"), tostring(err or "network error")),
+            timeout = 4,
+        })
+        return
+    end
+
+    self:handleUpdateVersionResponse(body, true, true)
+end
+
+function BookOrbit:handleUpdateVersionResponse(body, interactive, prompt_allowed)
+    local server_ver = body.serverVersion or "unknown"
+    local plugin_latest = body.pluginVersion
+    self.settings.update_check_last_at = os.time()
+
+    if type(plugin_latest) ~= "string" or plugin_latest == "unknown" then
+        G_reader_settings:flush()
+        if interactive then
+            UIManager:show(InfoMessage:new{
+                text = _("Could not determine the latest plugin version from the server."),
+                timeout = 4,
+            })
+        end
+        return
+    end
+
+    self.settings.update_latest_version = plugin_latest
+    G_reader_settings:flush()
+
+    if BookOrbitUpdater.isNewer(plugin_latest, PLUGIN_VERSION) ~= true then
+        if interactive then
+            UIManager:show(InfoMessage:new{
+                text = T(_("Plugin is up to date (v%1).\nServer: v%2"), PLUGIN_VERSION, server_ver),
+                timeout = 4,
+            })
+        end
+        return
+    end
+
+    if not prompt_allowed then
+        return
+    end
+
+    if not interactive and self.settings.update_dismissed_version == plugin_latest then
+        return
+    end
+    if not interactive then
+        self.settings.update_dismissed_version = plugin_latest
+        G_reader_settings:flush()
+    end
+
+    UIManager:show(ConfirmBox:new{
+        text = T(_("Update available: v%1 -> v%2\nServer: v%3\n\nDownload and apply the update now?"),
+            PLUGIN_VERSION, plugin_latest, server_ver),
+        ok_text = _("Update"),
+        ok_callback = function()
+            self:applyUpdate(plugin_latest)
+        end,
+    })
+end
+
+function BookOrbit:applyUpdate(new_version)
+    if self._updating then
+        UIManager:show(InfoMessage:new{ text = _("An update is already in progress."), timeout = 3 })
+        return
+    end
+    self._updating = true
+    self:_doApplyUpdate(new_version)
+    self._updating = false
+end
+
+function BookOrbit:_doApplyUpdate(new_version)
+    if not self.path then
+        UIManager:show(InfoMessage:new{
+            text = _("Cannot determine plugin path. Update aborted."),
+            timeout = 3,
+        })
+        return
+    end
+
+    local progress = InfoMessage:new{ text = T(_("Downloading BookOrbit v%1..."), new_version) }
+    UIManager:show(progress)
+    UIManager:forceRePaint()
+
+    local ok, err = BookOrbitUpdater.apply(self:newClient(), self.path)
+    UIManager:close(progress)
+
+    if not ok then
+        local msg
+        if type(err) == "number" and err == 503 then
+            msg = _("Update failed: the server does not have the plugin package available.")
+        else
+            msg = T(_("Update failed: %1"), tostring(err or "unknown error"))
+        end
+        UIManager:show(InfoMessage:new{ text = msg, timeout = 6 })
+        return
+    end
+
+    UIManager:show(ConfirmBox:new{
+        text = T(_("BookOrbit v%1 installed. KOReader needs to restart to apply the update."), new_version),
+        ok_text = _("Restart now"),
+        ok_callback = function()
+            -- Exit code 85 triggers an app restart on Kobo and most e-ink platforms.
+            -- On other platforms KOReader exits cleanly; reopen it to apply the update.
+            UIManager:quit(UIManager.RETURN_CODE_REBOOT or 85)
+        end,
+        cancel_text = _("Later"),
+    })
+end
+
+return BookOrbit
diff --git a/packages/types/src/__tests__/reading-session-source-bucket.spec.ts b/packages/types/src/__tests__/reading-session-source-bucket.spec.ts
new file mode 100644
index 000000000..d19edd0f2
--- /dev/null
+++ b/packages/types/src/__tests__/reading-session-source-bucket.spec.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  READING_SESSION_SOURCE_BUCKETS,
+  READING_SESSION_SOURCE_BUCKET_LABELS,
+  emptySourceBucketRecord,
+  toReadingSessionSourceBucket,
+} from "../reading-session-source-bucket";
+
+describe("toReadingSessionSourceBucket", () => {
+  it("maps web to bookorbit", () => {
+    expect(toReadingSessionSourceBucket("web")).toBe("bookorbit");
+  });
+
+  it("maps manual to bookorbit", () => {
+    expect(toReadingSessionSourceBucket("manual")).toBe("bookorbit");
+  });
+
+  it("maps koreader to koreader", () => {
+    expect(toReadingSessionSourceBucket("koreader")).toBe("koreader");
+  });
+
+  it("maps kobo to kobo", () => {
+    expect(toReadingSessionSourceBucket("kobo")).toBe("kobo");
+  });
+
+  it("maps null/undefined to bookorbit", () => {
+    expect(toReadingSessionSourceBucket(null)).toBe("bookorbit");
+    expect(toReadingSessionSourceBucket(undefined)).toBe("bookorbit");
+  });
+});
+
+describe("reading session source bucket constants", () => {
+  it("exposes exactly three buckets", () => {
+    expect(READING_SESSION_SOURCE_BUCKETS).toEqual(["bookorbit", "koreader", "kobo"]);
+  });
+
+  it("labels every bucket", () => {
+    expect(READING_SESSION_SOURCE_BUCKET_LABELS).toEqual({
+      bookorbit: "BookOrbit",
+      koreader: "KOReader",
+      kobo: "Kobo",
+    });
+  });
+
+  it("builds a zero-filled record", () => {
+    expect(emptySourceBucketRecord()).toEqual({ bookorbit: 0, koreader: 0, kobo: 0 });
+  });
+});
diff --git a/packages/types/src/annotation.ts b/packages/types/src/annotation.ts
index 3e13be94d..da8ebc1d6 100644
--- a/packages/types/src/annotation.ts
+++ b/packages/types/src/annotation.ts
@@ -1,18 +1,90 @@
+export type AnnotationPositionStatus = "exact" | "repaired" | "failed" | "pending";
+
+export const KOBO_HIGHLIGHT_COLORS = [
+  { name: "yellow", label: "Yellow", hex: "#F6F3B3" },
+  { name: "green", label: "Green", hex: "#C6E09E" },
+  { name: "blue", label: "Blue", hex: "#B2E1E8" },
+  { name: "pink", label: "Pink", hex: "#E8AFCF" },
+] as const;
+
+export type KoboHighlightColorName = (typeof KOBO_HIGHLIGHT_COLORS)[number]["name"];
+
+export const KOREADER_HIGHLIGHT_COLORS = [
+  { name: "red", label: "Red", hex: "#FF3300", appHex: "#F87171", koboFallback: "pink" },
+  { name: "orange", label: "Orange", hex: "#FF8800", appHex: "#FB923C", koboFallback: "yellow" },
+  { name: "yellow", label: "Yellow", hex: "#FFFF33", appHex: "#FACC15", koboFallback: "yellow" },
+  { name: "green", label: "Green", hex: "#00AA66", appHex: "#4ADE80", koboFallback: "green" },
+  { name: "olive", label: "Olive", hex: "#88FF77", appHex: "#84CC16", koboFallback: "green" },
+  { name: "cyan", label: "Cyan", hex: "#00FFEE", appHex: "#22D3EE", koboFallback: "blue" },
+  { name: "blue", label: "Blue", hex: "#0066FF", appHex: "#38BDF8", koboFallback: "blue" },
+  { name: "purple", label: "Purple", hex: "#EE00FF", appHex: "#C084FC", koboFallback: "pink" },
+  { name: "gray", label: "Gray", hex: "#808080", appHex: "#9CA3AF", koboFallback: "yellow" },
+] as const satisfies readonly {
+  name: string;
+  label: string;
+  hex: string;
+  appHex: string;
+  koboFallback: KoboHighlightColorName;
+}[];
+
+export type KoreaderHighlightColorName = (typeof KOREADER_HIGHLIGHT_COLORS)[number]["name"];
+
+export const ANNOTATION_HIGHLIGHT_COLORS = [
+  { name: "yellow", label: "Yellow", hex: "#FACC15", koreaderFallback: "yellow", koboFallback: "yellow" },
+  { name: "green", label: "Green", hex: "#4ADE80", koreaderFallback: "green", koboFallback: "green" },
+  { name: "blue", label: "Blue", hex: "#38BDF8", koreaderFallback: "blue", koboFallback: "blue" },
+  { name: "pink", label: "Pink", hex: "#F472B6", koreaderFallback: "purple", koboFallback: "pink" },
+  { name: "orange", label: "Orange", hex: "#FB923C", koreaderFallback: "orange", koboFallback: "yellow" },
+  { name: "red", label: "Red", hex: "#F87171", koreaderFallback: "red", koboFallback: "pink" },
+  { name: "olive", label: "Olive", hex: "#84CC16", koreaderFallback: "olive", koboFallback: "green" },
+  { name: "cyan", label: "Cyan", hex: "#22D3EE", koreaderFallback: "cyan", koboFallback: "blue" },
+  { name: "purple", label: "Purple", hex: "#C084FC", koreaderFallback: "purple", koboFallback: "pink" },
+  { name: "gray", label: "Gray", hex: "#9CA3AF", koreaderFallback: "gray", koboFallback: "yellow" },
+] as const satisfies readonly {
+  name: string;
+  label: string;
+  hex: string;
+  koreaderFallback: KoreaderHighlightColorName;
+  koboFallback: KoboHighlightColorName;
+}[];
+
+export type AnnotationHighlightColorName = (typeof ANNOTATION_HIGHLIGHT_COLORS)[number]["name"];
+
+export const KOREADER_EXACT_HIGHLIGHT_COLORS = [
+  { hex: "#FF3300", label: "KOReader Red" },
+  { hex: "#FF8800", label: "KOReader Orange" },
+  { hex: "#FFFF33", label: "KOReader Yellow" },
+  { hex: "#00AA66", label: "KOReader Green" },
+  { hex: "#88FF77", label: "KOReader Olive" },
+  { hex: "#00FFEE", label: "KOReader Cyan" },
+  { hex: "#0066FF", label: "KOReader Blue" },
+  { hex: "#EE00FF", label: "KOReader Purple" },
+  { hex: "#808080", label: "KOReader Gray" },
+] as const;
+
+export const ANNOTATION_COLOR_FILTER_OPTIONS = [...ANNOTATION_HIGHLIGHT_COLORS, ...KOREADER_EXACT_HIGHLIGHT_COLORS] as const;
+
 export interface AnnotationItem {
   id: number;
   bookId: number;
-  cfi: string;
+  cfi: string | null;
+  jumpFileId: number | null;
+  pageno: number | null;
   text: string;
   color: string;
   style: string;
   note: string | null;
   chapterTitle: string | null;
+  origin: "web" | "koreader" | "kobo";
+  positionStatus: AnnotationPositionStatus | null;
+  chapterIndex: number | null;
   createdAt: string;
 }
 
 export interface AnnotationStats {
   totalHighlights: number;
   colorBreakdown: { color: string; count: number }[];
+  originBreakdown: { origin: AnnotationItem["origin"]; count: number }[];
   chaptersWithHighlights: number;
   highlightsWithNotes: number;
   chapters: string[];
@@ -25,3 +97,58 @@ export interface AnnotationListResponse {
   pageSize: number;
   stats: AnnotationStats;
 }
+
+export interface AnnotationHubItem extends AnnotationItem {
+  bookTitle: string | null;
+  author: string | null;
+  deletedAt: string | null;
+}
+
+export interface AnnotationHubStats {
+  books: number;
+  withNotes: number;
+  originBreakdown: { origin: AnnotationItem["origin"]; count: number }[];
+}
+
+export interface AnnotationHubResponse {
+  items: AnnotationHubItem[];
+  total: number;
+  page: number;
+  pageSize: number;
+  stats: AnnotationHubStats;
+}
+
+export interface AnnotationHubBookFacet {
+  bookId: number;
+  bookTitle: string | null;
+  author: string | null;
+  count: number;
+}
+
+export type AnnotationPositionFormat = "cfi" | "xpointer" | "pdf" | "kobo_span";
+
+export interface AnnotationPositionInfo {
+  format: AnnotationPositionFormat;
+  status: AnnotationPositionStatus;
+  reason: string | null;
+  converterVersion: number | null;
+  updatedAt: string;
+}
+
+export interface AnnotationDeviceSyncInfo {
+  source: "koreader" | "kobo";
+  deviceId: string;
+  deviceName: string | null;
+  lastAppliedVersion: number;
+  upToDate: boolean;
+  deleteAckedAt: string | null;
+  lastSyncedAt: string;
+}
+
+export interface AnnotationSyncDetail {
+  annotationId: number;
+  origin: AnnotationItem["origin"];
+  version: number;
+  positions: AnnotationPositionInfo[];
+  devices: AnnotationDeviceSyncInfo[];
+}
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 6fb4c9efe..a33713da4 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -44,6 +44,7 @@ export * from "./font";
 export * from "./dictionary";
 export * from "./achievement";
 export * from "./reading-session";
+export * from "./reading-session-source-bucket";
 export * from "./annotation";
 export * from "./hardcover";
 export * from "./path";
diff --git a/packages/types/src/kobo.ts b/packages/types/src/kobo.ts
index bd6e21b34..dc6ed9cc2 100644
--- a/packages/types/src/kobo.ts
+++ b/packages/types/src/kobo.ts
@@ -16,6 +16,7 @@ export interface KoboSyncSettings {
   forceEnableHyphenation: boolean;
   kepubConversionLimitMb: number;
   twoWayProgressSync: boolean;
+  syncBookOrbitAnnotationsToKobo: boolean;
 }
 
 export interface CreateKoboDeviceRequest {
@@ -33,4 +34,5 @@ export interface UpdateKoboSyncSettingsRequest {
   forceEnableHyphenation?: boolean;
   kepubConversionLimitMb?: number;
   twoWayProgressSync?: boolean;
+  syncBookOrbitAnnotationsToKobo?: boolean;
 }
diff --git a/packages/types/src/koreader.ts b/packages/types/src/koreader.ts
index 22ca2cbc6..345e330a8 100644
--- a/packages/types/src/koreader.ts
+++ b/packages/types/src/koreader.ts
@@ -20,11 +20,36 @@ export interface KoreaderBookProgress {
   updatedAt: string;
 }
 
+export interface KoreaderDeviceSweepInfo {
+  deviceId: string;
+  deviceModel: string;
+  pluginVersion: string | null;
+  latestPluginVersion: string | null;
+  updateAvailable: boolean | null;
+  lastSweepAt: string;
+  lastSweepBooksMatched: number;
+  lastSweepPageStats: number;
+  lastSweepAnnotations: number;
+}
+
+export interface KoreaderPluginTotals {
+  matchedBooks: number;
+  trashedAnnotations: number;
+  pendingDeletes: number;
+  failedPositions: number;
+  pageStatEvents: number;
+  annotations: number;
+}
+
 export interface KoreaderSyncStatus {
   credentials: KoreaderCredentials | null;
   devices: KoreaderDeviceInfo[];
   totalSyncedBooks: number;
   lastSyncAt: string | null;
+  latestPluginVersion: string | null;
+  pluginUpdateAvailable: boolean;
+  sweeps: KoreaderDeviceSweepInfo[];
+  pluginTotals: KoreaderPluginTotals;
 }
 
 export interface KoreaderBookSyncInfo {
@@ -55,3 +80,125 @@ export interface TestKoreaderConnectionResult {
   username: string;
   serverUrl: string;
 }
+
+export type KoreaderCatalogSection =
+  | "libraries"
+  | "collections"
+  | "smart-scopes"
+  | "authors"
+  | "series"
+  | "search"
+  | "recent"
+  | "all-books"
+  | "continue-reading";
+
+export type KoreaderCatalogSort = "title" | "author" | "recently_added" | "recently_updated" | "recently_read" | "series";
+
+export type KoreaderCatalogSortOrder = "asc" | "desc";
+
+export type KoreaderCatalogReadStatusFilter = "unread" | "reading" | "finished";
+
+// Read statuses the catalog detail page can set on a book. A subset of the
+// full ReadStatus enum, chosen for reading-device ergonomics.
+export type KoreaderCatalogSettableReadStatus = "want_to_read" | "reading" | "on_hold" | "read" | "abandoned";
+
+export interface KoreaderCatalogSeriesSummary {
+  total: number;
+  finished: number;
+}
+
+export interface KoreaderCatalogEntry {
+  id: string;
+  title: string;
+  section: KoreaderCatalogSection;
+  subtitle?: string | null;
+  count?: number;
+  icon?: string | null;
+  href?: string;
+  booksHref?: string;
+}
+
+export interface KoreaderCatalogFile {
+  id: number;
+  format: string;
+  role: string;
+  sizeBytes: number | null;
+  durationSeconds: number | null;
+  downloadUrl: string;
+}
+
+export interface KoreaderCatalogProgress {
+  fileId: number;
+  percentage: number;
+  koreaderProgress: string | null;
+  updatedAt: string;
+}
+
+export interface KoreaderCatalogBookListItem {
+  id: number;
+  title: string;
+  authors: string[];
+  seriesName: string | null;
+  seriesIndex: number | null;
+  progressPercentage: number | null;
+  readStatus: string | null;
+  formats: string[];
+  hasCover: boolean;
+  thumbnailUrl: string | null;
+  detailUrl: string;
+  addedAt: string;
+  updatedAt: string;
+}
+
+export interface KoreaderCatalogBookDetail extends KoreaderCatalogBookListItem {
+  subtitle: string | null;
+  description: string | null;
+  publisher: string | null;
+  publishedYear: number | null;
+  language: string | null;
+  isbn10: string | null;
+  isbn13: string | null;
+  libraryId: number;
+  libraryName: string;
+  rating: number | null;
+  pageCount: number | null;
+  collections: { id: number; name: string }[];
+  genres: string[];
+  tags: string[];
+  progress: KoreaderCatalogProgress | null;
+  files: KoreaderCatalogFile[];
+}
+
+export interface KoreaderCatalogPage<T> {
+  items: T[];
+  total: number;
+  page: number;
+  size: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+  nextUrl: string | null;
+  previousUrl: string | null;
+  // Present when the page is scoped to a single series, summarising
+  // read-through progress across the whole series.
+  seriesSummary?: KoreaderCatalogSeriesSummary | null;
+}
+
+export interface KoreaderCatalogSectionResponse {
+  section: KoreaderCatalogSection;
+  items: KoreaderCatalogEntry[];
+  // Pagination is only emitted for large sections (authors, series).
+  page?: number;
+  hasNext?: boolean;
+  hasPrevious?: boolean;
+  nextUrl?: string | null;
+  previousUrl?: string | null;
+  query?: string | null;
+}
+
+export interface KoreaderCatalogReadStatusResult {
+  readStatus: KoreaderCatalogSettableReadStatus;
+}
+
+export interface KoreaderCatalogRatingResult {
+  rating: number | null;
+}
diff --git a/packages/types/src/reading-session-source-bucket.ts b/packages/types/src/reading-session-source-bucket.ts
new file mode 100644
index 000000000..53a185ffd
--- /dev/null
+++ b/packages/types/src/reading-session-source-bucket.ts
@@ -0,0 +1,22 @@
+import type { ReadingSessionSource } from "./reading-session";
+
+export const READING_SESSION_SOURCE_BUCKETS = ["bookorbit", "koreader", "kobo"] as const;
+export type ReadingSessionSourceBucket = (typeof READING_SESSION_SOURCE_BUCKETS)[number];
+
+export const READING_SESSION_SOURCE_BUCKET_LABELS: Record<ReadingSessionSourceBucket, string> = {
+  bookorbit: "BookOrbit",
+  koreader: "KOReader",
+  kobo: "Kobo",
+};
+
+// web/manual are both native BookOrbit surfaces; null/unknown (and historical Kobo-as-web
+// sessions that predate source tagging) collapse into the BookOrbit bucket by design.
+export function toReadingSessionSourceBucket(source: ReadingSessionSource | null | undefined): ReadingSessionSourceBucket {
+  if (source === "koreader") return "koreader";
+  if (source === "kobo") return "kobo";
+  return "bookorbit";
+}
+
+export function emptySourceBucketRecord(): Record<ReadingSessionSourceBucket, number> {
+  return { bookorbit: 0, koreader: 0, kobo: 0 };
+}
diff --git a/packages/types/src/reading-session.ts b/packages/types/src/reading-session.ts
index c03e10c0a..f841ee348 100644
--- a/packages/types/src/reading-session.ts
+++ b/packages/types/src/reading-session.ts
@@ -1,3 +1,8 @@
+import type { ReadingSessionSourceBucket } from "./reading-session-source-bucket";
+
+export const READING_SESSION_SOURCES = ["web", "koreader", "manual", "kobo"] as const;
+export type ReadingSessionSource = (typeof READING_SESSION_SOURCES)[number];
+
 export interface BookReadingSession {
   id: number;
   startedAt: string;
@@ -6,6 +11,13 @@ export interface BookReadingSession {
   progressDelta: number | null;
   endProgress: number | null;
   format: string | null;
+  source: ReadingSessionSource | null;
+}
+
+export interface BookReadingSourceSlice {
+  bucket: ReadingSessionSourceBucket;
+  totalSeconds: number;
+  totalSessions: number;
 }
 
 export interface BookReadingSessionStats {
@@ -15,6 +27,12 @@ export interface BookReadingSessionStats {
   firstSessionAt: string | null;
   lastSessionAt: string | null;
   dailySummary: { day: string; totalMinutes: number }[];
+  paceProgressDelta: number;
+  paceDurationSeconds: number;
+  progressSummary: { day: string; endProgress: number }[];
+  // Reading time/sessions split across the 3 display buckets, ordered by
+  // READING_SESSION_SOURCE_BUCKETS; only buckets with activity are included.
+  bySource: BookReadingSourceSlice[];
 }
 
 export interface BookReadingSessionListResponse {
diff --git a/packages/types/src/statistics.ts b/packages/types/src/statistics.ts
index c23c5100e..be3a91665 100644
--- a/packages/types/src/statistics.ts
+++ b/packages/types/src/statistics.ts
@@ -12,6 +12,7 @@ export type StatisticsChartId =
   | "format-share-over-time"
   | "page-count-distribution"
   | "reading-heatmap"
+  | "reading-source-distribution"
   | "peak-reading-hours"
   | "favorite-reading-days"
   | "completion-timeline"
@@ -78,6 +79,7 @@ export const DEFAULT_LIBRARY_CHART_ORDER: StatisticsChartId[] = [
 
 export const DEFAULT_USER_CHART_ORDER: StatisticsChartId[] = [
   "reading-heatmap",
+  "reading-source-distribution",
   "peak-reading-hours",
   "favorite-reading-days",
   "completion-timeline",
diff --git a/packages/types/src/user-statistics.ts b/packages/types/src/user-statistics.ts
index 8527db1a4..268d6b5d4 100644
--- a/packages/types/src/user-statistics.ts
+++ b/packages/types/src/user-statistics.ts
@@ -1,3 +1,5 @@
+import type { ReadingSessionSourceBucket } from "./reading-session-source-bucket";
+
 export interface UserStatisticsSummary {
   trackedBooks: number;
   startedBooks: number;
@@ -11,6 +13,19 @@ export interface UserDailyReadingStat {
   readingSeconds: number;
   progressDelta: number;
   eventsCount: number;
+  // Populated only by the reading heatmap (per-source tooltip); other daily-stat
+  // consumers leave it undefined.
+  bySource?: Record<ReadingSessionSourceBucket, number>;
+}
+
+export interface UserReadingSourceDistributionSlice {
+  bucket: ReadingSessionSourceBucket;
+  readingSeconds: number;
+}
+
+export interface UserReadingSourceDistribution {
+  totalSeconds: number;
+  slices: UserReadingSourceDistributionSlice[];
 }
 
 export interface UserPeakHourStat {
@@ -18,12 +33,15 @@ export interface UserPeakHourStat {
   readingSeconds: number;
   eventsCount: number;
   byFormat: Record<string, number>;
+  bySource: Record<ReadingSessionSourceBucket, number>;
 }
 
 export interface UserFavoriteDayStat {
   dayOfWeek: number;
   readingSeconds: number;
   eventsCount: number;
+  byFormat: Record<string, number>;
+  bySource: Record<ReadingSessionSourceBucket, number>;
 }
 
 export interface UserCompletionTimelinePoint {
@@ -76,6 +94,7 @@ export interface UserCompletionLatencyDistribution {
 export interface UserGenreReadingTimeItem {
   genre: string;
   readingSeconds: number;
+  bySource: Record<ReadingSessionSourceBucket, number>;
 }
 
 export interface UserReadingSessionTimelineItem {
@@ -83,6 +102,7 @@ export interface UserReadingSessionTimelineItem {
   bookId: number;
   bookTitle: string | null;
   bookFormat: string | null;
+  bookSource: ReadingSessionSourceBucket;
   startedAt: string;
   endedAt: string;
   durationSeconds: number;
@@ -99,6 +119,8 @@ export interface UserReadingSessionTimeline {
 export interface UserReadingPacePoint {
   durationSeconds: number;
   progressDelta: number;
+  bucket: ReadingSessionSourceBucket;
+  format: string;
 }
 
 export interface UserReadingSurvivalPoint {
diff --git a/scripts/e2e/suite-registry.mjs b/scripts/e2e/suite-registry.mjs
index 656913000..13109c9e0 100644
--- a/scripts/e2e/suite-registry.mjs
+++ b/scripts/e2e/suite-registry.mjs
@@ -423,6 +423,64 @@ export const E2E_SUITES = Object.freeze({
       ...SHARED_DB_AND_HELPER_PATHS,
     ],
   },
+  "koreader-annotation-exchange": {
+    id: "koreader-annotation-exchange",
+    name: "KOReader Annotation Exchange",
+    timeout: 45,
+    lane: "full",
+    description: "KOReader annotation exchange suite",
+    vitestTarget: "test/koreader-annotation-exchange.e2e-spec.ts",
+    junitOutput: `${TEST_RESULTS_DIR}/koreader-annotation-exchange-e2e-junit.xml`,
+    prepareDedicatedDatabase: true,
+    useDedicatedDatabase: true,
+    changedPaths: [
+      "server/src/modules/annotation/**",
+      "server/src/modules/koreader/**",
+      "server/src/modules/position-converter/**",
+      "server/test/koreader-annotation-exchange.e2e-spec.ts",
+      "server/test/e2e/reader-state-isolation/**",
+      ...SHARED_DB_AND_HELPER_PATHS,
+    ],
+  },
+  "annotations-hub": {
+    id: "annotations-hub",
+    name: "Annotations Hub",
+    timeout: 45,
+    lane: "full",
+    description: "Annotations hub suite",
+    vitestTarget: "test/annotations-hub.e2e-spec.ts",
+    junitOutput: `${TEST_RESULTS_DIR}/annotations-hub-e2e-junit.xml`,
+    prepareDedicatedDatabase: true,
+    useDedicatedDatabase: true,
+    changedPaths: [
+      "server/src/modules/annotation/**",
+      "server/src/modules/position-converter/**",
+      "server/test/annotations-hub.e2e-spec.ts",
+      "server/test/e2e/reader-state-isolation/**",
+      ...SHARED_DB_AND_HELPER_PATHS,
+    ],
+  },
+  "kobo-annotation-sync": {
+    id: "kobo-annotation-sync",
+    name: "Kobo Annotation Sync",
+    timeout: 60,
+    lane: "full",
+    description: "Kobo annotation three-way sync suite",
+    vitestTarget: "test/kobo-annotation-sync.e2e-spec.ts",
+    junitOutput: `${TEST_RESULTS_DIR}/kobo-annotation-sync-e2e-junit.xml`,
+    prepareDedicatedDatabase: true,
+    useDedicatedDatabase: true,
+    changedPaths: [
+      "server/src/modules/annotation/**",
+      "server/src/modules/kobo/**",
+      "server/src/modules/koreader/**",
+      "server/src/modules/position-converter/**",
+      "server/test/kobo-annotation-sync.e2e-spec.ts",
+      "server/test/e2e/reader-state-isolation/**",
+      "packages/types/src/kobo.ts",
+      ...SHARED_DB_AND_HELPER_PATHS,
+    ],
+  },
   "users-admin-lifecycle": {
     id: "users-admin-lifecycle",
     name: "Users Admin Lifecycle",
diff --git a/server/.env.example b/server/.env.example
index d79dd73f1..0a6d7441a 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -22,6 +22,10 @@ APP_DATA_PATH=../local/data
 # FILE_WRITE_DEBOUNCE_MS=3000
 # FILE_WRITE_MAX_CONCURRENT_WRITES=2
 
+# KOReader plugin source folder served by the preconfigured plugin download (optional).
+# Defaults to <project-root>/koreader-plugin/bookorbit.koplugin in dev; the Docker image sets it.
+# KOREADER_PLUGIN_PATH=../koreader-plugin/bookorbit.koplugin
+
 # Optional: allow Cloudflare Web Analytics beacon in CSP when automatic setup is enabled.
 # Keep unset/false to preserve strict CSP (`script-src 'self'`).
 # CSP_ALLOW_CLOUDFLARE_INSIGHTS=false
diff --git a/server/src/common/utils/reading-daily-stats.utils.test.ts b/server/src/common/utils/reading-daily-stats.utils.test.ts
new file mode 100644
index 000000000..dfef3ba8e
--- /dev/null
+++ b/server/src/common/utils/reading-daily-stats.utils.test.ts
@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  aggregateReadingSessionDailyStats,
+  getDayRangeForDateKeys,
+  getReadingSessionDayKeys,
+  splitReadingSessionByDay,
+} from './reading-daily-stats.utils';
+
+describe('reading daily stats utils', () => {
+  it('keeps a same-day session on one local day', () => {
+    const result = splitReadingSessionByDay(
+      {
+        startedAt: new Date('2026-04-15T10:00:00.000Z'),
+        endedAt: new Date('2026-04-15T10:30:00.000Z'),
+        durationSeconds: 1800,
+        progressDelta: 4,
+      },
+      'UTC',
+    );
+
+    expect(result).toEqual([{ day: '2026-04-15', readingSeconds: 1800, progressDelta: 4, sessionsCount: 1 }]);
+  });
+
+  it('splits a continuous session across local midnight', () => {
+    const result = splitReadingSessionByDay(
+      {
+        startedAt: new Date('2026-04-16T03:00:00.000Z'),
+        endedAt: new Date('2026-04-16T04:30:00.000Z'),
+        durationSeconds: 5400,
+        progressDelta: 9,
+      },
+      'America/New_York',
+    );
+
+    expect(result).toEqual([
+      { day: '2026-04-15', readingSeconds: 3600, progressDelta: 6, sessionsCount: 1 },
+      { day: '2026-04-16', readingSeconds: 1800, progressDelta: 3, sessionsCount: 1 },
+    ]);
+  });
+
+  it('preserves total seconds when proportional pieces need rounding', () => {
+    const result = splitReadingSessionByDay(
+      {
+        startedAt: new Date('2026-04-15T23:59:58.000Z'),
+        endedAt: new Date('2026-04-16T00:00:01.000Z'),
+        durationSeconds: 10,
+        progressDelta: 1,
+      },
+      'UTC',
+    );
+
+    expect(result.reduce((sum, row) => sum + row.readingSeconds, 0)).toBe(10);
+    expect(result.map((row) => row.day)).toEqual(['2026-04-15', '2026-04-16']);
+  });
+
+  it('does not truncate sessions that span more than 400 local days', () => {
+    const result = splitReadingSessionByDay(
+      {
+        startedAt: new Date('2024-01-01T00:00:00.000Z'),
+        endedAt: new Date('2025-06-01T00:00:00.000Z'),
+        durationSeconds: 86400,
+        progressDelta: 10,
+      },
+      'UTC',
+    );
+
+    expect(result.at(-1)?.day).toBe('2025-05-31');
+    expect(result.reduce((sum, row) => sum + row.readingSeconds, 0)).toBe(86400);
+    expect(result.reduce((sum, row) => sum + row.progressDelta, 0)).toBeCloseTo(10);
+  });
+
+  it('returns local day keys for every day touched by a session', () => {
+    const result = getReadingSessionDayKeys(
+      {
+        startedAt: new Date('2026-04-16T03:00:00.000Z'),
+        endedAt: new Date('2026-04-16T04:30:00.000Z'),
+        durationSeconds: 5400,
+        progressDelta: 9,
+      },
+      'America/New_York',
+    );
+
+    expect(result).toEqual(['2026-04-15', '2026-04-16']);
+  });
+
+  it('handles non-positive, invalid, and clockless sessions defensively', () => {
+    expect(
+      splitReadingSessionByDay(
+        {
+          startedAt: new Date('2026-04-15T10:00:00.000Z'),
+          endedAt: new Date('2026-04-15T10:00:00.000Z'),
+          durationSeconds: 0,
+          progressDelta: null,
+        },
+        'UTC',
+      ),
+    ).toEqual([]);
+
+    expect(
+      splitReadingSessionByDay(
+        {
+          startedAt: new Date(Number.NaN),
+          endedAt: new Date('2026-04-15T10:00:00.000Z'),
+          durationSeconds: 60,
+          progressDelta: null,
+        },
+        'UTC',
+      ),
+    ).toEqual([]);
+
+    expect(
+      splitReadingSessionByDay(
+        {
+          startedAt: new Date('2026-04-15T10:00:00.000Z'),
+          endedAt: new Date('2026-04-15T09:59:00.000Z'),
+          durationSeconds: 60,
+          progressDelta: null,
+        },
+        'UTC',
+      ),
+    ).toEqual([{ day: '2026-04-15', readingSeconds: 60, progressDelta: 0, sessionsCount: 1 }]);
+  });
+
+  it('aggregates only requested affected days', () => {
+    const result = aggregateReadingSessionDailyStats(
+      [
+        {
+          startedAt: new Date('2026-04-15T23:00:00.000Z'),
+          endedAt: new Date('2026-04-16T01:00:00.000Z'),
+          durationSeconds: 7200,
+          progressDelta: null,
+        },
+        {
+          startedAt: new Date('2026-04-16T10:00:00.000Z'),
+          endedAt: new Date('2026-04-16T10:30:00.000Z'),
+          durationSeconds: 1800,
+          progressDelta: 2,
+        },
+      ],
+      'UTC',
+      new Set(['2026-04-16']),
+    );
+
+    expect(result).toEqual([{ day: '2026-04-16', readingSeconds: 5400, progressDelta: 2, sessionsCount: 2 }]);
+  });
+
+  it('builds an exclusive UTC range for timezone-local affected days', () => {
+    const range = getDayRangeForDateKeys(['2026-04-15', '2026-04-16'], 'America/New_York');
+
+    expect(range?.start.toISOString()).toBe('2026-04-15T04:00:00.000Z');
+    expect(range?.end.toISOString()).toBe('2026-04-17T04:00:00.000Z');
+  });
+
+  it('returns null for an empty affected-day range', () => {
+    expect(getDayRangeForDateKeys([], 'UTC')).toBeNull();
+  });
+});
diff --git a/server/src/common/utils/reading-daily-stats.utils.ts b/server/src/common/utils/reading-daily-stats.utils.ts
new file mode 100644
index 000000000..d79ad218e
--- /dev/null
+++ b/server/src/common/utils/reading-daily-stats.utils.ts
@@ -0,0 +1,121 @@
+import { toDateKeyInTimeZone, toTimeZoneStartOfDay } from './timezone.utils';
+
+export interface ReadingSessionDailyStatsInput {
+  startedAt: Date;
+  endedAt: Date;
+  durationSeconds: number;
+  progressDelta: number | null;
+}
+
+export interface ReadingDailyStatsSegment {
+  day: string;
+  readingSeconds: number;
+  progressDelta: number;
+  sessionsCount: number;
+}
+
+export interface ReadingDailyStatsDayRange {
+  start: Date;
+  end: Date;
+}
+
+export function addDateKeyDays(dateKey: string, days: number): string {
+  const [year, month, day] = dateKey.split('-').map(Number);
+  const date = new Date(Date.UTC(year!, month! - 1, day! + days));
+  return date.toISOString().slice(0, 10);
+}
+
+export function getReadingSessionDayKeys(session: ReadingSessionDailyStatsInput, timeZone: string): string[] {
+  return splitReadingSessionByDay(session, timeZone).map((segment) => segment.day);
+}
+
+export function getDayRangeForDateKeys(days: string[], timeZone: string): ReadingDailyStatsDayRange | null {
+  if (days.length === 0) return null;
+  const sorted = [...new Set(days)].sort();
+  const firstDay = sorted[0]!;
+  const lastExclusive = addDateKeyDays(sorted[sorted.length - 1]!, 1);
+  return {
+    start: toTimeZoneStartOfDay(firstDay, timeZone),
+    end: toTimeZoneStartOfDay(lastExclusive, timeZone),
+  };
+}
+
+export function splitReadingSessionByDay(session: ReadingSessionDailyStatsInput, timeZone: string): ReadingDailyStatsSegment[] {
+  if (session.durationSeconds <= 0) return [];
+
+  const startMs = session.startedAt.getTime();
+  const endMs = session.endedAt.getTime();
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return [];
+
+  const wallClockMs = endMs - startMs;
+  if (wallClockMs <= 0) {
+    return [
+      {
+        day: toDateKeyInTimeZone(session.startedAt, timeZone),
+        readingSeconds: session.durationSeconds,
+        progressDelta: session.progressDelta ?? 0,
+        sessionsCount: 1,
+      },
+    ];
+  }
+
+  const pieces: Array<{ day: string; rawSeconds: number; fractional: number }> = [];
+  let cursor = new Date(startMs);
+
+  while (cursor.getTime() < endMs) {
+    const day = toDateKeyInTimeZone(cursor, timeZone);
+    const nextDayStart = toTimeZoneStartOfDay(addDateKeyDays(day, 1), timeZone);
+    const nextBoundaryMs = nextDayStart.getTime() > cursor.getTime() ? nextDayStart.getTime() : endMs;
+    const segmentEndMs = Math.min(endMs, nextBoundaryMs);
+    const overlapMs = Math.max(0, segmentEndMs - cursor.getTime());
+    const rawSeconds = (session.durationSeconds * overlapMs) / wallClockMs;
+    pieces.push({ day, rawSeconds, fractional: rawSeconds - Math.floor(rawSeconds) });
+    cursor = new Date(segmentEndMs);
+  }
+
+  if (pieces.length === 0) return [];
+
+  const secondsByIndex = pieces.map((piece) => Math.floor(piece.rawSeconds));
+  let remainder = session.durationSeconds - secondsByIndex.reduce((sum, seconds) => sum + seconds, 0);
+  const remainderOrder = pieces.map((piece, index) => ({ index, fractional: piece.fractional })).sort((a, b) => b.fractional - a.fractional);
+
+  for (const { index } of remainderOrder) {
+    if (remainder <= 0) break;
+    secondsByIndex[index] += 1;
+    remainder -= 1;
+  }
+
+  return pieces
+    .map((piece, index) => {
+      const readingSeconds = secondsByIndex[index] ?? 0;
+      return {
+        day: piece.day,
+        readingSeconds,
+        progressDelta: session.progressDelta == null ? 0 : session.progressDelta * (readingSeconds / session.durationSeconds),
+        sessionsCount: 1,
+      };
+    })
+    .filter((segment) => segment.readingSeconds > 0);
+}
+
+export function aggregateReadingSessionDailyStats(
+  sessions: ReadingSessionDailyStatsInput[],
+  timeZone: string,
+  days?: Set<string>,
+): ReadingDailyStatsSegment[] {
+  const byDay = new Map<string, ReadingDailyStatsSegment>();
+  for (const session of sessions) {
+    for (const segment of splitReadingSessionByDay(session, timeZone)) {
+      if (days && !days.has(segment.day)) continue;
+      const existing = byDay.get(segment.day);
+      if (existing) {
+        existing.readingSeconds += segment.readingSeconds;
+        existing.progressDelta += segment.progressDelta;
+        existing.sessionsCount += segment.sessionsCount;
+      } else {
+        byDay.set(segment.day, { ...segment });
+      }
+    }
+  }
+  return [...byDay.values()].sort((a, b) => a.day.localeCompare(b.day));
+}
diff --git a/server/src/common/utils/semver.utils.test.ts b/server/src/common/utils/semver.utils.test.ts
new file mode 100644
index 000000000..5fe74952c
--- /dev/null
+++ b/server/src/common/utils/semver.utils.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { isSemverNewer } from './semver.utils';
+
+describe('isSemverNewer', () => {
+  it.each([
+    ['1.0.1', '1.0.0'],
+    ['1.1.0', '1.0.9'],
+    ['2.0.0', '1.99.99'],
+    ['v1.2.3', '1.2.2'],
+    ['1.2.3-beta.1', '1.2.2'],
+  ])('returns true when %s is newer than %s', (candidate, current) => {
+    expect(isSemverNewer(candidate, current)).toBe(true);
+  });
+
+  it.each([
+    ['1.0.0', '1.0.0'],
+    ['1.0.0', '1.0.1'],
+    ['1.1.0', '2.0.0'],
+    ['v1.2.3', '1.2.3'],
+  ])('returns false when %s is not newer than %s', (candidate, current) => {
+    expect(isSemverNewer(candidate, current)).toBe(false);
+  });
+
+  it.each([
+    [null, '1.0.0'],
+    ['unknown', '1.0.0'],
+    ['1.0.0', null],
+    ['1.0', '1.0.0'],
+    ['1.0.0', 'local-build'],
+  ])('returns null when %s cannot be compared to %s', (candidate, current) => {
+    expect(isSemverNewer(candidate, current)).toBeNull();
+  });
+});
diff --git a/server/src/common/utils/semver.utils.ts b/server/src/common/utils/semver.utils.ts
new file mode 100644
index 000000000..f6e348ee7
--- /dev/null
+++ b/server/src/common/utils/semver.utils.ts
@@ -0,0 +1,15 @@
+export function isSemverNewer(candidate: string | null | undefined, current: string | null | undefined): boolean | null {
+  const parsedCandidate = parseSemver(candidate);
+  const parsedCurrent = parseSemver(current);
+  if (!parsedCandidate || !parsedCurrent) return null;
+  if (parsedCandidate[0] !== parsedCurrent[0]) return parsedCandidate[0] > parsedCurrent[0];
+  if (parsedCandidate[1] !== parsedCurrent[1]) return parsedCandidate[1] > parsedCurrent[1];
+  return parsedCandidate[2] > parsedCurrent[2];
+}
+
+function parseSemver(version: string | null | undefined): [number, number, number] | null {
+  if (!version) return null;
+  const match = version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]!), Number(match[2]!), Number(match[3]!)];
+}
diff --git a/server/src/config/config.ts b/server/src/config/config.ts
index 683ff5145..a624eded1 100644
--- a/server/src/config/config.ts
+++ b/server/src/config/config.ts
@@ -9,6 +9,7 @@ export const appConfig = registerAs('app', () => ({
   githubReleasesToken: process.env.GITHUB_RELEASES_TOKEN?.trim() || undefined,
   oidcAllowLocalIssuers: parseBooleanFlag(process.env.OIDC_ALLOW_LOCAL_ISSUERS, false),
   koboCloudscraperPython: process.env.KOBO_CLOUDSCRAPER_PYTHON?.trim() || undefined,
+  koreaderPluginSourcePath: process.env.KOREADER_PLUGIN_PATH?.trim() || undefined,
 }));
 
 export const dbConfig = registerAs('db', () => ({
diff --git a/server/src/config/env.validation.ts b/server/src/config/env.validation.ts
index e3a5b7f80..e87bacb29 100644
--- a/server/src/config/env.validation.ts
+++ b/server/src/config/env.validation.ts
@@ -71,6 +71,10 @@ const envSchema = z.object({
     .string()
     .transform((val) => val.trim())
     .optional(),
+  KOREADER_PLUGIN_PATH: z
+    .string()
+    .transform((val) => val.trim())
+    .optional(),
 });
 
 export function validateEnv(config: Record<string, unknown>) {
diff --git a/server/src/db/migrations/0027_consolidated-koreader-annotations.sql b/server/src/db/migrations/0027_consolidated-koreader-annotations.sql
new file mode 100644
index 000000000..81ac54a18
--- /dev/null
+++ b/server/src/db/migrations/0027_consolidated-koreader-annotations.sql
@@ -0,0 +1,93 @@
+CREATE TABLE "annotation_positions" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"annotation_id" integer NOT NULL,
+	"user_id" integer NOT NULL,
+	"book_file_id" integer,
+	"format" varchar(12) NOT NULL,
+	"pos0" text,
+	"pos1" text,
+	"status" varchar(10) DEFAULT 'exact' NOT NULL,
+	"converter_version" integer,
+	"extras" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "annotation_positions_format_chk" CHECK ("annotation_positions"."format" in ('cfi', 'xpointer', 'pdf', 'kobo_span')),
+	CONSTRAINT "annotation_positions_status_chk" CHECK ("annotation_positions"."status" in ('exact', 'repaired', 'failed', 'pending')),
+	CONSTRAINT "annotation_positions_pos0_chk" CHECK ("annotation_positions"."status" in ('failed', 'pending') or "annotation_positions"."pos0" is not null)
+);
+--> statement-breakpoint
+CREATE TABLE "annotation_sync_state" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"annotation_id" integer NOT NULL,
+	"user_id" integer NOT NULL,
+	"source" varchar(10) NOT NULL,
+	"device_id" varchar(100) NOT NULL,
+	"external_key" varchar(64) NOT NULL,
+	"external_created_at" varchar(19),
+	"last_applied_version" integer DEFAULT 0 NOT NULL,
+	"delete_acked_at" timestamp with time zone,
+	"first_synced_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_synced_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "annotation_sync_state_source_chk" CHECK ("annotation_sync_state"."source" in ('koreader', 'kobo'))
+);
+--> statement-breakpoint
+CREATE TABLE "koreader_device_sweeps" (
+	"user_id" integer NOT NULL,
+	"device_id" varchar(100) NOT NULL,
+	"device_model" varchar(100) DEFAULT 'KOReader' NOT NULL,
+	"plugin_version" varchar(20),
+	"last_sweep_at" timestamp with time zone NOT NULL,
+	"last_sweep_books_matched" integer DEFAULT 0 NOT NULL,
+	"last_sweep_page_stats" integer DEFAULT 0 NOT NULL,
+	"last_sweep_annotations" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "koreader_device_sweeps_user_id_device_id_pk" PRIMARY KEY("user_id","device_id")
+);
+--> statement-breakpoint
+CREATE TABLE "koreader_page_stats" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"user_id" integer NOT NULL,
+	"book_file_id" integer NOT NULL,
+	"device_id" varchar(100) NOT NULL,
+	"page" integer NOT NULL,
+	"start_time" bigint NOT NULL,
+	"duration_seconds" integer NOT NULL,
+	"total_pages" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "koreader_page_stats_duration_nonnegative_chk" CHECK ("koreader_page_stats"."duration_seconds" >= 0),
+	CONSTRAINT "koreader_page_stats_page_nonnegative_chk" CHECK ("koreader_page_stats"."page" >= 0),
+	CONSTRAINT "koreader_page_stats_total_pages_positive_chk" CHECK ("koreader_page_stats"."total_pages" > 0),
+	CONSTRAINT "koreader_page_stats_start_time_positive_chk" CHECK ("koreader_page_stats"."start_time" > 0)
+);
+--> statement-breakpoint
+ALTER TABLE "annotations" DROP CONSTRAINT "annotations_style_chk";--> statement-breakpoint
+ALTER TABLE "annotations" ADD COLUMN "origin" varchar(10) DEFAULT 'web' NOT NULL;--> statement-breakpoint
+ALTER TABLE "annotations" ADD COLUMN "version" integer DEFAULT 1 NOT NULL;--> statement-breakpoint
+ALTER TABLE "annotations" ADD COLUMN "deleted_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "annotations" ADD COLUMN "device_created_at" varchar(19);--> statement-breakpoint
+ALTER TABLE "annotations" ADD COLUMN "device_updated_at" varchar(19);--> statement-breakpoint
+ALTER TABLE "annotation_positions" ADD CONSTRAINT "annotation_positions_annotation_id_annotations_id_fk" FOREIGN KEY ("annotation_id") REFERENCES "public"."annotations"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "annotation_positions" ADD CONSTRAINT "annotation_positions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "annotation_positions" ADD CONSTRAINT "annotation_positions_book_file_id_book_files_id_fk" FOREIGN KEY ("book_file_id") REFERENCES "public"."book_files"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "annotation_sync_state" ADD CONSTRAINT "annotation_sync_state_annotation_id_annotations_id_fk" FOREIGN KEY ("annotation_id") REFERENCES "public"."annotations"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "annotation_sync_state" ADD CONSTRAINT "annotation_sync_state_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "koreader_device_sweeps" ADD CONSTRAINT "koreader_device_sweeps_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "koreader_page_stats" ADD CONSTRAINT "koreader_page_stats_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "koreader_page_stats" ADD CONSTRAINT "koreader_page_stats_book_file_id_book_files_id_fk" FOREIGN KEY ("book_file_id") REFERENCES "public"."book_files"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "annotation_positions_annotation_format_uidx" ON "annotation_positions" USING btree ("annotation_id","format");--> statement-breakpoint
+CREATE INDEX "annotation_positions_user_idx" ON "annotation_positions" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "annotation_positions_format_status_idx" ON "annotation_positions" USING btree ("format","status");--> statement-breakpoint
+CREATE UNIQUE INDEX "annotation_sync_state_annotation_source_device_uidx" ON "annotation_sync_state" USING btree ("annotation_id","source","device_id");--> statement-breakpoint
+CREATE INDEX "annotation_sync_state_user_source_device_key_idx" ON "annotation_sync_state" USING btree ("user_id","source","device_id","external_key");--> statement-breakpoint
+CREATE INDEX "annotation_sync_state_user_key_idx" ON "annotation_sync_state" USING btree ("user_id","external_key");--> statement-breakpoint
+CREATE INDEX "annotation_sync_state_annotation_id_idx" ON "annotation_sync_state" USING btree ("annotation_id");--> statement-breakpoint
+CREATE INDEX "kds_user_id_idx" ON "koreader_device_sweeps" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "kps_user_file_device_page_start_uidx" ON "koreader_page_stats" USING btree ("user_id","book_file_id","device_id","page","start_time");--> statement-breakpoint
+CREATE INDEX "kps_user_file_device_start_idx" ON "koreader_page_stats" USING btree ("user_id","book_file_id","device_id","start_time");--> statement-breakpoint
+CREATE INDEX "kps_user_id_idx" ON "koreader_page_stats" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "annotations_user_book_active_idx" ON "annotations" USING btree ("user_id","book_id") WHERE "annotations"."deleted_at" is null;--> statement-breakpoint
+INSERT INTO "annotation_positions" ("annotation_id", "user_id", "format", "pos0", "status", "converter_version")
+SELECT "id", "user_id", 'cfi', "cfi", 'exact', 0 FROM "annotations";--> statement-breakpoint
+ALTER TABLE "annotations" DROP COLUMN "cfi";--> statement-breakpoint
+ALTER TABLE "annotations" ADD CONSTRAINT "annotations_origin_chk" CHECK ("annotations"."origin" in ('web', 'koreader', 'kobo'));--> statement-breakpoint
+ALTER TABLE "annotations" ADD CONSTRAINT "annotations_style_chk" CHECK ("annotations"."style" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert'));
diff --git a/server/src/db/migrations/0028_kobo-annotation-spoke.sql b/server/src/db/migrations/0028_kobo-annotation-spoke.sql
new file mode 100644
index 000000000..6c8d2b37d
--- /dev/null
+++ b/server/src/db/migrations/0028_kobo-annotation-spoke.sql
@@ -0,0 +1,3 @@
+ALTER TABLE "kobo_devices" ADD COLUMN "client_device_id" varchar(128);--> statement-breakpoint
+ALTER TABLE "kobo_sync_settings" ADD COLUMN "sync_bookorbit_annotations_to_kobo" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "kobo_devices" ADD CONSTRAINT "kobo_devices_client_device_id_unique" UNIQUE("client_device_id");
\ No newline at end of file
diff --git a/server/src/db/migrations/0029_reading-session-source-book-id.sql b/server/src/db/migrations/0029_reading-session-source-book-id.sql
new file mode 100644
index 000000000..38c68a22b
--- /dev/null
+++ b/server/src/db/migrations/0029_reading-session-source-book-id.sql
@@ -0,0 +1,8 @@
+ALTER TABLE "reading_sessions" ALTER COLUMN "book_file_id" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "reading_sessions" ADD COLUMN "book_id" integer;--> statement-breakpoint
+ALTER TABLE "reading_sessions" ALTER COLUMN "source" DROP DEFAULT;--> statement-breakpoint
+ALTER TABLE "reading_sessions" ALTER COLUMN "source" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "reading_sessions" DROP CONSTRAINT "reading_sessions_source_chk";--> statement-breakpoint
+ALTER TABLE "reading_sessions" ADD CONSTRAINT "reading_sessions_book_id_books_id_fk" FOREIGN KEY ("book_id") REFERENCES "public"."books"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "rs_user_book_started_at_idx" ON "reading_sessions" USING btree ("user_id","book_id","started_at");--> statement-breakpoint
+ALTER TABLE "reading_sessions" ADD CONSTRAINT "reading_sessions_source_chk" CHECK ("reading_sessions"."source" in ('web', 'koreader', 'manual', 'kobo'));
diff --git a/server/src/db/migrations/0030_backfill-reading-session-source-book-id.sql b/server/src/db/migrations/0030_backfill-reading-session-source-book-id.sql
new file mode 100644
index 000000000..1b6626da8
--- /dev/null
+++ b/server/src/db/migrations/0030_backfill-reading-session-source-book-id.sql
@@ -0,0 +1,2 @@
+UPDATE reading_sessions rs SET book_id = bf.book_id FROM book_files bf WHERE bf.id = rs.book_file_id AND rs.book_id IS NULL;--> statement-breakpoint
+UPDATE reading_sessions SET source = 'koreader' WHERE session_id LIKE 'kor:%' AND source IS DISTINCT FROM 'koreader';
diff --git a/server/src/db/migrations/0031_reading-session-book-id-not-null.sql b/server/src/db/migrations/0031_reading-session-book-id-not-null.sql
new file mode 100644
index 000000000..6467c1aa9
--- /dev/null
+++ b/server/src/db/migrations/0031_reading-session-book-id-not-null.sql
@@ -0,0 +1 @@
+ALTER TABLE "reading_sessions" ALTER COLUMN "book_id" SET NOT NULL;
\ No newline at end of file
diff --git a/server/src/db/migrations/meta/0027_snapshot.json b/server/src/db/migrations/meta/0027_snapshot.json
new file mode 100644
index 000000000..2b90e1e07
--- /dev/null
+++ b/server/src/db/migrations/meta/0027_snapshot.json
@@ -0,0 +1,11333 @@
+{
+  "id": "d20a77d2-02c8-4790-973c-50845a9eab26",
+  "prevId": "3c86c042-ffb6-4726-bab4-1f527c0f38ff",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.audit_log": {
+      "name": "audit_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_username": {
+          "name": "actor_username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "resource": {
+          "name": "resource",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "resource_id": {
+          "name": "resource_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip": {
+          "name": "ip",
+          "type": "varchar(45)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_audit_user_id": {
+          "name": "idx_audit_user_id",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_resource": {
+          "name": "idx_audit_resource",
+          "columns": [
+            {
+              "expression": "resource",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "resource_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_action": {
+          "name": "idx_audit_action",
+          "columns": [
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_ip": {
+          "name": "idx_audit_ip",
+          "columns": [
+            {
+              "expression": "ip",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_created_at": {
+          "name": "idx_audit_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audit_log_user_id_users_id_fk": {
+          "name": "audit_log_user_id_users_id_fk",
+          "tableFrom": "audit_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.app_settings": {
+      "name": "app_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "app_settings_key_unique": {
+          "name": "app_settings_key_unique",
+          "nullsNotDistinct": false,
+          "columns": ["key"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.magic_access_tokens": {
+      "name": "magic_access_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "label": {
+          "name": "label",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_token": {
+          "name": "raw_token",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "use_count": {
+          "name": "use_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "magic_access_tokens_user_id_idx": {
+          "name": "magic_access_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "magic_access_tokens_user_id_users_id_fk": {
+          "name": "magic_access_tokens_user_id_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "magic_access_tokens_created_by_users_id_fk": {
+          "name": "magic_access_tokens_created_by_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["created_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "magic_access_tokens_token_hash_unique": {
+          "name": "magic_access_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "magic_access_tokens_use_count_nonneg_chk": {
+          "name": "magic_access_tokens_use_count_nonneg_chk",
+          "value": "\"magic_access_tokens\".\"use_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "used_at": {
+          "name": "used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "password_reset_tokens_user_id_idx": {
+          "name": "password_reset_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "password_reset_tokens_expires_at_idx": {
+          "name": "password_reset_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "password_reset_tokens_user_id_users_id_fk": {
+          "name": "password_reset_tokens_user_id_users_id_fk",
+          "tableFrom": "password_reset_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "password_reset_tokens_token_hash_unique": {
+          "name": "password_reset_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "password_reset_tokens_expires_after_created_chk": {
+          "name": "password_reset_tokens_expires_after_created_chk",
+          "value": "\"password_reset_tokens\".\"expires_at\" > \"password_reset_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.refresh_tokens": {
+      "name": "refresh_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rotated_at": {
+          "name": "rotated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replaced_by_token_hash": {
+          "name": "replaced_by_token_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_user_id_idx": {
+          "name": "refresh_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "refresh_tokens_expires_at_idx": {
+          "name": "refresh_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "refresh_tokens_token_hash_unique": {
+          "name": "refresh_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "refresh_tokens_expires_after_created_chk": {
+          "name": "refresh_tokens_expires_after_created_chk",
+          "value": "\"refresh_tokens\".\"expires_at\" > \"refresh_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_genres": {
+      "name": "user_content_filter_genres",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_genres_genre_id_idx": {
+          "name": "user_content_filter_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_genres_user_id_users_id_fk": {
+          "name": "user_content_filter_genres_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_genres_genre_id_genres_id_fk": {
+          "name": "user_content_filter_genres_genre_id_genres_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_genres_user_id_filter_type_genre_id_pk": {
+          "name": "user_content_filter_genres_user_id_filter_type_genre_id_pk",
+          "columns": ["user_id", "filter_type", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_tags": {
+      "name": "user_content_filter_tags",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_tags_tag_id_idx": {
+          "name": "user_content_filter_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_tags_user_id_users_id_fk": {
+          "name": "user_content_filter_tags_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_tags_tag_id_tags_id_fk": {
+          "name": "user_content_filter_tags_tag_id_tags_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_tags_user_id_filter_type_tag_id_pk": {
+          "name": "user_content_filter_tags_user_id_filter_type_tag_id_pk",
+          "columns": ["user_id", "filter_type", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_library_access": {
+      "name": "user_library_access",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_level": {
+          "name": "access_level",
+          "type": "library_access_level",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        }
+      },
+      "indexes": {
+        "user_library_access_library_user_idx": {
+          "name": "user_library_access_library_user_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_library_access_user_id_users_id_fk": {
+          "name": "user_library_access_user_id_users_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_library_access_library_id_libraries_id_fk": {
+          "name": "user_library_access_library_id_libraries_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_library_access_user_id_library_id_pk": {
+          "name": "user_library_access_user_id_library_id_pk",
+          "columns": ["user_id", "library_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_permissions": {
+      "name": "user_permissions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_permissions_user_id_users_id_fk": {
+          "name": "user_permissions_user_id_users_id_fk",
+          "tableFrom": "user_permissions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_permissions_user_id_permission_name_pk": {
+          "name": "user_permissions_user_id_permission_name_pk",
+          "columns": ["user_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_superuser": {
+          "name": "is_superuser",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_default_password": {
+          "name": "is_default_password",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "token_version": {
+          "name": "token_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "failed_login_attempts": {
+          "name": "failed_login_attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "locked_until": {
+          "name": "locked_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_source": {
+          "name": "avatar_source",
+          "type": "user_avatar_source",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'none'"
+        },
+        "avatar_version": {
+          "name": "avatar_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "provisioning_method": {
+          "name": "provisioning_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'local'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "users_username_lower_uidx": {
+          "name": "users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_email_lower_uidx": {
+          "name": "users_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"email\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_oidc_subject_issuer_uidx": {
+          "name": "users_oidc_subject_issuer_uidx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"oidc_subject\" is not null and \"users\".\"oidc_issuer\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        },
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["email"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "users_provisioning_method_chk": {
+          "name": "users_provisioning_method_chk",
+          "value": "\"users\".\"provisioning_method\" in ('local', 'manual', 'oidc', 'shared')"
+        },
+        "users_token_version_nonnegative_chk": {
+          "name": "users_token_version_nonnegative_chk",
+          "value": "\"users\".\"token_version\" >= 0"
+        },
+        "users_failed_login_attempts_nonnegative_chk": {
+          "name": "users_failed_login_attempts_nonnegative_chk",
+          "value": "\"users\".\"failed_login_attempts\" >= 0"
+        },
+        "users_avatar_version_nonnegative_chk": {
+          "name": "users_avatar_version_nonnegative_chk",
+          "value": "\"users\".\"avatar_version\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.comic_metadata": {
+      "name": "comic_metadata",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issue_number": {
+          "name": "issue_number",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "volume_name": {
+          "name": "volume_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pencillers": {
+          "name": "pencillers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "inkers": {
+          "name": "inkers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "colorists": {
+          "name": "colorists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "letterers": {
+          "name": "letterers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_artists": {
+          "name": "cover_artists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "characters": {
+          "name": "characters",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "teams": {
+          "name": "teams",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locations": {
+          "name": "locations",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "story_arcs": {
+          "name": "story_arcs",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comic_metadata_book_id_books_id_fk": {
+          "name": "comic_metadata_book_id_books_id_fk",
+          "tableFrom": "comic_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comic_metadata_book_id_unique": {
+          "name": "comic_metadata_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_plan_artifacts": {
+      "name": "migration_plan_artifacts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_snapshot_hash": {
+          "name": "source_snapshot_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_hash": {
+          "name": "profile_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_hash": {
+          "name": "plan_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan": {
+          "name": "plan",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_plan_artifacts_plan_hash_uidx": {
+          "name": "migration_plan_artifacts_plan_hash_uidx",
+          "columns": [
+            {
+              "expression": "plan_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_source_id_idx": {
+          "name": "migration_plan_artifacts_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_profile_id_idx": {
+          "name": "migration_plan_artifacts_profile_id_idx",
+          "columns": [
+            {
+              "expression": "profile_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_plan_artifacts_source_id_migration_sources_id_fk": {
+          "name": "migration_plan_artifacts_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_id_migration_profiles_id_fk": {
+          "name": "migration_plan_artifacts_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_created_by_user_id_users_id_fk": {
+          "name": "migration_plan_artifacts_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_source_fk": {
+          "name": "migration_plan_artifacts_profile_source_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_plan_artifacts_id_source_profile_unique": {
+          "name": "migration_plan_artifacts_id_source_profile_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id", "profile_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_profiles": {
+      "name": "migration_profiles",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "user_mappings": {
+          "name": "user_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path_mappings": {
+          "name": "path_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_profiles_source_name_version_uidx": {
+          "name": "migration_profiles_source_name_version_uidx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "version",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_profiles_source_id_idx": {
+          "name": "migration_profiles_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_profiles_source_id_migration_sources_id_fk": {
+          "name": "migration_profiles_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_profiles_created_by_user_id_users_id_fk": {
+          "name": "migration_profiles_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_profiles_id_source_id_unique": {
+          "name": "migration_profiles_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "migration_profiles_version_positive_chk": {
+          "name": "migration_profiles_version_positive_chk",
+          "value": "\"migration_profiles\".\"version\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_run_metrics": {
+      "name": "migration_run_metrics",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stage": {
+          "name": "stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "processed": {
+          "name": "processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "imported": {
+          "name": "imported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "skipped": {
+          "name": "skipped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "unresolved": {
+          "name": "unresolved",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "failed": {
+          "name": "failed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_run_metrics_run_stage_entity_uidx": {
+          "name": "migration_run_metrics_run_stage_entity_uidx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "stage",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_run_metrics_run_id_idx": {
+          "name": "migration_run_metrics_run_id_idx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_run_metrics_run_id_migration_runs_id_fk": {
+          "name": "migration_run_metrics_run_id_migration_runs_id_fk",
+          "tableFrom": "migration_run_metrics",
+          "tableTo": "migration_runs",
+          "columnsFrom": ["run_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_run_metrics_processed_nonnegative_chk": {
+          "name": "migration_run_metrics_processed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"processed\" >= 0"
+        },
+        "migration_run_metrics_imported_nonnegative_chk": {
+          "name": "migration_run_metrics_imported_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"imported\" >= 0"
+        },
+        "migration_run_metrics_skipped_nonnegative_chk": {
+          "name": "migration_run_metrics_skipped_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"skipped\" >= 0"
+        },
+        "migration_run_metrics_unresolved_nonnegative_chk": {
+          "name": "migration_run_metrics_unresolved_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"unresolved\" >= 0"
+        },
+        "migration_run_metrics_failed_nonnegative_chk": {
+          "name": "migration_run_metrics_failed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"failed\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_runs": {
+      "name": "migration_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_artifact_id": {
+          "name": "plan_artifact_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_key": {
+          "name": "target_key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'bookorbit'"
+        },
+        "state": {
+          "name": "state",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "current_stage": {
+          "name": "current_stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by_user_id": {
+          "name": "triggered_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_runs_source_target_state_idx": {
+          "name": "migration_runs_source_target_state_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "target_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_runs_state_idx": {
+          "name": "migration_runs_state_idx",
+          "columns": [
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_runs_source_id_migration_sources_id_fk": {
+          "name": "migration_runs_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_id_migration_profiles_id_fk": {
+          "name": "migration_runs_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk": {
+          "name": "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_triggered_by_user_id_users_id_fk": {
+          "name": "migration_runs_triggered_by_user_id_users_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "users",
+          "columnsFrom": ["triggered_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_source_fk": {
+          "name": "migration_runs_profile_source_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_source_profile_fk": {
+          "name": "migration_runs_plan_artifact_source_profile_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id", "source_id", "profile_id"],
+          "columnsTo": ["id", "source_id", "profile_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        },
+        "migration_runs_started_before_ended_chk": {
+          "name": "migration_runs_started_before_ended_chk",
+          "value": "\"migration_runs\".\"ended_at\" is null or \"migration_runs\".\"started_at\" is null or \"migration_runs\".\"ended_at\" >= \"migration_runs\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_sources": {
+      "name": "migration_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_config": {
+          "name": "connection_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "capabilities": {
+          "name": "capabilities",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_validated_at": {
+          "name": "last_validated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_sources_type_name_uidx": {
+          "name": "migration_sources_type_name_uidx",
+          "columns": [
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_sources_created_by_user_id_users_id_fk": {
+          "name": "migration_sources_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_sources",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.libraries": {
+      "name": "libraries",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cover_aspect_ratio": {
+          "name": "cover_aspect_ratio",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'2/3'"
+        },
+        "watch": {
+          "name": "watch",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "auto_scan_cron_expression": {
+          "name": "auto_scan_cron_expression",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_precedence": {
+          "name": "metadata_precedence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"folderStructure\",\"embedded\",\"nfoFile\",\"opfFile\",\"sidecar\"]'::jsonb"
+        },
+        "format_priority": {
+          "name": "format_priority",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"epub\",\"pdf\",\"cbz\",\"cbr\",\"cb7\",\"mobi\",\"azw3\",\"azw\",\"fb2\",\"m4b\",\"mp3\",\"m4a\",\"opus\",\"ogg\",\"flac\"]'::jsonb"
+        },
+        "allowed_formats": {
+          "name": "allowed_formats",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "organization_mode": {
+          "name": "organization_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'book_per_folder'"
+        },
+        "exclude_patterns": {
+          "name": "exclude_patterns",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "double precision",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0.25
+        },
+        "mark_as_finished_percent_complete": {
+          "name": "mark_as_finished_percent_complete",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 98
+        },
+        "file_write_enabled": {
+          "name": "file_write_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_write_cover": {
+          "name": "file_write_write_cover",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_enabled": {
+          "name": "file_write_epub_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_max_file_size_mb": {
+          "name": "file_write_epub_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_pdf_enabled": {
+          "name": "file_write_pdf_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_pdf_max_file_size_mb": {
+          "name": "file_write_pdf_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_cbx_enabled": {
+          "name": "file_write_cbx_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_cbx_max_file_size_mb": {
+          "name": "file_write_cbx_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_write_audio_enabled": {
+          "name": "file_write_audio_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_audio_max_file_size_mb": {
+          "name": "file_write_audio_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_rename_enabled": {
+          "name": "file_rename_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_naming_pattern": {
+          "name": "file_naming_pattern",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_fetch_preferences": {
+          "name": "metadata_fetch_preferences",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_config": {
+          "name": "book_metadata_fetch_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_run_at": {
+          "name": "book_metadata_fetch_last_run_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_queued_count": {
+          "name": "book_metadata_fetch_last_queued_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scan_mode": {
+          "name": "scan_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "poll_interval_seconds": {
+          "name": "poll_interval_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "default": 300
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "libraries_name_lower_uidx": {
+          "name": "libraries_name_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "libraries_display_order_nonnegative_chk": {
+          "name": "libraries_display_order_nonnegative_chk",
+          "value": "\"libraries\".\"display_order\" >= 0"
+        },
+        "libraries_organization_mode_chk": {
+          "name": "libraries_organization_mode_chk",
+          "value": "\"libraries\".\"organization_mode\" in ('book_per_folder', 'book_per_file')"
+        },
+        "libraries_reading_threshold_range_chk": {
+          "name": "libraries_reading_threshold_range_chk",
+          "value": "\"libraries\".\"reading_threshold\" >= 0 and \"libraries\".\"reading_threshold\" <= 100"
+        },
+        "libraries_mark_finished_percent_range_chk": {
+          "name": "libraries_mark_finished_percent_range_chk",
+          "value": "\"libraries\".\"mark_as_finished_percent_complete\" >= 0 and \"libraries\".\"mark_as_finished_percent_complete\" <= 100"
+        },
+        "libraries_scan_mode_chk": {
+          "name": "libraries_scan_mode_chk",
+          "value": "\"libraries\".\"scan_mode\" in ('auto', 'manual')"
+        },
+        "libraries_poll_interval_nonnegative_chk": {
+          "name": "libraries_poll_interval_nonnegative_chk",
+          "value": "\"libraries\".\"poll_interval_seconds\" is null or \"libraries\".\"poll_interval_seconds\" >= 0"
+        },
+        "libraries_file_write_epub_max_size_chk": {
+          "name": "libraries_file_write_epub_max_size_chk",
+          "value": "\"libraries\".\"file_write_epub_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_pdf_max_size_chk": {
+          "name": "libraries_file_write_pdf_max_size_chk",
+          "value": "\"libraries\".\"file_write_pdf_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_cbx_max_size_chk": {
+          "name": "libraries_file_write_cbx_max_size_chk",
+          "value": "\"libraries\".\"file_write_cbx_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_audio_max_size_chk": {
+          "name": "libraries_file_write_audio_max_size_chk",
+          "value": "\"libraries\".\"file_write_audio_max_file_size_mb\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.library_folders": {
+      "name": "library_folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "library_folders_library_id_idx": {
+          "name": "library_folders_library_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_folders_library_path_uidx": {
+          "name": "library_folders_library_path_uidx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_folders_library_id_libraries_id_fk": {
+          "name": "library_folders_library_id_libraries_id_fk",
+          "tableFrom": "library_folders",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "library_folders_id_library_id_unique": {
+          "name": "library_folders_id_library_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_files": {
+      "name": "book_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rel_path": {
+          "name": "rel_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ino": {
+          "name": "ino",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "mtime": {
+          "name": "mtime",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'content'"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_files_absolute_path_uidx": {
+          "name": "book_files_absolute_path_uidx",
+          "columns": [
+            {
+              "expression": "absolute_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_book_id_idx": {
+          "name": "book_files_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_id_idx": {
+          "name": "book_files_library_folder_id_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_file_hash_idx": {
+          "name": "book_files_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_ino_idx": {
+          "name": "book_files_ino_idx",
+          "columns": [
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_format_idx": {
+          "name": "book_files_format_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_file_hash_idx": {
+          "name": "book_files_library_folder_file_hash_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_ino_idx": {
+          "name": "book_files_library_folder_ino_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_files_book_id_books_id_fk": {
+          "name": "book_files_book_id_books_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_library_folder_id_library_folders_id_fk": {
+          "name": "book_files_library_folder_id_library_folders_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_book_folder_consistency_fk": {
+          "name": "book_files_book_folder_consistency_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id", "library_folder_id"],
+          "columnsTo": ["id", "library_folder_id"],
+          "onDelete": "no action",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_files_role_chk": {
+          "name": "book_files_role_chk",
+          "value": "\"book_files\".\"role\" in ('content', 'cover', 'metadata', 'supplement')"
+        },
+        "book_files_size_bytes_nonnegative_chk": {
+          "name": "book_files_size_bytes_nonnegative_chk",
+          "value": "\"book_files\".\"size_bytes\" is null or \"book_files\".\"size_bytes\" >= 0"
+        },
+        "book_files_duration_seconds_nonnegative_chk": {
+          "name": "book_files_duration_seconds_nonnegative_chk",
+          "value": "\"book_files\".\"duration_seconds\" is null or \"book_files\".\"duration_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.books": {
+      "name": "books",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "primary_file_id": {
+          "name": "primary_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_path": {
+          "name": "folder_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'present'"
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "books_library_id_folder_path_idx": {
+          "name": "books_library_id_folder_path_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_primary_file_id_idx": {
+          "name": "books_primary_file_id_idx",
+          "columns": [
+            {
+              "expression": "primary_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_status_idx": {
+          "name": "books_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_added_at_idx": {
+          "name": "books_library_added_at_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "books_library_id_libraries_id_fk": {
+          "name": "books_library_id_libraries_id_fk",
+          "tableFrom": "books",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_id_library_folders_id_fk": {
+          "name": "books_library_folder_id_library_folders_id_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_primary_file_id_book_files_id_fk": {
+          "name": "books_primary_file_id_book_files_id_fk",
+          "tableFrom": "books",
+          "tableTo": "book_files",
+          "columnsFrom": ["primary_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_library_fk": {
+          "name": "books_library_folder_library_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id", "library_id"],
+          "columnsTo": ["id", "library_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "books_id_library_folder_id_unique": {
+          "name": "books_id_library_folder_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_folder_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "books_status_chk": {
+          "name": "books_status_chk",
+          "value": "\"books\".\"status\" in ('present', 'missing', 'processing')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.collection_books": {
+      "name": "collection_books",
+      "schema": "",
+      "columns": {
+        "collection_id": {
+          "name": "collection_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collection_books_book_id_idx": {
+          "name": "collection_books_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collection_books_collection_id_collections_id_fk": {
+          "name": "collection_books_collection_id_collections_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "collections",
+          "columnsFrom": ["collection_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "collection_books_book_id_books_id_fk": {
+          "name": "collection_books_book_id_books_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "collection_books_collection_id_book_id_pk": {
+          "name": "collection_books_collection_id_book_id_pk",
+          "columns": ["collection_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.collections": {
+      "name": "collections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_to_kobo": {
+          "name": "sync_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collections_user_name_uidx": {
+          "name": "collections_user_name_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "collections_user_display_name_idx": {
+          "name": "collections_user_display_name_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collections_user_id_users_id_fk": {
+          "name": "collections_user_id_users_id_fk",
+          "tableFrom": "collections",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.smart_scopes": {
+      "name": "smart_scopes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "filter": {
+          "name": "filter",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_sort": {
+          "name": "default_sort",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "smart_scopes_user_id_users_id_fk": {
+          "name": "smart_scopes_user_id_users_id_fk",
+          "tableFrom": "smart_scopes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "smart_scopes_user_id_name_unique": {
+          "name": "smart_scopes_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series": {
+      "name": "book_series",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "normalized_name": {
+          "name": "normalized_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_normalized_name_uidx": {
+          "name": "book_series_normalized_name_uidx",
+          "columns": [
+            {
+              "expression": "normalized_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_name_trgm_idx": {
+          "name": "book_series_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "book_series_name_lower_idx": {
+          "name": "book_series_name_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.author_enrichment_queue": {
+      "name": "author_enrichment_queue",
+      "schema": "",
+      "columns": {
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unknown'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_success_at": {
+          "name": "last_success_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "author_enrichment_queue_status_next_attempt_idx": {
+          "name": "author_enrichment_queue_status_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_next_attempt_idx": {
+          "name": "author_enrichment_queue_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_single_processing_idx": {
+          "name": "author_enrichment_queue_single_processing_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"author_enrichment_queue\".\"status\" = 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "author_enrichment_queue_author_id_authors_id_fk": {
+          "name": "author_enrichment_queue_author_id_authors_id_fk",
+          "tableFrom": "author_enrichment_queue",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "author_enrichment_queue_status_chk": {
+          "name": "author_enrichment_queue_status_chk",
+          "value": "\"author_enrichment_queue\".\"status\" in ('queued', 'processing', 'rate_limited', 'failed', 'done')"
+        },
+        "author_enrichment_queue_reason_chk": {
+          "name": "author_enrichment_queue_reason_chk",
+          "value": "\"author_enrichment_queue\".\"reason\" in ('unknown', 'metadata_replace', 'manual_backfill', 'manual_backfill_all', 'author_rename', 'author_merge_target')"
+        },
+        "author_enrichment_queue_attempt_count_nonnegative_chk": {
+          "name": "author_enrichment_queue_attempt_count_nonnegative_chk",
+          "value": "\"author_enrichment_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.authors": {
+      "name": "authors",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_photo": {
+          "name": "has_photo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "last_enriched_at": {
+          "name": "last_enriched_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "authors_name_trgm_idx": {
+          "name": "authors_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "authors_name_unique": {
+          "name": "authors_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_authors": {
+      "name": "book_authors",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_authors_author_id_idx": {
+          "name": "book_authors_author_id_idx",
+          "columns": [
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_authors_book_display_idx": {
+          "name": "book_authors_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_authors_book_id_books_id_fk": {
+          "name": "book_authors_book_id_books_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_authors_author_id_authors_id_fk": {
+          "name": "book_authors_author_id_authors_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_authors_book_id_author_id_pk": {
+          "name": "book_authors_book_id_author_id_pk",
+          "columns": ["book_id", "author_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_genres": {
+      "name": "book_genres",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_genres_genre_id_idx": {
+          "name": "book_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_genres_book_id_books_id_fk": {
+          "name": "book_genres_book_id_books_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_genres_genre_id_genres_id_fk": {
+          "name": "book_genres_genre_id_genres_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_genres_book_id_genre_id_pk": {
+          "name": "book_genres_book_id_genre_id_pk",
+          "columns": ["book_id", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_metadata": {
+      "name": "book_metadata",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subtitle": {
+          "name": "subtitle",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn10": {
+          "name": "isbn10",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn13": {
+          "name": "isbn13",
+          "type": "varchar(13)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "publisher": {
+          "name": "publisher",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_year": {
+          "name": "published_year",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "language": {
+          "name": "language",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_count": {
+          "name": "page_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_name": {
+          "name": "series_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_source": {
+          "name": "cover_source",
+          "type": "varchar(9)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "google_books_id": {
+          "name": "google_books_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "goodreads_id": {
+          "name": "goodreads_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "amazon_id": {
+          "name": "amazon_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_id": {
+          "name": "hardcover_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "open_library_id": {
+          "name": "open_library_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "itunes_id": {
+          "name": "itunes_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_id": {
+          "name": "kobo_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_score": {
+          "name": "metadata_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_metadata_fetch_at": {
+          "name": "last_metadata_fetch_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(256)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_written_at": {
+          "name": "last_written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "abridged": {
+          "name": "abridged",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "audible_id": {
+          "name": "audible_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "comicvine_id": {
+          "name": "comicvine_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ranobedb_id": {
+          "name": "ranobedb_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapters": {
+          "name": "chapters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locked_fields": {
+          "name": "locked_fields",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bm_title_trgm_idx": {
+          "name": "bm_title_trgm_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_title_lower_idx": {
+          "name": "bm_title_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"title\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_trgm_idx": {
+          "name": "bm_series_trgm_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_series_id_idx": {
+          "name": "bm_series_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_lower_btrim_idx": {
+          "name": "bm_series_name_lower_btrim_idx",
+          "columns": [
+            {
+              "expression": "lower(btrim(\"series_name\"))",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_publisher_trgm_idx": {
+          "name": "bm_publisher_trgm_idx",
+          "columns": [
+            {
+              "expression": "publisher",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_language_idx": {
+          "name": "bm_language_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_language_trgm_idx": {
+          "name": "bm_language_trgm_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_published_year_idx": {
+          "name": "bm_published_year_idx",
+          "columns": [
+            {
+              "expression": "published_year",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_index_idx": {
+          "name": "bm_series_name_index_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn10_idx": {
+          "name": "bm_isbn10_idx",
+          "columns": [
+            {
+              "expression": "isbn10",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn13_idx": {
+          "name": "bm_isbn13_idx",
+          "columns": [
+            {
+              "expression": "isbn13",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_embedding_hnsw_cosine_idx": {
+          "name": "bm_embedding_hnsw_cosine_idx",
+          "columns": [
+            {
+              "expression": "\"embedding\" vector_cosine_ops",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_book_id_books_id_fk": {
+          "name": "book_metadata_book_id_books_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_metadata_series_id_book_series_id_fk": {
+          "name": "book_metadata_series_id_book_series_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "book_series",
+          "columnsFrom": ["series_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_rating_range_chk": {
+          "name": "book_metadata_rating_range_chk",
+          "value": "\"book_metadata\".\"rating\" is null or (\"book_metadata\".\"rating\" >= 1 and \"book_metadata\".\"rating\" <= 10)"
+        },
+        "book_metadata_published_year_range_chk": {
+          "name": "book_metadata_published_year_range_chk",
+          "value": "\"book_metadata\".\"published_year\" is null or (\"book_metadata\".\"published_year\" >= 1000 and \"book_metadata\".\"published_year\" <= 2200)"
+        },
+        "book_metadata_page_count_nonnegative_chk": {
+          "name": "book_metadata_page_count_nonnegative_chk",
+          "value": "\"book_metadata\".\"page_count\" is null or \"book_metadata\".\"page_count\" >= 0"
+        },
+        "book_metadata_duration_seconds_nonnegative_chk": {
+          "name": "book_metadata_duration_seconds_nonnegative_chk",
+          "value": "\"book_metadata\".\"duration_seconds\" is null or \"book_metadata\".\"duration_seconds\" >= 0"
+        },
+        "book_metadata_cover_source_chk": {
+          "name": "book_metadata_cover_source_chk",
+          "value": "\"book_metadata\".\"cover_source\" is null or \"book_metadata\".\"cover_source\" in ('extracted', 'custom')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_metadata_fetch_queue": {
+      "name": "book_metadata_fetch_queue",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'manual_trigger'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bmfq_status_idx": {
+          "name": "bmfq_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_created_at_idx": {
+          "name": "bmfq_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_status_created_book_idx": {
+          "name": "bmfq_status_created_book_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_fetch_queue_book_id_books_id_fk": {
+          "name": "book_metadata_fetch_queue_book_id_books_id_fk",
+          "tableFrom": "book_metadata_fetch_queue",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_fetch_queue_status_chk": {
+          "name": "book_metadata_fetch_queue_status_chk",
+          "value": "\"book_metadata_fetch_queue\".\"status\" in ('queued', 'processing', 'failed')"
+        },
+        "book_metadata_fetch_queue_reason_chk": {
+          "name": "book_metadata_fetch_queue_reason_chk",
+          "value": "\"book_metadata_fetch_queue\".\"reason\" in ('event_import', 'manual_trigger', 'manual_retry')"
+        },
+        "book_metadata_fetch_queue_attempt_count_nonnegative_chk": {
+          "name": "book_metadata_fetch_queue_attempt_count_nonnegative_chk",
+          "value": "\"book_metadata_fetch_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_tags": {
+      "name": "book_tags",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_tags_tag_id_idx": {
+          "name": "book_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_tags_book_id_books_id_fk": {
+          "name": "book_tags_book_id_books_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_tags_tag_id_tags_id_fk": {
+          "name": "book_tags_tag_id_tags_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_tags_book_id_tag_id_pk": {
+          "name": "book_tags_book_id_tag_id_pk",
+          "columns": ["book_id", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.genres": {
+      "name": "genres",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "genres_name_trgm_idx": {
+          "name": "genres_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "genres_name_unique": {
+          "name": "genres_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.tags": {
+      "name": "tags",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "tags_name_trgm_idx": {
+          "name": "tags_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "tags_name_unique": {
+          "name": "tags_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_narrators": {
+      "name": "book_narrators",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "narrator_id": {
+          "name": "narrator_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_narrators_narrator_id_idx": {
+          "name": "book_narrators_narrator_id_idx",
+          "columns": [
+            {
+              "expression": "narrator_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_narrators_book_id_books_id_fk": {
+          "name": "book_narrators_book_id_books_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_narrators_narrator_id_narrators_id_fk": {
+          "name": "book_narrators_narrator_id_narrators_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "narrators",
+          "columnsFrom": ["narrator_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_narrators_book_id_narrator_id_pk": {
+          "name": "book_narrators_book_id_narrator_id_pk",
+          "columns": ["book_id", "narrator_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.narrators": {
+      "name": "narrators",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "narrators_name_trgm_idx": {
+          "name": "narrators_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "narrators_name_unique": {
+          "name": "narrators_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.library_dir_scan_state": {
+      "name": "library_dir_scan_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dir_path": {
+          "name": "dir_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_mtime_ms": {
+          "name": "last_seen_mtime_ms",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "library_dir_scan_state_folder_dir_uidx": {
+          "name": "library_dir_scan_state_folder_dir_uidx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "dir_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_dir_scan_state_folder_idx": {
+          "name": "library_dir_scan_state_folder_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_dir_scan_state_library_folder_id_library_folders_id_fk": {
+          "name": "library_dir_scan_state_library_folder_id_library_folders_id_fk",
+          "tableFrom": "library_dir_scan_state",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.scan_jobs": {
+      "name": "scan_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'running'"
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_count": {
+          "name": "added_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_count": {
+          "name": "updated_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "missing_count": {
+          "name": "missing_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "scan_jobs_library_status_idx": {
+          "name": "scan_jobs_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "scan_jobs_library_id_libraries_id_fk": {
+          "name": "scan_jobs_library_id_libraries_id_fk",
+          "tableFrom": "scan_jobs",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "scan_jobs_status_chk": {
+          "name": "scan_jobs_status_chk",
+          "value": "\"scan_jobs\".\"status\" in ('running', 'completed', 'failed')"
+        },
+        "scan_jobs_triggered_by_chk": {
+          "name": "scan_jobs_triggered_by_chk",
+          "value": "\"scan_jobs\".\"triggered_by\" in ('manual', 'watcher', 'schedule')"
+        },
+        "scan_jobs_added_count_nonnegative_chk": {
+          "name": "scan_jobs_added_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"added_count\" >= 0"
+        },
+        "scan_jobs_updated_count_nonnegative_chk": {
+          "name": "scan_jobs_updated_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"updated_count\" >= 0"
+        },
+        "scan_jobs_missing_count_nonnegative_chk": {
+          "name": "scan_jobs_missing_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"missing_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_positions": {
+      "name": "annotation_positions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(12)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pos0": {
+          "name": "pos0",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pos1": {
+          "name": "pos1",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'exact'"
+        },
+        "converter_version": {
+          "name": "converter_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "extras": {
+          "name": "extras",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_positions_annotation_format_uidx": {
+          "name": "annotation_positions_annotation_format_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_user_idx": {
+          "name": "annotation_positions_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_format_status_idx": {
+          "name": "annotation_positions_format_status_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_positions_annotation_id_annotations_id_fk": {
+          "name": "annotation_positions_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_user_id_users_id_fk": {
+          "name": "annotation_positions_user_id_users_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_book_file_id_book_files_id_fk": {
+          "name": "annotation_positions_book_file_id_book_files_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_positions_format_chk": {
+          "name": "annotation_positions_format_chk",
+          "value": "\"annotation_positions\".\"format\" in ('cfi', 'xpointer', 'pdf', 'kobo_span')"
+        },
+        "annotation_positions_status_chk": {
+          "name": "annotation_positions_status_chk",
+          "value": "\"annotation_positions\".\"status\" in ('exact', 'repaired', 'failed', 'pending')"
+        },
+        "annotation_positions_pos0_chk": {
+          "name": "annotation_positions_pos0_chk",
+          "value": "\"annotation_positions\".\"status\" in ('failed', 'pending') or \"annotation_positions\".\"pos0\" is not null"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_sync_state": {
+      "name": "annotation_sync_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_key": {
+          "name": "external_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_created_at": {
+          "name": "external_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_applied_version": {
+          "name": "last_applied_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "delete_acked_at": {
+          "name": "delete_acked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_synced_at": {
+          "name": "first_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_sync_state_annotation_source_device_uidx": {
+          "name": "annotation_sync_state_annotation_source_device_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_source_device_key_idx": {
+          "name": "annotation_sync_state_user_source_device_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_key_idx": {
+          "name": "annotation_sync_state_user_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_annotation_id_idx": {
+          "name": "annotation_sync_state_annotation_id_idx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_sync_state_annotation_id_annotations_id_fk": {
+          "name": "annotation_sync_state_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_sync_state_user_id_users_id_fk": {
+          "name": "annotation_sync_state_user_id_users_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_sync_state_source_chk": {
+          "name": "annotation_sync_state_source_chk",
+          "value": "\"annotation_sync_state\".\"source\" in ('koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotations": {
+      "name": "annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'yellow'"
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'highlight'"
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_title": {
+          "name": "chapter_title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'web'"
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_created_at": {
+          "name": "device_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_updated_at": {
+          "name": "device_updated_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_user_id_idx": {
+          "name": "annotations_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_idx": {
+          "name": "annotations_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_active_idx": {
+          "name": "annotations_user_book_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"annotations\".\"deleted_at\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotations_user_id_users_id_fk": {
+          "name": "annotations_user_id_users_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotations_book_id_books_id_fk": {
+          "name": "annotations_book_id_books_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_style_chk": {
+          "name": "annotations_style_chk",
+          "value": "\"annotations\".\"style\" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')"
+        },
+        "annotations_origin_chk": {
+          "name": "annotations_origin_chk",
+          "value": "\"annotations\".\"origin\" in ('web', 'koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.audiobook_progress": {
+      "name": "audiobook_progress",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "current_file_id": {
+          "name": "current_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "abp_user_id_idx": {
+          "name": "abp_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audiobook_progress_user_id_users_id_fk": {
+          "name": "audiobook_progress_user_id_users_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_book_id_books_id_fk": {
+          "name": "audiobook_progress_book_id_books_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_current_file_id_book_files_id_fk": {
+          "name": "audiobook_progress_current_file_id_book_files_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["current_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "audiobook_progress_user_id_book_id_pk": {
+          "name": "audiobook_progress_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "audiobook_progress_percentage_range_chk": {
+          "name": "audiobook_progress_percentage_range_chk",
+          "value": "\"audiobook_progress\".\"percentage\" >= 0 and \"audiobook_progress\".\"percentage\" <= 100"
+        },
+        "audiobook_progress_position_seconds_nonnegative_chk": {
+          "name": "audiobook_progress_position_seconds_nonnegative_chk",
+          "value": "\"audiobook_progress\".\"position_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.bookmarks": {
+      "name": "bookmarks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bookmarks_user_book_idx": {
+          "name": "bookmarks_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_cfi_uidx": {
+          "name": "bookmarks_user_book_cfi_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "cfi",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"cfi\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_pos_uidx": {
+          "name": "bookmarks_user_book_pos_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position_seconds",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"position_seconds\" is not null and \"bookmarks\".\"cfi\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "bookmarks_user_id_users_id_fk": {
+          "name": "bookmarks_user_id_users_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "bookmarks_book_id_books_id_fk": {
+          "name": "bookmarks_book_id_books_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reader_default_preferences": {
+      "name": "reader_default_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format_group": {
+          "name": "format_group",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rdp_user_format_idx": {
+          "name": "rdp_user_format_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format_group",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_default_preferences_user_id_users_id_fk": {
+          "name": "reader_default_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_default_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reader_default_preferences_format_group_chk": {
+          "name": "reader_default_preferences_format_group_chk",
+          "value": "\"reader_default_preferences\".\"format_group\" in ('epub', 'pdf', 'cbx', 'audio')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reader_preferences": {
+      "name": "reader_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rp_user_file_idx": {
+          "name": "rp_user_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_preferences_user_id_users_id_fk": {
+          "name": "reader_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reader_preferences_book_file_id_book_files_id_fk": {
+          "name": "reader_preferences_book_file_id_book_files_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reading_progress": {
+      "name": "reading_progress",
+      "schema": "",
+      "columns": {
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_source": {
+          "name": "kobo_location_source",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_type": {
+          "name": "kobo_location_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_value": {
+          "name": "kobo_location_value",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_content_source_progress_percent": {
+          "name": "kobo_content_source_progress_percent",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "koreader_progress": {
+          "name": "koreader_progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reading_progress_user_id_idx": {
+          "name": "reading_progress_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reading_progress_user_updated_at_idx": {
+          "name": "reading_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_progress_book_file_id_book_files_id_fk": {
+          "name": "reading_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_progress_user_id_users_id_fk": {
+          "name": "reading_progress_user_id_users_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "reading_progress_book_file_id_user_id_pk": {
+          "name": "reading_progress_book_file_id_user_id_pk",
+          "columns": ["book_file_id", "user_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_progress_percentage_range_chk": {
+          "name": "reading_progress_percentage_range_chk",
+          "value": "\"reading_progress\".\"percentage\" >= 0 and \"reading_progress\".\"percentage\" <= 100"
+        },
+        "reading_progress_page_number_nonnegative_chk": {
+          "name": "reading_progress_page_number_nonnegative_chk",
+          "value": "\"reading_progress\".\"page_number\" is null or \"reading_progress\".\"page_number\" >= 0"
+        },
+        "reading_progress_position_seconds_nonnegative_chk": {
+          "name": "reading_progress_position_seconds_nonnegative_chk",
+          "value": "\"reading_progress\".\"position_seconds\" is null or \"reading_progress\".\"position_seconds\" >= 0"
+        },
+        "reading_progress_kobo_content_source_progress_range_chk": {
+          "name": "reading_progress_kobo_content_source_progress_range_chk",
+          "value": "\"reading_progress\".\"kobo_content_source_progress_percent\" is null or (\"reading_progress\".\"kobo_content_source_progress_percent\" >= 0 and \"reading_progress\".\"kobo_content_source_progress_percent\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reading_sessions": {
+      "name": "reading_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_progress": {
+          "name": "end_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "rs_user_session_id_uidx": {
+          "name": "rs_user_session_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_started_at_idx": {
+          "name": "rs_user_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_book_file_started_at_idx": {
+          "name": "rs_book_file_started_at_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_file_idx": {
+          "name": "rs_user_book_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_sessions_user_id_users_id_fk": {
+          "name": "reading_sessions_user_id_users_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_file_id_book_files_id_fk": {
+          "name": "reading_sessions_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_sessions_duration_seconds_nonnegative_chk": {
+          "name": "reading_sessions_duration_seconds_nonnegative_chk",
+          "value": "\"reading_sessions\".\"duration_seconds\" >= 0"
+        },
+        "reading_sessions_end_progress_range_chk": {
+          "name": "reading_sessions_end_progress_range_chk",
+          "value": "\"reading_sessions\".\"end_progress\" is null or (\"reading_sessions\".\"end_progress\" >= 0 and \"reading_sessions\".\"end_progress\" <= 100)"
+        },
+        "reading_sessions_ended_after_started_chk": {
+          "name": "reading_sessions_ended_after_started_chk",
+          "value": "\"reading_sessions\".\"ended_at\" >= \"reading_sessions\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_ratings": {
+      "name": "user_book_ratings",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubr_user_id_idx": {
+          "name": "ubr_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_id_idx": {
+          "name": "ubr_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_user_rating_idx": {
+          "name": "ubr_book_user_rating_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_ratings_user_id_users_id_fk": {
+          "name": "user_book_ratings_user_id_users_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_ratings_book_id_books_id_fk": {
+          "name": "user_book_ratings_book_id_books_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_ratings_user_id_book_id_pk": {
+          "name": "user_book_ratings_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_ratings_rating_range_chk": {
+          "name": "user_book_ratings_rating_range_chk",
+          "value": "\"user_book_ratings\".\"rating\" >= 1 and \"user_book_ratings\".\"rating\" <= 5"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_status": {
+      "name": "user_book_status",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unread'"
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubs_user_id_idx": {
+          "name": "ubs_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_user_status_idx": {
+          "name": "ubs_user_status_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_book_user_idx": {
+          "name": "ubs_book_user_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_status_user_id_users_id_fk": {
+          "name": "user_book_status_user_id_users_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_status_book_id_books_id_fk": {
+          "name": "user_book_status_book_id_books_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_status_user_id_book_id_pk": {
+          "name": "user_book_status_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_status_status_chk": {
+          "name": "user_book_status_status_chk",
+          "value": "\"user_book_status\".\"status\" in ('unread', 'want_to_read', 'reading', 'on_hold', 'rereading', 'read', 'skimmed', 'abandoned')"
+        },
+        "user_book_status_source_chk": {
+          "name": "user_book_status_source_chk",
+          "value": "\"user_book_status\".\"source\" in ('auto', 'manual')"
+        },
+        "user_book_status_finished_after_started_chk": {
+          "name": "user_book_status_finished_after_started_chk",
+          "value": "\"user_book_status\".\"finished_at\" is null or \"user_book_status\".\"started_at\" is null or \"user_book_status\".\"finished_at\" >= \"user_book_status\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_reading_daily_stats": {
+      "name": "user_reading_daily_stats",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "day": {
+          "name": "day",
+          "type": "date",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_seconds": {
+          "name": "reading_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "sessions_count": {
+          "name": "sessions_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "urds_user_day_idx": {
+          "name": "urds_user_day_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "day",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_reading_daily_stats_user_id_users_id_fk": {
+          "name": "user_reading_daily_stats_user_id_users_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_reading_daily_stats_library_id_libraries_id_fk": {
+          "name": "user_reading_daily_stats_library_id_libraries_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_reading_daily_stats_user_id_library_id_day_pk": {
+          "name": "user_reading_daily_stats_user_id_library_id_day_pk",
+          "columns": ["user_id", "library_id", "day"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_reading_daily_stats_reading_seconds_nonnegative_chk": {
+          "name": "user_reading_daily_stats_reading_seconds_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"reading_seconds\" >= 0"
+        },
+        "user_reading_daily_stats_sessions_count_nonnegative_chk": {
+          "name": "user_reading_daily_stats_sessions_count_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"sessions_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.oidc_group_mappings": {
+      "name": "oidc_group_mappings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_group_claim": {
+          "name": "oidc_group_claim",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_group_mappings_provider_claim_uidx": {
+          "name": "oidc_group_mappings_provider_claim_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_group_claim",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_group_mappings_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_group_mappings_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_group_mappings",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_identities": {
+      "name": "oidc_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "linked_at": {
+          "name": "linked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_identities_provider_subject_uidx": {
+          "name": "oidc_identities_provider_subject_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_provider_uidx": {
+          "name": "oidc_identities_user_provider_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_issuer_subject_uidx": {
+          "name": "oidc_identities_issuer_subject_uidx",
+          "columns": [
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_id_idx": {
+          "name": "oidc_identities_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_identities_user_id_users_id_fk": {
+          "name": "oidc_identities_user_id_users_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_identities_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_identities_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_permission_grants": {
+      "name": "oidc_permission_grants",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "oidc_permission_grants_user_id_users_id_fk": {
+          "name": "oidc_permission_grants_user_id_users_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_permission_grants_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_permission_grants_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "oidc_permission_grants_user_id_provider_id_permission_name_pk": {
+          "name": "oidc_permission_grants_user_id_provider_id_permission_name_pk",
+          "columns": ["user_id", "provider_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_providers": {
+      "name": "oidc_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "issuer_uri": {
+          "name": "issuer_uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'openid profile email'"
+        },
+        "icon_url": {
+          "name": "icon_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "claim_mapping": {
+          "name": "claim_mapping",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"username\":\"preferred_username\",\"name\":\"name\",\"email\":\"email\",\"groups\":\"groups\"}'::jsonb"
+        },
+        "auto_provision": {
+          "name": "auto_provision",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"enabled\":false,\"allowLocalLinking\":false,\"defaultPermissionNames\":[]}'::jsonb"
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_providers_enabled_order_idx": {
+          "name": "oidc_providers_enabled_order_idx",
+          "columns": [
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oidc_providers_slug_unique": {
+          "name": "oidc_providers_slug_unique",
+          "nullsNotDistinct": false,
+          "columns": ["slug"]
+        },
+        "oidc_providers_issuer_uri_unique": {
+          "name": "oidc_providers_issuer_uri_unique",
+          "nullsNotDistinct": false,
+          "columns": ["issuer_uri"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_sessions": {
+      "name": "oidc_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_session_id": {
+          "name": "oidc_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token_hint": {
+          "name": "id_token_hint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_refresh_token": {
+          "name": "idp_refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_sessions_user_active_idx": {
+          "name": "oidc_sessions_user_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"oidc_sessions\".\"revoked\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_subject_issuer_idx": {
+          "name": "oidc_sessions_subject_issuer_idx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_sid_idx": {
+          "name": "oidc_sessions_sid_idx",
+          "columns": [
+            {
+              "expression": "oidc_session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_expires_at_idx": {
+          "name": "oidc_sessions_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_provider_id_idx": {
+          "name": "oidc_sessions_provider_id_idx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_sessions_user_id_users_id_fk": {
+          "name": "oidc_sessions_user_id_users_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_sessions_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_sessions_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_states": {
+      "name": "oidc_states",
+      "schema": "",
+      "columns": {
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "meta": {
+          "name": "meta",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oidc_states_expires_at_idx": {
+          "name": "oidc_states_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_states_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_states_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_states",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_used_jtis": {
+      "name": "oidc_used_jtis",
+      "schema": "",
+      "columns": {
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_used_jtis_expires_at_idx": {
+          "name": "oidc_used_jtis_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.opds_users": {
+      "name": "opds_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "opds_sort_order",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'recent'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "opds_users_username_lower_uidx": {
+          "name": "opds_users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "opds_users_user_id_users_id_fk": {
+          "name": "opds_users_user_id_users_id_fk",
+          "tableFrom": "opds_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "opds_users_username_unique": {
+          "name": "opds_users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_book_entitlements": {
+      "name": "kobo_book_entitlements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "cover_image_id": {
+          "name": "cover_image_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "needs_legacy_numeric_removal": {
+          "name": "needs_legacy_numeric_removal",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_book_entitlements_user_id_idx": {
+          "name": "kobo_book_entitlements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kobo_book_entitlements_book_id_idx": {
+          "name": "kobo_book_entitlements_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_book_entitlements_user_id_users_id_fk": {
+          "name": "kobo_book_entitlements_user_id_users_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_book_entitlements_book_id_books_id_fk": {
+          "name": "kobo_book_entitlements_book_id_books_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_book_entitlements_user_book_unique": {
+          "name": "kobo_book_entitlements_user_book_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        },
+        "kobo_book_entitlements_user_entitlement_unique": {
+          "name": "kobo_book_entitlements_user_entitlement_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "entitlement_id"]
+        },
+        "kobo_book_entitlements_user_cover_unique": {
+          "name": "kobo_book_entitlements_user_cover_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "cover_image_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_devices": {
+      "name": "kobo_devices",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_at": {
+          "name": "last_seen_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_devices_user_id_idx": {
+          "name": "kobo_devices_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_devices_user_id_users_id_fk": {
+          "name": "kobo_devices_user_id_users_id_fk",
+          "tableFrom": "kobo_devices",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_devices_token_unique": {
+          "name": "kobo_devices_token_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_library_snapshots": {
+      "name": "kobo_library_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_library_snapshots_user_id_users_id_fk": {
+          "name": "kobo_library_snapshots_user_id_users_id_fk",
+          "tableFrom": "kobo_library_snapshots",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_library_snapshots_user_id_unique": {
+          "name": "kobo_library_snapshots_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_reading_states": {
+      "name": "kobo_reading_states",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at_kobo": {
+          "name": "created_at_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_modified_kobo": {
+          "name": "last_modified_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority_timestamp": {
+          "name": "priority_timestamp",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "current_bookmark": {
+          "name": "current_bookmark",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "statistics": {
+          "name": "statistics",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_info": {
+          "name": "status_info",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_reading_states_user_id_users_id_fk": {
+          "name": "kobo_reading_states_user_id_users_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_reading_states_book_id_books_id_fk": {
+          "name": "kobo_reading_states_book_id_books_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_reading_states_user_id_book_id_unique": {
+          "name": "kobo_reading_states_user_id_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_snapshot_books": {
+      "name": "kobo_snapshot_books",
+      "schema": "",
+      "columns": {
+        "snapshot_id": {
+          "name": "snapshot_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "synced": {
+          "name": "synced",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "pending_delete": {
+          "name": "pending_delete",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_new": {
+          "name": "is_new",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "removed_by_device": {
+          "name": "removed_by_device",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "delivery_hash": {
+          "name": "delivery_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_hash": {
+          "name": "metadata_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "kobo_snapshot_books_snapshot_synced_book_idx": {
+          "name": "kobo_snapshot_books_snapshot_synced_book_idx",
+          "columns": [
+            {
+              "expression": "snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "synced",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk": {
+          "name": "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "kobo_library_snapshots",
+          "columnsFrom": ["snapshot_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_snapshot_books_book_id_books_id_fk": {
+          "name": "kobo_snapshot_books_book_id_books_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "kobo_snapshot_books_snapshot_id_book_id_pk": {
+          "name": "kobo_snapshot_books_snapshot_id_book_id_pk",
+          "columns": ["snapshot_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_sync_settings": {
+      "name": "kobo_sync_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "finished_threshold": {
+          "name": "finished_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 99
+        },
+        "convert_to_kepub": {
+          "name": "convert_to_kepub",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "force_enable_hyphenation": {
+          "name": "force_enable_hyphenation",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "kepub_conversion_limit_mb": {
+          "name": "kepub_conversion_limit_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "two_way_progress_sync": {
+          "name": "two_way_progress_sync",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_sync_settings_user_id_users_id_fk": {
+          "name": "kobo_sync_settings_user_id_users_id_fk",
+          "tableFrom": "kobo_sync_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_sync_settings_user_id_unique": {
+          "name": "kobo_sync_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "kobo_sync_settings_reading_threshold_range_chk": {
+          "name": "kobo_sync_settings_reading_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"reading_threshold\" >= 0 and \"kobo_sync_settings\".\"reading_threshold\" <= 100"
+        },
+        "kobo_sync_settings_finished_threshold_range_chk": {
+          "name": "kobo_sync_settings_finished_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"finished_threshold\" >= 0 and \"kobo_sync_settings\".\"finished_threshold\" <= 100"
+        },
+        "kobo_sync_settings_conversion_limit_nonnegative_chk": {
+          "name": "kobo_sync_settings_conversion_limit_nonnegative_chk",
+          "value": "\"kobo_sync_settings\".\"kepub_conversion_limit_mb\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_dock_files": {
+      "name": "book_dock_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "file_name": {
+          "name": "file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "embedded_metadata": {
+          "name": "embedded_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "selected_metadata": {
+          "name": "selected_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata": {
+          "name": "fetched_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_path": {
+          "name": "cover_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_library_id": {
+          "name": "target_library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_folder_id": {
+          "name": "target_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata_sources": {
+          "name": "fetched_metadata_sources",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_edited_at": {
+          "name": "metadata_edited_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uploaded_by": {
+          "name": "uploaded_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_dock_files_status_idx": {
+          "name": "book_dock_files_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_dock_files_uploaded_by_idx": {
+          "name": "book_dock_files_uploaded_by_idx",
+          "columns": [
+            {
+              "expression": "uploaded_by",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_dock_files_target_library_id_libraries_id_fk": {
+          "name": "book_dock_files_target_library_id_libraries_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "libraries",
+          "columnsFrom": ["target_library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_target_folder_id_library_folders_id_fk": {
+          "name": "book_dock_files_target_folder_id_library_folders_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["target_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_uploaded_by_users_id_fk": {
+          "name": "book_dock_files_uploaded_by_users_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "users",
+          "columnsFrom": ["uploaded_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "book_dock_files_absolute_path_unique": {
+          "name": "book_dock_files_absolute_path_unique",
+          "nullsNotDistinct": false,
+          "columns": ["absolute_path"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "book_dock_files_status_chk": {
+          "name": "book_dock_files_status_chk",
+          "value": "\"book_dock_files\".\"status\" in ('pending', 'extracting', 'fetching', 'ready', 'error')"
+        },
+        "book_dock_files_confidence_range_chk": {
+          "name": "book_dock_files_confidence_range_chk",
+          "value": "\"book_dock_files\".\"confidence\" is null or (\"book_dock_files\".\"confidence\" >= 0 and \"book_dock_files\".\"confidence\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.file_write_log": {
+      "name": "file_write_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fields_written": {
+          "name": "fields_written",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "written_at": {
+          "name": "written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "fwl_book_id_written_at_idx": {
+          "name": "fwl_book_id_written_at_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "written_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "file_write_log_book_id_books_id_fk": {
+          "name": "file_write_log_book_id_books_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "file_write_log_book_file_id_book_files_id_fk": {
+          "name": "file_write_log_book_file_id_book_files_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "file_write_log_user_id_users_id_fk": {
+          "name": "file_write_log_user_id_users_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "file_write_log_status_chk": {
+          "name": "file_write_log_status_chk",
+          "value": "\"file_write_log\".\"status\" in ('success', 'skipped', 'failed')"
+        },
+        "file_write_log_triggered_by_chk": {
+          "name": "file_write_log_triggered_by_chk",
+          "value": "\"file_write_log\".\"triggered_by\" in ('auto', 'sync')"
+        },
+        "file_write_log_duration_ms_nonnegative_chk": {
+          "name": "file_write_log_duration_ms_nonnegative_chk",
+          "value": "\"file_write_log\".\"duration_ms\" is null or \"file_write_log\".\"duration_ms\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_templates": {
+      "name": "email_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_text": {
+          "name": "body_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system": {
+          "name": "is_system",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_templates_one_default_per_user_uidx": {
+          "name": "email_templates_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"is_default\" = true and \"email_templates\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_templates_system_name_unique": {
+          "name": "email_templates_system_name_unique",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"user_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_templates_user_id_users_id_fk": {
+          "name": "email_templates_user_id_users_id_fk",
+          "tableFrom": "email_templates",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_templates_user_id_name_unique": {
+          "name": "email_templates_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_providers": {
+      "name": "email_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "host": {
+          "name": "host",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "port": {
+          "name": "port",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_enc": {
+          "name": "password_enc",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_name": {
+          "name": "from_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_address": {
+          "name": "from_address",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth": {
+          "name": "auth",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "ssl": {
+          "name": "ssl",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "start_tls": {
+          "name": "start_tls",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_shared": {
+          "name": "is_shared",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system_provider": {
+          "name": "is_system_provider",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "tls_reject_unauthorized": {
+          "name": "tls_reject_unauthorized",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_providers_one_default_per_user_uidx": {
+          "name": "email_providers_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_default\" = true and \"email_providers\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_providers_one_system_provider_uidx": {
+          "name": "email_providers_one_system_provider_uidx",
+          "columns": [
+            {
+              "expression": "is_system_provider",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_system_provider\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_providers_user_id_users_id_fk": {
+          "name": "email_providers_user_id_users_id_fk",
+          "tableFrom": "email_providers",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_providers_user_id_name_unique": {
+          "name": "email_providers_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_providers_id_user_id_unique": {
+          "name": "email_providers_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_providers_port_range_chk": {
+          "name": "email_providers_port_range_chk",
+          "value": "\"email_providers\".\"port\" >= 1 and \"email_providers\".\"port\" <= 65535"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_group_members": {
+      "name": "email_recipient_group_members",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "recipient_id": {
+          "name": "recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_group_members_user_id_users_id_fk": {
+          "name": "email_recipient_group_members_user_id_users_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_id_email_recipient_groups_id_fk": {
+          "name": "email_recipient_group_members_group_id_email_recipient_groups_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_id_email_recipients_id_fk": {
+          "name": "email_recipient_group_members_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_user_fk": {
+          "name": "email_recipient_group_members_group_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_user_fk": {
+          "name": "email_recipient_group_members_recipient_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "email_recipient_group_members_group_id_recipient_id_pk": {
+          "name": "email_recipient_group_members_group_id_recipient_id_pk",
+          "columns": ["group_id", "recipient_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_groups": {
+      "name": "email_recipient_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_groups_user_id_users_id_fk": {
+          "name": "email_recipient_groups_user_id_users_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_groups_default_template_id_email_templates_id_fk": {
+          "name": "email_recipient_groups_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipient_groups_user_id_name_unique": {
+          "name": "email_recipient_groups_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_recipient_groups_id_user_id_unique": {
+          "name": "email_recipient_groups_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipients": {
+      "name": "email_recipients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "device_type": {
+          "name": "device_type",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "preferred_format": {
+          "name": "preferred_format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_recipients_user_email_lower_uidx": {
+          "name": "email_recipients_user_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_recipients_one_default_per_user_uidx": {
+          "name": "email_recipients_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_recipients\".\"is_default\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_recipients_user_id_users_id_fk": {
+          "name": "email_recipients_user_id_users_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipients_default_template_id_email_templates_id_fk": {
+          "name": "email_recipients_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipients_user_id_email_unique": {
+          "name": "email_recipients_user_id_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "email"]
+        },
+        "email_recipients_id_user_id_unique": {
+          "name": "email_recipients_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_recipients_device_type_chk": {
+          "name": "email_recipients_device_type_chk",
+          "value": "\"email_recipients\".\"device_type\" is null or \"email_recipients\".\"device_type\" in ('kindle', 'kobo', 'other')"
+        },
+        "email_recipients_preferred_format_chk": {
+          "name": "email_recipients_preferred_format_chk",
+          "value": "\"email_recipients\".\"preferred_format\" is null or \"email_recipients\".\"preferred_format\" in ('epub', 'pdf', 'mobi', 'azw3', 'cbz', 'cbr')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_preferences": {
+      "name": "email_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_provider_id": {
+          "name": "default_provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_recipient_id": {
+          "name": "default_recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_preferences_user_id_users_id_fk": {
+          "name": "email_preferences_user_id_users_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_provider_id_email_providers_id_fk": {
+          "name": "email_preferences_default_provider_id_email_providers_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_providers",
+          "columnsFrom": ["default_provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_id_email_recipients_id_fk": {
+          "name": "email_preferences_default_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_template_id_email_templates_id_fk": {
+          "name": "email_preferences_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_owner_fk": {
+          "name": "email_preferences_default_recipient_owner_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_preferences_user_id_unique": {
+          "name": "email_preferences_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_send_log": {
+      "name": "email_send_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "to_email": {
+          "name": "to_email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_name": {
+          "name": "to_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_send_log_user_created_at_idx": {
+          "name": "email_send_log_user_created_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_created_at_idx": {
+          "name": "email_send_log_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_status_next_retry_idx": {
+          "name": "email_send_log_status_next_retry_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_retry_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_send_log_user_id_users_id_fk": {
+          "name": "email_send_log_user_id_users_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_id_books_id_fk": {
+          "name": "email_send_log_book_id_books_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_file_id_book_files_id_fk": {
+          "name": "email_send_log_book_file_id_book_files_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_provider_id_email_providers_id_fk": {
+          "name": "email_send_log_provider_id_email_providers_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_template_id_email_templates_id_fk": {
+          "name": "email_send_log_template_id_email_templates_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_templates",
+          "columnsFrom": ["template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "email_send_log_status_chk": {
+          "name": "email_send_log_status_chk",
+          "value": "\"email_send_log\".\"status\" in ('pending', 'sent', 'failed')"
+        },
+        "email_send_log_attempt_count_nonnegative_chk": {
+          "name": "email_send_log_attempt_count_nonnegative_chk",
+          "value": "\"email_send_log\".\"attempt_count\" >= 0"
+        },
+        "email_send_log_sent_after_created_chk": {
+          "name": "email_send_log_sent_after_created_chk",
+          "value": "\"email_send_log\".\"sent_at\" is null or \"email_send_log\".\"sent_at\" >= \"email_send_log\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action_url": {
+          "name": "action_url",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "read": {
+          "name": "read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_id_idx": {
+          "name": "notifications_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_user_unread_idx": {
+          "name": "notifications_user_unread_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "read",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_created_at_idx": {
+          "name": "notifications_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "notifications_user_id_users_id_fk": {
+          "name": "notifications_user_id_users_id_fk",
+          "tableFrom": "notifications",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_duplicate_pairs": {
+      "name": "dismissed_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_duplicate_pairs_entity_a_idx": {
+          "name": "dismissed_duplicate_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_duplicate_pairs_entity_b_idx": {
+          "name": "dismissed_duplicate_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_duplicate_pairs_unique": {
+          "name": "dismissed_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_inline_duplicate_pairs": {
+      "name": "dismissed_inline_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_a": {
+          "name": "value_a",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_b": {
+          "name": "value_b",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_inline_pairs_entity_a_idx": {
+          "name": "dismissed_inline_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_inline_pairs_entity_b_idx": {
+          "name": "dismissed_inline_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_inline_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_inline_duplicate_pairs_unique": {
+          "name": "dismissed_inline_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "value_a", "value_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_candidates": {
+      "name": "entity_duplicate_candidates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sim_score": {
+          "name": "sim_score",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "entity_dup_candidates_type_sim_idx": {
+          "name": "entity_dup_candidates_type_sim_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sim_score",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_a_idx": {
+          "name": "entity_dup_candidates_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_b_idx": {
+          "name": "entity_dup_candidates_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "entity_duplicate_candidates_unique": {
+          "name": "entity_duplicate_candidates_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_scan_status": {
+      "name": "entity_duplicate_scan_status",
+      "schema": "",
+      "columns": {
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "is_computing": {
+          "name": "is_computing",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_pairs": {
+          "name": "total_pairs",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "processed_count": {
+          "name": "processed_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_count": {
+          "name": "total_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_fonts": {
+      "name": "user_fonts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "family_name": {
+          "name": "family_name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_file_name": {
+          "name": "original_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stored_file_name": {
+          "name": "stored_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 400
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "uf_user_hash_uidx": {
+          "name": "uf_user_hash_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "uf_user_family_weight_style_uidx": {
+          "name": "uf_user_family_weight_style_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "family_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "weight",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "style",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_fonts_user_id_users_id_fk": {
+          "name": "user_fonts_user_id_users_id_fk",
+          "tableFrom": "user_fonts",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_fonts_format_chk": {
+          "name": "user_fonts_format_chk",
+          "value": "\"user_fonts\".\"format\" in ('ttf', 'otf', 'woff', 'woff2')"
+        },
+        "user_fonts_weight_chk": {
+          "name": "user_fonts_weight_chk",
+          "value": "\"user_fonts\".\"weight\" >= 100 and \"user_fonts\".\"weight\" <= 900 and \"user_fonts\".\"weight\" % 100 = 0"
+        },
+        "user_fonts_style_chk": {
+          "name": "user_fonts_style_chk",
+          "value": "\"user_fonts\".\"style\" in ('normal', 'italic')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_file_chapters": {
+      "name": "book_file_chapters",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "href": {
+          "name": "href",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "spine_index": {
+          "name": "spine_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "book_file_chapters_book_file_id_chapter_index_uidx": {
+          "name": "book_file_chapters_book_file_id_chapter_index_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "chapter_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_chapters_book_file_id_idx": {
+          "name": "book_file_chapters_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_chapters_book_file_id_book_files_id_fk": {
+          "name": "book_file_chapters_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_chapters",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_file_hash_history": {
+      "name": "book_file_hash_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(30)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_file_hash_history_book_file_id_file_hash_idx": {
+          "name": "book_file_hash_history_book_file_id_file_hash_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_hash_history_file_hash_idx": {
+          "name": "book_file_hash_history_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_hash_history_book_file_id_book_files_id_fk": {
+          "name": "book_file_hash_history_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_hash_history",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_file_hash_history_reason_chk": {
+          "name": "book_file_hash_history_reason_chk",
+          "value": "\"book_file_hash_history\".\"reason\" in ('file_write', 'external_change', 'rescan')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_progress": {
+      "name": "koreader_device_progress",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device": {
+          "name": "device",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "progress": {
+          "name": "progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_timestamp": {
+          "name": "sync_timestamp",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "orphaned": {
+          "name": "orphaned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "orphaned_hash": {
+          "name": "orphaned_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_device_progress_book_user_device_uidx": {
+          "name": "koreader_device_progress_book_user_device_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"koreader_device_progress\".\"orphaned\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_orphaned_hash_idx": {
+          "name": "koreader_device_progress_orphaned_hash_idx",
+          "columns": [
+            {
+              "expression": "orphaned_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"orphaned\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_user_updated_at_idx": {
+          "name": "koreader_device_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_book_file_id_idx": {
+          "name": "koreader_device_progress_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"book_file_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_progress_book_file_id_book_files_id_fk": {
+          "name": "koreader_device_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "koreader_device_progress_user_id_users_id_fk": {
+          "name": "koreader_device_progress_user_id_users_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_device_progress_percentage_range_chk": {
+          "name": "koreader_device_progress_percentage_range_chk",
+          "value": "\"koreader_device_progress\".\"percentage\" is null or (\"koreader_device_progress\".\"percentage\" >= 0 and \"koreader_device_progress\".\"percentage\" <= 1)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_sweeps": {
+      "name": "koreader_device_sweeps",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_model": {
+          "name": "device_model",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "plugin_version": {
+          "name": "plugin_version",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_sweep_at": {
+          "name": "last_sweep_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_sweep_books_matched": {
+          "name": "last_sweep_books_matched",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_page_stats": {
+          "name": "last_sweep_page_stats",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_annotations": {
+          "name": "last_sweep_annotations",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kds_user_id_idx": {
+          "name": "kds_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_sweeps_user_id_users_id_fk": {
+          "name": "koreader_device_sweeps_user_id_users_id_fk",
+          "tableFrom": "koreader_device_sweeps",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "koreader_device_sweeps_user_id_device_id_pk": {
+          "name": "koreader_device_sweeps_user_id_device_id_pk",
+          "columns": ["user_id", "device_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.koreader_page_stats": {
+      "name": "koreader_page_stats",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page": {
+          "name": "page",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "total_pages": {
+          "name": "total_pages",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kps_user_file_device_page_start_uidx": {
+          "name": "kps_user_file_device_page_start_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_file_device_start_idx": {
+          "name": "kps_user_file_device_start_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_id_idx": {
+          "name": "kps_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_page_stats_user_id_users_id_fk": {
+          "name": "koreader_page_stats_user_id_users_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "koreader_page_stats_book_file_id_book_files_id_fk": {
+          "name": "koreader_page_stats_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_page_stats_duration_nonnegative_chk": {
+          "name": "koreader_page_stats_duration_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"duration_seconds\" >= 0"
+        },
+        "koreader_page_stats_page_nonnegative_chk": {
+          "name": "koreader_page_stats_page_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"page\" >= 0"
+        },
+        "koreader_page_stats_total_pages_positive_chk": {
+          "name": "koreader_page_stats_total_pages_positive_chk",
+          "value": "\"koreader_page_stats\".\"total_pages\" > 0"
+        },
+        "koreader_page_stats_start_time_positive_chk": {
+          "name": "koreader_page_stats_start_time_positive_chk",
+          "value": "\"koreader_page_stats\".\"start_time\" > 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_users": {
+      "name": "koreader_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_md5": {
+          "name": "password_md5",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_enabled": {
+          "name": "sync_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_users_user_id_uidx": {
+          "name": "koreader_users_user_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_users_username_uidx": {
+          "name": "koreader_users_username_uidx",
+          "columns": [
+            {
+              "expression": "username",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_users_user_id_users_id_fk": {
+          "name": "koreader_users_user_id_users_id_fk",
+          "tableFrom": "koreader_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.achievements": {
+      "name": "achievements",
+      "schema": "",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "varchar(64)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "group_key": {
+          "name": "group_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon_name": {
+          "name": "icon_name",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rarity": {
+          "name": "rarity",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hidden": {
+          "name": "hidden",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "achievements_category_sort_idx": {
+          "name": "achievements_category_sort_idx",
+          "columns": [
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "achievements_group_key_idx": {
+          "name": "achievements_group_key_idx",
+          "columns": [
+            {
+              "expression": "group_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "achievements_category_chk": {
+          "name": "achievements_category_chk",
+          "value": "\"achievements\".\"category\" in ('reading', 'library', 'exploration', 'dedication')"
+        },
+        "achievements_rarity_chk": {
+          "name": "achievements_rarity_chk",
+          "value": "\"achievements\".\"rarity\" in ('common', 'rare', 'epic', 'legendary')"
+        },
+        "achievements_tier_chk": {
+          "name": "achievements_tier_chk",
+          "value": "\"achievements\".\"tier\" is null or (\"achievements\".\"tier\" >= 1 and \"achievements\".\"tier\" <= 4)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_achievements": {
+      "name": "user_achievements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "achievement_key": {
+          "name": "achievement_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "awarded_at": {
+          "name": "awarded_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "context_json": {
+          "name": "context_json",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "user_achievements_user_key_uidx": {
+          "name": "user_achievements_user_key_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "achievement_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_id_idx": {
+          "name": "user_achievements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_awarded_at_idx": {
+          "name": "user_achievements_user_awarded_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "awarded_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_achievements_user_id_users_id_fk": {
+          "name": "user_achievements_user_id_users_id_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_achievements_achievement_key_achievements_key_fk": {
+          "name": "user_achievements_achievement_key_achievements_key_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "achievements",
+          "columnsFrom": ["achievement_key"],
+          "columnsTo": ["key"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_book_state": {
+      "name": "hardcover_book_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hardcover_book_id": {
+          "name": "hardcover_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_edition_id": {
+          "name": "hardcover_edition_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_user_book_id": {
+          "name": "hardcover_user_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_read_id": {
+          "name": "hardcover_read_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_method": {
+          "name": "match_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_error": {
+          "name": "match_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_status": {
+          "name": "last_synced_status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_progress": {
+          "name": "last_synced_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_rating": {
+          "name": "last_synced_rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_started_at": {
+          "name": "last_synced_started_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_finished_at": {
+          "name": "last_synced_finished_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_book_state_user_id_users_id_fk": {
+          "name": "hardcover_book_state_user_id_users_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "hardcover_book_state_book_id_books_id_fk": {
+          "name": "hardcover_book_state_book_id_books_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_book_state_user_book_uidx": {
+          "name": "hardcover_book_state_user_book_uidx",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_user_settings": {
+      "name": "hardcover_user_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "api_token": {
+          "name": "api_token",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_status_change": {
+          "name": "auto_sync_on_status_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_progress_update": {
+          "name": "auto_sync_on_progress_update",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_rating_change": {
+          "name": "auto_sync_on_rating_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "privacy_setting_id": {
+          "name": "privacy_setting_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 3
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_user_settings_user_id_users_id_fk": {
+          "name": "hardcover_user_settings_user_id_users_id_fk",
+          "tableFrom": "hardcover_user_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_user_settings_user_id_unique": {
+          "name": "hardcover_user_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_preferences": {
+      "name": "user_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "up_user_category_idx": {
+          "name": "up_user_category_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_preferences_user_id_users_id_fk": {
+          "name": "user_preferences_user_id_users_id_fk",
+          "tableFrom": "user_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.content_filter_type": {
+      "name": "content_filter_type",
+      "schema": "public",
+      "values": ["include", "exclude"]
+    },
+    "public.library_access_level": {
+      "name": "library_access_level",
+      "schema": "public",
+      "values": ["viewer", "editor", "owner"]
+    },
+    "public.user_avatar_source": {
+      "name": "user_avatar_source",
+      "schema": "public",
+      "values": ["none", "external", "uploaded"]
+    },
+    "public.opds_sort_order": {
+      "name": "opds_sort_order",
+      "schema": "public",
+      "values": ["recent", "title_asc", "title_desc", "author_asc", "author_desc", "series_asc", "series_desc"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/server/src/db/migrations/meta/0028_snapshot.json b/server/src/db/migrations/meta/0028_snapshot.json
new file mode 100644
index 000000000..98a5fff6c
--- /dev/null
+++ b/server/src/db/migrations/meta/0028_snapshot.json
@@ -0,0 +1,11351 @@
+{
+  "id": "ae965fcc-0970-44af-b1c9-2e7ea74893e5",
+  "prevId": "d20a77d2-02c8-4790-973c-50845a9eab26",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.audit_log": {
+      "name": "audit_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_username": {
+          "name": "actor_username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "resource": {
+          "name": "resource",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "resource_id": {
+          "name": "resource_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip": {
+          "name": "ip",
+          "type": "varchar(45)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_audit_user_id": {
+          "name": "idx_audit_user_id",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_resource": {
+          "name": "idx_audit_resource",
+          "columns": [
+            {
+              "expression": "resource",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "resource_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_action": {
+          "name": "idx_audit_action",
+          "columns": [
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_ip": {
+          "name": "idx_audit_ip",
+          "columns": [
+            {
+              "expression": "ip",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_created_at": {
+          "name": "idx_audit_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audit_log_user_id_users_id_fk": {
+          "name": "audit_log_user_id_users_id_fk",
+          "tableFrom": "audit_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.app_settings": {
+      "name": "app_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "app_settings_key_unique": {
+          "name": "app_settings_key_unique",
+          "nullsNotDistinct": false,
+          "columns": ["key"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.magic_access_tokens": {
+      "name": "magic_access_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "label": {
+          "name": "label",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_token": {
+          "name": "raw_token",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "use_count": {
+          "name": "use_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "magic_access_tokens_user_id_idx": {
+          "name": "magic_access_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "magic_access_tokens_user_id_users_id_fk": {
+          "name": "magic_access_tokens_user_id_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "magic_access_tokens_created_by_users_id_fk": {
+          "name": "magic_access_tokens_created_by_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["created_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "magic_access_tokens_token_hash_unique": {
+          "name": "magic_access_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "magic_access_tokens_use_count_nonneg_chk": {
+          "name": "magic_access_tokens_use_count_nonneg_chk",
+          "value": "\"magic_access_tokens\".\"use_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "used_at": {
+          "name": "used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "password_reset_tokens_user_id_idx": {
+          "name": "password_reset_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "password_reset_tokens_expires_at_idx": {
+          "name": "password_reset_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "password_reset_tokens_user_id_users_id_fk": {
+          "name": "password_reset_tokens_user_id_users_id_fk",
+          "tableFrom": "password_reset_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "password_reset_tokens_token_hash_unique": {
+          "name": "password_reset_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "password_reset_tokens_expires_after_created_chk": {
+          "name": "password_reset_tokens_expires_after_created_chk",
+          "value": "\"password_reset_tokens\".\"expires_at\" > \"password_reset_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.refresh_tokens": {
+      "name": "refresh_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rotated_at": {
+          "name": "rotated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replaced_by_token_hash": {
+          "name": "replaced_by_token_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_user_id_idx": {
+          "name": "refresh_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "refresh_tokens_expires_at_idx": {
+          "name": "refresh_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "refresh_tokens_token_hash_unique": {
+          "name": "refresh_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "refresh_tokens_expires_after_created_chk": {
+          "name": "refresh_tokens_expires_after_created_chk",
+          "value": "\"refresh_tokens\".\"expires_at\" > \"refresh_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_genres": {
+      "name": "user_content_filter_genres",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_genres_genre_id_idx": {
+          "name": "user_content_filter_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_genres_user_id_users_id_fk": {
+          "name": "user_content_filter_genres_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_genres_genre_id_genres_id_fk": {
+          "name": "user_content_filter_genres_genre_id_genres_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_genres_user_id_filter_type_genre_id_pk": {
+          "name": "user_content_filter_genres_user_id_filter_type_genre_id_pk",
+          "columns": ["user_id", "filter_type", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_tags": {
+      "name": "user_content_filter_tags",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_tags_tag_id_idx": {
+          "name": "user_content_filter_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_tags_user_id_users_id_fk": {
+          "name": "user_content_filter_tags_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_tags_tag_id_tags_id_fk": {
+          "name": "user_content_filter_tags_tag_id_tags_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_tags_user_id_filter_type_tag_id_pk": {
+          "name": "user_content_filter_tags_user_id_filter_type_tag_id_pk",
+          "columns": ["user_id", "filter_type", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_library_access": {
+      "name": "user_library_access",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_level": {
+          "name": "access_level",
+          "type": "library_access_level",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        }
+      },
+      "indexes": {
+        "user_library_access_library_user_idx": {
+          "name": "user_library_access_library_user_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_library_access_user_id_users_id_fk": {
+          "name": "user_library_access_user_id_users_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_library_access_library_id_libraries_id_fk": {
+          "name": "user_library_access_library_id_libraries_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_library_access_user_id_library_id_pk": {
+          "name": "user_library_access_user_id_library_id_pk",
+          "columns": ["user_id", "library_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_permissions": {
+      "name": "user_permissions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_permissions_user_id_users_id_fk": {
+          "name": "user_permissions_user_id_users_id_fk",
+          "tableFrom": "user_permissions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_permissions_user_id_permission_name_pk": {
+          "name": "user_permissions_user_id_permission_name_pk",
+          "columns": ["user_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_superuser": {
+          "name": "is_superuser",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_default_password": {
+          "name": "is_default_password",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "token_version": {
+          "name": "token_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "failed_login_attempts": {
+          "name": "failed_login_attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "locked_until": {
+          "name": "locked_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_source": {
+          "name": "avatar_source",
+          "type": "user_avatar_source",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'none'"
+        },
+        "avatar_version": {
+          "name": "avatar_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "provisioning_method": {
+          "name": "provisioning_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'local'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "users_username_lower_uidx": {
+          "name": "users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_email_lower_uidx": {
+          "name": "users_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"email\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_oidc_subject_issuer_uidx": {
+          "name": "users_oidc_subject_issuer_uidx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"oidc_subject\" is not null and \"users\".\"oidc_issuer\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        },
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["email"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "users_provisioning_method_chk": {
+          "name": "users_provisioning_method_chk",
+          "value": "\"users\".\"provisioning_method\" in ('local', 'manual', 'oidc', 'shared')"
+        },
+        "users_token_version_nonnegative_chk": {
+          "name": "users_token_version_nonnegative_chk",
+          "value": "\"users\".\"token_version\" >= 0"
+        },
+        "users_failed_login_attempts_nonnegative_chk": {
+          "name": "users_failed_login_attempts_nonnegative_chk",
+          "value": "\"users\".\"failed_login_attempts\" >= 0"
+        },
+        "users_avatar_version_nonnegative_chk": {
+          "name": "users_avatar_version_nonnegative_chk",
+          "value": "\"users\".\"avatar_version\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.comic_metadata": {
+      "name": "comic_metadata",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issue_number": {
+          "name": "issue_number",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "volume_name": {
+          "name": "volume_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pencillers": {
+          "name": "pencillers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "inkers": {
+          "name": "inkers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "colorists": {
+          "name": "colorists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "letterers": {
+          "name": "letterers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_artists": {
+          "name": "cover_artists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "characters": {
+          "name": "characters",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "teams": {
+          "name": "teams",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locations": {
+          "name": "locations",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "story_arcs": {
+          "name": "story_arcs",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comic_metadata_book_id_books_id_fk": {
+          "name": "comic_metadata_book_id_books_id_fk",
+          "tableFrom": "comic_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comic_metadata_book_id_unique": {
+          "name": "comic_metadata_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_plan_artifacts": {
+      "name": "migration_plan_artifacts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_snapshot_hash": {
+          "name": "source_snapshot_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_hash": {
+          "name": "profile_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_hash": {
+          "name": "plan_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan": {
+          "name": "plan",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_plan_artifacts_plan_hash_uidx": {
+          "name": "migration_plan_artifacts_plan_hash_uidx",
+          "columns": [
+            {
+              "expression": "plan_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_source_id_idx": {
+          "name": "migration_plan_artifacts_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_profile_id_idx": {
+          "name": "migration_plan_artifacts_profile_id_idx",
+          "columns": [
+            {
+              "expression": "profile_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_plan_artifacts_source_id_migration_sources_id_fk": {
+          "name": "migration_plan_artifacts_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_id_migration_profiles_id_fk": {
+          "name": "migration_plan_artifacts_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_created_by_user_id_users_id_fk": {
+          "name": "migration_plan_artifacts_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_source_fk": {
+          "name": "migration_plan_artifacts_profile_source_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_plan_artifacts_id_source_profile_unique": {
+          "name": "migration_plan_artifacts_id_source_profile_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id", "profile_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_profiles": {
+      "name": "migration_profiles",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "user_mappings": {
+          "name": "user_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path_mappings": {
+          "name": "path_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_profiles_source_name_version_uidx": {
+          "name": "migration_profiles_source_name_version_uidx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "version",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_profiles_source_id_idx": {
+          "name": "migration_profiles_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_profiles_source_id_migration_sources_id_fk": {
+          "name": "migration_profiles_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_profiles_created_by_user_id_users_id_fk": {
+          "name": "migration_profiles_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_profiles_id_source_id_unique": {
+          "name": "migration_profiles_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "migration_profiles_version_positive_chk": {
+          "name": "migration_profiles_version_positive_chk",
+          "value": "\"migration_profiles\".\"version\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_run_metrics": {
+      "name": "migration_run_metrics",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stage": {
+          "name": "stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "processed": {
+          "name": "processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "imported": {
+          "name": "imported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "skipped": {
+          "name": "skipped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "unresolved": {
+          "name": "unresolved",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "failed": {
+          "name": "failed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_run_metrics_run_stage_entity_uidx": {
+          "name": "migration_run_metrics_run_stage_entity_uidx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "stage",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_run_metrics_run_id_idx": {
+          "name": "migration_run_metrics_run_id_idx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_run_metrics_run_id_migration_runs_id_fk": {
+          "name": "migration_run_metrics_run_id_migration_runs_id_fk",
+          "tableFrom": "migration_run_metrics",
+          "tableTo": "migration_runs",
+          "columnsFrom": ["run_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_run_metrics_processed_nonnegative_chk": {
+          "name": "migration_run_metrics_processed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"processed\" >= 0"
+        },
+        "migration_run_metrics_imported_nonnegative_chk": {
+          "name": "migration_run_metrics_imported_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"imported\" >= 0"
+        },
+        "migration_run_metrics_skipped_nonnegative_chk": {
+          "name": "migration_run_metrics_skipped_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"skipped\" >= 0"
+        },
+        "migration_run_metrics_unresolved_nonnegative_chk": {
+          "name": "migration_run_metrics_unresolved_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"unresolved\" >= 0"
+        },
+        "migration_run_metrics_failed_nonnegative_chk": {
+          "name": "migration_run_metrics_failed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"failed\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_runs": {
+      "name": "migration_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_artifact_id": {
+          "name": "plan_artifact_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_key": {
+          "name": "target_key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'bookorbit'"
+        },
+        "state": {
+          "name": "state",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "current_stage": {
+          "name": "current_stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by_user_id": {
+          "name": "triggered_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_runs_source_target_state_idx": {
+          "name": "migration_runs_source_target_state_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "target_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_runs_state_idx": {
+          "name": "migration_runs_state_idx",
+          "columns": [
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_runs_source_id_migration_sources_id_fk": {
+          "name": "migration_runs_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_id_migration_profiles_id_fk": {
+          "name": "migration_runs_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk": {
+          "name": "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_triggered_by_user_id_users_id_fk": {
+          "name": "migration_runs_triggered_by_user_id_users_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "users",
+          "columnsFrom": ["triggered_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_source_fk": {
+          "name": "migration_runs_profile_source_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_source_profile_fk": {
+          "name": "migration_runs_plan_artifact_source_profile_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id", "source_id", "profile_id"],
+          "columnsTo": ["id", "source_id", "profile_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        },
+        "migration_runs_started_before_ended_chk": {
+          "name": "migration_runs_started_before_ended_chk",
+          "value": "\"migration_runs\".\"ended_at\" is null or \"migration_runs\".\"started_at\" is null or \"migration_runs\".\"ended_at\" >= \"migration_runs\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_sources": {
+      "name": "migration_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_config": {
+          "name": "connection_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "capabilities": {
+          "name": "capabilities",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_validated_at": {
+          "name": "last_validated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_sources_type_name_uidx": {
+          "name": "migration_sources_type_name_uidx",
+          "columns": [
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_sources_created_by_user_id_users_id_fk": {
+          "name": "migration_sources_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_sources",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.libraries": {
+      "name": "libraries",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cover_aspect_ratio": {
+          "name": "cover_aspect_ratio",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'2/3'"
+        },
+        "watch": {
+          "name": "watch",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "auto_scan_cron_expression": {
+          "name": "auto_scan_cron_expression",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_precedence": {
+          "name": "metadata_precedence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"folderStructure\",\"embedded\",\"nfoFile\",\"opfFile\",\"sidecar\"]'::jsonb"
+        },
+        "format_priority": {
+          "name": "format_priority",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"epub\",\"pdf\",\"cbz\",\"cbr\",\"cb7\",\"mobi\",\"azw3\",\"azw\",\"fb2\",\"m4b\",\"mp3\",\"m4a\",\"opus\",\"ogg\",\"flac\"]'::jsonb"
+        },
+        "allowed_formats": {
+          "name": "allowed_formats",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "organization_mode": {
+          "name": "organization_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'book_per_folder'"
+        },
+        "exclude_patterns": {
+          "name": "exclude_patterns",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "double precision",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0.25
+        },
+        "mark_as_finished_percent_complete": {
+          "name": "mark_as_finished_percent_complete",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 98
+        },
+        "file_write_enabled": {
+          "name": "file_write_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_write_cover": {
+          "name": "file_write_write_cover",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_enabled": {
+          "name": "file_write_epub_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_max_file_size_mb": {
+          "name": "file_write_epub_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_pdf_enabled": {
+          "name": "file_write_pdf_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_pdf_max_file_size_mb": {
+          "name": "file_write_pdf_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_cbx_enabled": {
+          "name": "file_write_cbx_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_cbx_max_file_size_mb": {
+          "name": "file_write_cbx_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_write_audio_enabled": {
+          "name": "file_write_audio_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_audio_max_file_size_mb": {
+          "name": "file_write_audio_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_rename_enabled": {
+          "name": "file_rename_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_naming_pattern": {
+          "name": "file_naming_pattern",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_fetch_preferences": {
+          "name": "metadata_fetch_preferences",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_config": {
+          "name": "book_metadata_fetch_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_run_at": {
+          "name": "book_metadata_fetch_last_run_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_queued_count": {
+          "name": "book_metadata_fetch_last_queued_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scan_mode": {
+          "name": "scan_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "poll_interval_seconds": {
+          "name": "poll_interval_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "default": 300
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "libraries_name_lower_uidx": {
+          "name": "libraries_name_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "libraries_display_order_nonnegative_chk": {
+          "name": "libraries_display_order_nonnegative_chk",
+          "value": "\"libraries\".\"display_order\" >= 0"
+        },
+        "libraries_organization_mode_chk": {
+          "name": "libraries_organization_mode_chk",
+          "value": "\"libraries\".\"organization_mode\" in ('book_per_folder', 'book_per_file')"
+        },
+        "libraries_reading_threshold_range_chk": {
+          "name": "libraries_reading_threshold_range_chk",
+          "value": "\"libraries\".\"reading_threshold\" >= 0 and \"libraries\".\"reading_threshold\" <= 100"
+        },
+        "libraries_mark_finished_percent_range_chk": {
+          "name": "libraries_mark_finished_percent_range_chk",
+          "value": "\"libraries\".\"mark_as_finished_percent_complete\" >= 0 and \"libraries\".\"mark_as_finished_percent_complete\" <= 100"
+        },
+        "libraries_scan_mode_chk": {
+          "name": "libraries_scan_mode_chk",
+          "value": "\"libraries\".\"scan_mode\" in ('auto', 'manual')"
+        },
+        "libraries_poll_interval_nonnegative_chk": {
+          "name": "libraries_poll_interval_nonnegative_chk",
+          "value": "\"libraries\".\"poll_interval_seconds\" is null or \"libraries\".\"poll_interval_seconds\" >= 0"
+        },
+        "libraries_file_write_epub_max_size_chk": {
+          "name": "libraries_file_write_epub_max_size_chk",
+          "value": "\"libraries\".\"file_write_epub_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_pdf_max_size_chk": {
+          "name": "libraries_file_write_pdf_max_size_chk",
+          "value": "\"libraries\".\"file_write_pdf_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_cbx_max_size_chk": {
+          "name": "libraries_file_write_cbx_max_size_chk",
+          "value": "\"libraries\".\"file_write_cbx_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_audio_max_size_chk": {
+          "name": "libraries_file_write_audio_max_size_chk",
+          "value": "\"libraries\".\"file_write_audio_max_file_size_mb\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.library_folders": {
+      "name": "library_folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "library_folders_library_id_idx": {
+          "name": "library_folders_library_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_folders_library_path_uidx": {
+          "name": "library_folders_library_path_uidx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_folders_library_id_libraries_id_fk": {
+          "name": "library_folders_library_id_libraries_id_fk",
+          "tableFrom": "library_folders",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "library_folders_id_library_id_unique": {
+          "name": "library_folders_id_library_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_files": {
+      "name": "book_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rel_path": {
+          "name": "rel_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ino": {
+          "name": "ino",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "mtime": {
+          "name": "mtime",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'content'"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_files_absolute_path_uidx": {
+          "name": "book_files_absolute_path_uidx",
+          "columns": [
+            {
+              "expression": "absolute_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_book_id_idx": {
+          "name": "book_files_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_id_idx": {
+          "name": "book_files_library_folder_id_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_file_hash_idx": {
+          "name": "book_files_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_ino_idx": {
+          "name": "book_files_ino_idx",
+          "columns": [
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_format_idx": {
+          "name": "book_files_format_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_file_hash_idx": {
+          "name": "book_files_library_folder_file_hash_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_ino_idx": {
+          "name": "book_files_library_folder_ino_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_files_book_id_books_id_fk": {
+          "name": "book_files_book_id_books_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_library_folder_id_library_folders_id_fk": {
+          "name": "book_files_library_folder_id_library_folders_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_book_folder_consistency_fk": {
+          "name": "book_files_book_folder_consistency_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id", "library_folder_id"],
+          "columnsTo": ["id", "library_folder_id"],
+          "onDelete": "no action",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_files_role_chk": {
+          "name": "book_files_role_chk",
+          "value": "\"book_files\".\"role\" in ('content', 'cover', 'metadata', 'supplement')"
+        },
+        "book_files_size_bytes_nonnegative_chk": {
+          "name": "book_files_size_bytes_nonnegative_chk",
+          "value": "\"book_files\".\"size_bytes\" is null or \"book_files\".\"size_bytes\" >= 0"
+        },
+        "book_files_duration_seconds_nonnegative_chk": {
+          "name": "book_files_duration_seconds_nonnegative_chk",
+          "value": "\"book_files\".\"duration_seconds\" is null or \"book_files\".\"duration_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.books": {
+      "name": "books",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "primary_file_id": {
+          "name": "primary_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_path": {
+          "name": "folder_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'present'"
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "books_library_id_folder_path_idx": {
+          "name": "books_library_id_folder_path_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_primary_file_id_idx": {
+          "name": "books_primary_file_id_idx",
+          "columns": [
+            {
+              "expression": "primary_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_status_idx": {
+          "name": "books_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_added_at_idx": {
+          "name": "books_library_added_at_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "books_library_id_libraries_id_fk": {
+          "name": "books_library_id_libraries_id_fk",
+          "tableFrom": "books",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_id_library_folders_id_fk": {
+          "name": "books_library_folder_id_library_folders_id_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_primary_file_id_book_files_id_fk": {
+          "name": "books_primary_file_id_book_files_id_fk",
+          "tableFrom": "books",
+          "tableTo": "book_files",
+          "columnsFrom": ["primary_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_library_fk": {
+          "name": "books_library_folder_library_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id", "library_id"],
+          "columnsTo": ["id", "library_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "books_id_library_folder_id_unique": {
+          "name": "books_id_library_folder_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_folder_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "books_status_chk": {
+          "name": "books_status_chk",
+          "value": "\"books\".\"status\" in ('present', 'missing', 'processing')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.collection_books": {
+      "name": "collection_books",
+      "schema": "",
+      "columns": {
+        "collection_id": {
+          "name": "collection_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collection_books_book_id_idx": {
+          "name": "collection_books_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collection_books_collection_id_collections_id_fk": {
+          "name": "collection_books_collection_id_collections_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "collections",
+          "columnsFrom": ["collection_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "collection_books_book_id_books_id_fk": {
+          "name": "collection_books_book_id_books_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "collection_books_collection_id_book_id_pk": {
+          "name": "collection_books_collection_id_book_id_pk",
+          "columns": ["collection_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.collections": {
+      "name": "collections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_to_kobo": {
+          "name": "sync_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collections_user_name_uidx": {
+          "name": "collections_user_name_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "collections_user_display_name_idx": {
+          "name": "collections_user_display_name_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collections_user_id_users_id_fk": {
+          "name": "collections_user_id_users_id_fk",
+          "tableFrom": "collections",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.smart_scopes": {
+      "name": "smart_scopes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "filter": {
+          "name": "filter",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_sort": {
+          "name": "default_sort",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "smart_scopes_user_id_users_id_fk": {
+          "name": "smart_scopes_user_id_users_id_fk",
+          "tableFrom": "smart_scopes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "smart_scopes_user_id_name_unique": {
+          "name": "smart_scopes_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series": {
+      "name": "book_series",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "normalized_name": {
+          "name": "normalized_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_normalized_name_uidx": {
+          "name": "book_series_normalized_name_uidx",
+          "columns": [
+            {
+              "expression": "normalized_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_name_trgm_idx": {
+          "name": "book_series_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "book_series_name_lower_idx": {
+          "name": "book_series_name_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.author_enrichment_queue": {
+      "name": "author_enrichment_queue",
+      "schema": "",
+      "columns": {
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unknown'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_success_at": {
+          "name": "last_success_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "author_enrichment_queue_status_next_attempt_idx": {
+          "name": "author_enrichment_queue_status_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_next_attempt_idx": {
+          "name": "author_enrichment_queue_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_single_processing_idx": {
+          "name": "author_enrichment_queue_single_processing_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"author_enrichment_queue\".\"status\" = 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "author_enrichment_queue_author_id_authors_id_fk": {
+          "name": "author_enrichment_queue_author_id_authors_id_fk",
+          "tableFrom": "author_enrichment_queue",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "author_enrichment_queue_status_chk": {
+          "name": "author_enrichment_queue_status_chk",
+          "value": "\"author_enrichment_queue\".\"status\" in ('queued', 'processing', 'rate_limited', 'failed', 'done')"
+        },
+        "author_enrichment_queue_reason_chk": {
+          "name": "author_enrichment_queue_reason_chk",
+          "value": "\"author_enrichment_queue\".\"reason\" in ('unknown', 'metadata_replace', 'manual_backfill', 'manual_backfill_all', 'author_rename', 'author_merge_target')"
+        },
+        "author_enrichment_queue_attempt_count_nonnegative_chk": {
+          "name": "author_enrichment_queue_attempt_count_nonnegative_chk",
+          "value": "\"author_enrichment_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.authors": {
+      "name": "authors",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_photo": {
+          "name": "has_photo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "last_enriched_at": {
+          "name": "last_enriched_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "authors_name_trgm_idx": {
+          "name": "authors_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "authors_name_unique": {
+          "name": "authors_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_authors": {
+      "name": "book_authors",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_authors_author_id_idx": {
+          "name": "book_authors_author_id_idx",
+          "columns": [
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_authors_book_display_idx": {
+          "name": "book_authors_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_authors_book_id_books_id_fk": {
+          "name": "book_authors_book_id_books_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_authors_author_id_authors_id_fk": {
+          "name": "book_authors_author_id_authors_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_authors_book_id_author_id_pk": {
+          "name": "book_authors_book_id_author_id_pk",
+          "columns": ["book_id", "author_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_genres": {
+      "name": "book_genres",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_genres_genre_id_idx": {
+          "name": "book_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_genres_book_id_books_id_fk": {
+          "name": "book_genres_book_id_books_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_genres_genre_id_genres_id_fk": {
+          "name": "book_genres_genre_id_genres_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_genres_book_id_genre_id_pk": {
+          "name": "book_genres_book_id_genre_id_pk",
+          "columns": ["book_id", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_metadata": {
+      "name": "book_metadata",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subtitle": {
+          "name": "subtitle",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn10": {
+          "name": "isbn10",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn13": {
+          "name": "isbn13",
+          "type": "varchar(13)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "publisher": {
+          "name": "publisher",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_year": {
+          "name": "published_year",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "language": {
+          "name": "language",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_count": {
+          "name": "page_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_name": {
+          "name": "series_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_source": {
+          "name": "cover_source",
+          "type": "varchar(9)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "google_books_id": {
+          "name": "google_books_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "goodreads_id": {
+          "name": "goodreads_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "amazon_id": {
+          "name": "amazon_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_id": {
+          "name": "hardcover_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "open_library_id": {
+          "name": "open_library_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "itunes_id": {
+          "name": "itunes_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_id": {
+          "name": "kobo_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_score": {
+          "name": "metadata_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_metadata_fetch_at": {
+          "name": "last_metadata_fetch_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(256)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_written_at": {
+          "name": "last_written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "abridged": {
+          "name": "abridged",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "audible_id": {
+          "name": "audible_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "comicvine_id": {
+          "name": "comicvine_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ranobedb_id": {
+          "name": "ranobedb_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapters": {
+          "name": "chapters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locked_fields": {
+          "name": "locked_fields",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bm_title_trgm_idx": {
+          "name": "bm_title_trgm_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_title_lower_idx": {
+          "name": "bm_title_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"title\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_trgm_idx": {
+          "name": "bm_series_trgm_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_series_id_idx": {
+          "name": "bm_series_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_lower_btrim_idx": {
+          "name": "bm_series_name_lower_btrim_idx",
+          "columns": [
+            {
+              "expression": "lower(btrim(\"series_name\"))",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_publisher_trgm_idx": {
+          "name": "bm_publisher_trgm_idx",
+          "columns": [
+            {
+              "expression": "publisher",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_language_idx": {
+          "name": "bm_language_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_language_trgm_idx": {
+          "name": "bm_language_trgm_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_published_year_idx": {
+          "name": "bm_published_year_idx",
+          "columns": [
+            {
+              "expression": "published_year",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_index_idx": {
+          "name": "bm_series_name_index_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn10_idx": {
+          "name": "bm_isbn10_idx",
+          "columns": [
+            {
+              "expression": "isbn10",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn13_idx": {
+          "name": "bm_isbn13_idx",
+          "columns": [
+            {
+              "expression": "isbn13",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_embedding_hnsw_cosine_idx": {
+          "name": "bm_embedding_hnsw_cosine_idx",
+          "columns": [
+            {
+              "expression": "\"embedding\" vector_cosine_ops",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_book_id_books_id_fk": {
+          "name": "book_metadata_book_id_books_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_metadata_series_id_book_series_id_fk": {
+          "name": "book_metadata_series_id_book_series_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "book_series",
+          "columnsFrom": ["series_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_rating_range_chk": {
+          "name": "book_metadata_rating_range_chk",
+          "value": "\"book_metadata\".\"rating\" is null or (\"book_metadata\".\"rating\" >= 1 and \"book_metadata\".\"rating\" <= 10)"
+        },
+        "book_metadata_published_year_range_chk": {
+          "name": "book_metadata_published_year_range_chk",
+          "value": "\"book_metadata\".\"published_year\" is null or (\"book_metadata\".\"published_year\" >= 1000 and \"book_metadata\".\"published_year\" <= 2200)"
+        },
+        "book_metadata_page_count_nonnegative_chk": {
+          "name": "book_metadata_page_count_nonnegative_chk",
+          "value": "\"book_metadata\".\"page_count\" is null or \"book_metadata\".\"page_count\" >= 0"
+        },
+        "book_metadata_duration_seconds_nonnegative_chk": {
+          "name": "book_metadata_duration_seconds_nonnegative_chk",
+          "value": "\"book_metadata\".\"duration_seconds\" is null or \"book_metadata\".\"duration_seconds\" >= 0"
+        },
+        "book_metadata_cover_source_chk": {
+          "name": "book_metadata_cover_source_chk",
+          "value": "\"book_metadata\".\"cover_source\" is null or \"book_metadata\".\"cover_source\" in ('extracted', 'custom')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_metadata_fetch_queue": {
+      "name": "book_metadata_fetch_queue",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'manual_trigger'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bmfq_status_idx": {
+          "name": "bmfq_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_created_at_idx": {
+          "name": "bmfq_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_status_created_book_idx": {
+          "name": "bmfq_status_created_book_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_fetch_queue_book_id_books_id_fk": {
+          "name": "book_metadata_fetch_queue_book_id_books_id_fk",
+          "tableFrom": "book_metadata_fetch_queue",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_fetch_queue_status_chk": {
+          "name": "book_metadata_fetch_queue_status_chk",
+          "value": "\"book_metadata_fetch_queue\".\"status\" in ('queued', 'processing', 'failed')"
+        },
+        "book_metadata_fetch_queue_reason_chk": {
+          "name": "book_metadata_fetch_queue_reason_chk",
+          "value": "\"book_metadata_fetch_queue\".\"reason\" in ('event_import', 'manual_trigger', 'manual_retry')"
+        },
+        "book_metadata_fetch_queue_attempt_count_nonnegative_chk": {
+          "name": "book_metadata_fetch_queue_attempt_count_nonnegative_chk",
+          "value": "\"book_metadata_fetch_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_tags": {
+      "name": "book_tags",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_tags_tag_id_idx": {
+          "name": "book_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_tags_book_id_books_id_fk": {
+          "name": "book_tags_book_id_books_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_tags_tag_id_tags_id_fk": {
+          "name": "book_tags_tag_id_tags_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_tags_book_id_tag_id_pk": {
+          "name": "book_tags_book_id_tag_id_pk",
+          "columns": ["book_id", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.genres": {
+      "name": "genres",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "genres_name_trgm_idx": {
+          "name": "genres_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "genres_name_unique": {
+          "name": "genres_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.tags": {
+      "name": "tags",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "tags_name_trgm_idx": {
+          "name": "tags_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "tags_name_unique": {
+          "name": "tags_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_narrators": {
+      "name": "book_narrators",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "narrator_id": {
+          "name": "narrator_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_narrators_narrator_id_idx": {
+          "name": "book_narrators_narrator_id_idx",
+          "columns": [
+            {
+              "expression": "narrator_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_narrators_book_id_books_id_fk": {
+          "name": "book_narrators_book_id_books_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_narrators_narrator_id_narrators_id_fk": {
+          "name": "book_narrators_narrator_id_narrators_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "narrators",
+          "columnsFrom": ["narrator_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_narrators_book_id_narrator_id_pk": {
+          "name": "book_narrators_book_id_narrator_id_pk",
+          "columns": ["book_id", "narrator_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.narrators": {
+      "name": "narrators",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "narrators_name_trgm_idx": {
+          "name": "narrators_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "narrators_name_unique": {
+          "name": "narrators_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.library_dir_scan_state": {
+      "name": "library_dir_scan_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dir_path": {
+          "name": "dir_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_mtime_ms": {
+          "name": "last_seen_mtime_ms",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "library_dir_scan_state_folder_dir_uidx": {
+          "name": "library_dir_scan_state_folder_dir_uidx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "dir_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_dir_scan_state_folder_idx": {
+          "name": "library_dir_scan_state_folder_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_dir_scan_state_library_folder_id_library_folders_id_fk": {
+          "name": "library_dir_scan_state_library_folder_id_library_folders_id_fk",
+          "tableFrom": "library_dir_scan_state",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.scan_jobs": {
+      "name": "scan_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'running'"
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_count": {
+          "name": "added_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_count": {
+          "name": "updated_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "missing_count": {
+          "name": "missing_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "scan_jobs_library_status_idx": {
+          "name": "scan_jobs_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "scan_jobs_library_id_libraries_id_fk": {
+          "name": "scan_jobs_library_id_libraries_id_fk",
+          "tableFrom": "scan_jobs",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "scan_jobs_status_chk": {
+          "name": "scan_jobs_status_chk",
+          "value": "\"scan_jobs\".\"status\" in ('running', 'completed', 'failed')"
+        },
+        "scan_jobs_triggered_by_chk": {
+          "name": "scan_jobs_triggered_by_chk",
+          "value": "\"scan_jobs\".\"triggered_by\" in ('manual', 'watcher', 'schedule')"
+        },
+        "scan_jobs_added_count_nonnegative_chk": {
+          "name": "scan_jobs_added_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"added_count\" >= 0"
+        },
+        "scan_jobs_updated_count_nonnegative_chk": {
+          "name": "scan_jobs_updated_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"updated_count\" >= 0"
+        },
+        "scan_jobs_missing_count_nonnegative_chk": {
+          "name": "scan_jobs_missing_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"missing_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_positions": {
+      "name": "annotation_positions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(12)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pos0": {
+          "name": "pos0",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pos1": {
+          "name": "pos1",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'exact'"
+        },
+        "converter_version": {
+          "name": "converter_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "extras": {
+          "name": "extras",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_positions_annotation_format_uidx": {
+          "name": "annotation_positions_annotation_format_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_user_idx": {
+          "name": "annotation_positions_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_format_status_idx": {
+          "name": "annotation_positions_format_status_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_positions_annotation_id_annotations_id_fk": {
+          "name": "annotation_positions_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_user_id_users_id_fk": {
+          "name": "annotation_positions_user_id_users_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_book_file_id_book_files_id_fk": {
+          "name": "annotation_positions_book_file_id_book_files_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_positions_format_chk": {
+          "name": "annotation_positions_format_chk",
+          "value": "\"annotation_positions\".\"format\" in ('cfi', 'xpointer', 'pdf', 'kobo_span')"
+        },
+        "annotation_positions_status_chk": {
+          "name": "annotation_positions_status_chk",
+          "value": "\"annotation_positions\".\"status\" in ('exact', 'repaired', 'failed', 'pending')"
+        },
+        "annotation_positions_pos0_chk": {
+          "name": "annotation_positions_pos0_chk",
+          "value": "\"annotation_positions\".\"status\" in ('failed', 'pending') or \"annotation_positions\".\"pos0\" is not null"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_sync_state": {
+      "name": "annotation_sync_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_key": {
+          "name": "external_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_created_at": {
+          "name": "external_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_applied_version": {
+          "name": "last_applied_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "delete_acked_at": {
+          "name": "delete_acked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_synced_at": {
+          "name": "first_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_sync_state_annotation_source_device_uidx": {
+          "name": "annotation_sync_state_annotation_source_device_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_source_device_key_idx": {
+          "name": "annotation_sync_state_user_source_device_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_key_idx": {
+          "name": "annotation_sync_state_user_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_annotation_id_idx": {
+          "name": "annotation_sync_state_annotation_id_idx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_sync_state_annotation_id_annotations_id_fk": {
+          "name": "annotation_sync_state_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_sync_state_user_id_users_id_fk": {
+          "name": "annotation_sync_state_user_id_users_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_sync_state_source_chk": {
+          "name": "annotation_sync_state_source_chk",
+          "value": "\"annotation_sync_state\".\"source\" in ('koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotations": {
+      "name": "annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'yellow'"
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'highlight'"
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_title": {
+          "name": "chapter_title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'web'"
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_created_at": {
+          "name": "device_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_updated_at": {
+          "name": "device_updated_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_user_id_idx": {
+          "name": "annotations_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_idx": {
+          "name": "annotations_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_active_idx": {
+          "name": "annotations_user_book_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"annotations\".\"deleted_at\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotations_user_id_users_id_fk": {
+          "name": "annotations_user_id_users_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotations_book_id_books_id_fk": {
+          "name": "annotations_book_id_books_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_style_chk": {
+          "name": "annotations_style_chk",
+          "value": "\"annotations\".\"style\" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')"
+        },
+        "annotations_origin_chk": {
+          "name": "annotations_origin_chk",
+          "value": "\"annotations\".\"origin\" in ('web', 'koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.audiobook_progress": {
+      "name": "audiobook_progress",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "current_file_id": {
+          "name": "current_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "abp_user_id_idx": {
+          "name": "abp_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audiobook_progress_user_id_users_id_fk": {
+          "name": "audiobook_progress_user_id_users_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_book_id_books_id_fk": {
+          "name": "audiobook_progress_book_id_books_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_current_file_id_book_files_id_fk": {
+          "name": "audiobook_progress_current_file_id_book_files_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["current_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "audiobook_progress_user_id_book_id_pk": {
+          "name": "audiobook_progress_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "audiobook_progress_percentage_range_chk": {
+          "name": "audiobook_progress_percentage_range_chk",
+          "value": "\"audiobook_progress\".\"percentage\" >= 0 and \"audiobook_progress\".\"percentage\" <= 100"
+        },
+        "audiobook_progress_position_seconds_nonnegative_chk": {
+          "name": "audiobook_progress_position_seconds_nonnegative_chk",
+          "value": "\"audiobook_progress\".\"position_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.bookmarks": {
+      "name": "bookmarks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bookmarks_user_book_idx": {
+          "name": "bookmarks_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_cfi_uidx": {
+          "name": "bookmarks_user_book_cfi_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "cfi",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"cfi\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_pos_uidx": {
+          "name": "bookmarks_user_book_pos_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position_seconds",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"position_seconds\" is not null and \"bookmarks\".\"cfi\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "bookmarks_user_id_users_id_fk": {
+          "name": "bookmarks_user_id_users_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "bookmarks_book_id_books_id_fk": {
+          "name": "bookmarks_book_id_books_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reader_default_preferences": {
+      "name": "reader_default_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format_group": {
+          "name": "format_group",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rdp_user_format_idx": {
+          "name": "rdp_user_format_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format_group",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_default_preferences_user_id_users_id_fk": {
+          "name": "reader_default_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_default_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reader_default_preferences_format_group_chk": {
+          "name": "reader_default_preferences_format_group_chk",
+          "value": "\"reader_default_preferences\".\"format_group\" in ('epub', 'pdf', 'cbx', 'audio')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reader_preferences": {
+      "name": "reader_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rp_user_file_idx": {
+          "name": "rp_user_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_preferences_user_id_users_id_fk": {
+          "name": "reader_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reader_preferences_book_file_id_book_files_id_fk": {
+          "name": "reader_preferences_book_file_id_book_files_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reading_progress": {
+      "name": "reading_progress",
+      "schema": "",
+      "columns": {
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_source": {
+          "name": "kobo_location_source",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_type": {
+          "name": "kobo_location_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_value": {
+          "name": "kobo_location_value",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_content_source_progress_percent": {
+          "name": "kobo_content_source_progress_percent",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "koreader_progress": {
+          "name": "koreader_progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reading_progress_user_id_idx": {
+          "name": "reading_progress_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reading_progress_user_updated_at_idx": {
+          "name": "reading_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_progress_book_file_id_book_files_id_fk": {
+          "name": "reading_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_progress_user_id_users_id_fk": {
+          "name": "reading_progress_user_id_users_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "reading_progress_book_file_id_user_id_pk": {
+          "name": "reading_progress_book_file_id_user_id_pk",
+          "columns": ["book_file_id", "user_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_progress_percentage_range_chk": {
+          "name": "reading_progress_percentage_range_chk",
+          "value": "\"reading_progress\".\"percentage\" >= 0 and \"reading_progress\".\"percentage\" <= 100"
+        },
+        "reading_progress_page_number_nonnegative_chk": {
+          "name": "reading_progress_page_number_nonnegative_chk",
+          "value": "\"reading_progress\".\"page_number\" is null or \"reading_progress\".\"page_number\" >= 0"
+        },
+        "reading_progress_position_seconds_nonnegative_chk": {
+          "name": "reading_progress_position_seconds_nonnegative_chk",
+          "value": "\"reading_progress\".\"position_seconds\" is null or \"reading_progress\".\"position_seconds\" >= 0"
+        },
+        "reading_progress_kobo_content_source_progress_range_chk": {
+          "name": "reading_progress_kobo_content_source_progress_range_chk",
+          "value": "\"reading_progress\".\"kobo_content_source_progress_percent\" is null or (\"reading_progress\".\"kobo_content_source_progress_percent\" >= 0 and \"reading_progress\".\"kobo_content_source_progress_percent\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reading_sessions": {
+      "name": "reading_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_progress": {
+          "name": "end_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "rs_user_session_id_uidx": {
+          "name": "rs_user_session_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_started_at_idx": {
+          "name": "rs_user_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_book_file_started_at_idx": {
+          "name": "rs_book_file_started_at_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_file_idx": {
+          "name": "rs_user_book_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_sessions_user_id_users_id_fk": {
+          "name": "reading_sessions_user_id_users_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_file_id_book_files_id_fk": {
+          "name": "reading_sessions_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_sessions_duration_seconds_nonnegative_chk": {
+          "name": "reading_sessions_duration_seconds_nonnegative_chk",
+          "value": "\"reading_sessions\".\"duration_seconds\" >= 0"
+        },
+        "reading_sessions_end_progress_range_chk": {
+          "name": "reading_sessions_end_progress_range_chk",
+          "value": "\"reading_sessions\".\"end_progress\" is null or (\"reading_sessions\".\"end_progress\" >= 0 and \"reading_sessions\".\"end_progress\" <= 100)"
+        },
+        "reading_sessions_ended_after_started_chk": {
+          "name": "reading_sessions_ended_after_started_chk",
+          "value": "\"reading_sessions\".\"ended_at\" >= \"reading_sessions\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_ratings": {
+      "name": "user_book_ratings",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubr_user_id_idx": {
+          "name": "ubr_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_id_idx": {
+          "name": "ubr_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_user_rating_idx": {
+          "name": "ubr_book_user_rating_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_ratings_user_id_users_id_fk": {
+          "name": "user_book_ratings_user_id_users_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_ratings_book_id_books_id_fk": {
+          "name": "user_book_ratings_book_id_books_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_ratings_user_id_book_id_pk": {
+          "name": "user_book_ratings_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_ratings_rating_range_chk": {
+          "name": "user_book_ratings_rating_range_chk",
+          "value": "\"user_book_ratings\".\"rating\" >= 1 and \"user_book_ratings\".\"rating\" <= 5"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_status": {
+      "name": "user_book_status",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unread'"
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubs_user_id_idx": {
+          "name": "ubs_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_user_status_idx": {
+          "name": "ubs_user_status_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_book_user_idx": {
+          "name": "ubs_book_user_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_status_user_id_users_id_fk": {
+          "name": "user_book_status_user_id_users_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_status_book_id_books_id_fk": {
+          "name": "user_book_status_book_id_books_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_status_user_id_book_id_pk": {
+          "name": "user_book_status_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_status_status_chk": {
+          "name": "user_book_status_status_chk",
+          "value": "\"user_book_status\".\"status\" in ('unread', 'want_to_read', 'reading', 'on_hold', 'rereading', 'read', 'skimmed', 'abandoned')"
+        },
+        "user_book_status_source_chk": {
+          "name": "user_book_status_source_chk",
+          "value": "\"user_book_status\".\"source\" in ('auto', 'manual')"
+        },
+        "user_book_status_finished_after_started_chk": {
+          "name": "user_book_status_finished_after_started_chk",
+          "value": "\"user_book_status\".\"finished_at\" is null or \"user_book_status\".\"started_at\" is null or \"user_book_status\".\"finished_at\" >= \"user_book_status\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_reading_daily_stats": {
+      "name": "user_reading_daily_stats",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "day": {
+          "name": "day",
+          "type": "date",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_seconds": {
+          "name": "reading_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "sessions_count": {
+          "name": "sessions_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "urds_user_day_idx": {
+          "name": "urds_user_day_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "day",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_reading_daily_stats_user_id_users_id_fk": {
+          "name": "user_reading_daily_stats_user_id_users_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_reading_daily_stats_library_id_libraries_id_fk": {
+          "name": "user_reading_daily_stats_library_id_libraries_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_reading_daily_stats_user_id_library_id_day_pk": {
+          "name": "user_reading_daily_stats_user_id_library_id_day_pk",
+          "columns": ["user_id", "library_id", "day"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_reading_daily_stats_reading_seconds_nonnegative_chk": {
+          "name": "user_reading_daily_stats_reading_seconds_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"reading_seconds\" >= 0"
+        },
+        "user_reading_daily_stats_sessions_count_nonnegative_chk": {
+          "name": "user_reading_daily_stats_sessions_count_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"sessions_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.oidc_group_mappings": {
+      "name": "oidc_group_mappings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_group_claim": {
+          "name": "oidc_group_claim",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_group_mappings_provider_claim_uidx": {
+          "name": "oidc_group_mappings_provider_claim_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_group_claim",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_group_mappings_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_group_mappings_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_group_mappings",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_identities": {
+      "name": "oidc_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "linked_at": {
+          "name": "linked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_identities_provider_subject_uidx": {
+          "name": "oidc_identities_provider_subject_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_provider_uidx": {
+          "name": "oidc_identities_user_provider_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_issuer_subject_uidx": {
+          "name": "oidc_identities_issuer_subject_uidx",
+          "columns": [
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_id_idx": {
+          "name": "oidc_identities_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_identities_user_id_users_id_fk": {
+          "name": "oidc_identities_user_id_users_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_identities_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_identities_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_permission_grants": {
+      "name": "oidc_permission_grants",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "oidc_permission_grants_user_id_users_id_fk": {
+          "name": "oidc_permission_grants_user_id_users_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_permission_grants_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_permission_grants_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "oidc_permission_grants_user_id_provider_id_permission_name_pk": {
+          "name": "oidc_permission_grants_user_id_provider_id_permission_name_pk",
+          "columns": ["user_id", "provider_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_providers": {
+      "name": "oidc_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "issuer_uri": {
+          "name": "issuer_uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'openid profile email'"
+        },
+        "icon_url": {
+          "name": "icon_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "claim_mapping": {
+          "name": "claim_mapping",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"username\":\"preferred_username\",\"name\":\"name\",\"email\":\"email\",\"groups\":\"groups\"}'::jsonb"
+        },
+        "auto_provision": {
+          "name": "auto_provision",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"enabled\":false,\"allowLocalLinking\":false,\"defaultPermissionNames\":[]}'::jsonb"
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_providers_enabled_order_idx": {
+          "name": "oidc_providers_enabled_order_idx",
+          "columns": [
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oidc_providers_slug_unique": {
+          "name": "oidc_providers_slug_unique",
+          "nullsNotDistinct": false,
+          "columns": ["slug"]
+        },
+        "oidc_providers_issuer_uri_unique": {
+          "name": "oidc_providers_issuer_uri_unique",
+          "nullsNotDistinct": false,
+          "columns": ["issuer_uri"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_sessions": {
+      "name": "oidc_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_session_id": {
+          "name": "oidc_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token_hint": {
+          "name": "id_token_hint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_refresh_token": {
+          "name": "idp_refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_sessions_user_active_idx": {
+          "name": "oidc_sessions_user_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"oidc_sessions\".\"revoked\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_subject_issuer_idx": {
+          "name": "oidc_sessions_subject_issuer_idx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_sid_idx": {
+          "name": "oidc_sessions_sid_idx",
+          "columns": [
+            {
+              "expression": "oidc_session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_expires_at_idx": {
+          "name": "oidc_sessions_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_provider_id_idx": {
+          "name": "oidc_sessions_provider_id_idx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_sessions_user_id_users_id_fk": {
+          "name": "oidc_sessions_user_id_users_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_sessions_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_sessions_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_states": {
+      "name": "oidc_states",
+      "schema": "",
+      "columns": {
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "meta": {
+          "name": "meta",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oidc_states_expires_at_idx": {
+          "name": "oidc_states_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_states_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_states_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_states",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_used_jtis": {
+      "name": "oidc_used_jtis",
+      "schema": "",
+      "columns": {
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_used_jtis_expires_at_idx": {
+          "name": "oidc_used_jtis_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.opds_users": {
+      "name": "opds_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "opds_sort_order",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'recent'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "opds_users_username_lower_uidx": {
+          "name": "opds_users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "opds_users_user_id_users_id_fk": {
+          "name": "opds_users_user_id_users_id_fk",
+          "tableFrom": "opds_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "opds_users_username_unique": {
+          "name": "opds_users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_book_entitlements": {
+      "name": "kobo_book_entitlements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "cover_image_id": {
+          "name": "cover_image_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "needs_legacy_numeric_removal": {
+          "name": "needs_legacy_numeric_removal",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_book_entitlements_user_id_idx": {
+          "name": "kobo_book_entitlements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kobo_book_entitlements_book_id_idx": {
+          "name": "kobo_book_entitlements_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_book_entitlements_user_id_users_id_fk": {
+          "name": "kobo_book_entitlements_user_id_users_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_book_entitlements_book_id_books_id_fk": {
+          "name": "kobo_book_entitlements_book_id_books_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_book_entitlements_user_book_unique": {
+          "name": "kobo_book_entitlements_user_book_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        },
+        "kobo_book_entitlements_user_entitlement_unique": {
+          "name": "kobo_book_entitlements_user_entitlement_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "entitlement_id"]
+        },
+        "kobo_book_entitlements_user_cover_unique": {
+          "name": "kobo_book_entitlements_user_cover_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "cover_image_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_devices": {
+      "name": "kobo_devices",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_device_id": {
+          "name": "client_device_id",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_seen_at": {
+          "name": "last_seen_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_devices_user_id_idx": {
+          "name": "kobo_devices_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_devices_user_id_users_id_fk": {
+          "name": "kobo_devices_user_id_users_id_fk",
+          "tableFrom": "kobo_devices",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_devices_token_unique": {
+          "name": "kobo_devices_token_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token"]
+        },
+        "kobo_devices_client_device_id_unique": {
+          "name": "kobo_devices_client_device_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["client_device_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_library_snapshots": {
+      "name": "kobo_library_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_library_snapshots_user_id_users_id_fk": {
+          "name": "kobo_library_snapshots_user_id_users_id_fk",
+          "tableFrom": "kobo_library_snapshots",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_library_snapshots_user_id_unique": {
+          "name": "kobo_library_snapshots_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_reading_states": {
+      "name": "kobo_reading_states",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at_kobo": {
+          "name": "created_at_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_modified_kobo": {
+          "name": "last_modified_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority_timestamp": {
+          "name": "priority_timestamp",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "current_bookmark": {
+          "name": "current_bookmark",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "statistics": {
+          "name": "statistics",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_info": {
+          "name": "status_info",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_reading_states_user_id_users_id_fk": {
+          "name": "kobo_reading_states_user_id_users_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_reading_states_book_id_books_id_fk": {
+          "name": "kobo_reading_states_book_id_books_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_reading_states_user_id_book_id_unique": {
+          "name": "kobo_reading_states_user_id_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_snapshot_books": {
+      "name": "kobo_snapshot_books",
+      "schema": "",
+      "columns": {
+        "snapshot_id": {
+          "name": "snapshot_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "synced": {
+          "name": "synced",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "pending_delete": {
+          "name": "pending_delete",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_new": {
+          "name": "is_new",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "removed_by_device": {
+          "name": "removed_by_device",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "delivery_hash": {
+          "name": "delivery_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_hash": {
+          "name": "metadata_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "kobo_snapshot_books_snapshot_synced_book_idx": {
+          "name": "kobo_snapshot_books_snapshot_synced_book_idx",
+          "columns": [
+            {
+              "expression": "snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "synced",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk": {
+          "name": "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "kobo_library_snapshots",
+          "columnsFrom": ["snapshot_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_snapshot_books_book_id_books_id_fk": {
+          "name": "kobo_snapshot_books_book_id_books_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "kobo_snapshot_books_snapshot_id_book_id_pk": {
+          "name": "kobo_snapshot_books_snapshot_id_book_id_pk",
+          "columns": ["snapshot_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_sync_settings": {
+      "name": "kobo_sync_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "finished_threshold": {
+          "name": "finished_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 99
+        },
+        "convert_to_kepub": {
+          "name": "convert_to_kepub",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "force_enable_hyphenation": {
+          "name": "force_enable_hyphenation",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "kepub_conversion_limit_mb": {
+          "name": "kepub_conversion_limit_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "two_way_progress_sync": {
+          "name": "two_way_progress_sync",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sync_bookorbit_annotations_to_kobo": {
+          "name": "sync_bookorbit_annotations_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_sync_settings_user_id_users_id_fk": {
+          "name": "kobo_sync_settings_user_id_users_id_fk",
+          "tableFrom": "kobo_sync_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_sync_settings_user_id_unique": {
+          "name": "kobo_sync_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "kobo_sync_settings_reading_threshold_range_chk": {
+          "name": "kobo_sync_settings_reading_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"reading_threshold\" >= 0 and \"kobo_sync_settings\".\"reading_threshold\" <= 100"
+        },
+        "kobo_sync_settings_finished_threshold_range_chk": {
+          "name": "kobo_sync_settings_finished_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"finished_threshold\" >= 0 and \"kobo_sync_settings\".\"finished_threshold\" <= 100"
+        },
+        "kobo_sync_settings_conversion_limit_nonnegative_chk": {
+          "name": "kobo_sync_settings_conversion_limit_nonnegative_chk",
+          "value": "\"kobo_sync_settings\".\"kepub_conversion_limit_mb\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_dock_files": {
+      "name": "book_dock_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "file_name": {
+          "name": "file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "embedded_metadata": {
+          "name": "embedded_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "selected_metadata": {
+          "name": "selected_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata": {
+          "name": "fetched_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_path": {
+          "name": "cover_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_library_id": {
+          "name": "target_library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_folder_id": {
+          "name": "target_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata_sources": {
+          "name": "fetched_metadata_sources",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_edited_at": {
+          "name": "metadata_edited_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uploaded_by": {
+          "name": "uploaded_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_dock_files_status_idx": {
+          "name": "book_dock_files_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_dock_files_uploaded_by_idx": {
+          "name": "book_dock_files_uploaded_by_idx",
+          "columns": [
+            {
+              "expression": "uploaded_by",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_dock_files_target_library_id_libraries_id_fk": {
+          "name": "book_dock_files_target_library_id_libraries_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "libraries",
+          "columnsFrom": ["target_library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_target_folder_id_library_folders_id_fk": {
+          "name": "book_dock_files_target_folder_id_library_folders_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["target_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_uploaded_by_users_id_fk": {
+          "name": "book_dock_files_uploaded_by_users_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "users",
+          "columnsFrom": ["uploaded_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "book_dock_files_absolute_path_unique": {
+          "name": "book_dock_files_absolute_path_unique",
+          "nullsNotDistinct": false,
+          "columns": ["absolute_path"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "book_dock_files_status_chk": {
+          "name": "book_dock_files_status_chk",
+          "value": "\"book_dock_files\".\"status\" in ('pending', 'extracting', 'fetching', 'ready', 'error')"
+        },
+        "book_dock_files_confidence_range_chk": {
+          "name": "book_dock_files_confidence_range_chk",
+          "value": "\"book_dock_files\".\"confidence\" is null or (\"book_dock_files\".\"confidence\" >= 0 and \"book_dock_files\".\"confidence\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.file_write_log": {
+      "name": "file_write_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fields_written": {
+          "name": "fields_written",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "written_at": {
+          "name": "written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "fwl_book_id_written_at_idx": {
+          "name": "fwl_book_id_written_at_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "written_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "file_write_log_book_id_books_id_fk": {
+          "name": "file_write_log_book_id_books_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "file_write_log_book_file_id_book_files_id_fk": {
+          "name": "file_write_log_book_file_id_book_files_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "file_write_log_user_id_users_id_fk": {
+          "name": "file_write_log_user_id_users_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "file_write_log_status_chk": {
+          "name": "file_write_log_status_chk",
+          "value": "\"file_write_log\".\"status\" in ('success', 'skipped', 'failed')"
+        },
+        "file_write_log_triggered_by_chk": {
+          "name": "file_write_log_triggered_by_chk",
+          "value": "\"file_write_log\".\"triggered_by\" in ('auto', 'sync')"
+        },
+        "file_write_log_duration_ms_nonnegative_chk": {
+          "name": "file_write_log_duration_ms_nonnegative_chk",
+          "value": "\"file_write_log\".\"duration_ms\" is null or \"file_write_log\".\"duration_ms\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_templates": {
+      "name": "email_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_text": {
+          "name": "body_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system": {
+          "name": "is_system",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_templates_one_default_per_user_uidx": {
+          "name": "email_templates_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"is_default\" = true and \"email_templates\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_templates_system_name_unique": {
+          "name": "email_templates_system_name_unique",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"user_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_templates_user_id_users_id_fk": {
+          "name": "email_templates_user_id_users_id_fk",
+          "tableFrom": "email_templates",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_templates_user_id_name_unique": {
+          "name": "email_templates_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_providers": {
+      "name": "email_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "host": {
+          "name": "host",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "port": {
+          "name": "port",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_enc": {
+          "name": "password_enc",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_name": {
+          "name": "from_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_address": {
+          "name": "from_address",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth": {
+          "name": "auth",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "ssl": {
+          "name": "ssl",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "start_tls": {
+          "name": "start_tls",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_shared": {
+          "name": "is_shared",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system_provider": {
+          "name": "is_system_provider",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "tls_reject_unauthorized": {
+          "name": "tls_reject_unauthorized",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_providers_one_default_per_user_uidx": {
+          "name": "email_providers_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_default\" = true and \"email_providers\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_providers_one_system_provider_uidx": {
+          "name": "email_providers_one_system_provider_uidx",
+          "columns": [
+            {
+              "expression": "is_system_provider",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_system_provider\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_providers_user_id_users_id_fk": {
+          "name": "email_providers_user_id_users_id_fk",
+          "tableFrom": "email_providers",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_providers_user_id_name_unique": {
+          "name": "email_providers_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_providers_id_user_id_unique": {
+          "name": "email_providers_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_providers_port_range_chk": {
+          "name": "email_providers_port_range_chk",
+          "value": "\"email_providers\".\"port\" >= 1 and \"email_providers\".\"port\" <= 65535"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_group_members": {
+      "name": "email_recipient_group_members",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "recipient_id": {
+          "name": "recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_group_members_user_id_users_id_fk": {
+          "name": "email_recipient_group_members_user_id_users_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_id_email_recipient_groups_id_fk": {
+          "name": "email_recipient_group_members_group_id_email_recipient_groups_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_id_email_recipients_id_fk": {
+          "name": "email_recipient_group_members_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_user_fk": {
+          "name": "email_recipient_group_members_group_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_user_fk": {
+          "name": "email_recipient_group_members_recipient_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "email_recipient_group_members_group_id_recipient_id_pk": {
+          "name": "email_recipient_group_members_group_id_recipient_id_pk",
+          "columns": ["group_id", "recipient_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_groups": {
+      "name": "email_recipient_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_groups_user_id_users_id_fk": {
+          "name": "email_recipient_groups_user_id_users_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_groups_default_template_id_email_templates_id_fk": {
+          "name": "email_recipient_groups_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipient_groups_user_id_name_unique": {
+          "name": "email_recipient_groups_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_recipient_groups_id_user_id_unique": {
+          "name": "email_recipient_groups_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipients": {
+      "name": "email_recipients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "device_type": {
+          "name": "device_type",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "preferred_format": {
+          "name": "preferred_format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_recipients_user_email_lower_uidx": {
+          "name": "email_recipients_user_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_recipients_one_default_per_user_uidx": {
+          "name": "email_recipients_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_recipients\".\"is_default\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_recipients_user_id_users_id_fk": {
+          "name": "email_recipients_user_id_users_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipients_default_template_id_email_templates_id_fk": {
+          "name": "email_recipients_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipients_user_id_email_unique": {
+          "name": "email_recipients_user_id_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "email"]
+        },
+        "email_recipients_id_user_id_unique": {
+          "name": "email_recipients_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_recipients_device_type_chk": {
+          "name": "email_recipients_device_type_chk",
+          "value": "\"email_recipients\".\"device_type\" is null or \"email_recipients\".\"device_type\" in ('kindle', 'kobo', 'other')"
+        },
+        "email_recipients_preferred_format_chk": {
+          "name": "email_recipients_preferred_format_chk",
+          "value": "\"email_recipients\".\"preferred_format\" is null or \"email_recipients\".\"preferred_format\" in ('epub', 'pdf', 'mobi', 'azw3', 'cbz', 'cbr')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_preferences": {
+      "name": "email_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_provider_id": {
+          "name": "default_provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_recipient_id": {
+          "name": "default_recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_preferences_user_id_users_id_fk": {
+          "name": "email_preferences_user_id_users_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_provider_id_email_providers_id_fk": {
+          "name": "email_preferences_default_provider_id_email_providers_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_providers",
+          "columnsFrom": ["default_provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_id_email_recipients_id_fk": {
+          "name": "email_preferences_default_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_template_id_email_templates_id_fk": {
+          "name": "email_preferences_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_owner_fk": {
+          "name": "email_preferences_default_recipient_owner_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_preferences_user_id_unique": {
+          "name": "email_preferences_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_send_log": {
+      "name": "email_send_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "to_email": {
+          "name": "to_email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_name": {
+          "name": "to_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_send_log_user_created_at_idx": {
+          "name": "email_send_log_user_created_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_created_at_idx": {
+          "name": "email_send_log_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_status_next_retry_idx": {
+          "name": "email_send_log_status_next_retry_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_retry_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_send_log_user_id_users_id_fk": {
+          "name": "email_send_log_user_id_users_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_id_books_id_fk": {
+          "name": "email_send_log_book_id_books_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_file_id_book_files_id_fk": {
+          "name": "email_send_log_book_file_id_book_files_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_provider_id_email_providers_id_fk": {
+          "name": "email_send_log_provider_id_email_providers_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_template_id_email_templates_id_fk": {
+          "name": "email_send_log_template_id_email_templates_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_templates",
+          "columnsFrom": ["template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "email_send_log_status_chk": {
+          "name": "email_send_log_status_chk",
+          "value": "\"email_send_log\".\"status\" in ('pending', 'sent', 'failed')"
+        },
+        "email_send_log_attempt_count_nonnegative_chk": {
+          "name": "email_send_log_attempt_count_nonnegative_chk",
+          "value": "\"email_send_log\".\"attempt_count\" >= 0"
+        },
+        "email_send_log_sent_after_created_chk": {
+          "name": "email_send_log_sent_after_created_chk",
+          "value": "\"email_send_log\".\"sent_at\" is null or \"email_send_log\".\"sent_at\" >= \"email_send_log\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action_url": {
+          "name": "action_url",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "read": {
+          "name": "read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_id_idx": {
+          "name": "notifications_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_user_unread_idx": {
+          "name": "notifications_user_unread_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "read",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_created_at_idx": {
+          "name": "notifications_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "notifications_user_id_users_id_fk": {
+          "name": "notifications_user_id_users_id_fk",
+          "tableFrom": "notifications",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_duplicate_pairs": {
+      "name": "dismissed_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_duplicate_pairs_entity_a_idx": {
+          "name": "dismissed_duplicate_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_duplicate_pairs_entity_b_idx": {
+          "name": "dismissed_duplicate_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_duplicate_pairs_unique": {
+          "name": "dismissed_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_inline_duplicate_pairs": {
+      "name": "dismissed_inline_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_a": {
+          "name": "value_a",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_b": {
+          "name": "value_b",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_inline_pairs_entity_a_idx": {
+          "name": "dismissed_inline_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_inline_pairs_entity_b_idx": {
+          "name": "dismissed_inline_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_inline_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_inline_duplicate_pairs_unique": {
+          "name": "dismissed_inline_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "value_a", "value_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_candidates": {
+      "name": "entity_duplicate_candidates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sim_score": {
+          "name": "sim_score",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "entity_dup_candidates_type_sim_idx": {
+          "name": "entity_dup_candidates_type_sim_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sim_score",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_a_idx": {
+          "name": "entity_dup_candidates_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_b_idx": {
+          "name": "entity_dup_candidates_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "entity_duplicate_candidates_unique": {
+          "name": "entity_duplicate_candidates_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_scan_status": {
+      "name": "entity_duplicate_scan_status",
+      "schema": "",
+      "columns": {
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "is_computing": {
+          "name": "is_computing",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_pairs": {
+          "name": "total_pairs",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "processed_count": {
+          "name": "processed_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_count": {
+          "name": "total_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_fonts": {
+      "name": "user_fonts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "family_name": {
+          "name": "family_name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_file_name": {
+          "name": "original_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stored_file_name": {
+          "name": "stored_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 400
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "uf_user_hash_uidx": {
+          "name": "uf_user_hash_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "uf_user_family_weight_style_uidx": {
+          "name": "uf_user_family_weight_style_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "family_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "weight",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "style",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_fonts_user_id_users_id_fk": {
+          "name": "user_fonts_user_id_users_id_fk",
+          "tableFrom": "user_fonts",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_fonts_format_chk": {
+          "name": "user_fonts_format_chk",
+          "value": "\"user_fonts\".\"format\" in ('ttf', 'otf', 'woff', 'woff2')"
+        },
+        "user_fonts_weight_chk": {
+          "name": "user_fonts_weight_chk",
+          "value": "\"user_fonts\".\"weight\" >= 100 and \"user_fonts\".\"weight\" <= 900 and \"user_fonts\".\"weight\" % 100 = 0"
+        },
+        "user_fonts_style_chk": {
+          "name": "user_fonts_style_chk",
+          "value": "\"user_fonts\".\"style\" in ('normal', 'italic')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_file_chapters": {
+      "name": "book_file_chapters",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "href": {
+          "name": "href",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "spine_index": {
+          "name": "spine_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "book_file_chapters_book_file_id_chapter_index_uidx": {
+          "name": "book_file_chapters_book_file_id_chapter_index_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "chapter_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_chapters_book_file_id_idx": {
+          "name": "book_file_chapters_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_chapters_book_file_id_book_files_id_fk": {
+          "name": "book_file_chapters_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_chapters",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_file_hash_history": {
+      "name": "book_file_hash_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(30)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_file_hash_history_book_file_id_file_hash_idx": {
+          "name": "book_file_hash_history_book_file_id_file_hash_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_hash_history_file_hash_idx": {
+          "name": "book_file_hash_history_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_hash_history_book_file_id_book_files_id_fk": {
+          "name": "book_file_hash_history_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_hash_history",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_file_hash_history_reason_chk": {
+          "name": "book_file_hash_history_reason_chk",
+          "value": "\"book_file_hash_history\".\"reason\" in ('file_write', 'external_change', 'rescan')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_progress": {
+      "name": "koreader_device_progress",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device": {
+          "name": "device",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "progress": {
+          "name": "progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_timestamp": {
+          "name": "sync_timestamp",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "orphaned": {
+          "name": "orphaned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "orphaned_hash": {
+          "name": "orphaned_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_device_progress_book_user_device_uidx": {
+          "name": "koreader_device_progress_book_user_device_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"koreader_device_progress\".\"orphaned\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_orphaned_hash_idx": {
+          "name": "koreader_device_progress_orphaned_hash_idx",
+          "columns": [
+            {
+              "expression": "orphaned_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"orphaned\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_user_updated_at_idx": {
+          "name": "koreader_device_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_book_file_id_idx": {
+          "name": "koreader_device_progress_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"book_file_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_progress_book_file_id_book_files_id_fk": {
+          "name": "koreader_device_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "koreader_device_progress_user_id_users_id_fk": {
+          "name": "koreader_device_progress_user_id_users_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_device_progress_percentage_range_chk": {
+          "name": "koreader_device_progress_percentage_range_chk",
+          "value": "\"koreader_device_progress\".\"percentage\" is null or (\"koreader_device_progress\".\"percentage\" >= 0 and \"koreader_device_progress\".\"percentage\" <= 1)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_sweeps": {
+      "name": "koreader_device_sweeps",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_model": {
+          "name": "device_model",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "plugin_version": {
+          "name": "plugin_version",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_sweep_at": {
+          "name": "last_sweep_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_sweep_books_matched": {
+          "name": "last_sweep_books_matched",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_page_stats": {
+          "name": "last_sweep_page_stats",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_annotations": {
+          "name": "last_sweep_annotations",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kds_user_id_idx": {
+          "name": "kds_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_sweeps_user_id_users_id_fk": {
+          "name": "koreader_device_sweeps_user_id_users_id_fk",
+          "tableFrom": "koreader_device_sweeps",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "koreader_device_sweeps_user_id_device_id_pk": {
+          "name": "koreader_device_sweeps_user_id_device_id_pk",
+          "columns": ["user_id", "device_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.koreader_page_stats": {
+      "name": "koreader_page_stats",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page": {
+          "name": "page",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "total_pages": {
+          "name": "total_pages",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kps_user_file_device_page_start_uidx": {
+          "name": "kps_user_file_device_page_start_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_file_device_start_idx": {
+          "name": "kps_user_file_device_start_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_id_idx": {
+          "name": "kps_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_page_stats_user_id_users_id_fk": {
+          "name": "koreader_page_stats_user_id_users_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "koreader_page_stats_book_file_id_book_files_id_fk": {
+          "name": "koreader_page_stats_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_page_stats_duration_nonnegative_chk": {
+          "name": "koreader_page_stats_duration_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"duration_seconds\" >= 0"
+        },
+        "koreader_page_stats_page_nonnegative_chk": {
+          "name": "koreader_page_stats_page_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"page\" >= 0"
+        },
+        "koreader_page_stats_total_pages_positive_chk": {
+          "name": "koreader_page_stats_total_pages_positive_chk",
+          "value": "\"koreader_page_stats\".\"total_pages\" > 0"
+        },
+        "koreader_page_stats_start_time_positive_chk": {
+          "name": "koreader_page_stats_start_time_positive_chk",
+          "value": "\"koreader_page_stats\".\"start_time\" > 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_users": {
+      "name": "koreader_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_md5": {
+          "name": "password_md5",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_enabled": {
+          "name": "sync_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_users_user_id_uidx": {
+          "name": "koreader_users_user_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_users_username_uidx": {
+          "name": "koreader_users_username_uidx",
+          "columns": [
+            {
+              "expression": "username",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_users_user_id_users_id_fk": {
+          "name": "koreader_users_user_id_users_id_fk",
+          "tableFrom": "koreader_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.achievements": {
+      "name": "achievements",
+      "schema": "",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "varchar(64)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "group_key": {
+          "name": "group_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon_name": {
+          "name": "icon_name",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rarity": {
+          "name": "rarity",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hidden": {
+          "name": "hidden",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "achievements_category_sort_idx": {
+          "name": "achievements_category_sort_idx",
+          "columns": [
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "achievements_group_key_idx": {
+          "name": "achievements_group_key_idx",
+          "columns": [
+            {
+              "expression": "group_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "achievements_category_chk": {
+          "name": "achievements_category_chk",
+          "value": "\"achievements\".\"category\" in ('reading', 'library', 'exploration', 'dedication')"
+        },
+        "achievements_rarity_chk": {
+          "name": "achievements_rarity_chk",
+          "value": "\"achievements\".\"rarity\" in ('common', 'rare', 'epic', 'legendary')"
+        },
+        "achievements_tier_chk": {
+          "name": "achievements_tier_chk",
+          "value": "\"achievements\".\"tier\" is null or (\"achievements\".\"tier\" >= 1 and \"achievements\".\"tier\" <= 4)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_achievements": {
+      "name": "user_achievements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "achievement_key": {
+          "name": "achievement_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "awarded_at": {
+          "name": "awarded_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "context_json": {
+          "name": "context_json",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "user_achievements_user_key_uidx": {
+          "name": "user_achievements_user_key_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "achievement_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_id_idx": {
+          "name": "user_achievements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_awarded_at_idx": {
+          "name": "user_achievements_user_awarded_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "awarded_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_achievements_user_id_users_id_fk": {
+          "name": "user_achievements_user_id_users_id_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_achievements_achievement_key_achievements_key_fk": {
+          "name": "user_achievements_achievement_key_achievements_key_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "achievements",
+          "columnsFrom": ["achievement_key"],
+          "columnsTo": ["key"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_book_state": {
+      "name": "hardcover_book_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hardcover_book_id": {
+          "name": "hardcover_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_edition_id": {
+          "name": "hardcover_edition_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_user_book_id": {
+          "name": "hardcover_user_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_read_id": {
+          "name": "hardcover_read_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_method": {
+          "name": "match_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_error": {
+          "name": "match_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_status": {
+          "name": "last_synced_status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_progress": {
+          "name": "last_synced_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_rating": {
+          "name": "last_synced_rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_started_at": {
+          "name": "last_synced_started_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_finished_at": {
+          "name": "last_synced_finished_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_book_state_user_id_users_id_fk": {
+          "name": "hardcover_book_state_user_id_users_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "hardcover_book_state_book_id_books_id_fk": {
+          "name": "hardcover_book_state_book_id_books_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_book_state_user_book_uidx": {
+          "name": "hardcover_book_state_user_book_uidx",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_user_settings": {
+      "name": "hardcover_user_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "api_token": {
+          "name": "api_token",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_status_change": {
+          "name": "auto_sync_on_status_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_progress_update": {
+          "name": "auto_sync_on_progress_update",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_rating_change": {
+          "name": "auto_sync_on_rating_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "privacy_setting_id": {
+          "name": "privacy_setting_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 3
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_user_settings_user_id_users_id_fk": {
+          "name": "hardcover_user_settings_user_id_users_id_fk",
+          "tableFrom": "hardcover_user_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_user_settings_user_id_unique": {
+          "name": "hardcover_user_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_preferences": {
+      "name": "user_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "up_user_category_idx": {
+          "name": "up_user_category_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_preferences_user_id_users_id_fk": {
+          "name": "user_preferences_user_id_users_id_fk",
+          "tableFrom": "user_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.content_filter_type": {
+      "name": "content_filter_type",
+      "schema": "public",
+      "values": ["include", "exclude"]
+    },
+    "public.library_access_level": {
+      "name": "library_access_level",
+      "schema": "public",
+      "values": ["viewer", "editor", "owner"]
+    },
+    "public.user_avatar_source": {
+      "name": "user_avatar_source",
+      "schema": "public",
+      "values": ["none", "external", "uploaded"]
+    },
+    "public.opds_sort_order": {
+      "name": "opds_sort_order",
+      "schema": "public",
+      "values": ["recent", "title_asc", "title_desc", "author_asc", "author_desc", "series_asc", "series_desc"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/server/src/db/migrations/meta/0029_snapshot.json b/server/src/db/migrations/meta/0029_snapshot.json
new file mode 100644
index 000000000..f6782883c
--- /dev/null
+++ b/server/src/db/migrations/meta/0029_snapshot.json
@@ -0,0 +1,11403 @@
+{
+  "id": "46499b98-ef74-447e-8013-4dab6d018ede",
+  "prevId": "ae965fcc-0970-44af-b1c9-2e7ea74893e5",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.audit_log": {
+      "name": "audit_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_username": {
+          "name": "actor_username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "resource": {
+          "name": "resource",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "resource_id": {
+          "name": "resource_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip": {
+          "name": "ip",
+          "type": "varchar(45)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_audit_user_id": {
+          "name": "idx_audit_user_id",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_resource": {
+          "name": "idx_audit_resource",
+          "columns": [
+            {
+              "expression": "resource",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "resource_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_action": {
+          "name": "idx_audit_action",
+          "columns": [
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_ip": {
+          "name": "idx_audit_ip",
+          "columns": [
+            {
+              "expression": "ip",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_created_at": {
+          "name": "idx_audit_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audit_log_user_id_users_id_fk": {
+          "name": "audit_log_user_id_users_id_fk",
+          "tableFrom": "audit_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.app_settings": {
+      "name": "app_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "app_settings_key_unique": {
+          "name": "app_settings_key_unique",
+          "nullsNotDistinct": false,
+          "columns": ["key"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.magic_access_tokens": {
+      "name": "magic_access_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "label": {
+          "name": "label",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_token": {
+          "name": "raw_token",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "use_count": {
+          "name": "use_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "magic_access_tokens_user_id_idx": {
+          "name": "magic_access_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "magic_access_tokens_user_id_users_id_fk": {
+          "name": "magic_access_tokens_user_id_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "magic_access_tokens_created_by_users_id_fk": {
+          "name": "magic_access_tokens_created_by_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["created_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "magic_access_tokens_token_hash_unique": {
+          "name": "magic_access_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "magic_access_tokens_use_count_nonneg_chk": {
+          "name": "magic_access_tokens_use_count_nonneg_chk",
+          "value": "\"magic_access_tokens\".\"use_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "used_at": {
+          "name": "used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "password_reset_tokens_user_id_idx": {
+          "name": "password_reset_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "password_reset_tokens_expires_at_idx": {
+          "name": "password_reset_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "password_reset_tokens_user_id_users_id_fk": {
+          "name": "password_reset_tokens_user_id_users_id_fk",
+          "tableFrom": "password_reset_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "password_reset_tokens_token_hash_unique": {
+          "name": "password_reset_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "password_reset_tokens_expires_after_created_chk": {
+          "name": "password_reset_tokens_expires_after_created_chk",
+          "value": "\"password_reset_tokens\".\"expires_at\" > \"password_reset_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.refresh_tokens": {
+      "name": "refresh_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rotated_at": {
+          "name": "rotated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replaced_by_token_hash": {
+          "name": "replaced_by_token_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_user_id_idx": {
+          "name": "refresh_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "refresh_tokens_expires_at_idx": {
+          "name": "refresh_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "refresh_tokens_token_hash_unique": {
+          "name": "refresh_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "refresh_tokens_expires_after_created_chk": {
+          "name": "refresh_tokens_expires_after_created_chk",
+          "value": "\"refresh_tokens\".\"expires_at\" > \"refresh_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_genres": {
+      "name": "user_content_filter_genres",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_genres_genre_id_idx": {
+          "name": "user_content_filter_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_genres_user_id_users_id_fk": {
+          "name": "user_content_filter_genres_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_genres_genre_id_genres_id_fk": {
+          "name": "user_content_filter_genres_genre_id_genres_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_genres_user_id_filter_type_genre_id_pk": {
+          "name": "user_content_filter_genres_user_id_filter_type_genre_id_pk",
+          "columns": ["user_id", "filter_type", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_tags": {
+      "name": "user_content_filter_tags",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_tags_tag_id_idx": {
+          "name": "user_content_filter_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_tags_user_id_users_id_fk": {
+          "name": "user_content_filter_tags_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_tags_tag_id_tags_id_fk": {
+          "name": "user_content_filter_tags_tag_id_tags_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_tags_user_id_filter_type_tag_id_pk": {
+          "name": "user_content_filter_tags_user_id_filter_type_tag_id_pk",
+          "columns": ["user_id", "filter_type", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_library_access": {
+      "name": "user_library_access",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_level": {
+          "name": "access_level",
+          "type": "library_access_level",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        }
+      },
+      "indexes": {
+        "user_library_access_library_user_idx": {
+          "name": "user_library_access_library_user_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_library_access_user_id_users_id_fk": {
+          "name": "user_library_access_user_id_users_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_library_access_library_id_libraries_id_fk": {
+          "name": "user_library_access_library_id_libraries_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_library_access_user_id_library_id_pk": {
+          "name": "user_library_access_user_id_library_id_pk",
+          "columns": ["user_id", "library_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_permissions": {
+      "name": "user_permissions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_permissions_user_id_users_id_fk": {
+          "name": "user_permissions_user_id_users_id_fk",
+          "tableFrom": "user_permissions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_permissions_user_id_permission_name_pk": {
+          "name": "user_permissions_user_id_permission_name_pk",
+          "columns": ["user_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_superuser": {
+          "name": "is_superuser",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_default_password": {
+          "name": "is_default_password",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "token_version": {
+          "name": "token_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "failed_login_attempts": {
+          "name": "failed_login_attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "locked_until": {
+          "name": "locked_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_source": {
+          "name": "avatar_source",
+          "type": "user_avatar_source",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'none'"
+        },
+        "avatar_version": {
+          "name": "avatar_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "provisioning_method": {
+          "name": "provisioning_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'local'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "users_username_lower_uidx": {
+          "name": "users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_email_lower_uidx": {
+          "name": "users_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"email\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_oidc_subject_issuer_uidx": {
+          "name": "users_oidc_subject_issuer_uidx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"oidc_subject\" is not null and \"users\".\"oidc_issuer\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        },
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["email"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "users_provisioning_method_chk": {
+          "name": "users_provisioning_method_chk",
+          "value": "\"users\".\"provisioning_method\" in ('local', 'manual', 'oidc', 'shared')"
+        },
+        "users_token_version_nonnegative_chk": {
+          "name": "users_token_version_nonnegative_chk",
+          "value": "\"users\".\"token_version\" >= 0"
+        },
+        "users_failed_login_attempts_nonnegative_chk": {
+          "name": "users_failed_login_attempts_nonnegative_chk",
+          "value": "\"users\".\"failed_login_attempts\" >= 0"
+        },
+        "users_avatar_version_nonnegative_chk": {
+          "name": "users_avatar_version_nonnegative_chk",
+          "value": "\"users\".\"avatar_version\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.comic_metadata": {
+      "name": "comic_metadata",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issue_number": {
+          "name": "issue_number",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "volume_name": {
+          "name": "volume_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pencillers": {
+          "name": "pencillers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "inkers": {
+          "name": "inkers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "colorists": {
+          "name": "colorists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "letterers": {
+          "name": "letterers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_artists": {
+          "name": "cover_artists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "characters": {
+          "name": "characters",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "teams": {
+          "name": "teams",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locations": {
+          "name": "locations",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "story_arcs": {
+          "name": "story_arcs",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comic_metadata_book_id_books_id_fk": {
+          "name": "comic_metadata_book_id_books_id_fk",
+          "tableFrom": "comic_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comic_metadata_book_id_unique": {
+          "name": "comic_metadata_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_plan_artifacts": {
+      "name": "migration_plan_artifacts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_snapshot_hash": {
+          "name": "source_snapshot_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_hash": {
+          "name": "profile_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_hash": {
+          "name": "plan_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan": {
+          "name": "plan",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_plan_artifacts_plan_hash_uidx": {
+          "name": "migration_plan_artifacts_plan_hash_uidx",
+          "columns": [
+            {
+              "expression": "plan_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_source_id_idx": {
+          "name": "migration_plan_artifacts_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_profile_id_idx": {
+          "name": "migration_plan_artifacts_profile_id_idx",
+          "columns": [
+            {
+              "expression": "profile_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_plan_artifacts_source_id_migration_sources_id_fk": {
+          "name": "migration_plan_artifacts_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_id_migration_profiles_id_fk": {
+          "name": "migration_plan_artifacts_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_created_by_user_id_users_id_fk": {
+          "name": "migration_plan_artifacts_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_source_fk": {
+          "name": "migration_plan_artifacts_profile_source_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_plan_artifacts_id_source_profile_unique": {
+          "name": "migration_plan_artifacts_id_source_profile_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id", "profile_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_profiles": {
+      "name": "migration_profiles",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "user_mappings": {
+          "name": "user_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path_mappings": {
+          "name": "path_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_profiles_source_name_version_uidx": {
+          "name": "migration_profiles_source_name_version_uidx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "version",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_profiles_source_id_idx": {
+          "name": "migration_profiles_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_profiles_source_id_migration_sources_id_fk": {
+          "name": "migration_profiles_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_profiles_created_by_user_id_users_id_fk": {
+          "name": "migration_profiles_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_profiles_id_source_id_unique": {
+          "name": "migration_profiles_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "migration_profiles_version_positive_chk": {
+          "name": "migration_profiles_version_positive_chk",
+          "value": "\"migration_profiles\".\"version\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_run_metrics": {
+      "name": "migration_run_metrics",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stage": {
+          "name": "stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "processed": {
+          "name": "processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "imported": {
+          "name": "imported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "skipped": {
+          "name": "skipped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "unresolved": {
+          "name": "unresolved",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "failed": {
+          "name": "failed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_run_metrics_run_stage_entity_uidx": {
+          "name": "migration_run_metrics_run_stage_entity_uidx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "stage",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_run_metrics_run_id_idx": {
+          "name": "migration_run_metrics_run_id_idx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_run_metrics_run_id_migration_runs_id_fk": {
+          "name": "migration_run_metrics_run_id_migration_runs_id_fk",
+          "tableFrom": "migration_run_metrics",
+          "tableTo": "migration_runs",
+          "columnsFrom": ["run_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_run_metrics_processed_nonnegative_chk": {
+          "name": "migration_run_metrics_processed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"processed\" >= 0"
+        },
+        "migration_run_metrics_imported_nonnegative_chk": {
+          "name": "migration_run_metrics_imported_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"imported\" >= 0"
+        },
+        "migration_run_metrics_skipped_nonnegative_chk": {
+          "name": "migration_run_metrics_skipped_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"skipped\" >= 0"
+        },
+        "migration_run_metrics_unresolved_nonnegative_chk": {
+          "name": "migration_run_metrics_unresolved_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"unresolved\" >= 0"
+        },
+        "migration_run_metrics_failed_nonnegative_chk": {
+          "name": "migration_run_metrics_failed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"failed\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_runs": {
+      "name": "migration_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_artifact_id": {
+          "name": "plan_artifact_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_key": {
+          "name": "target_key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'bookorbit'"
+        },
+        "state": {
+          "name": "state",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "current_stage": {
+          "name": "current_stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by_user_id": {
+          "name": "triggered_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_runs_source_target_state_idx": {
+          "name": "migration_runs_source_target_state_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "target_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_runs_state_idx": {
+          "name": "migration_runs_state_idx",
+          "columns": [
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_runs_source_id_migration_sources_id_fk": {
+          "name": "migration_runs_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_id_migration_profiles_id_fk": {
+          "name": "migration_runs_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk": {
+          "name": "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_triggered_by_user_id_users_id_fk": {
+          "name": "migration_runs_triggered_by_user_id_users_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "users",
+          "columnsFrom": ["triggered_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_source_fk": {
+          "name": "migration_runs_profile_source_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_source_profile_fk": {
+          "name": "migration_runs_plan_artifact_source_profile_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id", "source_id", "profile_id"],
+          "columnsTo": ["id", "source_id", "profile_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        },
+        "migration_runs_started_before_ended_chk": {
+          "name": "migration_runs_started_before_ended_chk",
+          "value": "\"migration_runs\".\"ended_at\" is null or \"migration_runs\".\"started_at\" is null or \"migration_runs\".\"ended_at\" >= \"migration_runs\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_sources": {
+      "name": "migration_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_config": {
+          "name": "connection_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "capabilities": {
+          "name": "capabilities",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_validated_at": {
+          "name": "last_validated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_sources_type_name_uidx": {
+          "name": "migration_sources_type_name_uidx",
+          "columns": [
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_sources_created_by_user_id_users_id_fk": {
+          "name": "migration_sources_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_sources",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.libraries": {
+      "name": "libraries",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cover_aspect_ratio": {
+          "name": "cover_aspect_ratio",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'2/3'"
+        },
+        "watch": {
+          "name": "watch",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "auto_scan_cron_expression": {
+          "name": "auto_scan_cron_expression",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_precedence": {
+          "name": "metadata_precedence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"folderStructure\",\"embedded\",\"nfoFile\",\"opfFile\",\"sidecar\"]'::jsonb"
+        },
+        "format_priority": {
+          "name": "format_priority",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"epub\",\"pdf\",\"cbz\",\"cbr\",\"cb7\",\"mobi\",\"azw3\",\"azw\",\"fb2\",\"m4b\",\"mp3\",\"m4a\",\"opus\",\"ogg\",\"flac\"]'::jsonb"
+        },
+        "allowed_formats": {
+          "name": "allowed_formats",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "organization_mode": {
+          "name": "organization_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'book_per_folder'"
+        },
+        "exclude_patterns": {
+          "name": "exclude_patterns",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "double precision",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0.25
+        },
+        "mark_as_finished_percent_complete": {
+          "name": "mark_as_finished_percent_complete",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 98
+        },
+        "file_write_enabled": {
+          "name": "file_write_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_write_cover": {
+          "name": "file_write_write_cover",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_enabled": {
+          "name": "file_write_epub_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_max_file_size_mb": {
+          "name": "file_write_epub_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_pdf_enabled": {
+          "name": "file_write_pdf_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_pdf_max_file_size_mb": {
+          "name": "file_write_pdf_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_cbx_enabled": {
+          "name": "file_write_cbx_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_cbx_max_file_size_mb": {
+          "name": "file_write_cbx_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_write_audio_enabled": {
+          "name": "file_write_audio_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_audio_max_file_size_mb": {
+          "name": "file_write_audio_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_rename_enabled": {
+          "name": "file_rename_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_naming_pattern": {
+          "name": "file_naming_pattern",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_fetch_preferences": {
+          "name": "metadata_fetch_preferences",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_config": {
+          "name": "book_metadata_fetch_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_run_at": {
+          "name": "book_metadata_fetch_last_run_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_queued_count": {
+          "name": "book_metadata_fetch_last_queued_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scan_mode": {
+          "name": "scan_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "poll_interval_seconds": {
+          "name": "poll_interval_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "default": 300
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "libraries_name_lower_uidx": {
+          "name": "libraries_name_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "libraries_display_order_nonnegative_chk": {
+          "name": "libraries_display_order_nonnegative_chk",
+          "value": "\"libraries\".\"display_order\" >= 0"
+        },
+        "libraries_organization_mode_chk": {
+          "name": "libraries_organization_mode_chk",
+          "value": "\"libraries\".\"organization_mode\" in ('book_per_folder', 'book_per_file')"
+        },
+        "libraries_reading_threshold_range_chk": {
+          "name": "libraries_reading_threshold_range_chk",
+          "value": "\"libraries\".\"reading_threshold\" >= 0 and \"libraries\".\"reading_threshold\" <= 100"
+        },
+        "libraries_mark_finished_percent_range_chk": {
+          "name": "libraries_mark_finished_percent_range_chk",
+          "value": "\"libraries\".\"mark_as_finished_percent_complete\" >= 0 and \"libraries\".\"mark_as_finished_percent_complete\" <= 100"
+        },
+        "libraries_scan_mode_chk": {
+          "name": "libraries_scan_mode_chk",
+          "value": "\"libraries\".\"scan_mode\" in ('auto', 'manual')"
+        },
+        "libraries_poll_interval_nonnegative_chk": {
+          "name": "libraries_poll_interval_nonnegative_chk",
+          "value": "\"libraries\".\"poll_interval_seconds\" is null or \"libraries\".\"poll_interval_seconds\" >= 0"
+        },
+        "libraries_file_write_epub_max_size_chk": {
+          "name": "libraries_file_write_epub_max_size_chk",
+          "value": "\"libraries\".\"file_write_epub_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_pdf_max_size_chk": {
+          "name": "libraries_file_write_pdf_max_size_chk",
+          "value": "\"libraries\".\"file_write_pdf_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_cbx_max_size_chk": {
+          "name": "libraries_file_write_cbx_max_size_chk",
+          "value": "\"libraries\".\"file_write_cbx_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_audio_max_size_chk": {
+          "name": "libraries_file_write_audio_max_size_chk",
+          "value": "\"libraries\".\"file_write_audio_max_file_size_mb\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.library_folders": {
+      "name": "library_folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "library_folders_library_id_idx": {
+          "name": "library_folders_library_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_folders_library_path_uidx": {
+          "name": "library_folders_library_path_uidx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_folders_library_id_libraries_id_fk": {
+          "name": "library_folders_library_id_libraries_id_fk",
+          "tableFrom": "library_folders",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "library_folders_id_library_id_unique": {
+          "name": "library_folders_id_library_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_files": {
+      "name": "book_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rel_path": {
+          "name": "rel_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ino": {
+          "name": "ino",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "mtime": {
+          "name": "mtime",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'content'"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_files_absolute_path_uidx": {
+          "name": "book_files_absolute_path_uidx",
+          "columns": [
+            {
+              "expression": "absolute_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_book_id_idx": {
+          "name": "book_files_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_id_idx": {
+          "name": "book_files_library_folder_id_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_file_hash_idx": {
+          "name": "book_files_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_ino_idx": {
+          "name": "book_files_ino_idx",
+          "columns": [
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_format_idx": {
+          "name": "book_files_format_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_file_hash_idx": {
+          "name": "book_files_library_folder_file_hash_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_ino_idx": {
+          "name": "book_files_library_folder_ino_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_files_book_id_books_id_fk": {
+          "name": "book_files_book_id_books_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_library_folder_id_library_folders_id_fk": {
+          "name": "book_files_library_folder_id_library_folders_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_book_folder_consistency_fk": {
+          "name": "book_files_book_folder_consistency_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id", "library_folder_id"],
+          "columnsTo": ["id", "library_folder_id"],
+          "onDelete": "no action",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_files_role_chk": {
+          "name": "book_files_role_chk",
+          "value": "\"book_files\".\"role\" in ('content', 'cover', 'metadata', 'supplement')"
+        },
+        "book_files_size_bytes_nonnegative_chk": {
+          "name": "book_files_size_bytes_nonnegative_chk",
+          "value": "\"book_files\".\"size_bytes\" is null or \"book_files\".\"size_bytes\" >= 0"
+        },
+        "book_files_duration_seconds_nonnegative_chk": {
+          "name": "book_files_duration_seconds_nonnegative_chk",
+          "value": "\"book_files\".\"duration_seconds\" is null or \"book_files\".\"duration_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.books": {
+      "name": "books",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "primary_file_id": {
+          "name": "primary_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_path": {
+          "name": "folder_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'present'"
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "books_library_id_folder_path_idx": {
+          "name": "books_library_id_folder_path_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_primary_file_id_idx": {
+          "name": "books_primary_file_id_idx",
+          "columns": [
+            {
+              "expression": "primary_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_status_idx": {
+          "name": "books_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_added_at_idx": {
+          "name": "books_library_added_at_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "books_library_id_libraries_id_fk": {
+          "name": "books_library_id_libraries_id_fk",
+          "tableFrom": "books",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_id_library_folders_id_fk": {
+          "name": "books_library_folder_id_library_folders_id_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_primary_file_id_book_files_id_fk": {
+          "name": "books_primary_file_id_book_files_id_fk",
+          "tableFrom": "books",
+          "tableTo": "book_files",
+          "columnsFrom": ["primary_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_library_fk": {
+          "name": "books_library_folder_library_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id", "library_id"],
+          "columnsTo": ["id", "library_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "books_id_library_folder_id_unique": {
+          "name": "books_id_library_folder_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_folder_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "books_status_chk": {
+          "name": "books_status_chk",
+          "value": "\"books\".\"status\" in ('present', 'missing', 'processing')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.collection_books": {
+      "name": "collection_books",
+      "schema": "",
+      "columns": {
+        "collection_id": {
+          "name": "collection_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collection_books_book_id_idx": {
+          "name": "collection_books_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collection_books_collection_id_collections_id_fk": {
+          "name": "collection_books_collection_id_collections_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "collections",
+          "columnsFrom": ["collection_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "collection_books_book_id_books_id_fk": {
+          "name": "collection_books_book_id_books_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "collection_books_collection_id_book_id_pk": {
+          "name": "collection_books_collection_id_book_id_pk",
+          "columns": ["collection_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.collections": {
+      "name": "collections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_to_kobo": {
+          "name": "sync_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collections_user_name_uidx": {
+          "name": "collections_user_name_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "collections_user_display_name_idx": {
+          "name": "collections_user_display_name_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collections_user_id_users_id_fk": {
+          "name": "collections_user_id_users_id_fk",
+          "tableFrom": "collections",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.smart_scopes": {
+      "name": "smart_scopes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "filter": {
+          "name": "filter",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_sort": {
+          "name": "default_sort",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "smart_scopes_user_id_users_id_fk": {
+          "name": "smart_scopes_user_id_users_id_fk",
+          "tableFrom": "smart_scopes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "smart_scopes_user_id_name_unique": {
+          "name": "smart_scopes_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series": {
+      "name": "book_series",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "normalized_name": {
+          "name": "normalized_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_normalized_name_uidx": {
+          "name": "book_series_normalized_name_uidx",
+          "columns": [
+            {
+              "expression": "normalized_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_name_trgm_idx": {
+          "name": "book_series_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "book_series_name_lower_idx": {
+          "name": "book_series_name_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.author_enrichment_queue": {
+      "name": "author_enrichment_queue",
+      "schema": "",
+      "columns": {
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unknown'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_success_at": {
+          "name": "last_success_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "author_enrichment_queue_status_next_attempt_idx": {
+          "name": "author_enrichment_queue_status_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_next_attempt_idx": {
+          "name": "author_enrichment_queue_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_single_processing_idx": {
+          "name": "author_enrichment_queue_single_processing_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"author_enrichment_queue\".\"status\" = 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "author_enrichment_queue_author_id_authors_id_fk": {
+          "name": "author_enrichment_queue_author_id_authors_id_fk",
+          "tableFrom": "author_enrichment_queue",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "author_enrichment_queue_status_chk": {
+          "name": "author_enrichment_queue_status_chk",
+          "value": "\"author_enrichment_queue\".\"status\" in ('queued', 'processing', 'rate_limited', 'failed', 'done')"
+        },
+        "author_enrichment_queue_reason_chk": {
+          "name": "author_enrichment_queue_reason_chk",
+          "value": "\"author_enrichment_queue\".\"reason\" in ('unknown', 'metadata_replace', 'manual_backfill', 'manual_backfill_all', 'author_rename', 'author_merge_target')"
+        },
+        "author_enrichment_queue_attempt_count_nonnegative_chk": {
+          "name": "author_enrichment_queue_attempt_count_nonnegative_chk",
+          "value": "\"author_enrichment_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.authors": {
+      "name": "authors",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_photo": {
+          "name": "has_photo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "last_enriched_at": {
+          "name": "last_enriched_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "authors_name_trgm_idx": {
+          "name": "authors_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "authors_name_unique": {
+          "name": "authors_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_authors": {
+      "name": "book_authors",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_authors_author_id_idx": {
+          "name": "book_authors_author_id_idx",
+          "columns": [
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_authors_book_display_idx": {
+          "name": "book_authors_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_authors_book_id_books_id_fk": {
+          "name": "book_authors_book_id_books_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_authors_author_id_authors_id_fk": {
+          "name": "book_authors_author_id_authors_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_authors_book_id_author_id_pk": {
+          "name": "book_authors_book_id_author_id_pk",
+          "columns": ["book_id", "author_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_genres": {
+      "name": "book_genres",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_genres_genre_id_idx": {
+          "name": "book_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_genres_book_id_books_id_fk": {
+          "name": "book_genres_book_id_books_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_genres_genre_id_genres_id_fk": {
+          "name": "book_genres_genre_id_genres_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_genres_book_id_genre_id_pk": {
+          "name": "book_genres_book_id_genre_id_pk",
+          "columns": ["book_id", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_metadata": {
+      "name": "book_metadata",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subtitle": {
+          "name": "subtitle",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn10": {
+          "name": "isbn10",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn13": {
+          "name": "isbn13",
+          "type": "varchar(13)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "publisher": {
+          "name": "publisher",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_year": {
+          "name": "published_year",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "language": {
+          "name": "language",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_count": {
+          "name": "page_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_name": {
+          "name": "series_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_source": {
+          "name": "cover_source",
+          "type": "varchar(9)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "google_books_id": {
+          "name": "google_books_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "goodreads_id": {
+          "name": "goodreads_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "amazon_id": {
+          "name": "amazon_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_id": {
+          "name": "hardcover_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "open_library_id": {
+          "name": "open_library_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "itunes_id": {
+          "name": "itunes_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_id": {
+          "name": "kobo_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_score": {
+          "name": "metadata_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_metadata_fetch_at": {
+          "name": "last_metadata_fetch_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(256)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_written_at": {
+          "name": "last_written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "abridged": {
+          "name": "abridged",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "audible_id": {
+          "name": "audible_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "comicvine_id": {
+          "name": "comicvine_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ranobedb_id": {
+          "name": "ranobedb_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapters": {
+          "name": "chapters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locked_fields": {
+          "name": "locked_fields",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bm_title_trgm_idx": {
+          "name": "bm_title_trgm_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_title_lower_idx": {
+          "name": "bm_title_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"title\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_trgm_idx": {
+          "name": "bm_series_trgm_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_series_id_idx": {
+          "name": "bm_series_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_lower_btrim_idx": {
+          "name": "bm_series_name_lower_btrim_idx",
+          "columns": [
+            {
+              "expression": "lower(btrim(\"series_name\"))",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_publisher_trgm_idx": {
+          "name": "bm_publisher_trgm_idx",
+          "columns": [
+            {
+              "expression": "publisher",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_language_idx": {
+          "name": "bm_language_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_language_trgm_idx": {
+          "name": "bm_language_trgm_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_published_year_idx": {
+          "name": "bm_published_year_idx",
+          "columns": [
+            {
+              "expression": "published_year",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_index_idx": {
+          "name": "bm_series_name_index_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn10_idx": {
+          "name": "bm_isbn10_idx",
+          "columns": [
+            {
+              "expression": "isbn10",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn13_idx": {
+          "name": "bm_isbn13_idx",
+          "columns": [
+            {
+              "expression": "isbn13",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_embedding_hnsw_cosine_idx": {
+          "name": "bm_embedding_hnsw_cosine_idx",
+          "columns": [
+            {
+              "expression": "\"embedding\" vector_cosine_ops",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_book_id_books_id_fk": {
+          "name": "book_metadata_book_id_books_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_metadata_series_id_book_series_id_fk": {
+          "name": "book_metadata_series_id_book_series_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "book_series",
+          "columnsFrom": ["series_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_rating_range_chk": {
+          "name": "book_metadata_rating_range_chk",
+          "value": "\"book_metadata\".\"rating\" is null or (\"book_metadata\".\"rating\" >= 1 and \"book_metadata\".\"rating\" <= 10)"
+        },
+        "book_metadata_published_year_range_chk": {
+          "name": "book_metadata_published_year_range_chk",
+          "value": "\"book_metadata\".\"published_year\" is null or (\"book_metadata\".\"published_year\" >= 1000 and \"book_metadata\".\"published_year\" <= 2200)"
+        },
+        "book_metadata_page_count_nonnegative_chk": {
+          "name": "book_metadata_page_count_nonnegative_chk",
+          "value": "\"book_metadata\".\"page_count\" is null or \"book_metadata\".\"page_count\" >= 0"
+        },
+        "book_metadata_duration_seconds_nonnegative_chk": {
+          "name": "book_metadata_duration_seconds_nonnegative_chk",
+          "value": "\"book_metadata\".\"duration_seconds\" is null or \"book_metadata\".\"duration_seconds\" >= 0"
+        },
+        "book_metadata_cover_source_chk": {
+          "name": "book_metadata_cover_source_chk",
+          "value": "\"book_metadata\".\"cover_source\" is null or \"book_metadata\".\"cover_source\" in ('extracted', 'custom')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_metadata_fetch_queue": {
+      "name": "book_metadata_fetch_queue",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'manual_trigger'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bmfq_status_idx": {
+          "name": "bmfq_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_created_at_idx": {
+          "name": "bmfq_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_status_created_book_idx": {
+          "name": "bmfq_status_created_book_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_fetch_queue_book_id_books_id_fk": {
+          "name": "book_metadata_fetch_queue_book_id_books_id_fk",
+          "tableFrom": "book_metadata_fetch_queue",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_fetch_queue_status_chk": {
+          "name": "book_metadata_fetch_queue_status_chk",
+          "value": "\"book_metadata_fetch_queue\".\"status\" in ('queued', 'processing', 'failed')"
+        },
+        "book_metadata_fetch_queue_reason_chk": {
+          "name": "book_metadata_fetch_queue_reason_chk",
+          "value": "\"book_metadata_fetch_queue\".\"reason\" in ('event_import', 'manual_trigger', 'manual_retry')"
+        },
+        "book_metadata_fetch_queue_attempt_count_nonnegative_chk": {
+          "name": "book_metadata_fetch_queue_attempt_count_nonnegative_chk",
+          "value": "\"book_metadata_fetch_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_tags": {
+      "name": "book_tags",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_tags_tag_id_idx": {
+          "name": "book_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_tags_book_id_books_id_fk": {
+          "name": "book_tags_book_id_books_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_tags_tag_id_tags_id_fk": {
+          "name": "book_tags_tag_id_tags_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_tags_book_id_tag_id_pk": {
+          "name": "book_tags_book_id_tag_id_pk",
+          "columns": ["book_id", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.genres": {
+      "name": "genres",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "genres_name_trgm_idx": {
+          "name": "genres_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "genres_name_unique": {
+          "name": "genres_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.tags": {
+      "name": "tags",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "tags_name_trgm_idx": {
+          "name": "tags_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "tags_name_unique": {
+          "name": "tags_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_narrators": {
+      "name": "book_narrators",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "narrator_id": {
+          "name": "narrator_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_narrators_narrator_id_idx": {
+          "name": "book_narrators_narrator_id_idx",
+          "columns": [
+            {
+              "expression": "narrator_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_narrators_book_id_books_id_fk": {
+          "name": "book_narrators_book_id_books_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_narrators_narrator_id_narrators_id_fk": {
+          "name": "book_narrators_narrator_id_narrators_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "narrators",
+          "columnsFrom": ["narrator_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_narrators_book_id_narrator_id_pk": {
+          "name": "book_narrators_book_id_narrator_id_pk",
+          "columns": ["book_id", "narrator_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.narrators": {
+      "name": "narrators",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "narrators_name_trgm_idx": {
+          "name": "narrators_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "narrators_name_unique": {
+          "name": "narrators_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.library_dir_scan_state": {
+      "name": "library_dir_scan_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dir_path": {
+          "name": "dir_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_mtime_ms": {
+          "name": "last_seen_mtime_ms",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "library_dir_scan_state_folder_dir_uidx": {
+          "name": "library_dir_scan_state_folder_dir_uidx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "dir_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_dir_scan_state_folder_idx": {
+          "name": "library_dir_scan_state_folder_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_dir_scan_state_library_folder_id_library_folders_id_fk": {
+          "name": "library_dir_scan_state_library_folder_id_library_folders_id_fk",
+          "tableFrom": "library_dir_scan_state",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.scan_jobs": {
+      "name": "scan_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'running'"
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_count": {
+          "name": "added_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_count": {
+          "name": "updated_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "missing_count": {
+          "name": "missing_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "scan_jobs_library_status_idx": {
+          "name": "scan_jobs_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "scan_jobs_library_id_libraries_id_fk": {
+          "name": "scan_jobs_library_id_libraries_id_fk",
+          "tableFrom": "scan_jobs",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "scan_jobs_status_chk": {
+          "name": "scan_jobs_status_chk",
+          "value": "\"scan_jobs\".\"status\" in ('running', 'completed', 'failed')"
+        },
+        "scan_jobs_triggered_by_chk": {
+          "name": "scan_jobs_triggered_by_chk",
+          "value": "\"scan_jobs\".\"triggered_by\" in ('manual', 'watcher', 'schedule')"
+        },
+        "scan_jobs_added_count_nonnegative_chk": {
+          "name": "scan_jobs_added_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"added_count\" >= 0"
+        },
+        "scan_jobs_updated_count_nonnegative_chk": {
+          "name": "scan_jobs_updated_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"updated_count\" >= 0"
+        },
+        "scan_jobs_missing_count_nonnegative_chk": {
+          "name": "scan_jobs_missing_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"missing_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_positions": {
+      "name": "annotation_positions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(12)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pos0": {
+          "name": "pos0",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pos1": {
+          "name": "pos1",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'exact'"
+        },
+        "converter_version": {
+          "name": "converter_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "extras": {
+          "name": "extras",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_positions_annotation_format_uidx": {
+          "name": "annotation_positions_annotation_format_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_user_idx": {
+          "name": "annotation_positions_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_format_status_idx": {
+          "name": "annotation_positions_format_status_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_positions_annotation_id_annotations_id_fk": {
+          "name": "annotation_positions_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_user_id_users_id_fk": {
+          "name": "annotation_positions_user_id_users_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_book_file_id_book_files_id_fk": {
+          "name": "annotation_positions_book_file_id_book_files_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_positions_format_chk": {
+          "name": "annotation_positions_format_chk",
+          "value": "\"annotation_positions\".\"format\" in ('cfi', 'xpointer', 'pdf', 'kobo_span')"
+        },
+        "annotation_positions_status_chk": {
+          "name": "annotation_positions_status_chk",
+          "value": "\"annotation_positions\".\"status\" in ('exact', 'repaired', 'failed', 'pending')"
+        },
+        "annotation_positions_pos0_chk": {
+          "name": "annotation_positions_pos0_chk",
+          "value": "\"annotation_positions\".\"status\" in ('failed', 'pending') or \"annotation_positions\".\"pos0\" is not null"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_sync_state": {
+      "name": "annotation_sync_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_key": {
+          "name": "external_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_created_at": {
+          "name": "external_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_applied_version": {
+          "name": "last_applied_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "delete_acked_at": {
+          "name": "delete_acked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_synced_at": {
+          "name": "first_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_sync_state_annotation_source_device_uidx": {
+          "name": "annotation_sync_state_annotation_source_device_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_source_device_key_idx": {
+          "name": "annotation_sync_state_user_source_device_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_key_idx": {
+          "name": "annotation_sync_state_user_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_annotation_id_idx": {
+          "name": "annotation_sync_state_annotation_id_idx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_sync_state_annotation_id_annotations_id_fk": {
+          "name": "annotation_sync_state_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_sync_state_user_id_users_id_fk": {
+          "name": "annotation_sync_state_user_id_users_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_sync_state_source_chk": {
+          "name": "annotation_sync_state_source_chk",
+          "value": "\"annotation_sync_state\".\"source\" in ('koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotations": {
+      "name": "annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'yellow'"
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'highlight'"
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_title": {
+          "name": "chapter_title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'web'"
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_created_at": {
+          "name": "device_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_updated_at": {
+          "name": "device_updated_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_user_id_idx": {
+          "name": "annotations_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_idx": {
+          "name": "annotations_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_active_idx": {
+          "name": "annotations_user_book_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"annotations\".\"deleted_at\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotations_user_id_users_id_fk": {
+          "name": "annotations_user_id_users_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotations_book_id_books_id_fk": {
+          "name": "annotations_book_id_books_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_style_chk": {
+          "name": "annotations_style_chk",
+          "value": "\"annotations\".\"style\" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')"
+        },
+        "annotations_origin_chk": {
+          "name": "annotations_origin_chk",
+          "value": "\"annotations\".\"origin\" in ('web', 'koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.audiobook_progress": {
+      "name": "audiobook_progress",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "current_file_id": {
+          "name": "current_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "abp_user_id_idx": {
+          "name": "abp_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audiobook_progress_user_id_users_id_fk": {
+          "name": "audiobook_progress_user_id_users_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_book_id_books_id_fk": {
+          "name": "audiobook_progress_book_id_books_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_current_file_id_book_files_id_fk": {
+          "name": "audiobook_progress_current_file_id_book_files_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["current_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "audiobook_progress_user_id_book_id_pk": {
+          "name": "audiobook_progress_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "audiobook_progress_percentage_range_chk": {
+          "name": "audiobook_progress_percentage_range_chk",
+          "value": "\"audiobook_progress\".\"percentage\" >= 0 and \"audiobook_progress\".\"percentage\" <= 100"
+        },
+        "audiobook_progress_position_seconds_nonnegative_chk": {
+          "name": "audiobook_progress_position_seconds_nonnegative_chk",
+          "value": "\"audiobook_progress\".\"position_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.bookmarks": {
+      "name": "bookmarks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bookmarks_user_book_idx": {
+          "name": "bookmarks_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_cfi_uidx": {
+          "name": "bookmarks_user_book_cfi_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "cfi",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"cfi\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_pos_uidx": {
+          "name": "bookmarks_user_book_pos_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position_seconds",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"position_seconds\" is not null and \"bookmarks\".\"cfi\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "bookmarks_user_id_users_id_fk": {
+          "name": "bookmarks_user_id_users_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "bookmarks_book_id_books_id_fk": {
+          "name": "bookmarks_book_id_books_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reader_default_preferences": {
+      "name": "reader_default_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format_group": {
+          "name": "format_group",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rdp_user_format_idx": {
+          "name": "rdp_user_format_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format_group",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_default_preferences_user_id_users_id_fk": {
+          "name": "reader_default_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_default_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reader_default_preferences_format_group_chk": {
+          "name": "reader_default_preferences_format_group_chk",
+          "value": "\"reader_default_preferences\".\"format_group\" in ('epub', 'pdf', 'cbx', 'audio')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reader_preferences": {
+      "name": "reader_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rp_user_file_idx": {
+          "name": "rp_user_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_preferences_user_id_users_id_fk": {
+          "name": "reader_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reader_preferences_book_file_id_book_files_id_fk": {
+          "name": "reader_preferences_book_file_id_book_files_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reading_progress": {
+      "name": "reading_progress",
+      "schema": "",
+      "columns": {
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_source": {
+          "name": "kobo_location_source",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_type": {
+          "name": "kobo_location_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_value": {
+          "name": "kobo_location_value",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_content_source_progress_percent": {
+          "name": "kobo_content_source_progress_percent",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "koreader_progress": {
+          "name": "koreader_progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reading_progress_user_id_idx": {
+          "name": "reading_progress_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reading_progress_user_updated_at_idx": {
+          "name": "reading_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_progress_book_file_id_book_files_id_fk": {
+          "name": "reading_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_progress_user_id_users_id_fk": {
+          "name": "reading_progress_user_id_users_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "reading_progress_book_file_id_user_id_pk": {
+          "name": "reading_progress_book_file_id_user_id_pk",
+          "columns": ["book_file_id", "user_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_progress_percentage_range_chk": {
+          "name": "reading_progress_percentage_range_chk",
+          "value": "\"reading_progress\".\"percentage\" >= 0 and \"reading_progress\".\"percentage\" <= 100"
+        },
+        "reading_progress_page_number_nonnegative_chk": {
+          "name": "reading_progress_page_number_nonnegative_chk",
+          "value": "\"reading_progress\".\"page_number\" is null or \"reading_progress\".\"page_number\" >= 0"
+        },
+        "reading_progress_position_seconds_nonnegative_chk": {
+          "name": "reading_progress_position_seconds_nonnegative_chk",
+          "value": "\"reading_progress\".\"position_seconds\" is null or \"reading_progress\".\"position_seconds\" >= 0"
+        },
+        "reading_progress_kobo_content_source_progress_range_chk": {
+          "name": "reading_progress_kobo_content_source_progress_range_chk",
+          "value": "\"reading_progress\".\"kobo_content_source_progress_percent\" is null or (\"reading_progress\".\"kobo_content_source_progress_percent\" >= 0 and \"reading_progress\".\"kobo_content_source_progress_percent\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reading_sessions": {
+      "name": "reading_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_progress": {
+          "name": "end_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "rs_user_session_id_uidx": {
+          "name": "rs_user_session_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_started_at_idx": {
+          "name": "rs_user_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_book_file_started_at_idx": {
+          "name": "rs_book_file_started_at_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_file_idx": {
+          "name": "rs_user_book_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_started_at_idx": {
+          "name": "rs_user_book_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_sessions_user_id_users_id_fk": {
+          "name": "reading_sessions_user_id_users_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_file_id_book_files_id_fk": {
+          "name": "reading_sessions_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_id_books_id_fk": {
+          "name": "reading_sessions_book_id_books_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_sessions_source_chk": {
+          "name": "reading_sessions_source_chk",
+          "value": "\"reading_sessions\".\"source\" in ('web', 'koreader', 'manual', 'kobo')"
+        },
+        "reading_sessions_duration_seconds_nonnegative_chk": {
+          "name": "reading_sessions_duration_seconds_nonnegative_chk",
+          "value": "\"reading_sessions\".\"duration_seconds\" >= 0"
+        },
+        "reading_sessions_end_progress_range_chk": {
+          "name": "reading_sessions_end_progress_range_chk",
+          "value": "\"reading_sessions\".\"end_progress\" is null or (\"reading_sessions\".\"end_progress\" >= 0 and \"reading_sessions\".\"end_progress\" <= 100)"
+        },
+        "reading_sessions_ended_after_started_chk": {
+          "name": "reading_sessions_ended_after_started_chk",
+          "value": "\"reading_sessions\".\"ended_at\" >= \"reading_sessions\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_ratings": {
+      "name": "user_book_ratings",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubr_user_id_idx": {
+          "name": "ubr_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_id_idx": {
+          "name": "ubr_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_user_rating_idx": {
+          "name": "ubr_book_user_rating_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_ratings_user_id_users_id_fk": {
+          "name": "user_book_ratings_user_id_users_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_ratings_book_id_books_id_fk": {
+          "name": "user_book_ratings_book_id_books_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_ratings_user_id_book_id_pk": {
+          "name": "user_book_ratings_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_ratings_rating_range_chk": {
+          "name": "user_book_ratings_rating_range_chk",
+          "value": "\"user_book_ratings\".\"rating\" >= 1 and \"user_book_ratings\".\"rating\" <= 5"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_status": {
+      "name": "user_book_status",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unread'"
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubs_user_id_idx": {
+          "name": "ubs_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_user_status_idx": {
+          "name": "ubs_user_status_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_book_user_idx": {
+          "name": "ubs_book_user_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_status_user_id_users_id_fk": {
+          "name": "user_book_status_user_id_users_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_status_book_id_books_id_fk": {
+          "name": "user_book_status_book_id_books_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_status_user_id_book_id_pk": {
+          "name": "user_book_status_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_status_status_chk": {
+          "name": "user_book_status_status_chk",
+          "value": "\"user_book_status\".\"status\" in ('unread', 'want_to_read', 'reading', 'on_hold', 'rereading', 'read', 'skimmed', 'abandoned')"
+        },
+        "user_book_status_source_chk": {
+          "name": "user_book_status_source_chk",
+          "value": "\"user_book_status\".\"source\" in ('auto', 'manual')"
+        },
+        "user_book_status_finished_after_started_chk": {
+          "name": "user_book_status_finished_after_started_chk",
+          "value": "\"user_book_status\".\"finished_at\" is null or \"user_book_status\".\"started_at\" is null or \"user_book_status\".\"finished_at\" >= \"user_book_status\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_reading_daily_stats": {
+      "name": "user_reading_daily_stats",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "day": {
+          "name": "day",
+          "type": "date",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_seconds": {
+          "name": "reading_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "sessions_count": {
+          "name": "sessions_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "urds_user_day_idx": {
+          "name": "urds_user_day_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "day",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_reading_daily_stats_user_id_users_id_fk": {
+          "name": "user_reading_daily_stats_user_id_users_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_reading_daily_stats_library_id_libraries_id_fk": {
+          "name": "user_reading_daily_stats_library_id_libraries_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_reading_daily_stats_user_id_library_id_day_pk": {
+          "name": "user_reading_daily_stats_user_id_library_id_day_pk",
+          "columns": ["user_id", "library_id", "day"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_reading_daily_stats_reading_seconds_nonnegative_chk": {
+          "name": "user_reading_daily_stats_reading_seconds_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"reading_seconds\" >= 0"
+        },
+        "user_reading_daily_stats_sessions_count_nonnegative_chk": {
+          "name": "user_reading_daily_stats_sessions_count_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"sessions_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.oidc_group_mappings": {
+      "name": "oidc_group_mappings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_group_claim": {
+          "name": "oidc_group_claim",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_group_mappings_provider_claim_uidx": {
+          "name": "oidc_group_mappings_provider_claim_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_group_claim",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_group_mappings_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_group_mappings_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_group_mappings",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_identities": {
+      "name": "oidc_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "linked_at": {
+          "name": "linked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_identities_provider_subject_uidx": {
+          "name": "oidc_identities_provider_subject_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_provider_uidx": {
+          "name": "oidc_identities_user_provider_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_issuer_subject_uidx": {
+          "name": "oidc_identities_issuer_subject_uidx",
+          "columns": [
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_id_idx": {
+          "name": "oidc_identities_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_identities_user_id_users_id_fk": {
+          "name": "oidc_identities_user_id_users_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_identities_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_identities_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_permission_grants": {
+      "name": "oidc_permission_grants",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "oidc_permission_grants_user_id_users_id_fk": {
+          "name": "oidc_permission_grants_user_id_users_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_permission_grants_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_permission_grants_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "oidc_permission_grants_user_id_provider_id_permission_name_pk": {
+          "name": "oidc_permission_grants_user_id_provider_id_permission_name_pk",
+          "columns": ["user_id", "provider_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_providers": {
+      "name": "oidc_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "issuer_uri": {
+          "name": "issuer_uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'openid profile email'"
+        },
+        "icon_url": {
+          "name": "icon_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "claim_mapping": {
+          "name": "claim_mapping",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"username\":\"preferred_username\",\"name\":\"name\",\"email\":\"email\",\"groups\":\"groups\"}'::jsonb"
+        },
+        "auto_provision": {
+          "name": "auto_provision",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"enabled\":false,\"allowLocalLinking\":false,\"defaultPermissionNames\":[]}'::jsonb"
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_providers_enabled_order_idx": {
+          "name": "oidc_providers_enabled_order_idx",
+          "columns": [
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oidc_providers_slug_unique": {
+          "name": "oidc_providers_slug_unique",
+          "nullsNotDistinct": false,
+          "columns": ["slug"]
+        },
+        "oidc_providers_issuer_uri_unique": {
+          "name": "oidc_providers_issuer_uri_unique",
+          "nullsNotDistinct": false,
+          "columns": ["issuer_uri"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_sessions": {
+      "name": "oidc_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_session_id": {
+          "name": "oidc_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token_hint": {
+          "name": "id_token_hint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_refresh_token": {
+          "name": "idp_refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_sessions_user_active_idx": {
+          "name": "oidc_sessions_user_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"oidc_sessions\".\"revoked\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_subject_issuer_idx": {
+          "name": "oidc_sessions_subject_issuer_idx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_sid_idx": {
+          "name": "oidc_sessions_sid_idx",
+          "columns": [
+            {
+              "expression": "oidc_session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_expires_at_idx": {
+          "name": "oidc_sessions_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_provider_id_idx": {
+          "name": "oidc_sessions_provider_id_idx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_sessions_user_id_users_id_fk": {
+          "name": "oidc_sessions_user_id_users_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_sessions_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_sessions_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_states": {
+      "name": "oidc_states",
+      "schema": "",
+      "columns": {
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "meta": {
+          "name": "meta",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oidc_states_expires_at_idx": {
+          "name": "oidc_states_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_states_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_states_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_states",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_used_jtis": {
+      "name": "oidc_used_jtis",
+      "schema": "",
+      "columns": {
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_used_jtis_expires_at_idx": {
+          "name": "oidc_used_jtis_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.opds_users": {
+      "name": "opds_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "opds_sort_order",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'recent'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "opds_users_username_lower_uidx": {
+          "name": "opds_users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "opds_users_user_id_users_id_fk": {
+          "name": "opds_users_user_id_users_id_fk",
+          "tableFrom": "opds_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "opds_users_username_unique": {
+          "name": "opds_users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_book_entitlements": {
+      "name": "kobo_book_entitlements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "cover_image_id": {
+          "name": "cover_image_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "needs_legacy_numeric_removal": {
+          "name": "needs_legacy_numeric_removal",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_book_entitlements_user_id_idx": {
+          "name": "kobo_book_entitlements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kobo_book_entitlements_book_id_idx": {
+          "name": "kobo_book_entitlements_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_book_entitlements_user_id_users_id_fk": {
+          "name": "kobo_book_entitlements_user_id_users_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_book_entitlements_book_id_books_id_fk": {
+          "name": "kobo_book_entitlements_book_id_books_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_book_entitlements_user_book_unique": {
+          "name": "kobo_book_entitlements_user_book_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        },
+        "kobo_book_entitlements_user_entitlement_unique": {
+          "name": "kobo_book_entitlements_user_entitlement_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "entitlement_id"]
+        },
+        "kobo_book_entitlements_user_cover_unique": {
+          "name": "kobo_book_entitlements_user_cover_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "cover_image_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_devices": {
+      "name": "kobo_devices",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_device_id": {
+          "name": "client_device_id",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_seen_at": {
+          "name": "last_seen_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_devices_user_id_idx": {
+          "name": "kobo_devices_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_devices_user_id_users_id_fk": {
+          "name": "kobo_devices_user_id_users_id_fk",
+          "tableFrom": "kobo_devices",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_devices_token_unique": {
+          "name": "kobo_devices_token_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token"]
+        },
+        "kobo_devices_client_device_id_unique": {
+          "name": "kobo_devices_client_device_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["client_device_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_library_snapshots": {
+      "name": "kobo_library_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_library_snapshots_user_id_users_id_fk": {
+          "name": "kobo_library_snapshots_user_id_users_id_fk",
+          "tableFrom": "kobo_library_snapshots",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_library_snapshots_user_id_unique": {
+          "name": "kobo_library_snapshots_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_reading_states": {
+      "name": "kobo_reading_states",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at_kobo": {
+          "name": "created_at_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_modified_kobo": {
+          "name": "last_modified_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority_timestamp": {
+          "name": "priority_timestamp",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "current_bookmark": {
+          "name": "current_bookmark",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "statistics": {
+          "name": "statistics",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_info": {
+          "name": "status_info",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_reading_states_user_id_users_id_fk": {
+          "name": "kobo_reading_states_user_id_users_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_reading_states_book_id_books_id_fk": {
+          "name": "kobo_reading_states_book_id_books_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_reading_states_user_id_book_id_unique": {
+          "name": "kobo_reading_states_user_id_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_snapshot_books": {
+      "name": "kobo_snapshot_books",
+      "schema": "",
+      "columns": {
+        "snapshot_id": {
+          "name": "snapshot_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "synced": {
+          "name": "synced",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "pending_delete": {
+          "name": "pending_delete",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_new": {
+          "name": "is_new",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "removed_by_device": {
+          "name": "removed_by_device",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "delivery_hash": {
+          "name": "delivery_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_hash": {
+          "name": "metadata_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "kobo_snapshot_books_snapshot_synced_book_idx": {
+          "name": "kobo_snapshot_books_snapshot_synced_book_idx",
+          "columns": [
+            {
+              "expression": "snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "synced",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk": {
+          "name": "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "kobo_library_snapshots",
+          "columnsFrom": ["snapshot_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_snapshot_books_book_id_books_id_fk": {
+          "name": "kobo_snapshot_books_book_id_books_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "kobo_snapshot_books_snapshot_id_book_id_pk": {
+          "name": "kobo_snapshot_books_snapshot_id_book_id_pk",
+          "columns": ["snapshot_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_sync_settings": {
+      "name": "kobo_sync_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "finished_threshold": {
+          "name": "finished_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 99
+        },
+        "convert_to_kepub": {
+          "name": "convert_to_kepub",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "force_enable_hyphenation": {
+          "name": "force_enable_hyphenation",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "kepub_conversion_limit_mb": {
+          "name": "kepub_conversion_limit_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "two_way_progress_sync": {
+          "name": "two_way_progress_sync",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sync_bookorbit_annotations_to_kobo": {
+          "name": "sync_bookorbit_annotations_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_sync_settings_user_id_users_id_fk": {
+          "name": "kobo_sync_settings_user_id_users_id_fk",
+          "tableFrom": "kobo_sync_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_sync_settings_user_id_unique": {
+          "name": "kobo_sync_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "kobo_sync_settings_reading_threshold_range_chk": {
+          "name": "kobo_sync_settings_reading_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"reading_threshold\" >= 0 and \"kobo_sync_settings\".\"reading_threshold\" <= 100"
+        },
+        "kobo_sync_settings_finished_threshold_range_chk": {
+          "name": "kobo_sync_settings_finished_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"finished_threshold\" >= 0 and \"kobo_sync_settings\".\"finished_threshold\" <= 100"
+        },
+        "kobo_sync_settings_conversion_limit_nonnegative_chk": {
+          "name": "kobo_sync_settings_conversion_limit_nonnegative_chk",
+          "value": "\"kobo_sync_settings\".\"kepub_conversion_limit_mb\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_dock_files": {
+      "name": "book_dock_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "file_name": {
+          "name": "file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "embedded_metadata": {
+          "name": "embedded_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "selected_metadata": {
+          "name": "selected_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata": {
+          "name": "fetched_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_path": {
+          "name": "cover_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_library_id": {
+          "name": "target_library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_folder_id": {
+          "name": "target_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata_sources": {
+          "name": "fetched_metadata_sources",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_edited_at": {
+          "name": "metadata_edited_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uploaded_by": {
+          "name": "uploaded_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_dock_files_status_idx": {
+          "name": "book_dock_files_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_dock_files_uploaded_by_idx": {
+          "name": "book_dock_files_uploaded_by_idx",
+          "columns": [
+            {
+              "expression": "uploaded_by",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_dock_files_target_library_id_libraries_id_fk": {
+          "name": "book_dock_files_target_library_id_libraries_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "libraries",
+          "columnsFrom": ["target_library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_target_folder_id_library_folders_id_fk": {
+          "name": "book_dock_files_target_folder_id_library_folders_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["target_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_uploaded_by_users_id_fk": {
+          "name": "book_dock_files_uploaded_by_users_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "users",
+          "columnsFrom": ["uploaded_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "book_dock_files_absolute_path_unique": {
+          "name": "book_dock_files_absolute_path_unique",
+          "nullsNotDistinct": false,
+          "columns": ["absolute_path"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "book_dock_files_status_chk": {
+          "name": "book_dock_files_status_chk",
+          "value": "\"book_dock_files\".\"status\" in ('pending', 'extracting', 'fetching', 'ready', 'error')"
+        },
+        "book_dock_files_confidence_range_chk": {
+          "name": "book_dock_files_confidence_range_chk",
+          "value": "\"book_dock_files\".\"confidence\" is null or (\"book_dock_files\".\"confidence\" >= 0 and \"book_dock_files\".\"confidence\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.file_write_log": {
+      "name": "file_write_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fields_written": {
+          "name": "fields_written",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "written_at": {
+          "name": "written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "fwl_book_id_written_at_idx": {
+          "name": "fwl_book_id_written_at_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "written_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "file_write_log_book_id_books_id_fk": {
+          "name": "file_write_log_book_id_books_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "file_write_log_book_file_id_book_files_id_fk": {
+          "name": "file_write_log_book_file_id_book_files_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "file_write_log_user_id_users_id_fk": {
+          "name": "file_write_log_user_id_users_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "file_write_log_status_chk": {
+          "name": "file_write_log_status_chk",
+          "value": "\"file_write_log\".\"status\" in ('success', 'skipped', 'failed')"
+        },
+        "file_write_log_triggered_by_chk": {
+          "name": "file_write_log_triggered_by_chk",
+          "value": "\"file_write_log\".\"triggered_by\" in ('auto', 'sync')"
+        },
+        "file_write_log_duration_ms_nonnegative_chk": {
+          "name": "file_write_log_duration_ms_nonnegative_chk",
+          "value": "\"file_write_log\".\"duration_ms\" is null or \"file_write_log\".\"duration_ms\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_templates": {
+      "name": "email_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_text": {
+          "name": "body_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system": {
+          "name": "is_system",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_templates_one_default_per_user_uidx": {
+          "name": "email_templates_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"is_default\" = true and \"email_templates\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_templates_system_name_unique": {
+          "name": "email_templates_system_name_unique",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"user_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_templates_user_id_users_id_fk": {
+          "name": "email_templates_user_id_users_id_fk",
+          "tableFrom": "email_templates",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_templates_user_id_name_unique": {
+          "name": "email_templates_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_providers": {
+      "name": "email_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "host": {
+          "name": "host",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "port": {
+          "name": "port",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_enc": {
+          "name": "password_enc",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_name": {
+          "name": "from_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_address": {
+          "name": "from_address",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth": {
+          "name": "auth",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "ssl": {
+          "name": "ssl",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "start_tls": {
+          "name": "start_tls",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_shared": {
+          "name": "is_shared",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system_provider": {
+          "name": "is_system_provider",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "tls_reject_unauthorized": {
+          "name": "tls_reject_unauthorized",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_providers_one_default_per_user_uidx": {
+          "name": "email_providers_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_default\" = true and \"email_providers\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_providers_one_system_provider_uidx": {
+          "name": "email_providers_one_system_provider_uidx",
+          "columns": [
+            {
+              "expression": "is_system_provider",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_system_provider\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_providers_user_id_users_id_fk": {
+          "name": "email_providers_user_id_users_id_fk",
+          "tableFrom": "email_providers",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_providers_user_id_name_unique": {
+          "name": "email_providers_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_providers_id_user_id_unique": {
+          "name": "email_providers_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_providers_port_range_chk": {
+          "name": "email_providers_port_range_chk",
+          "value": "\"email_providers\".\"port\" >= 1 and \"email_providers\".\"port\" <= 65535"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_group_members": {
+      "name": "email_recipient_group_members",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "recipient_id": {
+          "name": "recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_group_members_user_id_users_id_fk": {
+          "name": "email_recipient_group_members_user_id_users_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_id_email_recipient_groups_id_fk": {
+          "name": "email_recipient_group_members_group_id_email_recipient_groups_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_id_email_recipients_id_fk": {
+          "name": "email_recipient_group_members_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_user_fk": {
+          "name": "email_recipient_group_members_group_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_user_fk": {
+          "name": "email_recipient_group_members_recipient_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "email_recipient_group_members_group_id_recipient_id_pk": {
+          "name": "email_recipient_group_members_group_id_recipient_id_pk",
+          "columns": ["group_id", "recipient_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_groups": {
+      "name": "email_recipient_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_groups_user_id_users_id_fk": {
+          "name": "email_recipient_groups_user_id_users_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_groups_default_template_id_email_templates_id_fk": {
+          "name": "email_recipient_groups_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipient_groups_user_id_name_unique": {
+          "name": "email_recipient_groups_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_recipient_groups_id_user_id_unique": {
+          "name": "email_recipient_groups_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipients": {
+      "name": "email_recipients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "device_type": {
+          "name": "device_type",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "preferred_format": {
+          "name": "preferred_format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_recipients_user_email_lower_uidx": {
+          "name": "email_recipients_user_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_recipients_one_default_per_user_uidx": {
+          "name": "email_recipients_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_recipients\".\"is_default\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_recipients_user_id_users_id_fk": {
+          "name": "email_recipients_user_id_users_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipients_default_template_id_email_templates_id_fk": {
+          "name": "email_recipients_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipients_user_id_email_unique": {
+          "name": "email_recipients_user_id_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "email"]
+        },
+        "email_recipients_id_user_id_unique": {
+          "name": "email_recipients_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_recipients_device_type_chk": {
+          "name": "email_recipients_device_type_chk",
+          "value": "\"email_recipients\".\"device_type\" is null or \"email_recipients\".\"device_type\" in ('kindle', 'kobo', 'other')"
+        },
+        "email_recipients_preferred_format_chk": {
+          "name": "email_recipients_preferred_format_chk",
+          "value": "\"email_recipients\".\"preferred_format\" is null or \"email_recipients\".\"preferred_format\" in ('epub', 'pdf', 'mobi', 'azw3', 'cbz', 'cbr')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_preferences": {
+      "name": "email_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_provider_id": {
+          "name": "default_provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_recipient_id": {
+          "name": "default_recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_preferences_user_id_users_id_fk": {
+          "name": "email_preferences_user_id_users_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_provider_id_email_providers_id_fk": {
+          "name": "email_preferences_default_provider_id_email_providers_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_providers",
+          "columnsFrom": ["default_provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_id_email_recipients_id_fk": {
+          "name": "email_preferences_default_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_template_id_email_templates_id_fk": {
+          "name": "email_preferences_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_owner_fk": {
+          "name": "email_preferences_default_recipient_owner_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_preferences_user_id_unique": {
+          "name": "email_preferences_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_send_log": {
+      "name": "email_send_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "to_email": {
+          "name": "to_email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_name": {
+          "name": "to_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_send_log_user_created_at_idx": {
+          "name": "email_send_log_user_created_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_created_at_idx": {
+          "name": "email_send_log_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_status_next_retry_idx": {
+          "name": "email_send_log_status_next_retry_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_retry_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_send_log_user_id_users_id_fk": {
+          "name": "email_send_log_user_id_users_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_id_books_id_fk": {
+          "name": "email_send_log_book_id_books_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_file_id_book_files_id_fk": {
+          "name": "email_send_log_book_file_id_book_files_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_provider_id_email_providers_id_fk": {
+          "name": "email_send_log_provider_id_email_providers_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_template_id_email_templates_id_fk": {
+          "name": "email_send_log_template_id_email_templates_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_templates",
+          "columnsFrom": ["template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "email_send_log_status_chk": {
+          "name": "email_send_log_status_chk",
+          "value": "\"email_send_log\".\"status\" in ('pending', 'sent', 'failed')"
+        },
+        "email_send_log_attempt_count_nonnegative_chk": {
+          "name": "email_send_log_attempt_count_nonnegative_chk",
+          "value": "\"email_send_log\".\"attempt_count\" >= 0"
+        },
+        "email_send_log_sent_after_created_chk": {
+          "name": "email_send_log_sent_after_created_chk",
+          "value": "\"email_send_log\".\"sent_at\" is null or \"email_send_log\".\"sent_at\" >= \"email_send_log\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action_url": {
+          "name": "action_url",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "read": {
+          "name": "read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_id_idx": {
+          "name": "notifications_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_user_unread_idx": {
+          "name": "notifications_user_unread_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "read",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_created_at_idx": {
+          "name": "notifications_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "notifications_user_id_users_id_fk": {
+          "name": "notifications_user_id_users_id_fk",
+          "tableFrom": "notifications",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_duplicate_pairs": {
+      "name": "dismissed_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_duplicate_pairs_entity_a_idx": {
+          "name": "dismissed_duplicate_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_duplicate_pairs_entity_b_idx": {
+          "name": "dismissed_duplicate_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_duplicate_pairs_unique": {
+          "name": "dismissed_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_inline_duplicate_pairs": {
+      "name": "dismissed_inline_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_a": {
+          "name": "value_a",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_b": {
+          "name": "value_b",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_inline_pairs_entity_a_idx": {
+          "name": "dismissed_inline_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_inline_pairs_entity_b_idx": {
+          "name": "dismissed_inline_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_inline_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_inline_duplicate_pairs_unique": {
+          "name": "dismissed_inline_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "value_a", "value_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_candidates": {
+      "name": "entity_duplicate_candidates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sim_score": {
+          "name": "sim_score",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "entity_dup_candidates_type_sim_idx": {
+          "name": "entity_dup_candidates_type_sim_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sim_score",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_a_idx": {
+          "name": "entity_dup_candidates_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_b_idx": {
+          "name": "entity_dup_candidates_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "entity_duplicate_candidates_unique": {
+          "name": "entity_duplicate_candidates_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_scan_status": {
+      "name": "entity_duplicate_scan_status",
+      "schema": "",
+      "columns": {
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "is_computing": {
+          "name": "is_computing",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_pairs": {
+          "name": "total_pairs",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "processed_count": {
+          "name": "processed_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_count": {
+          "name": "total_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_fonts": {
+      "name": "user_fonts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "family_name": {
+          "name": "family_name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_file_name": {
+          "name": "original_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stored_file_name": {
+          "name": "stored_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 400
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "uf_user_hash_uidx": {
+          "name": "uf_user_hash_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "uf_user_family_weight_style_uidx": {
+          "name": "uf_user_family_weight_style_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "family_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "weight",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "style",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_fonts_user_id_users_id_fk": {
+          "name": "user_fonts_user_id_users_id_fk",
+          "tableFrom": "user_fonts",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_fonts_format_chk": {
+          "name": "user_fonts_format_chk",
+          "value": "\"user_fonts\".\"format\" in ('ttf', 'otf', 'woff', 'woff2')"
+        },
+        "user_fonts_weight_chk": {
+          "name": "user_fonts_weight_chk",
+          "value": "\"user_fonts\".\"weight\" >= 100 and \"user_fonts\".\"weight\" <= 900 and \"user_fonts\".\"weight\" % 100 = 0"
+        },
+        "user_fonts_style_chk": {
+          "name": "user_fonts_style_chk",
+          "value": "\"user_fonts\".\"style\" in ('normal', 'italic')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_file_chapters": {
+      "name": "book_file_chapters",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "href": {
+          "name": "href",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "spine_index": {
+          "name": "spine_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "book_file_chapters_book_file_id_chapter_index_uidx": {
+          "name": "book_file_chapters_book_file_id_chapter_index_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "chapter_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_chapters_book_file_id_idx": {
+          "name": "book_file_chapters_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_chapters_book_file_id_book_files_id_fk": {
+          "name": "book_file_chapters_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_chapters",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_file_hash_history": {
+      "name": "book_file_hash_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(30)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_file_hash_history_book_file_id_file_hash_idx": {
+          "name": "book_file_hash_history_book_file_id_file_hash_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_hash_history_file_hash_idx": {
+          "name": "book_file_hash_history_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_hash_history_book_file_id_book_files_id_fk": {
+          "name": "book_file_hash_history_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_hash_history",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_file_hash_history_reason_chk": {
+          "name": "book_file_hash_history_reason_chk",
+          "value": "\"book_file_hash_history\".\"reason\" in ('file_write', 'external_change', 'rescan')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_progress": {
+      "name": "koreader_device_progress",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device": {
+          "name": "device",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "progress": {
+          "name": "progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_timestamp": {
+          "name": "sync_timestamp",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "orphaned": {
+          "name": "orphaned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "orphaned_hash": {
+          "name": "orphaned_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_device_progress_book_user_device_uidx": {
+          "name": "koreader_device_progress_book_user_device_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"koreader_device_progress\".\"orphaned\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_orphaned_hash_idx": {
+          "name": "koreader_device_progress_orphaned_hash_idx",
+          "columns": [
+            {
+              "expression": "orphaned_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"orphaned\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_user_updated_at_idx": {
+          "name": "koreader_device_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_book_file_id_idx": {
+          "name": "koreader_device_progress_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"book_file_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_progress_book_file_id_book_files_id_fk": {
+          "name": "koreader_device_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "koreader_device_progress_user_id_users_id_fk": {
+          "name": "koreader_device_progress_user_id_users_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_device_progress_percentage_range_chk": {
+          "name": "koreader_device_progress_percentage_range_chk",
+          "value": "\"koreader_device_progress\".\"percentage\" is null or (\"koreader_device_progress\".\"percentage\" >= 0 and \"koreader_device_progress\".\"percentage\" <= 1)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_sweeps": {
+      "name": "koreader_device_sweeps",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_model": {
+          "name": "device_model",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "plugin_version": {
+          "name": "plugin_version",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_sweep_at": {
+          "name": "last_sweep_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_sweep_books_matched": {
+          "name": "last_sweep_books_matched",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_page_stats": {
+          "name": "last_sweep_page_stats",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_annotations": {
+          "name": "last_sweep_annotations",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kds_user_id_idx": {
+          "name": "kds_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_sweeps_user_id_users_id_fk": {
+          "name": "koreader_device_sweeps_user_id_users_id_fk",
+          "tableFrom": "koreader_device_sweeps",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "koreader_device_sweeps_user_id_device_id_pk": {
+          "name": "koreader_device_sweeps_user_id_device_id_pk",
+          "columns": ["user_id", "device_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.koreader_page_stats": {
+      "name": "koreader_page_stats",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page": {
+          "name": "page",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "total_pages": {
+          "name": "total_pages",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kps_user_file_device_page_start_uidx": {
+          "name": "kps_user_file_device_page_start_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_file_device_start_idx": {
+          "name": "kps_user_file_device_start_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_id_idx": {
+          "name": "kps_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_page_stats_user_id_users_id_fk": {
+          "name": "koreader_page_stats_user_id_users_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "koreader_page_stats_book_file_id_book_files_id_fk": {
+          "name": "koreader_page_stats_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_page_stats_duration_nonnegative_chk": {
+          "name": "koreader_page_stats_duration_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"duration_seconds\" >= 0"
+        },
+        "koreader_page_stats_page_nonnegative_chk": {
+          "name": "koreader_page_stats_page_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"page\" >= 0"
+        },
+        "koreader_page_stats_total_pages_positive_chk": {
+          "name": "koreader_page_stats_total_pages_positive_chk",
+          "value": "\"koreader_page_stats\".\"total_pages\" > 0"
+        },
+        "koreader_page_stats_start_time_positive_chk": {
+          "name": "koreader_page_stats_start_time_positive_chk",
+          "value": "\"koreader_page_stats\".\"start_time\" > 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_users": {
+      "name": "koreader_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_md5": {
+          "name": "password_md5",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_enabled": {
+          "name": "sync_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_users_user_id_uidx": {
+          "name": "koreader_users_user_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_users_username_uidx": {
+          "name": "koreader_users_username_uidx",
+          "columns": [
+            {
+              "expression": "username",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_users_user_id_users_id_fk": {
+          "name": "koreader_users_user_id_users_id_fk",
+          "tableFrom": "koreader_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.achievements": {
+      "name": "achievements",
+      "schema": "",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "varchar(64)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "group_key": {
+          "name": "group_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon_name": {
+          "name": "icon_name",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rarity": {
+          "name": "rarity",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hidden": {
+          "name": "hidden",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "achievements_category_sort_idx": {
+          "name": "achievements_category_sort_idx",
+          "columns": [
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "achievements_group_key_idx": {
+          "name": "achievements_group_key_idx",
+          "columns": [
+            {
+              "expression": "group_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "achievements_category_chk": {
+          "name": "achievements_category_chk",
+          "value": "\"achievements\".\"category\" in ('reading', 'library', 'exploration', 'dedication')"
+        },
+        "achievements_rarity_chk": {
+          "name": "achievements_rarity_chk",
+          "value": "\"achievements\".\"rarity\" in ('common', 'rare', 'epic', 'legendary')"
+        },
+        "achievements_tier_chk": {
+          "name": "achievements_tier_chk",
+          "value": "\"achievements\".\"tier\" is null or (\"achievements\".\"tier\" >= 1 and \"achievements\".\"tier\" <= 4)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_achievements": {
+      "name": "user_achievements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "achievement_key": {
+          "name": "achievement_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "awarded_at": {
+          "name": "awarded_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "context_json": {
+          "name": "context_json",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "user_achievements_user_key_uidx": {
+          "name": "user_achievements_user_key_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "achievement_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_id_idx": {
+          "name": "user_achievements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_awarded_at_idx": {
+          "name": "user_achievements_user_awarded_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "awarded_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_achievements_user_id_users_id_fk": {
+          "name": "user_achievements_user_id_users_id_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_achievements_achievement_key_achievements_key_fk": {
+          "name": "user_achievements_achievement_key_achievements_key_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "achievements",
+          "columnsFrom": ["achievement_key"],
+          "columnsTo": ["key"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_book_state": {
+      "name": "hardcover_book_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hardcover_book_id": {
+          "name": "hardcover_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_edition_id": {
+          "name": "hardcover_edition_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_user_book_id": {
+          "name": "hardcover_user_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_read_id": {
+          "name": "hardcover_read_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_method": {
+          "name": "match_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_error": {
+          "name": "match_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_status": {
+          "name": "last_synced_status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_progress": {
+          "name": "last_synced_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_rating": {
+          "name": "last_synced_rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_started_at": {
+          "name": "last_synced_started_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_finished_at": {
+          "name": "last_synced_finished_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_book_state_user_id_users_id_fk": {
+          "name": "hardcover_book_state_user_id_users_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "hardcover_book_state_book_id_books_id_fk": {
+          "name": "hardcover_book_state_book_id_books_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_book_state_user_book_uidx": {
+          "name": "hardcover_book_state_user_book_uidx",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_user_settings": {
+      "name": "hardcover_user_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "api_token": {
+          "name": "api_token",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_status_change": {
+          "name": "auto_sync_on_status_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_progress_update": {
+          "name": "auto_sync_on_progress_update",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_rating_change": {
+          "name": "auto_sync_on_rating_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "privacy_setting_id": {
+          "name": "privacy_setting_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 3
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_user_settings_user_id_users_id_fk": {
+          "name": "hardcover_user_settings_user_id_users_id_fk",
+          "tableFrom": "hardcover_user_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_user_settings_user_id_unique": {
+          "name": "hardcover_user_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_preferences": {
+      "name": "user_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "up_user_category_idx": {
+          "name": "up_user_category_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_preferences_user_id_users_id_fk": {
+          "name": "user_preferences_user_id_users_id_fk",
+          "tableFrom": "user_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.content_filter_type": {
+      "name": "content_filter_type",
+      "schema": "public",
+      "values": ["include", "exclude"]
+    },
+    "public.library_access_level": {
+      "name": "library_access_level",
+      "schema": "public",
+      "values": ["viewer", "editor", "owner"]
+    },
+    "public.user_avatar_source": {
+      "name": "user_avatar_source",
+      "schema": "public",
+      "values": ["none", "external", "uploaded"]
+    },
+    "public.opds_sort_order": {
+      "name": "opds_sort_order",
+      "schema": "public",
+      "values": ["recent", "title_asc", "title_desc", "author_asc", "author_desc", "series_asc", "series_desc"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/server/src/db/migrations/meta/0030_snapshot.json b/server/src/db/migrations/meta/0030_snapshot.json
new file mode 100644
index 000000000..cf0a05678
--- /dev/null
+++ b/server/src/db/migrations/meta/0030_snapshot.json
@@ -0,0 +1,11403 @@
+{
+  "id": "1ad09390-1ed7-4667-b97c-e93645001b9b",
+  "prevId": "46499b98-ef74-447e-8013-4dab6d018ede",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.audit_log": {
+      "name": "audit_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_username": {
+          "name": "actor_username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "resource": {
+          "name": "resource",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "resource_id": {
+          "name": "resource_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip": {
+          "name": "ip",
+          "type": "varchar(45)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_audit_user_id": {
+          "name": "idx_audit_user_id",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "idx_audit_resource": {
+          "name": "idx_audit_resource",
+          "columns": [
+            {
+              "expression": "resource",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "resource_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "idx_audit_action": {
+          "name": "idx_audit_action",
+          "columns": [
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "idx_audit_ip": {
+          "name": "idx_audit_ip",
+          "columns": [
+            {
+              "expression": "ip",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "idx_audit_created_at": {
+          "name": "idx_audit_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "audit_log_user_id_users_id_fk": {
+          "name": "audit_log_user_id_users_id_fk",
+          "tableFrom": "audit_log",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.app_settings": {
+      "name": "app_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "app_settings_key_unique": {
+          "name": "app_settings_key_unique",
+          "columns": ["key"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.magic_access_tokens": {
+      "name": "magic_access_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "label": {
+          "name": "label",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_token": {
+          "name": "raw_token",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "use_count": {
+          "name": "use_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "magic_access_tokens_user_id_idx": {
+          "name": "magic_access_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "magic_access_tokens_user_id_users_id_fk": {
+          "name": "magic_access_tokens_user_id_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "magic_access_tokens_created_by_users_id_fk": {
+          "name": "magic_access_tokens_created_by_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "columnsFrom": ["created_by"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "magic_access_tokens_token_hash_unique": {
+          "name": "magic_access_tokens_token_hash_unique",
+          "columns": ["token_hash"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "magic_access_tokens_use_count_nonneg_chk": {
+          "name": "magic_access_tokens_use_count_nonneg_chk",
+          "value": "\"magic_access_tokens\".\"use_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "used_at": {
+          "name": "used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "password_reset_tokens_user_id_idx": {
+          "name": "password_reset_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "password_reset_tokens_expires_at_idx": {
+          "name": "password_reset_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "password_reset_tokens_user_id_users_id_fk": {
+          "name": "password_reset_tokens_user_id_users_id_fk",
+          "tableFrom": "password_reset_tokens",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "password_reset_tokens_token_hash_unique": {
+          "name": "password_reset_tokens_token_hash_unique",
+          "columns": ["token_hash"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "password_reset_tokens_expires_after_created_chk": {
+          "name": "password_reset_tokens_expires_after_created_chk",
+          "value": "\"password_reset_tokens\".\"expires_at\" > \"password_reset_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.refresh_tokens": {
+      "name": "refresh_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rotated_at": {
+          "name": "rotated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replaced_by_token_hash": {
+          "name": "replaced_by_token_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_user_id_idx": {
+          "name": "refresh_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "refresh_tokens_expires_at_idx": {
+          "name": "refresh_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "refresh_tokens_token_hash_unique": {
+          "name": "refresh_tokens_token_hash_unique",
+          "columns": ["token_hash"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "refresh_tokens_expires_after_created_chk": {
+          "name": "refresh_tokens_expires_after_created_chk",
+          "value": "\"refresh_tokens\".\"expires_at\" > \"refresh_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_genres": {
+      "name": "user_content_filter_genres",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_genres_genre_id_idx": {
+          "name": "user_content_filter_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_genres_user_id_users_id_fk": {
+          "name": "user_content_filter_genres_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_content_filter_genres_genre_id_genres_id_fk": {
+          "name": "user_content_filter_genres_genre_id_genres_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "columnsFrom": ["genre_id"],
+          "tableTo": "genres",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_genres_user_id_filter_type_genre_id_pk": {
+          "name": "user_content_filter_genres_user_id_filter_type_genre_id_pk",
+          "columns": ["user_id", "filter_type", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_tags": {
+      "name": "user_content_filter_tags",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_tags_tag_id_idx": {
+          "name": "user_content_filter_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_tags_user_id_users_id_fk": {
+          "name": "user_content_filter_tags_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_content_filter_tags_tag_id_tags_id_fk": {
+          "name": "user_content_filter_tags_tag_id_tags_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "columnsFrom": ["tag_id"],
+          "tableTo": "tags",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_tags_user_id_filter_type_tag_id_pk": {
+          "name": "user_content_filter_tags_user_id_filter_type_tag_id_pk",
+          "columns": ["user_id", "filter_type", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_library_access": {
+      "name": "user_library_access",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_level": {
+          "name": "access_level",
+          "type": "library_access_level",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        }
+      },
+      "indexes": {
+        "user_library_access_library_user_idx": {
+          "name": "user_library_access_library_user_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_library_access_user_id_users_id_fk": {
+          "name": "user_library_access_user_id_users_id_fk",
+          "tableFrom": "user_library_access",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_library_access_library_id_libraries_id_fk": {
+          "name": "user_library_access_library_id_libraries_id_fk",
+          "tableFrom": "user_library_access",
+          "columnsFrom": ["library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_library_access_user_id_library_id_pk": {
+          "name": "user_library_access_user_id_library_id_pk",
+          "columns": ["user_id", "library_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_permissions": {
+      "name": "user_permissions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_permissions_user_id_users_id_fk": {
+          "name": "user_permissions_user_id_users_id_fk",
+          "tableFrom": "user_permissions",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_permissions_user_id_permission_name_pk": {
+          "name": "user_permissions_user_id_permission_name_pk",
+          "columns": ["user_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_superuser": {
+          "name": "is_superuser",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_default_password": {
+          "name": "is_default_password",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "token_version": {
+          "name": "token_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "failed_login_attempts": {
+          "name": "failed_login_attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "locked_until": {
+          "name": "locked_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_source": {
+          "name": "avatar_source",
+          "type": "user_avatar_source",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'none'"
+        },
+        "avatar_version": {
+          "name": "avatar_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "provisioning_method": {
+          "name": "provisioning_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'local'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "users_username_lower_uidx": {
+          "name": "users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "users_email_lower_uidx": {
+          "name": "users_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"email\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"users\".\"email\" is not null",
+          "concurrently": false
+        },
+        "users_oidc_subject_issuer_uidx": {
+          "name": "users_oidc_subject_issuer_uidx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"users\".\"oidc_subject\" is not null and \"users\".\"oidc_issuer\" is not null",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "columns": ["username"],
+          "nullsNotDistinct": false
+        },
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": ["email"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "users_provisioning_method_chk": {
+          "name": "users_provisioning_method_chk",
+          "value": "\"users\".\"provisioning_method\" in ('local', 'manual', 'oidc', 'shared')"
+        },
+        "users_token_version_nonnegative_chk": {
+          "name": "users_token_version_nonnegative_chk",
+          "value": "\"users\".\"token_version\" >= 0"
+        },
+        "users_failed_login_attempts_nonnegative_chk": {
+          "name": "users_failed_login_attempts_nonnegative_chk",
+          "value": "\"users\".\"failed_login_attempts\" >= 0"
+        },
+        "users_avatar_version_nonnegative_chk": {
+          "name": "users_avatar_version_nonnegative_chk",
+          "value": "\"users\".\"avatar_version\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.comic_metadata": {
+      "name": "comic_metadata",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issue_number": {
+          "name": "issue_number",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "volume_name": {
+          "name": "volume_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pencillers": {
+          "name": "pencillers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "inkers": {
+          "name": "inkers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "colorists": {
+          "name": "colorists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "letterers": {
+          "name": "letterers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_artists": {
+          "name": "cover_artists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "characters": {
+          "name": "characters",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "teams": {
+          "name": "teams",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locations": {
+          "name": "locations",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "story_arcs": {
+          "name": "story_arcs",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comic_metadata_book_id_books_id_fk": {
+          "name": "comic_metadata_book_id_books_id_fk",
+          "tableFrom": "comic_metadata",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comic_metadata_book_id_unique": {
+          "name": "comic_metadata_book_id_unique",
+          "columns": ["book_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_plan_artifacts": {
+      "name": "migration_plan_artifacts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_snapshot_hash": {
+          "name": "source_snapshot_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_hash": {
+          "name": "profile_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_hash": {
+          "name": "plan_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan": {
+          "name": "plan",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_plan_artifacts_plan_hash_uidx": {
+          "name": "migration_plan_artifacts_plan_hash_uidx",
+          "columns": [
+            {
+              "expression": "plan_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_plan_artifacts_source_id_idx": {
+          "name": "migration_plan_artifacts_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_plan_artifacts_profile_id_idx": {
+          "name": "migration_plan_artifacts_profile_id_idx",
+          "columns": [
+            {
+              "expression": "profile_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "migration_plan_artifacts_source_id_migration_sources_id_fk": {
+          "name": "migration_plan_artifacts_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "columnsFrom": ["source_id"],
+          "tableTo": "migration_sources",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "migration_plan_artifacts_profile_id_migration_profiles_id_fk": {
+          "name": "migration_plan_artifacts_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "columnsFrom": ["profile_id"],
+          "tableTo": "migration_profiles",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "migration_plan_artifacts_created_by_user_id_users_id_fk": {
+          "name": "migration_plan_artifacts_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "columnsFrom": ["created_by_user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "migration_plan_artifacts_profile_source_fk": {
+          "name": "migration_plan_artifacts_profile_source_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "columnsFrom": ["profile_id", "source_id"],
+          "tableTo": "migration_profiles",
+          "columnsTo": ["id", "source_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_plan_artifacts_id_source_profile_unique": {
+          "name": "migration_plan_artifacts_id_source_profile_unique",
+          "columns": ["id", "source_id", "profile_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_profiles": {
+      "name": "migration_profiles",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "user_mappings": {
+          "name": "user_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path_mappings": {
+          "name": "path_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_profiles_source_name_version_uidx": {
+          "name": "migration_profiles_source_name_version_uidx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "version",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_profiles_source_id_idx": {
+          "name": "migration_profiles_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "migration_profiles_source_id_migration_sources_id_fk": {
+          "name": "migration_profiles_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_profiles",
+          "columnsFrom": ["source_id"],
+          "tableTo": "migration_sources",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "migration_profiles_created_by_user_id_users_id_fk": {
+          "name": "migration_profiles_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_profiles",
+          "columnsFrom": ["created_by_user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_profiles_id_source_id_unique": {
+          "name": "migration_profiles_id_source_id_unique",
+          "columns": ["id", "source_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "migration_profiles_version_positive_chk": {
+          "name": "migration_profiles_version_positive_chk",
+          "value": "\"migration_profiles\".\"version\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_run_metrics": {
+      "name": "migration_run_metrics",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stage": {
+          "name": "stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "processed": {
+          "name": "processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "imported": {
+          "name": "imported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "skipped": {
+          "name": "skipped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "unresolved": {
+          "name": "unresolved",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "failed": {
+          "name": "failed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_run_metrics_run_stage_entity_uidx": {
+          "name": "migration_run_metrics_run_stage_entity_uidx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "stage",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_run_metrics_run_id_idx": {
+          "name": "migration_run_metrics_run_id_idx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "migration_run_metrics_run_id_migration_runs_id_fk": {
+          "name": "migration_run_metrics_run_id_migration_runs_id_fk",
+          "tableFrom": "migration_run_metrics",
+          "columnsFrom": ["run_id"],
+          "tableTo": "migration_runs",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_run_metrics_processed_nonnegative_chk": {
+          "name": "migration_run_metrics_processed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"processed\" >= 0"
+        },
+        "migration_run_metrics_imported_nonnegative_chk": {
+          "name": "migration_run_metrics_imported_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"imported\" >= 0"
+        },
+        "migration_run_metrics_skipped_nonnegative_chk": {
+          "name": "migration_run_metrics_skipped_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"skipped\" >= 0"
+        },
+        "migration_run_metrics_unresolved_nonnegative_chk": {
+          "name": "migration_run_metrics_unresolved_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"unresolved\" >= 0"
+        },
+        "migration_run_metrics_failed_nonnegative_chk": {
+          "name": "migration_run_metrics_failed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"failed\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_runs": {
+      "name": "migration_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_artifact_id": {
+          "name": "plan_artifact_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_key": {
+          "name": "target_key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'bookorbit'"
+        },
+        "state": {
+          "name": "state",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "current_stage": {
+          "name": "current_stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by_user_id": {
+          "name": "triggered_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_runs_source_target_state_idx": {
+          "name": "migration_runs_source_target_state_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "target_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_runs_state_idx": {
+          "name": "migration_runs_state_idx",
+          "columns": [
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "migration_runs_source_id_migration_sources_id_fk": {
+          "name": "migration_runs_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["source_id"],
+          "tableTo": "migration_sources",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "migration_runs_profile_id_migration_profiles_id_fk": {
+          "name": "migration_runs_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["profile_id"],
+          "tableTo": "migration_profiles",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk": {
+          "name": "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["plan_artifact_id"],
+          "tableTo": "migration_plan_artifacts",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "migration_runs_triggered_by_user_id_users_id_fk": {
+          "name": "migration_runs_triggered_by_user_id_users_id_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["triggered_by_user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "migration_runs_profile_source_fk": {
+          "name": "migration_runs_profile_source_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["profile_id", "source_id"],
+          "tableTo": "migration_profiles",
+          "columnsTo": ["id", "source_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        },
+        "migration_runs_plan_artifact_source_profile_fk": {
+          "name": "migration_runs_plan_artifact_source_profile_fk",
+          "tableFrom": "migration_runs",
+          "columnsFrom": ["plan_artifact_id", "source_id", "profile_id"],
+          "tableTo": "migration_plan_artifacts",
+          "columnsTo": ["id", "source_id", "profile_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        },
+        "migration_runs_started_before_ended_chk": {
+          "name": "migration_runs_started_before_ended_chk",
+          "value": "\"migration_runs\".\"ended_at\" is null or \"migration_runs\".\"started_at\" is null or \"migration_runs\".\"ended_at\" >= \"migration_runs\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_sources": {
+      "name": "migration_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_config": {
+          "name": "connection_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "capabilities": {
+          "name": "capabilities",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_validated_at": {
+          "name": "last_validated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_sources_type_name_uidx": {
+          "name": "migration_sources_type_name_uidx",
+          "columns": [
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "migration_sources_created_by_user_id_users_id_fk": {
+          "name": "migration_sources_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_sources",
+          "columnsFrom": ["created_by_user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.libraries": {
+      "name": "libraries",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cover_aspect_ratio": {
+          "name": "cover_aspect_ratio",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'2/3'"
+        },
+        "watch": {
+          "name": "watch",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "auto_scan_cron_expression": {
+          "name": "auto_scan_cron_expression",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_precedence": {
+          "name": "metadata_precedence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"folderStructure\",\"embedded\",\"nfoFile\",\"opfFile\",\"sidecar\"]'::jsonb"
+        },
+        "format_priority": {
+          "name": "format_priority",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"epub\",\"pdf\",\"cbz\",\"cbr\",\"cb7\",\"mobi\",\"azw3\",\"azw\",\"fb2\",\"m4b\",\"mp3\",\"m4a\",\"opus\",\"ogg\",\"flac\"]'::jsonb"
+        },
+        "allowed_formats": {
+          "name": "allowed_formats",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "organization_mode": {
+          "name": "organization_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'book_per_folder'"
+        },
+        "exclude_patterns": {
+          "name": "exclude_patterns",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "double precision",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0.25
+        },
+        "mark_as_finished_percent_complete": {
+          "name": "mark_as_finished_percent_complete",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 98
+        },
+        "file_write_enabled": {
+          "name": "file_write_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_write_cover": {
+          "name": "file_write_write_cover",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_enabled": {
+          "name": "file_write_epub_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_max_file_size_mb": {
+          "name": "file_write_epub_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_pdf_enabled": {
+          "name": "file_write_pdf_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_pdf_max_file_size_mb": {
+          "name": "file_write_pdf_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_cbx_enabled": {
+          "name": "file_write_cbx_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_cbx_max_file_size_mb": {
+          "name": "file_write_cbx_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_write_audio_enabled": {
+          "name": "file_write_audio_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_audio_max_file_size_mb": {
+          "name": "file_write_audio_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_rename_enabled": {
+          "name": "file_rename_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_naming_pattern": {
+          "name": "file_naming_pattern",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_fetch_preferences": {
+          "name": "metadata_fetch_preferences",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_config": {
+          "name": "book_metadata_fetch_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_run_at": {
+          "name": "book_metadata_fetch_last_run_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_queued_count": {
+          "name": "book_metadata_fetch_last_queued_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scan_mode": {
+          "name": "scan_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "poll_interval_seconds": {
+          "name": "poll_interval_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "default": 300
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "libraries_name_lower_uidx": {
+          "name": "libraries_name_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "libraries_display_order_nonnegative_chk": {
+          "name": "libraries_display_order_nonnegative_chk",
+          "value": "\"libraries\".\"display_order\" >= 0"
+        },
+        "libraries_organization_mode_chk": {
+          "name": "libraries_organization_mode_chk",
+          "value": "\"libraries\".\"organization_mode\" in ('book_per_folder', 'book_per_file')"
+        },
+        "libraries_reading_threshold_range_chk": {
+          "name": "libraries_reading_threshold_range_chk",
+          "value": "\"libraries\".\"reading_threshold\" >= 0 and \"libraries\".\"reading_threshold\" <= 100"
+        },
+        "libraries_mark_finished_percent_range_chk": {
+          "name": "libraries_mark_finished_percent_range_chk",
+          "value": "\"libraries\".\"mark_as_finished_percent_complete\" >= 0 and \"libraries\".\"mark_as_finished_percent_complete\" <= 100"
+        },
+        "libraries_scan_mode_chk": {
+          "name": "libraries_scan_mode_chk",
+          "value": "\"libraries\".\"scan_mode\" in ('auto', 'manual')"
+        },
+        "libraries_poll_interval_nonnegative_chk": {
+          "name": "libraries_poll_interval_nonnegative_chk",
+          "value": "\"libraries\".\"poll_interval_seconds\" is null or \"libraries\".\"poll_interval_seconds\" >= 0"
+        },
+        "libraries_file_write_epub_max_size_chk": {
+          "name": "libraries_file_write_epub_max_size_chk",
+          "value": "\"libraries\".\"file_write_epub_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_pdf_max_size_chk": {
+          "name": "libraries_file_write_pdf_max_size_chk",
+          "value": "\"libraries\".\"file_write_pdf_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_cbx_max_size_chk": {
+          "name": "libraries_file_write_cbx_max_size_chk",
+          "value": "\"libraries\".\"file_write_cbx_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_audio_max_size_chk": {
+          "name": "libraries_file_write_audio_max_size_chk",
+          "value": "\"libraries\".\"file_write_audio_max_file_size_mb\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.library_folders": {
+      "name": "library_folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "library_folders_library_id_idx": {
+          "name": "library_folders_library_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "library_folders_library_path_uidx": {
+          "name": "library_folders_library_path_uidx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "library_folders_library_id_libraries_id_fk": {
+          "name": "library_folders_library_id_libraries_id_fk",
+          "tableFrom": "library_folders",
+          "columnsFrom": ["library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "library_folders_id_library_id_unique": {
+          "name": "library_folders_id_library_id_unique",
+          "columns": ["id", "library_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_files": {
+      "name": "book_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rel_path": {
+          "name": "rel_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ino": {
+          "name": "ino",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "mtime": {
+          "name": "mtime",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'content'"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_files_absolute_path_uidx": {
+          "name": "book_files_absolute_path_uidx",
+          "columns": [
+            {
+              "expression": "absolute_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_book_id_idx": {
+          "name": "book_files_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_library_folder_id_idx": {
+          "name": "book_files_library_folder_id_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_file_hash_idx": {
+          "name": "book_files_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_ino_idx": {
+          "name": "book_files_ino_idx",
+          "columns": [
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_format_idx": {
+          "name": "book_files_format_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_library_folder_file_hash_idx": {
+          "name": "book_files_library_folder_file_hash_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_files_library_folder_ino_idx": {
+          "name": "book_files_library_folder_ino_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_files_book_id_books_id_fk": {
+          "name": "book_files_book_id_books_id_fk",
+          "tableFrom": "book_files",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_files_library_folder_id_library_folders_id_fk": {
+          "name": "book_files_library_folder_id_library_folders_id_fk",
+          "tableFrom": "book_files",
+          "columnsFrom": ["library_folder_id"],
+          "tableTo": "library_folders",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_files_book_folder_consistency_fk": {
+          "name": "book_files_book_folder_consistency_fk",
+          "tableFrom": "book_files",
+          "columnsFrom": ["book_id", "library_folder_id"],
+          "tableTo": "books",
+          "columnsTo": ["id", "library_folder_id"],
+          "onUpdate": "cascade",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_files_role_chk": {
+          "name": "book_files_role_chk",
+          "value": "\"book_files\".\"role\" in ('content', 'cover', 'metadata', 'supplement')"
+        },
+        "book_files_size_bytes_nonnegative_chk": {
+          "name": "book_files_size_bytes_nonnegative_chk",
+          "value": "\"book_files\".\"size_bytes\" is null or \"book_files\".\"size_bytes\" >= 0"
+        },
+        "book_files_duration_seconds_nonnegative_chk": {
+          "name": "book_files_duration_seconds_nonnegative_chk",
+          "value": "\"book_files\".\"duration_seconds\" is null or \"book_files\".\"duration_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.books": {
+      "name": "books",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "primary_file_id": {
+          "name": "primary_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_path": {
+          "name": "folder_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'present'"
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "books_library_id_folder_path_idx": {
+          "name": "books_library_id_folder_path_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "books_primary_file_id_idx": {
+          "name": "books_primary_file_id_idx",
+          "columns": [
+            {
+              "expression": "primary_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "books_library_status_idx": {
+          "name": "books_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "books_library_added_at_idx": {
+          "name": "books_library_added_at_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "books_library_id_libraries_id_fk": {
+          "name": "books_library_id_libraries_id_fk",
+          "tableFrom": "books",
+          "columnsFrom": ["library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "books_library_folder_id_library_folders_id_fk": {
+          "name": "books_library_folder_id_library_folders_id_fk",
+          "tableFrom": "books",
+          "columnsFrom": ["library_folder_id"],
+          "tableTo": "library_folders",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "books_primary_file_id_book_files_id_fk": {
+          "name": "books_primary_file_id_book_files_id_fk",
+          "tableFrom": "books",
+          "columnsFrom": ["primary_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "books_library_folder_library_fk": {
+          "name": "books_library_folder_library_fk",
+          "tableFrom": "books",
+          "columnsFrom": ["library_folder_id", "library_id"],
+          "tableTo": "library_folders",
+          "columnsTo": ["id", "library_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "books_id_library_folder_id_unique": {
+          "name": "books_id_library_folder_id_unique",
+          "columns": ["id", "library_folder_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "books_status_chk": {
+          "name": "books_status_chk",
+          "value": "\"books\".\"status\" in ('present', 'missing', 'processing')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.collection_books": {
+      "name": "collection_books",
+      "schema": "",
+      "columns": {
+        "collection_id": {
+          "name": "collection_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collection_books_book_id_idx": {
+          "name": "collection_books_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "collection_books_collection_id_collections_id_fk": {
+          "name": "collection_books_collection_id_collections_id_fk",
+          "tableFrom": "collection_books",
+          "columnsFrom": ["collection_id"],
+          "tableTo": "collections",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "collection_books_book_id_books_id_fk": {
+          "name": "collection_books_book_id_books_id_fk",
+          "tableFrom": "collection_books",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "collection_books_collection_id_book_id_pk": {
+          "name": "collection_books_collection_id_book_id_pk",
+          "columns": ["collection_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.collections": {
+      "name": "collections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_to_kobo": {
+          "name": "sync_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collections_user_name_uidx": {
+          "name": "collections_user_name_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "collections_user_display_name_idx": {
+          "name": "collections_user_display_name_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "collections_user_id_users_id_fk": {
+          "name": "collections_user_id_users_id_fk",
+          "tableFrom": "collections",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.smart_scopes": {
+      "name": "smart_scopes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "filter": {
+          "name": "filter",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_sort": {
+          "name": "default_sort",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "smart_scopes_user_id_users_id_fk": {
+          "name": "smart_scopes_user_id_users_id_fk",
+          "tableFrom": "smart_scopes",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "smart_scopes_user_id_name_unique": {
+          "name": "smart_scopes_user_id_name_unique",
+          "columns": ["user_id", "name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series": {
+      "name": "book_series",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "normalized_name": {
+          "name": "normalized_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_normalized_name_uidx": {
+          "name": "book_series_normalized_name_uidx",
+          "columns": [
+            {
+              "expression": "normalized_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_series_name_trgm_idx": {
+          "name": "book_series_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        },
+        "book_series_name_lower_idx": {
+          "name": "book_series_name_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.author_enrichment_queue": {
+      "name": "author_enrichment_queue",
+      "schema": "",
+      "columns": {
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unknown'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_success_at": {
+          "name": "last_success_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "author_enrichment_queue_status_next_attempt_idx": {
+          "name": "author_enrichment_queue_status_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "author_enrichment_queue_next_attempt_idx": {
+          "name": "author_enrichment_queue_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "author_enrichment_queue_single_processing_idx": {
+          "name": "author_enrichment_queue_single_processing_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"author_enrichment_queue\".\"status\" = 'processing'",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "author_enrichment_queue_author_id_authors_id_fk": {
+          "name": "author_enrichment_queue_author_id_authors_id_fk",
+          "tableFrom": "author_enrichment_queue",
+          "columnsFrom": ["author_id"],
+          "tableTo": "authors",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "author_enrichment_queue_status_chk": {
+          "name": "author_enrichment_queue_status_chk",
+          "value": "\"author_enrichment_queue\".\"status\" in ('queued', 'processing', 'rate_limited', 'failed', 'done')"
+        },
+        "author_enrichment_queue_reason_chk": {
+          "name": "author_enrichment_queue_reason_chk",
+          "value": "\"author_enrichment_queue\".\"reason\" in ('unknown', 'metadata_replace', 'manual_backfill', 'manual_backfill_all', 'author_rename', 'author_merge_target')"
+        },
+        "author_enrichment_queue_attempt_count_nonnegative_chk": {
+          "name": "author_enrichment_queue_attempt_count_nonnegative_chk",
+          "value": "\"author_enrichment_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.authors": {
+      "name": "authors",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_photo": {
+          "name": "has_photo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "last_enriched_at": {
+          "name": "last_enriched_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "authors_name_trgm_idx": {
+          "name": "authors_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "authors_name_unique": {
+          "name": "authors_name_unique",
+          "columns": ["name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_authors": {
+      "name": "book_authors",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_authors_author_id_idx": {
+          "name": "book_authors_author_id_idx",
+          "columns": [
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_authors_book_display_idx": {
+          "name": "book_authors_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_authors_book_id_books_id_fk": {
+          "name": "book_authors_book_id_books_id_fk",
+          "tableFrom": "book_authors",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_authors_author_id_authors_id_fk": {
+          "name": "book_authors_author_id_authors_id_fk",
+          "tableFrom": "book_authors",
+          "columnsFrom": ["author_id"],
+          "tableTo": "authors",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_authors_book_id_author_id_pk": {
+          "name": "book_authors_book_id_author_id_pk",
+          "columns": ["book_id", "author_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_genres": {
+      "name": "book_genres",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_genres_genre_id_idx": {
+          "name": "book_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_genres_book_id_books_id_fk": {
+          "name": "book_genres_book_id_books_id_fk",
+          "tableFrom": "book_genres",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_genres_genre_id_genres_id_fk": {
+          "name": "book_genres_genre_id_genres_id_fk",
+          "tableFrom": "book_genres",
+          "columnsFrom": ["genre_id"],
+          "tableTo": "genres",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_genres_book_id_genre_id_pk": {
+          "name": "book_genres_book_id_genre_id_pk",
+          "columns": ["book_id", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_metadata": {
+      "name": "book_metadata",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subtitle": {
+          "name": "subtitle",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn10": {
+          "name": "isbn10",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn13": {
+          "name": "isbn13",
+          "type": "varchar(13)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "publisher": {
+          "name": "publisher",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_year": {
+          "name": "published_year",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "language": {
+          "name": "language",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_count": {
+          "name": "page_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_name": {
+          "name": "series_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_source": {
+          "name": "cover_source",
+          "type": "varchar(9)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "google_books_id": {
+          "name": "google_books_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "goodreads_id": {
+          "name": "goodreads_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "amazon_id": {
+          "name": "amazon_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_id": {
+          "name": "hardcover_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "open_library_id": {
+          "name": "open_library_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "itunes_id": {
+          "name": "itunes_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_id": {
+          "name": "kobo_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_score": {
+          "name": "metadata_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_metadata_fetch_at": {
+          "name": "last_metadata_fetch_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(256)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_written_at": {
+          "name": "last_written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "abridged": {
+          "name": "abridged",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "audible_id": {
+          "name": "audible_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "comicvine_id": {
+          "name": "comicvine_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ranobedb_id": {
+          "name": "ranobedb_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapters": {
+          "name": "chapters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locked_fields": {
+          "name": "locked_fields",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bm_title_trgm_idx": {
+          "name": "bm_title_trgm_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        },
+        "bm_title_lower_idx": {
+          "name": "bm_title_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"title\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_series_trgm_idx": {
+          "name": "bm_series_trgm_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        },
+        "bm_series_id_idx": {
+          "name": "bm_series_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_series_name_lower_btrim_idx": {
+          "name": "bm_series_name_lower_btrim_idx",
+          "columns": [
+            {
+              "expression": "lower(btrim(\"series_name\"))",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_publisher_trgm_idx": {
+          "name": "bm_publisher_trgm_idx",
+          "columns": [
+            {
+              "expression": "publisher",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        },
+        "bm_language_idx": {
+          "name": "bm_language_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_language_trgm_idx": {
+          "name": "bm_language_trgm_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        },
+        "bm_published_year_idx": {
+          "name": "bm_published_year_idx",
+          "columns": [
+            {
+              "expression": "published_year",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_series_name_index_idx": {
+          "name": "bm_series_name_index_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_isbn10_idx": {
+          "name": "bm_isbn10_idx",
+          "columns": [
+            {
+              "expression": "isbn10",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_isbn13_idx": {
+          "name": "bm_isbn13_idx",
+          "columns": [
+            {
+              "expression": "isbn13",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bm_embedding_hnsw_cosine_idx": {
+          "name": "bm_embedding_hnsw_cosine_idx",
+          "columns": [
+            {
+              "expression": "\"embedding\" vector_cosine_ops",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "hnsw",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_book_id_books_id_fk": {
+          "name": "book_metadata_book_id_books_id_fk",
+          "tableFrom": "book_metadata",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_metadata_series_id_book_series_id_fk": {
+          "name": "book_metadata_series_id_book_series_id_fk",
+          "tableFrom": "book_metadata",
+          "columnsFrom": ["series_id"],
+          "tableTo": "book_series",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_rating_range_chk": {
+          "name": "book_metadata_rating_range_chk",
+          "value": "\"book_metadata\".\"rating\" is null or (\"book_metadata\".\"rating\" >= 1 and \"book_metadata\".\"rating\" <= 10)"
+        },
+        "book_metadata_published_year_range_chk": {
+          "name": "book_metadata_published_year_range_chk",
+          "value": "\"book_metadata\".\"published_year\" is null or (\"book_metadata\".\"published_year\" >= 1000 and \"book_metadata\".\"published_year\" <= 2200)"
+        },
+        "book_metadata_page_count_nonnegative_chk": {
+          "name": "book_metadata_page_count_nonnegative_chk",
+          "value": "\"book_metadata\".\"page_count\" is null or \"book_metadata\".\"page_count\" >= 0"
+        },
+        "book_metadata_duration_seconds_nonnegative_chk": {
+          "name": "book_metadata_duration_seconds_nonnegative_chk",
+          "value": "\"book_metadata\".\"duration_seconds\" is null or \"book_metadata\".\"duration_seconds\" >= 0"
+        },
+        "book_metadata_cover_source_chk": {
+          "name": "book_metadata_cover_source_chk",
+          "value": "\"book_metadata\".\"cover_source\" is null or \"book_metadata\".\"cover_source\" in ('extracted', 'custom')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_metadata_fetch_queue": {
+      "name": "book_metadata_fetch_queue",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'manual_trigger'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bmfq_status_idx": {
+          "name": "bmfq_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bmfq_created_at_idx": {
+          "name": "bmfq_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bmfq_status_created_book_idx": {
+          "name": "bmfq_status_created_book_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_fetch_queue_book_id_books_id_fk": {
+          "name": "book_metadata_fetch_queue_book_id_books_id_fk",
+          "tableFrom": "book_metadata_fetch_queue",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_fetch_queue_status_chk": {
+          "name": "book_metadata_fetch_queue_status_chk",
+          "value": "\"book_metadata_fetch_queue\".\"status\" in ('queued', 'processing', 'failed')"
+        },
+        "book_metadata_fetch_queue_reason_chk": {
+          "name": "book_metadata_fetch_queue_reason_chk",
+          "value": "\"book_metadata_fetch_queue\".\"reason\" in ('event_import', 'manual_trigger', 'manual_retry')"
+        },
+        "book_metadata_fetch_queue_attempt_count_nonnegative_chk": {
+          "name": "book_metadata_fetch_queue_attempt_count_nonnegative_chk",
+          "value": "\"book_metadata_fetch_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_tags": {
+      "name": "book_tags",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_tags_tag_id_idx": {
+          "name": "book_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_tags_book_id_books_id_fk": {
+          "name": "book_tags_book_id_books_id_fk",
+          "tableFrom": "book_tags",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_tags_tag_id_tags_id_fk": {
+          "name": "book_tags_tag_id_tags_id_fk",
+          "tableFrom": "book_tags",
+          "columnsFrom": ["tag_id"],
+          "tableTo": "tags",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_tags_book_id_tag_id_pk": {
+          "name": "book_tags_book_id_tag_id_pk",
+          "columns": ["book_id", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.genres": {
+      "name": "genres",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "genres_name_trgm_idx": {
+          "name": "genres_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "genres_name_unique": {
+          "name": "genres_name_unique",
+          "columns": ["name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.tags": {
+      "name": "tags",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "tags_name_trgm_idx": {
+          "name": "tags_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "tags_name_unique": {
+          "name": "tags_name_unique",
+          "columns": ["name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_narrators": {
+      "name": "book_narrators",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "narrator_id": {
+          "name": "narrator_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_narrators_narrator_id_idx": {
+          "name": "book_narrators_narrator_id_idx",
+          "columns": [
+            {
+              "expression": "narrator_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_narrators_book_id_books_id_fk": {
+          "name": "book_narrators_book_id_books_id_fk",
+          "tableFrom": "book_narrators",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "book_narrators_narrator_id_narrators_id_fk": {
+          "name": "book_narrators_narrator_id_narrators_id_fk",
+          "tableFrom": "book_narrators",
+          "columnsFrom": ["narrator_id"],
+          "tableTo": "narrators",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_narrators_book_id_narrator_id_pk": {
+          "name": "book_narrators_book_id_narrator_id_pk",
+          "columns": ["book_id", "narrator_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.narrators": {
+      "name": "narrators",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "narrators_name_trgm_idx": {
+          "name": "narrators_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "gin",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "narrators_name_unique": {
+          "name": "narrators_name_unique",
+          "columns": ["name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.library_dir_scan_state": {
+      "name": "library_dir_scan_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dir_path": {
+          "name": "dir_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_mtime_ms": {
+          "name": "last_seen_mtime_ms",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "library_dir_scan_state_folder_dir_uidx": {
+          "name": "library_dir_scan_state_folder_dir_uidx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "dir_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "library_dir_scan_state_folder_idx": {
+          "name": "library_dir_scan_state_folder_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "library_dir_scan_state_library_folder_id_library_folders_id_fk": {
+          "name": "library_dir_scan_state_library_folder_id_library_folders_id_fk",
+          "tableFrom": "library_dir_scan_state",
+          "columnsFrom": ["library_folder_id"],
+          "tableTo": "library_folders",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.scan_jobs": {
+      "name": "scan_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'running'"
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_count": {
+          "name": "added_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_count": {
+          "name": "updated_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "missing_count": {
+          "name": "missing_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "scan_jobs_library_status_idx": {
+          "name": "scan_jobs_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "scan_jobs_library_id_libraries_id_fk": {
+          "name": "scan_jobs_library_id_libraries_id_fk",
+          "tableFrom": "scan_jobs",
+          "columnsFrom": ["library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "scan_jobs_status_chk": {
+          "name": "scan_jobs_status_chk",
+          "value": "\"scan_jobs\".\"status\" in ('running', 'completed', 'failed')"
+        },
+        "scan_jobs_triggered_by_chk": {
+          "name": "scan_jobs_triggered_by_chk",
+          "value": "\"scan_jobs\".\"triggered_by\" in ('manual', 'watcher', 'schedule')"
+        },
+        "scan_jobs_added_count_nonnegative_chk": {
+          "name": "scan_jobs_added_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"added_count\" >= 0"
+        },
+        "scan_jobs_updated_count_nonnegative_chk": {
+          "name": "scan_jobs_updated_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"updated_count\" >= 0"
+        },
+        "scan_jobs_missing_count_nonnegative_chk": {
+          "name": "scan_jobs_missing_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"missing_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_positions": {
+      "name": "annotation_positions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(12)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pos0": {
+          "name": "pos0",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pos1": {
+          "name": "pos1",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'exact'"
+        },
+        "converter_version": {
+          "name": "converter_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "extras": {
+          "name": "extras",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_positions_annotation_format_uidx": {
+          "name": "annotation_positions_annotation_format_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotation_positions_user_idx": {
+          "name": "annotation_positions_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotation_positions_format_status_idx": {
+          "name": "annotation_positions_format_status_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "annotation_positions_annotation_id_annotations_id_fk": {
+          "name": "annotation_positions_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_positions",
+          "columnsFrom": ["annotation_id"],
+          "tableTo": "annotations",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "annotation_positions_user_id_users_id_fk": {
+          "name": "annotation_positions_user_id_users_id_fk",
+          "tableFrom": "annotation_positions",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "annotation_positions_book_file_id_book_files_id_fk": {
+          "name": "annotation_positions_book_file_id_book_files_id_fk",
+          "tableFrom": "annotation_positions",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_positions_format_chk": {
+          "name": "annotation_positions_format_chk",
+          "value": "\"annotation_positions\".\"format\" in ('cfi', 'xpointer', 'pdf', 'kobo_span')"
+        },
+        "annotation_positions_status_chk": {
+          "name": "annotation_positions_status_chk",
+          "value": "\"annotation_positions\".\"status\" in ('exact', 'repaired', 'failed', 'pending')"
+        },
+        "annotation_positions_pos0_chk": {
+          "name": "annotation_positions_pos0_chk",
+          "value": "\"annotation_positions\".\"status\" in ('failed', 'pending') or \"annotation_positions\".\"pos0\" is not null"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_sync_state": {
+      "name": "annotation_sync_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_key": {
+          "name": "external_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_created_at": {
+          "name": "external_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_applied_version": {
+          "name": "last_applied_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "delete_acked_at": {
+          "name": "delete_acked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_synced_at": {
+          "name": "first_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_sync_state_annotation_source_device_uidx": {
+          "name": "annotation_sync_state_annotation_source_device_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotation_sync_state_user_source_device_key_idx": {
+          "name": "annotation_sync_state_user_source_device_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotation_sync_state_user_key_idx": {
+          "name": "annotation_sync_state_user_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotation_sync_state_annotation_id_idx": {
+          "name": "annotation_sync_state_annotation_id_idx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "annotation_sync_state_annotation_id_annotations_id_fk": {
+          "name": "annotation_sync_state_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "columnsFrom": ["annotation_id"],
+          "tableTo": "annotations",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "annotation_sync_state_user_id_users_id_fk": {
+          "name": "annotation_sync_state_user_id_users_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_sync_state_source_chk": {
+          "name": "annotation_sync_state_source_chk",
+          "value": "\"annotation_sync_state\".\"source\" in ('koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotations": {
+      "name": "annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'yellow'"
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'highlight'"
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_title": {
+          "name": "chapter_title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'web'"
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_created_at": {
+          "name": "device_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_updated_at": {
+          "name": "device_updated_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_user_id_idx": {
+          "name": "annotations_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotations_user_book_idx": {
+          "name": "annotations_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "annotations_user_book_active_idx": {
+          "name": "annotations_user_book_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "where": "\"annotations\".\"deleted_at\" is null",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "annotations_user_id_users_id_fk": {
+          "name": "annotations_user_id_users_id_fk",
+          "tableFrom": "annotations",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "annotations_book_id_books_id_fk": {
+          "name": "annotations_book_id_books_id_fk",
+          "tableFrom": "annotations",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_style_chk": {
+          "name": "annotations_style_chk",
+          "value": "\"annotations\".\"style\" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')"
+        },
+        "annotations_origin_chk": {
+          "name": "annotations_origin_chk",
+          "value": "\"annotations\".\"origin\" in ('web', 'koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.audiobook_progress": {
+      "name": "audiobook_progress",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "current_file_id": {
+          "name": "current_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "abp_user_id_idx": {
+          "name": "abp_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "audiobook_progress_user_id_users_id_fk": {
+          "name": "audiobook_progress_user_id_users_id_fk",
+          "tableFrom": "audiobook_progress",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "audiobook_progress_book_id_books_id_fk": {
+          "name": "audiobook_progress_book_id_books_id_fk",
+          "tableFrom": "audiobook_progress",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "audiobook_progress_current_file_id_book_files_id_fk": {
+          "name": "audiobook_progress_current_file_id_book_files_id_fk",
+          "tableFrom": "audiobook_progress",
+          "columnsFrom": ["current_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "audiobook_progress_user_id_book_id_pk": {
+          "name": "audiobook_progress_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "audiobook_progress_percentage_range_chk": {
+          "name": "audiobook_progress_percentage_range_chk",
+          "value": "\"audiobook_progress\".\"percentage\" >= 0 and \"audiobook_progress\".\"percentage\" <= 100"
+        },
+        "audiobook_progress_position_seconds_nonnegative_chk": {
+          "name": "audiobook_progress_position_seconds_nonnegative_chk",
+          "value": "\"audiobook_progress\".\"position_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.bookmarks": {
+      "name": "bookmarks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bookmarks_user_book_idx": {
+          "name": "bookmarks_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "bookmarks_user_book_cfi_uidx": {
+          "name": "bookmarks_user_book_cfi_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "cfi",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"bookmarks\".\"cfi\" is not null",
+          "concurrently": false
+        },
+        "bookmarks_user_book_pos_uidx": {
+          "name": "bookmarks_user_book_pos_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position_seconds",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"bookmarks\".\"position_seconds\" is not null and \"bookmarks\".\"cfi\" is null",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "bookmarks_user_id_users_id_fk": {
+          "name": "bookmarks_user_id_users_id_fk",
+          "tableFrom": "bookmarks",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "bookmarks_book_id_books_id_fk": {
+          "name": "bookmarks_book_id_books_id_fk",
+          "tableFrom": "bookmarks",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reader_default_preferences": {
+      "name": "reader_default_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format_group": {
+          "name": "format_group",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rdp_user_format_idx": {
+          "name": "rdp_user_format_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format_group",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "reader_default_preferences_user_id_users_id_fk": {
+          "name": "reader_default_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_default_preferences",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reader_default_preferences_format_group_chk": {
+          "name": "reader_default_preferences_format_group_chk",
+          "value": "\"reader_default_preferences\".\"format_group\" in ('epub', 'pdf', 'cbx', 'audio')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reader_preferences": {
+      "name": "reader_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rp_user_file_idx": {
+          "name": "rp_user_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "reader_preferences_user_id_users_id_fk": {
+          "name": "reader_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_preferences",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "reader_preferences_book_file_id_book_files_id_fk": {
+          "name": "reader_preferences_book_file_id_book_files_id_fk",
+          "tableFrom": "reader_preferences",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reading_progress": {
+      "name": "reading_progress",
+      "schema": "",
+      "columns": {
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_source": {
+          "name": "kobo_location_source",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_type": {
+          "name": "kobo_location_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_value": {
+          "name": "kobo_location_value",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_content_source_progress_percent": {
+          "name": "kobo_content_source_progress_percent",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "koreader_progress": {
+          "name": "koreader_progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reading_progress_user_id_idx": {
+          "name": "reading_progress_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "reading_progress_user_updated_at_idx": {
+          "name": "reading_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "reading_progress_book_file_id_book_files_id_fk": {
+          "name": "reading_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_progress",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "reading_progress_user_id_users_id_fk": {
+          "name": "reading_progress_user_id_users_id_fk",
+          "tableFrom": "reading_progress",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "reading_progress_book_file_id_user_id_pk": {
+          "name": "reading_progress_book_file_id_user_id_pk",
+          "columns": ["book_file_id", "user_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_progress_percentage_range_chk": {
+          "name": "reading_progress_percentage_range_chk",
+          "value": "\"reading_progress\".\"percentage\" >= 0 and \"reading_progress\".\"percentage\" <= 100"
+        },
+        "reading_progress_page_number_nonnegative_chk": {
+          "name": "reading_progress_page_number_nonnegative_chk",
+          "value": "\"reading_progress\".\"page_number\" is null or \"reading_progress\".\"page_number\" >= 0"
+        },
+        "reading_progress_position_seconds_nonnegative_chk": {
+          "name": "reading_progress_position_seconds_nonnegative_chk",
+          "value": "\"reading_progress\".\"position_seconds\" is null or \"reading_progress\".\"position_seconds\" >= 0"
+        },
+        "reading_progress_kobo_content_source_progress_range_chk": {
+          "name": "reading_progress_kobo_content_source_progress_range_chk",
+          "value": "\"reading_progress\".\"kobo_content_source_progress_percent\" is null or (\"reading_progress\".\"kobo_content_source_progress_percent\" >= 0 and \"reading_progress\".\"kobo_content_source_progress_percent\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reading_sessions": {
+      "name": "reading_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_progress": {
+          "name": "end_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "rs_user_session_id_uidx": {
+          "name": "rs_user_session_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "rs_user_started_at_idx": {
+          "name": "rs_user_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "rs_book_file_started_at_idx": {
+          "name": "rs_book_file_started_at_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "rs_user_book_file_idx": {
+          "name": "rs_user_book_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "rs_user_book_started_at_idx": {
+          "name": "rs_user_book_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "reading_sessions_user_id_users_id_fk": {
+          "name": "reading_sessions_user_id_users_id_fk",
+          "tableFrom": "reading_sessions",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "reading_sessions_book_file_id_book_files_id_fk": {
+          "name": "reading_sessions_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_sessions",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "reading_sessions_book_id_books_id_fk": {
+          "name": "reading_sessions_book_id_books_id_fk",
+          "tableFrom": "reading_sessions",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_sessions_source_chk": {
+          "name": "reading_sessions_source_chk",
+          "value": "\"reading_sessions\".\"source\" in ('web', 'koreader', 'manual', 'kobo')"
+        },
+        "reading_sessions_duration_seconds_nonnegative_chk": {
+          "name": "reading_sessions_duration_seconds_nonnegative_chk",
+          "value": "\"reading_sessions\".\"duration_seconds\" >= 0"
+        },
+        "reading_sessions_end_progress_range_chk": {
+          "name": "reading_sessions_end_progress_range_chk",
+          "value": "\"reading_sessions\".\"end_progress\" is null or (\"reading_sessions\".\"end_progress\" >= 0 and \"reading_sessions\".\"end_progress\" <= 100)"
+        },
+        "reading_sessions_ended_after_started_chk": {
+          "name": "reading_sessions_ended_after_started_chk",
+          "value": "\"reading_sessions\".\"ended_at\" >= \"reading_sessions\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_ratings": {
+      "name": "user_book_ratings",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubr_user_id_idx": {
+          "name": "ubr_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "ubr_book_id_idx": {
+          "name": "ubr_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "ubr_book_user_rating_idx": {
+          "name": "ubr_book_user_rating_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_book_ratings_user_id_users_id_fk": {
+          "name": "user_book_ratings_user_id_users_id_fk",
+          "tableFrom": "user_book_ratings",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_book_ratings_book_id_books_id_fk": {
+          "name": "user_book_ratings_book_id_books_id_fk",
+          "tableFrom": "user_book_ratings",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_ratings_user_id_book_id_pk": {
+          "name": "user_book_ratings_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_ratings_rating_range_chk": {
+          "name": "user_book_ratings_rating_range_chk",
+          "value": "\"user_book_ratings\".\"rating\" >= 1 and \"user_book_ratings\".\"rating\" <= 5"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_status": {
+      "name": "user_book_status",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unread'"
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubs_user_id_idx": {
+          "name": "ubs_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "ubs_user_status_idx": {
+          "name": "ubs_user_status_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "ubs_book_user_idx": {
+          "name": "ubs_book_user_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_book_status_user_id_users_id_fk": {
+          "name": "user_book_status_user_id_users_id_fk",
+          "tableFrom": "user_book_status",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_book_status_book_id_books_id_fk": {
+          "name": "user_book_status_book_id_books_id_fk",
+          "tableFrom": "user_book_status",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_status_user_id_book_id_pk": {
+          "name": "user_book_status_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_status_status_chk": {
+          "name": "user_book_status_status_chk",
+          "value": "\"user_book_status\".\"status\" in ('unread', 'want_to_read', 'reading', 'on_hold', 'rereading', 'read', 'skimmed', 'abandoned')"
+        },
+        "user_book_status_source_chk": {
+          "name": "user_book_status_source_chk",
+          "value": "\"user_book_status\".\"source\" in ('auto', 'manual')"
+        },
+        "user_book_status_finished_after_started_chk": {
+          "name": "user_book_status_finished_after_started_chk",
+          "value": "\"user_book_status\".\"finished_at\" is null or \"user_book_status\".\"started_at\" is null or \"user_book_status\".\"finished_at\" >= \"user_book_status\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_reading_daily_stats": {
+      "name": "user_reading_daily_stats",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "day": {
+          "name": "day",
+          "type": "date",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_seconds": {
+          "name": "reading_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "sessions_count": {
+          "name": "sessions_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "urds_user_day_idx": {
+          "name": "urds_user_day_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "day",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_reading_daily_stats_user_id_users_id_fk": {
+          "name": "user_reading_daily_stats_user_id_users_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_reading_daily_stats_library_id_libraries_id_fk": {
+          "name": "user_reading_daily_stats_library_id_libraries_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "columnsFrom": ["library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_reading_daily_stats_user_id_library_id_day_pk": {
+          "name": "user_reading_daily_stats_user_id_library_id_day_pk",
+          "columns": ["user_id", "library_id", "day"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_reading_daily_stats_reading_seconds_nonnegative_chk": {
+          "name": "user_reading_daily_stats_reading_seconds_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"reading_seconds\" >= 0"
+        },
+        "user_reading_daily_stats_sessions_count_nonnegative_chk": {
+          "name": "user_reading_daily_stats_sessions_count_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"sessions_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.oidc_group_mappings": {
+      "name": "oidc_group_mappings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_group_claim": {
+          "name": "oidc_group_claim",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_group_mappings_provider_claim_uidx": {
+          "name": "oidc_group_mappings_provider_claim_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_group_claim",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "oidc_group_mappings_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_group_mappings_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_group_mappings",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "oidc_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_identities": {
+      "name": "oidc_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "linked_at": {
+          "name": "linked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_identities_provider_subject_uidx": {
+          "name": "oidc_identities_provider_subject_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_identities_user_provider_uidx": {
+          "name": "oidc_identities_user_provider_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_identities_issuer_subject_uidx": {
+          "name": "oidc_identities_issuer_subject_uidx",
+          "columns": [
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_identities_user_id_idx": {
+          "name": "oidc_identities_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "oidc_identities_user_id_users_id_fk": {
+          "name": "oidc_identities_user_id_users_id_fk",
+          "tableFrom": "oidc_identities",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "oidc_identities_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_identities_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_identities",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "oidc_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_permission_grants": {
+      "name": "oidc_permission_grants",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "oidc_permission_grants_user_id_users_id_fk": {
+          "name": "oidc_permission_grants_user_id_users_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "oidc_permission_grants_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_permission_grants_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "oidc_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "oidc_permission_grants_user_id_provider_id_permission_name_pk": {
+          "name": "oidc_permission_grants_user_id_provider_id_permission_name_pk",
+          "columns": ["user_id", "provider_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_providers": {
+      "name": "oidc_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "issuer_uri": {
+          "name": "issuer_uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'openid profile email'"
+        },
+        "icon_url": {
+          "name": "icon_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "claim_mapping": {
+          "name": "claim_mapping",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"username\":\"preferred_username\",\"name\":\"name\",\"email\":\"email\",\"groups\":\"groups\"}'::jsonb"
+        },
+        "auto_provision": {
+          "name": "auto_provision",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"enabled\":false,\"allowLocalLinking\":false,\"defaultPermissionNames\":[]}'::jsonb"
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_providers_enabled_order_idx": {
+          "name": "oidc_providers_enabled_order_idx",
+          "columns": [
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oidc_providers_slug_unique": {
+          "name": "oidc_providers_slug_unique",
+          "columns": ["slug"],
+          "nullsNotDistinct": false
+        },
+        "oidc_providers_issuer_uri_unique": {
+          "name": "oidc_providers_issuer_uri_unique",
+          "columns": ["issuer_uri"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_sessions": {
+      "name": "oidc_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_session_id": {
+          "name": "oidc_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token_hint": {
+          "name": "id_token_hint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_refresh_token": {
+          "name": "idp_refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_sessions_user_active_idx": {
+          "name": "oidc_sessions_user_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "where": "\"oidc_sessions\".\"revoked\" = false",
+          "concurrently": false
+        },
+        "oidc_sessions_subject_issuer_idx": {
+          "name": "oidc_sessions_subject_issuer_idx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_sessions_sid_idx": {
+          "name": "oidc_sessions_sid_idx",
+          "columns": [
+            {
+              "expression": "oidc_session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_sessions_expires_at_idx": {
+          "name": "oidc_sessions_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "oidc_sessions_provider_id_idx": {
+          "name": "oidc_sessions_provider_id_idx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "oidc_sessions_user_id_users_id_fk": {
+          "name": "oidc_sessions_user_id_users_id_fk",
+          "tableFrom": "oidc_sessions",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "oidc_sessions_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_sessions_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_sessions",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "oidc_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_states": {
+      "name": "oidc_states",
+      "schema": "",
+      "columns": {
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "meta": {
+          "name": "meta",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oidc_states_expires_at_idx": {
+          "name": "oidc_states_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "oidc_states_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_states_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_states",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "oidc_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_used_jtis": {
+      "name": "oidc_used_jtis",
+      "schema": "",
+      "columns": {
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_used_jtis_expires_at_idx": {
+          "name": "oidc_used_jtis_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.opds_users": {
+      "name": "opds_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "opds_sort_order",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'recent'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "opds_users_username_lower_uidx": {
+          "name": "opds_users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "opds_users_user_id_users_id_fk": {
+          "name": "opds_users_user_id_users_id_fk",
+          "tableFrom": "opds_users",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "opds_users_username_unique": {
+          "name": "opds_users_username_unique",
+          "columns": ["username"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_book_entitlements": {
+      "name": "kobo_book_entitlements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "cover_image_id": {
+          "name": "cover_image_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "needs_legacy_numeric_removal": {
+          "name": "needs_legacy_numeric_removal",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_book_entitlements_user_id_idx": {
+          "name": "kobo_book_entitlements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "kobo_book_entitlements_book_id_idx": {
+          "name": "kobo_book_entitlements_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "kobo_book_entitlements_user_id_users_id_fk": {
+          "name": "kobo_book_entitlements_user_id_users_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "kobo_book_entitlements_book_id_books_id_fk": {
+          "name": "kobo_book_entitlements_book_id_books_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_book_entitlements_user_book_unique": {
+          "name": "kobo_book_entitlements_user_book_unique",
+          "columns": ["user_id", "book_id"],
+          "nullsNotDistinct": false
+        },
+        "kobo_book_entitlements_user_entitlement_unique": {
+          "name": "kobo_book_entitlements_user_entitlement_unique",
+          "columns": ["user_id", "entitlement_id"],
+          "nullsNotDistinct": false
+        },
+        "kobo_book_entitlements_user_cover_unique": {
+          "name": "kobo_book_entitlements_user_cover_unique",
+          "columns": ["user_id", "cover_image_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_devices": {
+      "name": "kobo_devices",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_device_id": {
+          "name": "client_device_id",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_seen_at": {
+          "name": "last_seen_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_devices_user_id_idx": {
+          "name": "kobo_devices_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "kobo_devices_user_id_users_id_fk": {
+          "name": "kobo_devices_user_id_users_id_fk",
+          "tableFrom": "kobo_devices",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_devices_token_unique": {
+          "name": "kobo_devices_token_unique",
+          "columns": ["token"],
+          "nullsNotDistinct": false
+        },
+        "kobo_devices_client_device_id_unique": {
+          "name": "kobo_devices_client_device_id_unique",
+          "columns": ["client_device_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_library_snapshots": {
+      "name": "kobo_library_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_library_snapshots_user_id_users_id_fk": {
+          "name": "kobo_library_snapshots_user_id_users_id_fk",
+          "tableFrom": "kobo_library_snapshots",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_library_snapshots_user_id_unique": {
+          "name": "kobo_library_snapshots_user_id_unique",
+          "columns": ["user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_reading_states": {
+      "name": "kobo_reading_states",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at_kobo": {
+          "name": "created_at_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_modified_kobo": {
+          "name": "last_modified_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority_timestamp": {
+          "name": "priority_timestamp",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "current_bookmark": {
+          "name": "current_bookmark",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "statistics": {
+          "name": "statistics",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_info": {
+          "name": "status_info",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_reading_states_user_id_users_id_fk": {
+          "name": "kobo_reading_states_user_id_users_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "kobo_reading_states_book_id_books_id_fk": {
+          "name": "kobo_reading_states_book_id_books_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_reading_states_user_id_book_id_unique": {
+          "name": "kobo_reading_states_user_id_book_id_unique",
+          "columns": ["user_id", "book_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_snapshot_books": {
+      "name": "kobo_snapshot_books",
+      "schema": "",
+      "columns": {
+        "snapshot_id": {
+          "name": "snapshot_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "synced": {
+          "name": "synced",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "pending_delete": {
+          "name": "pending_delete",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_new": {
+          "name": "is_new",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "removed_by_device": {
+          "name": "removed_by_device",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "delivery_hash": {
+          "name": "delivery_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_hash": {
+          "name": "metadata_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "kobo_snapshot_books_snapshot_synced_book_idx": {
+          "name": "kobo_snapshot_books_snapshot_synced_book_idx",
+          "columns": [
+            {
+              "expression": "snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "synced",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk": {
+          "name": "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "columnsFrom": ["snapshot_id"],
+          "tableTo": "kobo_library_snapshots",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "kobo_snapshot_books_book_id_books_id_fk": {
+          "name": "kobo_snapshot_books_book_id_books_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "kobo_snapshot_books_snapshot_id_book_id_pk": {
+          "name": "kobo_snapshot_books_snapshot_id_book_id_pk",
+          "columns": ["snapshot_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_sync_settings": {
+      "name": "kobo_sync_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "finished_threshold": {
+          "name": "finished_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 99
+        },
+        "convert_to_kepub": {
+          "name": "convert_to_kepub",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "force_enable_hyphenation": {
+          "name": "force_enable_hyphenation",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "kepub_conversion_limit_mb": {
+          "name": "kepub_conversion_limit_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "two_way_progress_sync": {
+          "name": "two_way_progress_sync",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sync_bookorbit_annotations_to_kobo": {
+          "name": "sync_bookorbit_annotations_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_sync_settings_user_id_users_id_fk": {
+          "name": "kobo_sync_settings_user_id_users_id_fk",
+          "tableFrom": "kobo_sync_settings",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_sync_settings_user_id_unique": {
+          "name": "kobo_sync_settings_user_id_unique",
+          "columns": ["user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "kobo_sync_settings_reading_threshold_range_chk": {
+          "name": "kobo_sync_settings_reading_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"reading_threshold\" >= 0 and \"kobo_sync_settings\".\"reading_threshold\" <= 100"
+        },
+        "kobo_sync_settings_finished_threshold_range_chk": {
+          "name": "kobo_sync_settings_finished_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"finished_threshold\" >= 0 and \"kobo_sync_settings\".\"finished_threshold\" <= 100"
+        },
+        "kobo_sync_settings_conversion_limit_nonnegative_chk": {
+          "name": "kobo_sync_settings_conversion_limit_nonnegative_chk",
+          "value": "\"kobo_sync_settings\".\"kepub_conversion_limit_mb\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_dock_files": {
+      "name": "book_dock_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "file_name": {
+          "name": "file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "embedded_metadata": {
+          "name": "embedded_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "selected_metadata": {
+          "name": "selected_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata": {
+          "name": "fetched_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_path": {
+          "name": "cover_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_library_id": {
+          "name": "target_library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_folder_id": {
+          "name": "target_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata_sources": {
+          "name": "fetched_metadata_sources",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_edited_at": {
+          "name": "metadata_edited_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uploaded_by": {
+          "name": "uploaded_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_dock_files_status_idx": {
+          "name": "book_dock_files_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_dock_files_uploaded_by_idx": {
+          "name": "book_dock_files_uploaded_by_idx",
+          "columns": [
+            {
+              "expression": "uploaded_by",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_dock_files_target_library_id_libraries_id_fk": {
+          "name": "book_dock_files_target_library_id_libraries_id_fk",
+          "tableFrom": "book_dock_files",
+          "columnsFrom": ["target_library_id"],
+          "tableTo": "libraries",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "book_dock_files_target_folder_id_library_folders_id_fk": {
+          "name": "book_dock_files_target_folder_id_library_folders_id_fk",
+          "tableFrom": "book_dock_files",
+          "columnsFrom": ["target_folder_id"],
+          "tableTo": "library_folders",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "book_dock_files_uploaded_by_users_id_fk": {
+          "name": "book_dock_files_uploaded_by_users_id_fk",
+          "tableFrom": "book_dock_files",
+          "columnsFrom": ["uploaded_by"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "book_dock_files_absolute_path_unique": {
+          "name": "book_dock_files_absolute_path_unique",
+          "columns": ["absolute_path"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "book_dock_files_status_chk": {
+          "name": "book_dock_files_status_chk",
+          "value": "\"book_dock_files\".\"status\" in ('pending', 'extracting', 'fetching', 'ready', 'error')"
+        },
+        "book_dock_files_confidence_range_chk": {
+          "name": "book_dock_files_confidence_range_chk",
+          "value": "\"book_dock_files\".\"confidence\" is null or (\"book_dock_files\".\"confidence\" >= 0 and \"book_dock_files\".\"confidence\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.file_write_log": {
+      "name": "file_write_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fields_written": {
+          "name": "fields_written",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "written_at": {
+          "name": "written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "fwl_book_id_written_at_idx": {
+          "name": "fwl_book_id_written_at_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "written_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "file_write_log_book_id_books_id_fk": {
+          "name": "file_write_log_book_id_books_id_fk",
+          "tableFrom": "file_write_log",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "file_write_log_book_file_id_book_files_id_fk": {
+          "name": "file_write_log_book_file_id_book_files_id_fk",
+          "tableFrom": "file_write_log",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "file_write_log_user_id_users_id_fk": {
+          "name": "file_write_log_user_id_users_id_fk",
+          "tableFrom": "file_write_log",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "file_write_log_status_chk": {
+          "name": "file_write_log_status_chk",
+          "value": "\"file_write_log\".\"status\" in ('success', 'skipped', 'failed')"
+        },
+        "file_write_log_triggered_by_chk": {
+          "name": "file_write_log_triggered_by_chk",
+          "value": "\"file_write_log\".\"triggered_by\" in ('auto', 'sync')"
+        },
+        "file_write_log_duration_ms_nonnegative_chk": {
+          "name": "file_write_log_duration_ms_nonnegative_chk",
+          "value": "\"file_write_log\".\"duration_ms\" is null or \"file_write_log\".\"duration_ms\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_templates": {
+      "name": "email_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_text": {
+          "name": "body_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system": {
+          "name": "is_system",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_templates_one_default_per_user_uidx": {
+          "name": "email_templates_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"email_templates\".\"is_default\" = true and \"email_templates\".\"user_id\" is not null",
+          "concurrently": false
+        },
+        "email_templates_system_name_unique": {
+          "name": "email_templates_system_name_unique",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"email_templates\".\"user_id\" is null",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "email_templates_user_id_users_id_fk": {
+          "name": "email_templates_user_id_users_id_fk",
+          "tableFrom": "email_templates",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_templates_user_id_name_unique": {
+          "name": "email_templates_user_id_name_unique",
+          "columns": ["user_id", "name"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_providers": {
+      "name": "email_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "host": {
+          "name": "host",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "port": {
+          "name": "port",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_enc": {
+          "name": "password_enc",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_name": {
+          "name": "from_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_address": {
+          "name": "from_address",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth": {
+          "name": "auth",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "ssl": {
+          "name": "ssl",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "start_tls": {
+          "name": "start_tls",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_shared": {
+          "name": "is_shared",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system_provider": {
+          "name": "is_system_provider",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "tls_reject_unauthorized": {
+          "name": "tls_reject_unauthorized",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_providers_one_default_per_user_uidx": {
+          "name": "email_providers_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"email_providers\".\"is_default\" = true and \"email_providers\".\"user_id\" is not null",
+          "concurrently": false
+        },
+        "email_providers_one_system_provider_uidx": {
+          "name": "email_providers_one_system_provider_uidx",
+          "columns": [
+            {
+              "expression": "is_system_provider",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"email_providers\".\"is_system_provider\" = true",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "email_providers_user_id_users_id_fk": {
+          "name": "email_providers_user_id_users_id_fk",
+          "tableFrom": "email_providers",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_providers_user_id_name_unique": {
+          "name": "email_providers_user_id_name_unique",
+          "columns": ["user_id", "name"],
+          "nullsNotDistinct": false
+        },
+        "email_providers_id_user_id_unique": {
+          "name": "email_providers_id_user_id_unique",
+          "columns": ["id", "user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_providers_port_range_chk": {
+          "name": "email_providers_port_range_chk",
+          "value": "\"email_providers\".\"port\" >= 1 and \"email_providers\".\"port\" <= 65535"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_group_members": {
+      "name": "email_recipient_group_members",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "recipient_id": {
+          "name": "recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_group_members_user_id_users_id_fk": {
+          "name": "email_recipient_group_members_user_id_users_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_recipient_group_members_group_id_email_recipient_groups_id_fk": {
+          "name": "email_recipient_group_members_group_id_email_recipient_groups_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "columnsFrom": ["group_id"],
+          "tableTo": "email_recipient_groups",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_recipient_group_members_recipient_id_email_recipients_id_fk": {
+          "name": "email_recipient_group_members_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "columnsFrom": ["recipient_id"],
+          "tableTo": "email_recipients",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_recipient_group_members_group_user_fk": {
+          "name": "email_recipient_group_members_group_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "columnsFrom": ["group_id", "user_id"],
+          "tableTo": "email_recipient_groups",
+          "columnsTo": ["id", "user_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        },
+        "email_recipient_group_members_recipient_user_fk": {
+          "name": "email_recipient_group_members_recipient_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "columnsFrom": ["recipient_id", "user_id"],
+          "tableTo": "email_recipients",
+          "columnsTo": ["id", "user_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "email_recipient_group_members_group_id_recipient_id_pk": {
+          "name": "email_recipient_group_members_group_id_recipient_id_pk",
+          "columns": ["group_id", "recipient_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_groups": {
+      "name": "email_recipient_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_groups_user_id_users_id_fk": {
+          "name": "email_recipient_groups_user_id_users_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_recipient_groups_default_template_id_email_templates_id_fk": {
+          "name": "email_recipient_groups_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "columnsFrom": ["default_template_id"],
+          "tableTo": "email_templates",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipient_groups_user_id_name_unique": {
+          "name": "email_recipient_groups_user_id_name_unique",
+          "columns": ["user_id", "name"],
+          "nullsNotDistinct": false
+        },
+        "email_recipient_groups_id_user_id_unique": {
+          "name": "email_recipient_groups_id_user_id_unique",
+          "columns": ["id", "user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipients": {
+      "name": "email_recipients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "device_type": {
+          "name": "device_type",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "preferred_format": {
+          "name": "preferred_format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_recipients_user_email_lower_uidx": {
+          "name": "email_recipients_user_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"email\")",
+              "isExpression": true,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "email_recipients_one_default_per_user_uidx": {
+          "name": "email_recipients_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"email_recipients\".\"is_default\" = true",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "email_recipients_user_id_users_id_fk": {
+          "name": "email_recipients_user_id_users_id_fk",
+          "tableFrom": "email_recipients",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_recipients_default_template_id_email_templates_id_fk": {
+          "name": "email_recipients_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipients",
+          "columnsFrom": ["default_template_id"],
+          "tableTo": "email_templates",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipients_user_id_email_unique": {
+          "name": "email_recipients_user_id_email_unique",
+          "columns": ["user_id", "email"],
+          "nullsNotDistinct": false
+        },
+        "email_recipients_id_user_id_unique": {
+          "name": "email_recipients_id_user_id_unique",
+          "columns": ["id", "user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_recipients_device_type_chk": {
+          "name": "email_recipients_device_type_chk",
+          "value": "\"email_recipients\".\"device_type\" is null or \"email_recipients\".\"device_type\" in ('kindle', 'kobo', 'other')"
+        },
+        "email_recipients_preferred_format_chk": {
+          "name": "email_recipients_preferred_format_chk",
+          "value": "\"email_recipients\".\"preferred_format\" is null or \"email_recipients\".\"preferred_format\" in ('epub', 'pdf', 'mobi', 'azw3', 'cbz', 'cbr')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_preferences": {
+      "name": "email_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_provider_id": {
+          "name": "default_provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_recipient_id": {
+          "name": "default_recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_preferences_user_id_users_id_fk": {
+          "name": "email_preferences_user_id_users_id_fk",
+          "tableFrom": "email_preferences",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_preferences_default_provider_id_email_providers_id_fk": {
+          "name": "email_preferences_default_provider_id_email_providers_id_fk",
+          "tableFrom": "email_preferences",
+          "columnsFrom": ["default_provider_id"],
+          "tableTo": "email_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_preferences_default_recipient_id_email_recipients_id_fk": {
+          "name": "email_preferences_default_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_preferences",
+          "columnsFrom": ["default_recipient_id"],
+          "tableTo": "email_recipients",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_preferences_default_template_id_email_templates_id_fk": {
+          "name": "email_preferences_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_preferences",
+          "columnsFrom": ["default_template_id"],
+          "tableTo": "email_templates",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_preferences_default_recipient_owner_fk": {
+          "name": "email_preferences_default_recipient_owner_fk",
+          "tableFrom": "email_preferences",
+          "columnsFrom": ["default_recipient_id", "user_id"],
+          "tableTo": "email_recipients",
+          "columnsTo": ["id", "user_id"],
+          "onUpdate": "no action",
+          "onDelete": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_preferences_user_id_unique": {
+          "name": "email_preferences_user_id_unique",
+          "columns": ["user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_send_log": {
+      "name": "email_send_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "to_email": {
+          "name": "to_email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_name": {
+          "name": "to_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_send_log_user_created_at_idx": {
+          "name": "email_send_log_user_created_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "email_send_log_created_at_idx": {
+          "name": "email_send_log_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "email_send_log_status_next_retry_idx": {
+          "name": "email_send_log_status_next_retry_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_retry_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "email_send_log_user_id_users_id_fk": {
+          "name": "email_send_log_user_id_users_id_fk",
+          "tableFrom": "email_send_log",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "email_send_log_book_id_books_id_fk": {
+          "name": "email_send_log_book_id_books_id_fk",
+          "tableFrom": "email_send_log",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_send_log_book_file_id_book_files_id_fk": {
+          "name": "email_send_log_book_file_id_book_files_id_fk",
+          "tableFrom": "email_send_log",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_send_log_provider_id_email_providers_id_fk": {
+          "name": "email_send_log_provider_id_email_providers_id_fk",
+          "tableFrom": "email_send_log",
+          "columnsFrom": ["provider_id"],
+          "tableTo": "email_providers",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "email_send_log_template_id_email_templates_id_fk": {
+          "name": "email_send_log_template_id_email_templates_id_fk",
+          "tableFrom": "email_send_log",
+          "columnsFrom": ["template_id"],
+          "tableTo": "email_templates",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "email_send_log_status_chk": {
+          "name": "email_send_log_status_chk",
+          "value": "\"email_send_log\".\"status\" in ('pending', 'sent', 'failed')"
+        },
+        "email_send_log_attempt_count_nonnegative_chk": {
+          "name": "email_send_log_attempt_count_nonnegative_chk",
+          "value": "\"email_send_log\".\"attempt_count\" >= 0"
+        },
+        "email_send_log_sent_after_created_chk": {
+          "name": "email_send_log_sent_after_created_chk",
+          "value": "\"email_send_log\".\"sent_at\" is null or \"email_send_log\".\"sent_at\" >= \"email_send_log\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action_url": {
+          "name": "action_url",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "read": {
+          "name": "read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_id_idx": {
+          "name": "notifications_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "notifications_user_unread_idx": {
+          "name": "notifications_user_unread_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "read",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "notifications_created_at_idx": {
+          "name": "notifications_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "notifications_user_id_users_id_fk": {
+          "name": "notifications_user_id_users_id_fk",
+          "tableFrom": "notifications",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_duplicate_pairs": {
+      "name": "dismissed_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_duplicate_pairs_entity_a_idx": {
+          "name": "dismissed_duplicate_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "dismissed_duplicate_pairs_entity_b_idx": {
+          "name": "dismissed_duplicate_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "dismissed_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_duplicate_pairs",
+          "columnsFrom": ["dismissed_by"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_duplicate_pairs_unique": {
+          "name": "dismissed_duplicate_pairs_unique",
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_inline_duplicate_pairs": {
+      "name": "dismissed_inline_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_a": {
+          "name": "value_a",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_b": {
+          "name": "value_b",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_inline_pairs_entity_a_idx": {
+          "name": "dismissed_inline_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "dismissed_inline_pairs_entity_b_idx": {
+          "name": "dismissed_inline_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_inline_duplicate_pairs",
+          "columnsFrom": ["dismissed_by"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_inline_duplicate_pairs_unique": {
+          "name": "dismissed_inline_duplicate_pairs_unique",
+          "columns": ["entity_type", "value_a", "value_b"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_candidates": {
+      "name": "entity_duplicate_candidates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sim_score": {
+          "name": "sim_score",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "entity_dup_candidates_type_sim_idx": {
+          "name": "entity_dup_candidates_type_sim_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sim_score",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "entity_dup_candidates_entity_a_idx": {
+          "name": "entity_dup_candidates_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "entity_dup_candidates_entity_b_idx": {
+          "name": "entity_dup_candidates_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "entity_duplicate_candidates_unique": {
+          "name": "entity_duplicate_candidates_unique",
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_scan_status": {
+      "name": "entity_duplicate_scan_status",
+      "schema": "",
+      "columns": {
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "is_computing": {
+          "name": "is_computing",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_pairs": {
+          "name": "total_pairs",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "processed_count": {
+          "name": "processed_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_count": {
+          "name": "total_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_fonts": {
+      "name": "user_fonts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "family_name": {
+          "name": "family_name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_file_name": {
+          "name": "original_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stored_file_name": {
+          "name": "stored_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 400
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "uf_user_hash_uidx": {
+          "name": "uf_user_hash_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "uf_user_family_weight_style_uidx": {
+          "name": "uf_user_family_weight_style_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "family_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "weight",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "style",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_fonts_user_id_users_id_fk": {
+          "name": "user_fonts_user_id_users_id_fk",
+          "tableFrom": "user_fonts",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_fonts_format_chk": {
+          "name": "user_fonts_format_chk",
+          "value": "\"user_fonts\".\"format\" in ('ttf', 'otf', 'woff', 'woff2')"
+        },
+        "user_fonts_weight_chk": {
+          "name": "user_fonts_weight_chk",
+          "value": "\"user_fonts\".\"weight\" >= 100 and \"user_fonts\".\"weight\" <= 900 and \"user_fonts\".\"weight\" % 100 = 0"
+        },
+        "user_fonts_style_chk": {
+          "name": "user_fonts_style_chk",
+          "value": "\"user_fonts\".\"style\" in ('normal', 'italic')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_file_chapters": {
+      "name": "book_file_chapters",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "href": {
+          "name": "href",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "spine_index": {
+          "name": "spine_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "book_file_chapters_book_file_id_chapter_index_uidx": {
+          "name": "book_file_chapters_book_file_id_chapter_index_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "chapter_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_file_chapters_book_file_id_idx": {
+          "name": "book_file_chapters_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_file_chapters_book_file_id_book_files_id_fk": {
+          "name": "book_file_chapters_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_chapters",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_file_hash_history": {
+      "name": "book_file_hash_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(30)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_file_hash_history_book_file_id_file_hash_idx": {
+          "name": "book_file_hash_history_book_file_id_file_hash_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "book_file_hash_history_file_hash_idx": {
+          "name": "book_file_hash_history_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "book_file_hash_history_book_file_id_book_files_id_fk": {
+          "name": "book_file_hash_history_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_hash_history",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_file_hash_history_reason_chk": {
+          "name": "book_file_hash_history_reason_chk",
+          "value": "\"book_file_hash_history\".\"reason\" in ('file_write', 'external_change', 'rescan')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_progress": {
+      "name": "koreader_device_progress",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device": {
+          "name": "device",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "progress": {
+          "name": "progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_timestamp": {
+          "name": "sync_timestamp",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "orphaned": {
+          "name": "orphaned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "orphaned_hash": {
+          "name": "orphaned_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_device_progress_book_user_device_uidx": {
+          "name": "koreader_device_progress_book_user_device_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "where": "\"koreader_device_progress\".\"orphaned\" = false",
+          "concurrently": false
+        },
+        "koreader_device_progress_orphaned_hash_idx": {
+          "name": "koreader_device_progress_orphaned_hash_idx",
+          "columns": [
+            {
+              "expression": "orphaned_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "where": "\"koreader_device_progress\".\"orphaned\" = true",
+          "concurrently": false
+        },
+        "koreader_device_progress_user_updated_at_idx": {
+          "name": "koreader_device_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "koreader_device_progress_book_file_id_idx": {
+          "name": "koreader_device_progress_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "where": "\"koreader_device_progress\".\"book_file_id\" is not null",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_progress_book_file_id_book_files_id_fk": {
+          "name": "koreader_device_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "set null"
+        },
+        "koreader_device_progress_user_id_users_id_fk": {
+          "name": "koreader_device_progress_user_id_users_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_device_progress_percentage_range_chk": {
+          "name": "koreader_device_progress_percentage_range_chk",
+          "value": "\"koreader_device_progress\".\"percentage\" is null or (\"koreader_device_progress\".\"percentage\" >= 0 and \"koreader_device_progress\".\"percentage\" <= 1)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_sweeps": {
+      "name": "koreader_device_sweeps",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_model": {
+          "name": "device_model",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "plugin_version": {
+          "name": "plugin_version",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_sweep_at": {
+          "name": "last_sweep_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_sweep_books_matched": {
+          "name": "last_sweep_books_matched",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_page_stats": {
+          "name": "last_sweep_page_stats",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_annotations": {
+          "name": "last_sweep_annotations",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kds_user_id_idx": {
+          "name": "kds_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_sweeps_user_id_users_id_fk": {
+          "name": "koreader_device_sweeps_user_id_users_id_fk",
+          "tableFrom": "koreader_device_sweeps",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {
+        "koreader_device_sweeps_user_id_device_id_pk": {
+          "name": "koreader_device_sweeps_user_id_device_id_pk",
+          "columns": ["user_id", "device_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.koreader_page_stats": {
+      "name": "koreader_page_stats",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page": {
+          "name": "page",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "total_pages": {
+          "name": "total_pages",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kps_user_file_device_page_start_uidx": {
+          "name": "kps_user_file_device_page_start_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "kps_user_file_device_start_idx": {
+          "name": "kps_user_file_device_start_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "kps_user_id_idx": {
+          "name": "kps_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "koreader_page_stats_user_id_users_id_fk": {
+          "name": "koreader_page_stats_user_id_users_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "koreader_page_stats_book_file_id_book_files_id_fk": {
+          "name": "koreader_page_stats_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "columnsFrom": ["book_file_id"],
+          "tableTo": "book_files",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_page_stats_duration_nonnegative_chk": {
+          "name": "koreader_page_stats_duration_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"duration_seconds\" >= 0"
+        },
+        "koreader_page_stats_page_nonnegative_chk": {
+          "name": "koreader_page_stats_page_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"page\" >= 0"
+        },
+        "koreader_page_stats_total_pages_positive_chk": {
+          "name": "koreader_page_stats_total_pages_positive_chk",
+          "value": "\"koreader_page_stats\".\"total_pages\" > 0"
+        },
+        "koreader_page_stats_start_time_positive_chk": {
+          "name": "koreader_page_stats_start_time_positive_chk",
+          "value": "\"koreader_page_stats\".\"start_time\" > 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_users": {
+      "name": "koreader_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_md5": {
+          "name": "password_md5",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_enabled": {
+          "name": "sync_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_users_user_id_uidx": {
+          "name": "koreader_users_user_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "koreader_users_username_uidx": {
+          "name": "koreader_users_username_uidx",
+          "columns": [
+            {
+              "expression": "username",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "koreader_users_user_id_users_id_fk": {
+          "name": "koreader_users_user_id_users_id_fk",
+          "tableFrom": "koreader_users",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.achievements": {
+      "name": "achievements",
+      "schema": "",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "varchar(64)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "group_key": {
+          "name": "group_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon_name": {
+          "name": "icon_name",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rarity": {
+          "name": "rarity",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hidden": {
+          "name": "hidden",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "achievements_category_sort_idx": {
+          "name": "achievements_category_sort_idx",
+          "columns": [
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "achievements_group_key_idx": {
+          "name": "achievements_group_key_idx",
+          "columns": [
+            {
+              "expression": "group_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "achievements_category_chk": {
+          "name": "achievements_category_chk",
+          "value": "\"achievements\".\"category\" in ('reading', 'library', 'exploration', 'dedication')"
+        },
+        "achievements_rarity_chk": {
+          "name": "achievements_rarity_chk",
+          "value": "\"achievements\".\"rarity\" in ('common', 'rare', 'epic', 'legendary')"
+        },
+        "achievements_tier_chk": {
+          "name": "achievements_tier_chk",
+          "value": "\"achievements\".\"tier\" is null or (\"achievements\".\"tier\" >= 1 and \"achievements\".\"tier\" <= 4)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_achievements": {
+      "name": "user_achievements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "achievement_key": {
+          "name": "achievement_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "awarded_at": {
+          "name": "awarded_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "context_json": {
+          "name": "context_json",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "user_achievements_user_key_uidx": {
+          "name": "user_achievements_user_key_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "achievement_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "user_achievements_user_id_idx": {
+          "name": "user_achievements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        },
+        "user_achievements_user_awarded_at_idx": {
+          "name": "user_achievements_user_awarded_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "awarded_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_achievements_user_id_users_id_fk": {
+          "name": "user_achievements_user_id_users_id_fk",
+          "tableFrom": "user_achievements",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "user_achievements_achievement_key_achievements_key_fk": {
+          "name": "user_achievements_achievement_key_achievements_key_fk",
+          "tableFrom": "user_achievements",
+          "columnsFrom": ["achievement_key"],
+          "tableTo": "achievements",
+          "columnsTo": ["key"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_book_state": {
+      "name": "hardcover_book_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hardcover_book_id": {
+          "name": "hardcover_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_edition_id": {
+          "name": "hardcover_edition_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_user_book_id": {
+          "name": "hardcover_user_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_read_id": {
+          "name": "hardcover_read_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_method": {
+          "name": "match_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_error": {
+          "name": "match_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_status": {
+          "name": "last_synced_status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_progress": {
+          "name": "last_synced_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_rating": {
+          "name": "last_synced_rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_started_at": {
+          "name": "last_synced_started_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_finished_at": {
+          "name": "last_synced_finished_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_book_state_user_id_users_id_fk": {
+          "name": "hardcover_book_state_user_id_users_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        },
+        "hardcover_book_state_book_id_books_id_fk": {
+          "name": "hardcover_book_state_book_id_books_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "columnsFrom": ["book_id"],
+          "tableTo": "books",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_book_state_user_book_uidx": {
+          "name": "hardcover_book_state_user_book_uidx",
+          "columns": ["user_id", "book_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_user_settings": {
+      "name": "hardcover_user_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "api_token": {
+          "name": "api_token",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_status_change": {
+          "name": "auto_sync_on_status_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_progress_update": {
+          "name": "auto_sync_on_progress_update",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_rating_change": {
+          "name": "auto_sync_on_rating_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "privacy_setting_id": {
+          "name": "privacy_setting_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 3
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_user_settings_user_id_users_id_fk": {
+          "name": "hardcover_user_settings_user_id_users_id_fk",
+          "tableFrom": "hardcover_user_settings",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_user_settings_user_id_unique": {
+          "name": "hardcover_user_settings_user_id_unique",
+          "columns": ["user_id"],
+          "nullsNotDistinct": false
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_preferences": {
+      "name": "user_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "up_user_category_idx": {
+          "name": "up_user_category_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "with": {},
+          "method": "btree",
+          "concurrently": false
+        }
+      },
+      "foreignKeys": {
+        "user_preferences_user_id_users_id_fk": {
+          "name": "user_preferences_user_id_users_id_fk",
+          "tableFrom": "user_preferences",
+          "columnsFrom": ["user_id"],
+          "tableTo": "users",
+          "columnsTo": ["id"],
+          "onUpdate": "no action",
+          "onDelete": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.content_filter_type": {
+      "name": "content_filter_type",
+      "schema": "public",
+      "values": ["include", "exclude"]
+    },
+    "public.library_access_level": {
+      "name": "library_access_level",
+      "schema": "public",
+      "values": ["viewer", "editor", "owner"]
+    },
+    "public.user_avatar_source": {
+      "name": "user_avatar_source",
+      "schema": "public",
+      "values": ["none", "external", "uploaded"]
+    },
+    "public.opds_sort_order": {
+      "name": "opds_sort_order",
+      "schema": "public",
+      "values": ["recent", "title_asc", "title_desc", "author_asc", "author_desc", "series_asc", "series_desc"]
+    }
+  },
+  "schemas": {},
+  "views": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/server/src/db/migrations/meta/0031_snapshot.json b/server/src/db/migrations/meta/0031_snapshot.json
new file mode 100644
index 000000000..df4492647
--- /dev/null
+++ b/server/src/db/migrations/meta/0031_snapshot.json
@@ -0,0 +1,11751 @@
+{
+  "id": "139350a5-21b2-4334-b46b-6884119c7964",
+  "prevId": "1ad09390-1ed7-4667-b97c-e93645001b9b",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.audit_log": {
+      "name": "audit_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_username": {
+          "name": "actor_username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "resource": {
+          "name": "resource",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "resource_id": {
+          "name": "resource_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ip": {
+          "name": "ip",
+          "type": "varchar(45)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "idx_audit_user_id": {
+          "name": "idx_audit_user_id",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_resource": {
+          "name": "idx_audit_resource",
+          "columns": [
+            {
+              "expression": "resource",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "resource_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_action": {
+          "name": "idx_audit_action",
+          "columns": [
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_ip": {
+          "name": "idx_audit_ip",
+          "columns": [
+            {
+              "expression": "ip",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "idx_audit_created_at": {
+          "name": "idx_audit_created_at",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audit_log_user_id_users_id_fk": {
+          "name": "audit_log_user_id_users_id_fk",
+          "tableFrom": "audit_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.app_settings": {
+      "name": "app_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "app_settings_key_unique": {
+          "name": "app_settings_key_unique",
+          "nullsNotDistinct": false,
+          "columns": ["key"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.magic_access_tokens": {
+      "name": "magic_access_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "label": {
+          "name": "label",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "raw_token": {
+          "name": "raw_token",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "use_count": {
+          "name": "use_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "magic_access_tokens_user_id_idx": {
+          "name": "magic_access_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "magic_access_tokens_user_id_users_id_fk": {
+          "name": "magic_access_tokens_user_id_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "magic_access_tokens_created_by_users_id_fk": {
+          "name": "magic_access_tokens_created_by_users_id_fk",
+          "tableFrom": "magic_access_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["created_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "magic_access_tokens_token_hash_unique": {
+          "name": "magic_access_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "magic_access_tokens_use_count_nonneg_chk": {
+          "name": "magic_access_tokens_use_count_nonneg_chk",
+          "value": "\"magic_access_tokens\".\"use_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "used_at": {
+          "name": "used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "password_reset_tokens_user_id_idx": {
+          "name": "password_reset_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "password_reset_tokens_expires_at_idx": {
+          "name": "password_reset_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "password_reset_tokens_user_id_users_id_fk": {
+          "name": "password_reset_tokens_user_id_users_id_fk",
+          "tableFrom": "password_reset_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "password_reset_tokens_token_hash_unique": {
+          "name": "password_reset_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "password_reset_tokens_expires_after_created_chk": {
+          "name": "password_reset_tokens_expires_after_created_chk",
+          "value": "\"password_reset_tokens\".\"expires_at\" > \"password_reset_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.refresh_tokens": {
+      "name": "refresh_tokens",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rotated_at": {
+          "name": "rotated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replaced_by_token_hash": {
+          "name": "replaced_by_token_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_user_id_idx": {
+          "name": "refresh_tokens_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "refresh_tokens_expires_at_idx": {
+          "name": "refresh_tokens_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "refresh_tokens_token_hash_unique": {
+          "name": "refresh_tokens_token_hash_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token_hash"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "refresh_tokens_expires_after_created_chk": {
+          "name": "refresh_tokens_expires_after_created_chk",
+          "value": "\"refresh_tokens\".\"expires_at\" > \"refresh_tokens\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_genres": {
+      "name": "user_content_filter_genres",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_genres_genre_id_idx": {
+          "name": "user_content_filter_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_genres_user_id_users_id_fk": {
+          "name": "user_content_filter_genres_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_genres_genre_id_genres_id_fk": {
+          "name": "user_content_filter_genres_genre_id_genres_id_fk",
+          "tableFrom": "user_content_filter_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_genres_user_id_filter_type_genre_id_pk": {
+          "name": "user_content_filter_genres_user_id_filter_type_genre_id_pk",
+          "columns": ["user_id", "filter_type", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_content_filter_tags": {
+      "name": "user_content_filter_tags",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "filter_type": {
+          "name": "filter_type",
+          "type": "content_filter_type",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "user_content_filter_tags_tag_id_idx": {
+          "name": "user_content_filter_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_content_filter_tags_user_id_users_id_fk": {
+          "name": "user_content_filter_tags_user_id_users_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_content_filter_tags_tag_id_tags_id_fk": {
+          "name": "user_content_filter_tags_tag_id_tags_id_fk",
+          "tableFrom": "user_content_filter_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_content_filter_tags_user_id_filter_type_tag_id_pk": {
+          "name": "user_content_filter_tags_user_id_filter_type_tag_id_pk",
+          "columns": ["user_id", "filter_type", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_library_access": {
+      "name": "user_library_access",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_level": {
+          "name": "access_level",
+          "type": "library_access_level",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        }
+      },
+      "indexes": {
+        "user_library_access_library_user_idx": {
+          "name": "user_library_access_library_user_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_library_access_user_id_users_id_fk": {
+          "name": "user_library_access_user_id_users_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_library_access_library_id_libraries_id_fk": {
+          "name": "user_library_access_library_id_libraries_id_fk",
+          "tableFrom": "user_library_access",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_library_access_user_id_library_id_pk": {
+          "name": "user_library_access_user_id_library_id_pk",
+          "columns": ["user_id", "library_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_permissions": {
+      "name": "user_permissions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "user_permissions_user_id_users_id_fk": {
+          "name": "user_permissions_user_id_users_id_fk",
+          "tableFrom": "user_permissions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_permissions_user_id_permission_name_pk": {
+          "name": "user_permissions_user_id_permission_name_pk",
+          "columns": ["user_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "active": {
+          "name": "active",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_superuser": {
+          "name": "is_superuser",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_default_password": {
+          "name": "is_default_password",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "token_version": {
+          "name": "token_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "failed_login_attempts": {
+          "name": "failed_login_attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "locked_until": {
+          "name": "locked_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_url": {
+          "name": "avatar_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "avatar_source": {
+          "name": "avatar_source",
+          "type": "user_avatar_source",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'none'"
+        },
+        "avatar_version": {
+          "name": "avatar_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "provisioning_method": {
+          "name": "provisioning_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'local'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "users_username_lower_uidx": {
+          "name": "users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_email_lower_uidx": {
+          "name": "users_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"email\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "users_oidc_subject_issuer_uidx": {
+          "name": "users_oidc_subject_issuer_uidx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"users\".\"oidc_subject\" is not null and \"users\".\"oidc_issuer\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        },
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["email"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "users_provisioning_method_chk": {
+          "name": "users_provisioning_method_chk",
+          "value": "\"users\".\"provisioning_method\" in ('local', 'manual', 'oidc', 'shared')"
+        },
+        "users_token_version_nonnegative_chk": {
+          "name": "users_token_version_nonnegative_chk",
+          "value": "\"users\".\"token_version\" >= 0"
+        },
+        "users_failed_login_attempts_nonnegative_chk": {
+          "name": "users_failed_login_attempts_nonnegative_chk",
+          "value": "\"users\".\"failed_login_attempts\" >= 0"
+        },
+        "users_avatar_version_nonnegative_chk": {
+          "name": "users_avatar_version_nonnegative_chk",
+          "value": "\"users\".\"avatar_version\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.comic_metadata": {
+      "name": "comic_metadata",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issue_number": {
+          "name": "issue_number",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "volume_name": {
+          "name": "volume_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pencillers": {
+          "name": "pencillers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "inkers": {
+          "name": "inkers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "colorists": {
+          "name": "colorists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "letterers": {
+          "name": "letterers",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_artists": {
+          "name": "cover_artists",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "characters": {
+          "name": "characters",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "teams": {
+          "name": "teams",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locations": {
+          "name": "locations",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "story_arcs": {
+          "name": "story_arcs",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "comic_metadata_book_id_books_id_fk": {
+          "name": "comic_metadata_book_id_books_id_fk",
+          "tableFrom": "comic_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "comic_metadata_book_id_unique": {
+          "name": "comic_metadata_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_plan_artifacts": {
+      "name": "migration_plan_artifacts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_snapshot_hash": {
+          "name": "source_snapshot_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_hash": {
+          "name": "profile_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_hash": {
+          "name": "plan_hash",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan": {
+          "name": "plan",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_plan_artifacts_plan_hash_uidx": {
+          "name": "migration_plan_artifacts_plan_hash_uidx",
+          "columns": [
+            {
+              "expression": "plan_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_source_id_idx": {
+          "name": "migration_plan_artifacts_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_plan_artifacts_profile_id_idx": {
+          "name": "migration_plan_artifacts_profile_id_idx",
+          "columns": [
+            {
+              "expression": "profile_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_plan_artifacts_source_id_migration_sources_id_fk": {
+          "name": "migration_plan_artifacts_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_id_migration_profiles_id_fk": {
+          "name": "migration_plan_artifacts_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_created_by_user_id_users_id_fk": {
+          "name": "migration_plan_artifacts_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_plan_artifacts_profile_source_fk": {
+          "name": "migration_plan_artifacts_profile_source_fk",
+          "tableFrom": "migration_plan_artifacts",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_plan_artifacts_id_source_profile_unique": {
+          "name": "migration_plan_artifacts_id_source_profile_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id", "profile_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.migration_profiles": {
+      "name": "migration_profiles",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "user_mappings": {
+          "name": "user_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path_mappings": {
+          "name": "path_mappings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_profiles_source_name_version_uidx": {
+          "name": "migration_profiles_source_name_version_uidx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "version",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_profiles_source_id_idx": {
+          "name": "migration_profiles_source_id_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_profiles_source_id_migration_sources_id_fk": {
+          "name": "migration_profiles_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_profiles_created_by_user_id_users_id_fk": {
+          "name": "migration_profiles_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_profiles",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "migration_profiles_id_source_id_unique": {
+          "name": "migration_profiles_id_source_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "source_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "migration_profiles_version_positive_chk": {
+          "name": "migration_profiles_version_positive_chk",
+          "value": "\"migration_profiles\".\"version\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_run_metrics": {
+      "name": "migration_run_metrics",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stage": {
+          "name": "stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "processed": {
+          "name": "processed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "imported": {
+          "name": "imported",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "skipped": {
+          "name": "skipped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "unresolved": {
+          "name": "unresolved",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "failed": {
+          "name": "failed",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_run_metrics_run_stage_entity_uidx": {
+          "name": "migration_run_metrics_run_stage_entity_uidx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "stage",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_run_metrics_run_id_idx": {
+          "name": "migration_run_metrics_run_id_idx",
+          "columns": [
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_run_metrics_run_id_migration_runs_id_fk": {
+          "name": "migration_run_metrics_run_id_migration_runs_id_fk",
+          "tableFrom": "migration_run_metrics",
+          "tableTo": "migration_runs",
+          "columnsFrom": ["run_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_run_metrics_processed_nonnegative_chk": {
+          "name": "migration_run_metrics_processed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"processed\" >= 0"
+        },
+        "migration_run_metrics_imported_nonnegative_chk": {
+          "name": "migration_run_metrics_imported_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"imported\" >= 0"
+        },
+        "migration_run_metrics_skipped_nonnegative_chk": {
+          "name": "migration_run_metrics_skipped_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"skipped\" >= 0"
+        },
+        "migration_run_metrics_unresolved_nonnegative_chk": {
+          "name": "migration_run_metrics_unresolved_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"unresolved\" >= 0"
+        },
+        "migration_run_metrics_failed_nonnegative_chk": {
+          "name": "migration_run_metrics_failed_nonnegative_chk",
+          "value": "\"migration_run_metrics\".\"failed\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_runs": {
+      "name": "migration_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_id": {
+          "name": "source_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "profile_id": {
+          "name": "profile_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plan_artifact_id": {
+          "name": "plan_artifact_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_key": {
+          "name": "target_key",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'bookorbit'"
+        },
+        "state": {
+          "name": "state",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "current_stage": {
+          "name": "current_stage",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by_user_id": {
+          "name": "triggered_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_runs_source_target_state_idx": {
+          "name": "migration_runs_source_target_state_idx",
+          "columns": [
+            {
+              "expression": "source_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "target_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_runs_state_idx": {
+          "name": "migration_runs_state_idx",
+          "columns": [
+            {
+              "expression": "state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_runs_source_id_migration_sources_id_fk": {
+          "name": "migration_runs_source_id_migration_sources_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_sources",
+          "columnsFrom": ["source_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_id_migration_profiles_id_fk": {
+          "name": "migration_runs_profile_id_migration_profiles_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk": {
+          "name": "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_triggered_by_user_id_users_id_fk": {
+          "name": "migration_runs_triggered_by_user_id_users_id_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "users",
+          "columnsFrom": ["triggered_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "migration_runs_profile_source_fk": {
+          "name": "migration_runs_profile_source_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_profiles",
+          "columnsFrom": ["profile_id", "source_id"],
+          "columnsTo": ["id", "source_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "migration_runs_plan_artifact_source_profile_fk": {
+          "name": "migration_runs_plan_artifact_source_profile_fk",
+          "tableFrom": "migration_runs",
+          "tableTo": "migration_plan_artifacts",
+          "columnsFrom": ["plan_artifact_id", "source_id", "profile_id"],
+          "columnsTo": ["id", "source_id", "profile_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        },
+        "migration_runs_started_before_ended_chk": {
+          "name": "migration_runs_started_before_ended_chk",
+          "value": "\"migration_runs\".\"ended_at\" is null or \"migration_runs\".\"started_at\" is null or \"migration_runs\".\"ended_at\" >= \"migration_runs\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.migration_sources": {
+      "name": "migration_sources",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_config": {
+          "name": "connection_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "capabilities": {
+          "name": "capabilities",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_validated_at": {
+          "name": "last_validated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "migration_sources_type_name_uidx": {
+          "name": "migration_sources_type_name_uidx",
+          "columns": [
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "migration_sources_created_by_user_id_users_id_fk": {
+          "name": "migration_sources_created_by_user_id_users_id_fk",
+          "tableFrom": "migration_sources",
+          "tableTo": "users",
+          "columnsFrom": ["created_by_user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.libraries": {
+      "name": "libraries",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cover_aspect_ratio": {
+          "name": "cover_aspect_ratio",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'2/3'"
+        },
+        "watch": {
+          "name": "watch",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "auto_scan_cron_expression": {
+          "name": "auto_scan_cron_expression",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_precedence": {
+          "name": "metadata_precedence",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"folderStructure\",\"embedded\",\"nfoFile\",\"opfFile\",\"sidecar\"]'::jsonb"
+        },
+        "format_priority": {
+          "name": "format_priority",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[\"epub\",\"pdf\",\"cbz\",\"cbr\",\"cb7\",\"mobi\",\"azw3\",\"azw\",\"fb2\",\"m4b\",\"mp3\",\"m4a\",\"opus\",\"ogg\",\"flac\"]'::jsonb"
+        },
+        "allowed_formats": {
+          "name": "allowed_formats",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "organization_mode": {
+          "name": "organization_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'book_per_folder'"
+        },
+        "exclude_patterns": {
+          "name": "exclude_patterns",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "double precision",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0.25
+        },
+        "mark_as_finished_percent_complete": {
+          "name": "mark_as_finished_percent_complete",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 98
+        },
+        "file_write_enabled": {
+          "name": "file_write_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_write_cover": {
+          "name": "file_write_write_cover",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_enabled": {
+          "name": "file_write_epub_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_epub_max_file_size_mb": {
+          "name": "file_write_epub_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_pdf_enabled": {
+          "name": "file_write_pdf_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "file_write_pdf_max_file_size_mb": {
+          "name": "file_write_pdf_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "file_write_cbx_enabled": {
+          "name": "file_write_cbx_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_cbx_max_file_size_mb": {
+          "name": "file_write_cbx_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_write_audio_enabled": {
+          "name": "file_write_audio_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_write_audio_max_file_size_mb": {
+          "name": "file_write_audio_max_file_size_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 500
+        },
+        "file_rename_enabled": {
+          "name": "file_rename_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_naming_pattern": {
+          "name": "file_naming_pattern",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_fetch_preferences": {
+          "name": "metadata_fetch_preferences",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_config": {
+          "name": "book_metadata_fetch_config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_run_at": {
+          "name": "book_metadata_fetch_last_run_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_metadata_fetch_last_queued_count": {
+          "name": "book_metadata_fetch_last_queued_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scan_mode": {
+          "name": "scan_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "poll_interval_seconds": {
+          "name": "poll_interval_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "default": 300
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "libraries_name_lower_uidx": {
+          "name": "libraries_name_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "libraries_display_order_nonnegative_chk": {
+          "name": "libraries_display_order_nonnegative_chk",
+          "value": "\"libraries\".\"display_order\" >= 0"
+        },
+        "libraries_organization_mode_chk": {
+          "name": "libraries_organization_mode_chk",
+          "value": "\"libraries\".\"organization_mode\" in ('book_per_folder', 'book_per_file')"
+        },
+        "libraries_reading_threshold_range_chk": {
+          "name": "libraries_reading_threshold_range_chk",
+          "value": "\"libraries\".\"reading_threshold\" >= 0 and \"libraries\".\"reading_threshold\" <= 100"
+        },
+        "libraries_mark_finished_percent_range_chk": {
+          "name": "libraries_mark_finished_percent_range_chk",
+          "value": "\"libraries\".\"mark_as_finished_percent_complete\" >= 0 and \"libraries\".\"mark_as_finished_percent_complete\" <= 100"
+        },
+        "libraries_scan_mode_chk": {
+          "name": "libraries_scan_mode_chk",
+          "value": "\"libraries\".\"scan_mode\" in ('auto', 'manual')"
+        },
+        "libraries_poll_interval_nonnegative_chk": {
+          "name": "libraries_poll_interval_nonnegative_chk",
+          "value": "\"libraries\".\"poll_interval_seconds\" is null or \"libraries\".\"poll_interval_seconds\" >= 0"
+        },
+        "libraries_file_write_epub_max_size_chk": {
+          "name": "libraries_file_write_epub_max_size_chk",
+          "value": "\"libraries\".\"file_write_epub_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_pdf_max_size_chk": {
+          "name": "libraries_file_write_pdf_max_size_chk",
+          "value": "\"libraries\".\"file_write_pdf_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_cbx_max_size_chk": {
+          "name": "libraries_file_write_cbx_max_size_chk",
+          "value": "\"libraries\".\"file_write_cbx_max_file_size_mb\" >= 1"
+        },
+        "libraries_file_write_audio_max_size_chk": {
+          "name": "libraries_file_write_audio_max_size_chk",
+          "value": "\"libraries\".\"file_write_audio_max_file_size_mb\" >= 1"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.library_folders": {
+      "name": "library_folders",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "path": {
+          "name": "path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "library_folders_library_id_idx": {
+          "name": "library_folders_library_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_folders_library_path_uidx": {
+          "name": "library_folders_library_path_uidx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_folders_library_id_libraries_id_fk": {
+          "name": "library_folders_library_id_libraries_id_fk",
+          "tableFrom": "library_folders",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "library_folders_id_library_id_unique": {
+          "name": "library_folders_id_library_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_files": {
+      "name": "book_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rel_path": {
+          "name": "rel_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ino": {
+          "name": "ino",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "mtime": {
+          "name": "mtime",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "role": {
+          "name": "role",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'content'"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_files_absolute_path_uidx": {
+          "name": "book_files_absolute_path_uidx",
+          "columns": [
+            {
+              "expression": "absolute_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_book_id_idx": {
+          "name": "book_files_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_id_idx": {
+          "name": "book_files_library_folder_id_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_file_hash_idx": {
+          "name": "book_files_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_ino_idx": {
+          "name": "book_files_ino_idx",
+          "columns": [
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_format_idx": {
+          "name": "book_files_format_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_file_hash_idx": {
+          "name": "book_files_library_folder_file_hash_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_files_library_folder_ino_idx": {
+          "name": "book_files_library_folder_ino_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ino",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_files_book_id_books_id_fk": {
+          "name": "book_files_book_id_books_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_library_folder_id_library_folders_id_fk": {
+          "name": "book_files_library_folder_id_library_folders_id_fk",
+          "tableFrom": "book_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_files_book_folder_consistency_fk": {
+          "name": "book_files_book_folder_consistency_fk",
+          "tableFrom": "book_files",
+          "tableTo": "books",
+          "columnsFrom": ["book_id", "library_folder_id"],
+          "columnsTo": ["id", "library_folder_id"],
+          "onDelete": "no action",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_files_role_chk": {
+          "name": "book_files_role_chk",
+          "value": "\"book_files\".\"role\" in ('content', 'cover', 'metadata', 'supplement')"
+        },
+        "book_files_size_bytes_nonnegative_chk": {
+          "name": "book_files_size_bytes_nonnegative_chk",
+          "value": "\"book_files\".\"size_bytes\" is null or \"book_files\".\"size_bytes\" >= 0"
+        },
+        "book_files_duration_seconds_nonnegative_chk": {
+          "name": "book_files_duration_seconds_nonnegative_chk",
+          "value": "\"book_files\".\"duration_seconds\" is null or \"book_files\".\"duration_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.books": {
+      "name": "books",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "primary_file_id": {
+          "name": "primary_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "primary_author_sort_name": {
+          "name": "primary_author_sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "folder_path": {
+          "name": "folder_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'present'"
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "books_library_id_folder_path_idx": {
+          "name": "books_library_id_folder_path_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "folder_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_primary_file_id_idx": {
+          "name": "books_primary_file_id_idx",
+          "columns": [
+            {
+              "expression": "primary_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_status_idx": {
+          "name": "books_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_added_at_idx": {
+          "name": "books_library_added_at_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_visible_added_id_idx": {
+          "name": "books_library_visible_added_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"added_at\" desc",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"books\".\"status\" <> 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_author_sort_id_idx": {
+          "name": "books_library_author_sort_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"primary_author_sort_name\" asc nulls last",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"books\".\"status\" <> 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "books_library_author_sort_desc_id_idx": {
+          "name": "books_library_author_sort_desc_id_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "\"primary_author_sort_name\" desc nulls last",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"books\".\"status\" <> 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "books_library_id_libraries_id_fk": {
+          "name": "books_library_id_libraries_id_fk",
+          "tableFrom": "books",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_id_library_folders_id_fk": {
+          "name": "books_library_folder_id_library_folders_id_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "books_primary_file_id_book_files_id_fk": {
+          "name": "books_primary_file_id_book_files_id_fk",
+          "tableFrom": "books",
+          "tableTo": "book_files",
+          "columnsFrom": ["primary_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "books_library_folder_library_fk": {
+          "name": "books_library_folder_library_fk",
+          "tableFrom": "books",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id", "library_id"],
+          "columnsTo": ["id", "library_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "books_id_library_folder_id_unique": {
+          "name": "books_id_library_folder_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "library_folder_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "books_status_chk": {
+          "name": "books_status_chk",
+          "value": "\"books\".\"status\" in ('present', 'missing', 'processing')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.collection_books": {
+      "name": "collection_books",
+      "schema": "",
+      "columns": {
+        "collection_id": {
+          "name": "collection_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_at": {
+          "name": "added_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collection_books_book_id_idx": {
+          "name": "collection_books_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collection_books_collection_id_collections_id_fk": {
+          "name": "collection_books_collection_id_collections_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "collections",
+          "columnsFrom": ["collection_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "collection_books_book_id_books_id_fk": {
+          "name": "collection_books_book_id_books_id_fk",
+          "tableFrom": "collection_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "collection_books_collection_id_book_id_pk": {
+          "name": "collection_books_collection_id_book_id_pk",
+          "columns": ["collection_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.collections": {
+      "name": "collections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_to_kobo": {
+          "name": "sync_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "collections_user_name_uidx": {
+          "name": "collections_user_name_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "collections_user_display_name_idx": {
+          "name": "collections_user_display_name_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "collections_user_id_users_id_fk": {
+          "name": "collections_user_id_users_id_fk",
+          "tableFrom": "collections",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.smart_scopes": {
+      "name": "smart_scopes",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "filter": {
+          "name": "filter",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_sort": {
+          "name": "default_sort",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "is_public": {
+          "name": "is_public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "smart_scopes_user_id_users_id_fk": {
+          "name": "smart_scopes_user_id_users_id_fk",
+          "tableFrom": "smart_scopes",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "smart_scopes_user_id_name_unique": {
+          "name": "smart_scopes_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series": {
+      "name": "book_series",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "normalized_name": {
+          "name": "normalized_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_normalized_name_uidx": {
+          "name": "book_series_normalized_name_uidx",
+          "columns": [
+            {
+              "expression": "normalized_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_name_trgm_idx": {
+          "name": "book_series_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "book_series_name_lower_idx": {
+          "name": "book_series_name_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"name\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_series_memberships": {
+      "name": "book_series_memberships",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_series_memberships_book_display_uidx": {
+          "name": "book_series_memberships_book_display_uidx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_memberships_series_index_book_idx": {
+          "name": "book_series_memberships_series_index_book_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_series_memberships_book_display_idx": {
+          "name": "book_series_memberships_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_series_memberships_book_id_books_id_fk": {
+          "name": "book_series_memberships_book_id_books_id_fk",
+          "tableFrom": "book_series_memberships",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_series_memberships_series_id_book_series_id_fk": {
+          "name": "book_series_memberships_series_id_book_series_id_fk",
+          "tableFrom": "book_series_memberships",
+          "tableTo": "book_series",
+          "columnsFrom": ["series_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_series_memberships_book_id_series_id_pk": {
+          "name": "book_series_memberships_book_id_series_id_pk",
+          "columns": ["book_id", "series_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_series_memberships_display_order_nonnegative_chk": {
+          "name": "book_series_memberships_display_order_nonnegative_chk",
+          "value": "\"book_series_memberships\".\"display_order\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.author_enrichment_queue": {
+      "name": "author_enrichment_queue",
+      "schema": "",
+      "columns": {
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unknown'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_success_at": {
+          "name": "last_success_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "author_enrichment_queue_status_next_attempt_idx": {
+          "name": "author_enrichment_queue_status_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_next_attempt_idx": {
+          "name": "author_enrichment_queue_next_attempt_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "author_enrichment_queue_single_processing_idx": {
+          "name": "author_enrichment_queue_single_processing_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"author_enrichment_queue\".\"status\" = 'processing'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "author_enrichment_queue_author_id_authors_id_fk": {
+          "name": "author_enrichment_queue_author_id_authors_id_fk",
+          "tableFrom": "author_enrichment_queue",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "author_enrichment_queue_status_chk": {
+          "name": "author_enrichment_queue_status_chk",
+          "value": "\"author_enrichment_queue\".\"status\" in ('queued', 'processing', 'rate_limited', 'failed', 'done')"
+        },
+        "author_enrichment_queue_reason_chk": {
+          "name": "author_enrichment_queue_reason_chk",
+          "value": "\"author_enrichment_queue\".\"reason\" in ('unknown', 'metadata_replace', 'manual_backfill', 'manual_backfill_all', 'author_rename', 'author_merge_target')"
+        },
+        "author_enrichment_queue_attempt_count_nonnegative_chk": {
+          "name": "author_enrichment_queue_attempt_count_nonnegative_chk",
+          "value": "\"author_enrichment_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.authors": {
+      "name": "authors",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "has_photo": {
+          "name": "has_photo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "last_enriched_at": {
+          "name": "last_enriched_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "authors_name_trgm_idx": {
+          "name": "authors_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "authors_name_unique": {
+          "name": "authors_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_authors": {
+      "name": "book_authors",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "author_id": {
+          "name": "author_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_authors_author_id_idx": {
+          "name": "book_authors_author_id_idx",
+          "columns": [
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_authors_book_display_idx": {
+          "name": "book_authors_book_display_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_authors_book_display_author_idx": {
+          "name": "book_authors_book_display_author_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "author_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_authors_book_id_books_id_fk": {
+          "name": "book_authors_book_id_books_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_authors_author_id_authors_id_fk": {
+          "name": "book_authors_author_id_authors_id_fk",
+          "tableFrom": "book_authors",
+          "tableTo": "authors",
+          "columnsFrom": ["author_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_authors_book_id_author_id_pk": {
+          "name": "book_authors_book_id_author_id_pk",
+          "columns": ["book_id", "author_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_genres": {
+      "name": "book_genres",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "genre_id": {
+          "name": "genre_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_genres_genre_id_idx": {
+          "name": "book_genres_genre_id_idx",
+          "columns": [
+            {
+              "expression": "genre_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_genres_book_id_books_id_fk": {
+          "name": "book_genres_book_id_books_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_genres_genre_id_genres_id_fk": {
+          "name": "book_genres_genre_id_genres_id_fk",
+          "tableFrom": "book_genres",
+          "tableTo": "genres",
+          "columnsFrom": ["genre_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_genres_book_id_genre_id_pk": {
+          "name": "book_genres_book_id_genre_id_pk",
+          "columns": ["book_id", "genre_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_metadata": {
+      "name": "book_metadata",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subtitle": {
+          "name": "subtitle",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn10": {
+          "name": "isbn10",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "isbn13": {
+          "name": "isbn13",
+          "type": "varchar(13)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "publisher": {
+          "name": "publisher",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_year": {
+          "name": "published_year",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "language": {
+          "name": "language",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_count": {
+          "name": "page_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_id": {
+          "name": "series_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_name": {
+          "name": "series_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "series_index": {
+          "name": "series_index",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_source": {
+          "name": "cover_source",
+          "type": "varchar(9)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "google_books_id": {
+          "name": "google_books_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "goodreads_id": {
+          "name": "goodreads_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "amazon_id": {
+          "name": "amazon_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_id": {
+          "name": "hardcover_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "open_library_id": {
+          "name": "open_library_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "itunes_id": {
+          "name": "itunes_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_id": {
+          "name": "kobo_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_score": {
+          "name": "metadata_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_metadata_fetch_at": {
+          "name": "last_metadata_fetch_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "embedding": {
+          "name": "embedding",
+          "type": "vector(256)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_written_at": {
+          "name": "last_written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "abridged": {
+          "name": "abridged",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "audible_id": {
+          "name": "audible_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "comicvine_id": {
+          "name": "comicvine_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ranobedb_id": {
+          "name": "ranobedb_id",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "lubimyczytac_id": {
+          "name": "lubimyczytac_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "aladin_id": {
+          "name": "aladin_id",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapters": {
+          "name": "chapters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "locked_fields": {
+          "name": "locked_fields",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bm_title_trgm_idx": {
+          "name": "bm_title_trgm_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_title_lower_idx": {
+          "name": "bm_title_lower_idx",
+          "columns": [
+            {
+              "expression": "lower(\"title\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_title_book_id_idx": {
+          "name": "bm_title_book_id_idx",
+          "columns": [
+            {
+              "expression": "title",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_trgm_idx": {
+          "name": "bm_series_trgm_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_series_id_idx": {
+          "name": "bm_series_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_id_index_book_id_idx": {
+          "name": "bm_series_id_index_book_id_idx",
+          "columns": [
+            {
+              "expression": "series_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_lower_btrim_idx": {
+          "name": "bm_series_name_lower_btrim_idx",
+          "columns": [
+            {
+              "expression": "lower(btrim(\"series_name\"))",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_publisher_trgm_idx": {
+          "name": "bm_publisher_trgm_idx",
+          "columns": [
+            {
+              "expression": "publisher",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_language_idx": {
+          "name": "bm_language_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_language_trgm_idx": {
+          "name": "bm_language_trgm_idx",
+          "columns": [
+            {
+              "expression": "language",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        },
+        "bm_published_year_idx": {
+          "name": "bm_published_year_idx",
+          "columns": [
+            {
+              "expression": "published_year",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_series_name_index_idx": {
+          "name": "bm_series_name_index_idx",
+          "columns": [
+            {
+              "expression": "series_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "series_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn10_idx": {
+          "name": "bm_isbn10_idx",
+          "columns": [
+            {
+              "expression": "isbn10",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_isbn13_idx": {
+          "name": "bm_isbn13_idx",
+          "columns": [
+            {
+              "expression": "isbn13",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bm_embedding_hnsw_cosine_idx": {
+          "name": "bm_embedding_hnsw_cosine_idx",
+          "columns": [
+            {
+              "expression": "\"embedding\" vector_cosine_ops",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "hnsw",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_book_id_books_id_fk": {
+          "name": "book_metadata_book_id_books_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_metadata_series_id_book_series_id_fk": {
+          "name": "book_metadata_series_id_book_series_id_fk",
+          "tableFrom": "book_metadata",
+          "tableTo": "book_series",
+          "columnsFrom": ["series_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_rating_range_chk": {
+          "name": "book_metadata_rating_range_chk",
+          "value": "\"book_metadata\".\"rating\" is null or (\"book_metadata\".\"rating\" >= 1 and \"book_metadata\".\"rating\" <= 10)"
+        },
+        "book_metadata_published_year_range_chk": {
+          "name": "book_metadata_published_year_range_chk",
+          "value": "\"book_metadata\".\"published_year\" is null or (\"book_metadata\".\"published_year\" >= 1000 and \"book_metadata\".\"published_year\" <= 2200)"
+        },
+        "book_metadata_page_count_nonnegative_chk": {
+          "name": "book_metadata_page_count_nonnegative_chk",
+          "value": "\"book_metadata\".\"page_count\" is null or \"book_metadata\".\"page_count\" >= 0"
+        },
+        "book_metadata_duration_seconds_nonnegative_chk": {
+          "name": "book_metadata_duration_seconds_nonnegative_chk",
+          "value": "\"book_metadata\".\"duration_seconds\" is null or \"book_metadata\".\"duration_seconds\" >= 0"
+        },
+        "book_metadata_cover_source_chk": {
+          "name": "book_metadata_cover_source_chk",
+          "value": "\"book_metadata\".\"cover_source\" is null or \"book_metadata\".\"cover_source\" in ('extracted', 'custom')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_metadata_fetch_queue": {
+      "name": "book_metadata_fetch_queue",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'manual_trigger'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_attempt_at": {
+          "name": "last_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_http_status": {
+          "name": "last_http_status",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bmfq_status_idx": {
+          "name": "bmfq_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_created_at_idx": {
+          "name": "bmfq_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bmfq_status_created_book_idx": {
+          "name": "bmfq_status_created_book_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_metadata_fetch_queue_book_id_books_id_fk": {
+          "name": "book_metadata_fetch_queue_book_id_books_id_fk",
+          "tableFrom": "book_metadata_fetch_queue",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_metadata_fetch_queue_status_chk": {
+          "name": "book_metadata_fetch_queue_status_chk",
+          "value": "\"book_metadata_fetch_queue\".\"status\" in ('queued', 'processing', 'failed')"
+        },
+        "book_metadata_fetch_queue_reason_chk": {
+          "name": "book_metadata_fetch_queue_reason_chk",
+          "value": "\"book_metadata_fetch_queue\".\"reason\" in ('event_import', 'manual_trigger', 'manual_retry')"
+        },
+        "book_metadata_fetch_queue_attempt_count_nonnegative_chk": {
+          "name": "book_metadata_fetch_queue_attempt_count_nonnegative_chk",
+          "value": "\"book_metadata_fetch_queue\".\"attempt_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_tags": {
+      "name": "book_tags",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tag_id": {
+          "name": "tag_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "book_tags_tag_id_idx": {
+          "name": "book_tags_tag_id_idx",
+          "columns": [
+            {
+              "expression": "tag_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_tags_book_id_books_id_fk": {
+          "name": "book_tags_book_id_books_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_tags_tag_id_tags_id_fk": {
+          "name": "book_tags_tag_id_tags_id_fk",
+          "tableFrom": "book_tags",
+          "tableTo": "tags",
+          "columnsFrom": ["tag_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_tags_book_id_tag_id_pk": {
+          "name": "book_tags_book_id_tag_id_pk",
+          "columns": ["book_id", "tag_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.genres": {
+      "name": "genres",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "genres_name_trgm_idx": {
+          "name": "genres_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "genres_name_unique": {
+          "name": "genres_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.tags": {
+      "name": "tags",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "tags_name_trgm_idx": {
+          "name": "tags_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "tags_name_unique": {
+          "name": "tags_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_narrators": {
+      "name": "book_narrators",
+      "schema": "",
+      "columns": {
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "narrator_id": {
+          "name": "narrator_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        }
+      },
+      "indexes": {
+        "book_narrators_narrator_id_idx": {
+          "name": "book_narrators_narrator_id_idx",
+          "columns": [
+            {
+              "expression": "narrator_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_narrators_book_id_books_id_fk": {
+          "name": "book_narrators_book_id_books_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "book_narrators_narrator_id_narrators_id_fk": {
+          "name": "book_narrators_narrator_id_narrators_id_fk",
+          "tableFrom": "book_narrators",
+          "tableTo": "narrators",
+          "columnsFrom": ["narrator_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "book_narrators_book_id_narrator_id_pk": {
+          "name": "book_narrators_book_id_narrator_id_pk",
+          "columns": ["book_id", "narrator_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.narrators": {
+      "name": "narrators",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_name": {
+          "name": "sort_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "narrators_name_trgm_idx": {
+          "name": "narrators_name_trgm_idx",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last",
+              "opclass": "gin_trgm_ops"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "narrators_name_unique": {
+          "name": "narrators_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.library_dir_scan_state": {
+      "name": "library_dir_scan_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_folder_id": {
+          "name": "library_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dir_path": {
+          "name": "dir_path",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_seen_mtime_ms": {
+          "name": "last_seen_mtime_ms",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "library_dir_scan_state_folder_dir_uidx": {
+          "name": "library_dir_scan_state_folder_dir_uidx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "dir_path",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "library_dir_scan_state_folder_idx": {
+          "name": "library_dir_scan_state_folder_idx",
+          "columns": [
+            {
+              "expression": "library_folder_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "library_dir_scan_state_library_folder_id_library_folders_id_fk": {
+          "name": "library_dir_scan_state_library_folder_id_library_folders_id_fk",
+          "tableFrom": "library_dir_scan_state",
+          "tableTo": "library_folders",
+          "columnsFrom": ["library_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.scan_jobs": {
+      "name": "scan_jobs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'running'"
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "added_count": {
+          "name": "added_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_count": {
+          "name": "updated_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "missing_count": {
+          "name": "missing_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "scan_jobs_library_status_idx": {
+          "name": "scan_jobs_library_status_idx",
+          "columns": [
+            {
+              "expression": "library_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "scan_jobs_library_id_libraries_id_fk": {
+          "name": "scan_jobs_library_id_libraries_id_fk",
+          "tableFrom": "scan_jobs",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "scan_jobs_status_chk": {
+          "name": "scan_jobs_status_chk",
+          "value": "\"scan_jobs\".\"status\" in ('running', 'completed', 'failed')"
+        },
+        "scan_jobs_triggered_by_chk": {
+          "name": "scan_jobs_triggered_by_chk",
+          "value": "\"scan_jobs\".\"triggered_by\" in ('manual', 'watcher', 'schedule')"
+        },
+        "scan_jobs_added_count_nonnegative_chk": {
+          "name": "scan_jobs_added_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"added_count\" >= 0"
+        },
+        "scan_jobs_updated_count_nonnegative_chk": {
+          "name": "scan_jobs_updated_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"updated_count\" >= 0"
+        },
+        "scan_jobs_missing_count_nonnegative_chk": {
+          "name": "scan_jobs_missing_count_nonnegative_chk",
+          "value": "\"scan_jobs\".\"missing_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_positions": {
+      "name": "annotation_positions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(12)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "pos0": {
+          "name": "pos0",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pos1": {
+          "name": "pos1",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'exact'"
+        },
+        "converter_version": {
+          "name": "converter_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "extras": {
+          "name": "extras",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_positions_annotation_format_uidx": {
+          "name": "annotation_positions_annotation_format_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_user_idx": {
+          "name": "annotation_positions_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_positions_format_status_idx": {
+          "name": "annotation_positions_format_status_idx",
+          "columns": [
+            {
+              "expression": "format",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_positions_annotation_id_annotations_id_fk": {
+          "name": "annotation_positions_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_user_id_users_id_fk": {
+          "name": "annotation_positions_user_id_users_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_positions_book_file_id_book_files_id_fk": {
+          "name": "annotation_positions_book_file_id_book_files_id_fk",
+          "tableFrom": "annotation_positions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_positions_format_chk": {
+          "name": "annotation_positions_format_chk",
+          "value": "\"annotation_positions\".\"format\" in ('cfi', 'xpointer', 'pdf', 'kobo_span')"
+        },
+        "annotation_positions_status_chk": {
+          "name": "annotation_positions_status_chk",
+          "value": "\"annotation_positions\".\"status\" in ('exact', 'repaired', 'failed', 'pending')"
+        },
+        "annotation_positions_pos0_chk": {
+          "name": "annotation_positions_pos0_chk",
+          "value": "\"annotation_positions\".\"status\" in ('failed', 'pending') or \"annotation_positions\".\"pos0\" is not null"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotation_sync_state": {
+      "name": "annotation_sync_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "annotation_id": {
+          "name": "annotation_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_key": {
+          "name": "external_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "external_created_at": {
+          "name": "external_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_applied_version": {
+          "name": "last_applied_version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "delete_acked_at": {
+          "name": "delete_acked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "first_synced_at": {
+          "name": "first_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotation_sync_state_annotation_source_device_uidx": {
+          "name": "annotation_sync_state_annotation_source_device_uidx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_source_device_key_idx": {
+          "name": "annotation_sync_state_user_source_device_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "source",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_user_key_idx": {
+          "name": "annotation_sync_state_user_key_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "external_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotation_sync_state_annotation_id_idx": {
+          "name": "annotation_sync_state_annotation_id_idx",
+          "columns": [
+            {
+              "expression": "annotation_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotation_sync_state_annotation_id_annotations_id_fk": {
+          "name": "annotation_sync_state_annotation_id_annotations_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "annotations",
+          "columnsFrom": ["annotation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotation_sync_state_user_id_users_id_fk": {
+          "name": "annotation_sync_state_user_id_users_id_fk",
+          "tableFrom": "annotation_sync_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotation_sync_state_source_chk": {
+          "name": "annotation_sync_state_source_chk",
+          "value": "\"annotation_sync_state\".\"source\" in ('koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.annotations": {
+      "name": "annotations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "text": {
+          "name": "text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'yellow'"
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'highlight'"
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_title": {
+          "name": "chapter_title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "origin": {
+          "name": "origin",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'web'"
+        },
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_created_at": {
+          "name": "device_created_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "device_updated_at": {
+          "name": "device_updated_at",
+          "type": "varchar(19)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "annotations_user_id_idx": {
+          "name": "annotations_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_idx": {
+          "name": "annotations_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "annotations_user_book_active_idx": {
+          "name": "annotations_user_book_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"annotations\".\"deleted_at\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "annotations_user_id_users_id_fk": {
+          "name": "annotations_user_id_users_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "annotations_book_id_books_id_fk": {
+          "name": "annotations_book_id_books_id_fk",
+          "tableFrom": "annotations",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "annotations_style_chk": {
+          "name": "annotations_style_chk",
+          "value": "\"annotations\".\"style\" in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')"
+        },
+        "annotations_origin_chk": {
+          "name": "annotations_origin_chk",
+          "value": "\"annotations\".\"origin\" in ('web', 'koreader', 'kobo')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.audiobook_progress": {
+      "name": "audiobook_progress",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "current_file_id": {
+          "name": "current_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "abp_user_id_idx": {
+          "name": "abp_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "audiobook_progress_user_id_users_id_fk": {
+          "name": "audiobook_progress_user_id_users_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_book_id_books_id_fk": {
+          "name": "audiobook_progress_book_id_books_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "audiobook_progress_current_file_id_book_files_id_fk": {
+          "name": "audiobook_progress_current_file_id_book_files_id_fk",
+          "tableFrom": "audiobook_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["current_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "audiobook_progress_user_id_book_id_pk": {
+          "name": "audiobook_progress_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "audiobook_progress_percentage_range_chk": {
+          "name": "audiobook_progress_percentage_range_chk",
+          "value": "\"audiobook_progress\".\"percentage\" >= 0 and \"audiobook_progress\".\"percentage\" <= 100"
+        },
+        "audiobook_progress_position_seconds_nonnegative_chk": {
+          "name": "audiobook_progress_position_seconds_nonnegative_chk",
+          "value": "\"audiobook_progress\".\"position_seconds\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.bookmarks": {
+      "name": "bookmarks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "bookmarks_user_book_idx": {
+          "name": "bookmarks_user_book_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_cfi_uidx": {
+          "name": "bookmarks_user_book_cfi_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "cfi",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"cfi\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "bookmarks_user_book_pos_uidx": {
+          "name": "bookmarks_user_book_pos_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "position_seconds",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"bookmarks\".\"position_seconds\" is not null and \"bookmarks\".\"cfi\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "bookmarks_user_id_users_id_fk": {
+          "name": "bookmarks_user_id_users_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "bookmarks_book_id_books_id_fk": {
+          "name": "bookmarks_book_id_books_id_fk",
+          "tableFrom": "bookmarks",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reader_default_preferences": {
+      "name": "reader_default_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format_group": {
+          "name": "format_group",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rdp_user_format_idx": {
+          "name": "rdp_user_format_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "format_group",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_default_preferences_user_id_users_id_fk": {
+          "name": "reader_default_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_default_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reader_default_preferences_format_group_chk": {
+          "name": "reader_default_preferences_format_group_chk",
+          "value": "\"reader_default_preferences\".\"format_group\" in ('epub', 'pdf', 'cbx', 'audio')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reader_preferences": {
+      "name": "reader_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "settings": {
+          "name": "settings",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "rp_user_file_idx": {
+          "name": "rp_user_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reader_preferences_user_id_users_id_fk": {
+          "name": "reader_preferences_user_id_users_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reader_preferences_book_file_id_book_files_id_fk": {
+          "name": "reader_preferences_book_file_id_book_files_id_fk",
+          "tableFrom": "reader_preferences",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.reading_progress": {
+      "name": "reading_progress",
+      "schema": "",
+      "columns": {
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "cfi": {
+          "name": "cfi",
+          "type": "varchar(2000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "position_seconds": {
+          "name": "position_seconds",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_source": {
+          "name": "kobo_location_source",
+          "type": "varchar(4096)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_type": {
+          "name": "kobo_location_type",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_location_value": {
+          "name": "kobo_location_value",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "kobo_content_source_progress_percent": {
+          "name": "kobo_content_source_progress_percent",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "koreader_progress": {
+          "name": "koreader_progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "reading_progress_user_id_idx": {
+          "name": "reading_progress_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "reading_progress_user_updated_at_idx": {
+          "name": "reading_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_progress_book_file_id_book_files_id_fk": {
+          "name": "reading_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_progress_user_id_users_id_fk": {
+          "name": "reading_progress_user_id_users_id_fk",
+          "tableFrom": "reading_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "reading_progress_book_file_id_user_id_pk": {
+          "name": "reading_progress_book_file_id_user_id_pk",
+          "columns": ["book_file_id", "user_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_progress_percentage_range_chk": {
+          "name": "reading_progress_percentage_range_chk",
+          "value": "\"reading_progress\".\"percentage\" >= 0 and \"reading_progress\".\"percentage\" <= 100"
+        },
+        "reading_progress_page_number_nonnegative_chk": {
+          "name": "reading_progress_page_number_nonnegative_chk",
+          "value": "\"reading_progress\".\"page_number\" is null or \"reading_progress\".\"page_number\" >= 0"
+        },
+        "reading_progress_position_seconds_nonnegative_chk": {
+          "name": "reading_progress_position_seconds_nonnegative_chk",
+          "value": "\"reading_progress\".\"position_seconds\" is null or \"reading_progress\".\"position_seconds\" >= 0"
+        },
+        "reading_progress_kobo_content_source_progress_range_chk": {
+          "name": "reading_progress_kobo_content_source_progress_range_chk",
+          "value": "\"reading_progress\".\"kobo_content_source_progress_percent\" is null or (\"reading_progress\".\"kobo_content_source_progress_percent\" >= 0 and \"reading_progress\".\"kobo_content_source_progress_percent\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.reading_sessions": {
+      "name": "reading_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "end_progress": {
+          "name": "end_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "rs_user_session_id_uidx": {
+          "name": "rs_user_session_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_started_at_idx": {
+          "name": "rs_user_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_book_file_started_at_idx": {
+          "name": "rs_book_file_started_at_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_file_idx": {
+          "name": "rs_user_book_file_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rs_user_book_started_at_idx": {
+          "name": "rs_user_book_started_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "started_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "reading_sessions_user_id_users_id_fk": {
+          "name": "reading_sessions_user_id_users_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_file_id_book_files_id_fk": {
+          "name": "reading_sessions_book_file_id_book_files_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "reading_sessions_book_id_books_id_fk": {
+          "name": "reading_sessions_book_id_books_id_fk",
+          "tableFrom": "reading_sessions",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "reading_sessions_source_chk": {
+          "name": "reading_sessions_source_chk",
+          "value": "\"reading_sessions\".\"source\" in ('web', 'koreader', 'manual', 'kobo')"
+        },
+        "reading_sessions_duration_seconds_nonnegative_chk": {
+          "name": "reading_sessions_duration_seconds_nonnegative_chk",
+          "value": "\"reading_sessions\".\"duration_seconds\" >= 0"
+        },
+        "reading_sessions_end_progress_range_chk": {
+          "name": "reading_sessions_end_progress_range_chk",
+          "value": "\"reading_sessions\".\"end_progress\" is null or (\"reading_sessions\".\"end_progress\" >= 0 and \"reading_sessions\".\"end_progress\" <= 100)"
+        },
+        "reading_sessions_ended_after_started_chk": {
+          "name": "reading_sessions_ended_after_started_chk",
+          "value": "\"reading_sessions\".\"ended_at\" >= \"reading_sessions\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_ratings": {
+      "name": "user_book_ratings",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rating": {
+          "name": "rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubr_user_id_idx": {
+          "name": "ubr_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_id_idx": {
+          "name": "ubr_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubr_book_user_rating_idx": {
+          "name": "ubr_book_user_rating_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_ratings_user_id_users_id_fk": {
+          "name": "user_book_ratings_user_id_users_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_ratings_book_id_books_id_fk": {
+          "name": "user_book_ratings_book_id_books_id_fk",
+          "tableFrom": "user_book_ratings",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_ratings_user_id_book_id_pk": {
+          "name": "user_book_ratings_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_ratings_rating_range_chk": {
+          "name": "user_book_ratings_rating_range_chk",
+          "value": "\"user_book_ratings\".\"rating\" >= 1 and \"user_book_ratings\".\"rating\" <= 5"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_book_status": {
+      "name": "user_book_status",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'unread'"
+        },
+        "source": {
+          "name": "source",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'auto'"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "ubs_user_id_idx": {
+          "name": "ubs_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_user_status_idx": {
+          "name": "ubs_user_status_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "ubs_book_user_idx": {
+          "name": "ubs_book_user_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_book_status_user_id_users_id_fk": {
+          "name": "user_book_status_user_id_users_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_book_status_book_id_books_id_fk": {
+          "name": "user_book_status_book_id_books_id_fk",
+          "tableFrom": "user_book_status",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_book_status_user_id_book_id_pk": {
+          "name": "user_book_status_user_id_book_id_pk",
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_book_status_status_chk": {
+          "name": "user_book_status_status_chk",
+          "value": "\"user_book_status\".\"status\" in ('unread', 'want_to_read', 'reading', 'on_hold', 'rereading', 'read', 'skimmed', 'abandoned')"
+        },
+        "user_book_status_source_chk": {
+          "name": "user_book_status_source_chk",
+          "value": "\"user_book_status\".\"source\" in ('auto', 'manual')"
+        },
+        "user_book_status_finished_after_started_chk": {
+          "name": "user_book_status_finished_after_started_chk",
+          "value": "\"user_book_status\".\"finished_at\" is null or \"user_book_status\".\"started_at\" is null or \"user_book_status\".\"finished_at\" >= \"user_book_status\".\"started_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_reading_daily_stats": {
+      "name": "user_reading_daily_stats",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "library_id": {
+          "name": "library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "day": {
+          "name": "day",
+          "type": "date",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_seconds": {
+          "name": "reading_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "progress_delta": {
+          "name": "progress_delta",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "sessions_count": {
+          "name": "sessions_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "urds_user_day_idx": {
+          "name": "urds_user_day_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "day",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_reading_daily_stats_user_id_users_id_fk": {
+          "name": "user_reading_daily_stats_user_id_users_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_reading_daily_stats_library_id_libraries_id_fk": {
+          "name": "user_reading_daily_stats_library_id_libraries_id_fk",
+          "tableFrom": "user_reading_daily_stats",
+          "tableTo": "libraries",
+          "columnsFrom": ["library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "user_reading_daily_stats_user_id_library_id_day_pk": {
+          "name": "user_reading_daily_stats_user_id_library_id_day_pk",
+          "columns": ["user_id", "library_id", "day"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_reading_daily_stats_reading_seconds_nonnegative_chk": {
+          "name": "user_reading_daily_stats_reading_seconds_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"reading_seconds\" >= 0"
+        },
+        "user_reading_daily_stats_sessions_count_nonnegative_chk": {
+          "name": "user_reading_daily_stats_sessions_count_nonnegative_chk",
+          "value": "\"user_reading_daily_stats\".\"sessions_count\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.oidc_group_mappings": {
+      "name": "oidc_group_mappings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_group_claim": {
+          "name": "oidc_group_claim",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_group_mappings_provider_claim_uidx": {
+          "name": "oidc_group_mappings_provider_claim_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_group_claim",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_group_mappings_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_group_mappings_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_group_mappings",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_identities": {
+      "name": "oidc_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "linked_at": {
+          "name": "linked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_identities_provider_subject_uidx": {
+          "name": "oidc_identities_provider_subject_uidx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_provider_uidx": {
+          "name": "oidc_identities_user_provider_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_issuer_subject_uidx": {
+          "name": "oidc_identities_issuer_subject_uidx",
+          "columns": [
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_identities_user_id_idx": {
+          "name": "oidc_identities_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_identities_user_id_users_id_fk": {
+          "name": "oidc_identities_user_id_users_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_identities_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_identities_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_identities",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_permission_grants": {
+      "name": "oidc_permission_grants",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "permission_name": {
+          "name": "permission_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "oidc_permission_grants_user_id_users_id_fk": {
+          "name": "oidc_permission_grants_user_id_users_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_permission_grants_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_permission_grants_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_permission_grants",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "oidc_permission_grants_user_id_provider_id_permission_name_pk": {
+          "name": "oidc_permission_grants_user_id_provider_id_permission_name_pk",
+          "columns": ["user_id", "provider_id", "permission_name"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_providers": {
+      "name": "oidc_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "issuer_uri": {
+          "name": "issuer_uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'openid profile email'"
+        },
+        "icon_url": {
+          "name": "icon_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "claim_mapping": {
+          "name": "claim_mapping",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"username\":\"preferred_username\",\"name\":\"name\",\"email\":\"email\",\"groups\":\"groups\"}'::jsonb"
+        },
+        "auto_provision": {
+          "name": "auto_provision",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"enabled\":false,\"allowLocalLinking\":false,\"defaultPermissionNames\":[]}'::jsonb"
+        },
+        "display_order": {
+          "name": "display_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "oidc_providers_enabled_order_idx": {
+          "name": "oidc_providers_enabled_order_idx",
+          "columns": [
+            {
+              "expression": "enabled",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "display_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oidc_providers_slug_unique": {
+          "name": "oidc_providers_slug_unique",
+          "nullsNotDistinct": false,
+          "columns": ["slug"]
+        },
+        "oidc_providers_issuer_uri_unique": {
+          "name": "oidc_providers_issuer_uri_unique",
+          "nullsNotDistinct": false,
+          "columns": ["issuer_uri"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_sessions": {
+      "name": "oidc_sessions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_subject": {
+          "name": "oidc_subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "oidc_session_id": {
+          "name": "oidc_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token_hint": {
+          "name": "id_token_hint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_refresh_token": {
+          "name": "idp_refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_sessions_user_active_idx": {
+          "name": "oidc_sessions_user_active_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"oidc_sessions\".\"revoked\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_subject_issuer_idx": {
+          "name": "oidc_sessions_subject_issuer_idx",
+          "columns": [
+            {
+              "expression": "oidc_subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "oidc_issuer",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_sid_idx": {
+          "name": "oidc_sessions_sid_idx",
+          "columns": [
+            {
+              "expression": "oidc_session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_expires_at_idx": {
+          "name": "oidc_sessions_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oidc_sessions_provider_id_idx": {
+          "name": "oidc_sessions_provider_id_idx",
+          "columns": [
+            {
+              "expression": "provider_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_sessions_user_id_users_id_fk": {
+          "name": "oidc_sessions_user_id_users_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oidc_sessions_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_sessions_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_sessions",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_states": {
+      "name": "oidc_states",
+      "schema": "",
+      "columns": {
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "meta": {
+          "name": "meta",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oidc_states_expires_at_idx": {
+          "name": "oidc_states_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oidc_states_provider_id_oidc_providers_id_fk": {
+          "name": "oidc_states_provider_id_oidc_providers_id_fk",
+          "tableFrom": "oidc_states",
+          "tableTo": "oidc_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oidc_used_jtis": {
+      "name": "oidc_used_jtis",
+      "schema": "",
+      "columns": {
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oidc_used_jtis_expires_at_idx": {
+          "name": "oidc_used_jtis_expires_at_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.opds_users": {
+      "name": "opds_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "opds_sort_order",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'recent'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "opds_users_username_lower_uidx": {
+          "name": "opds_users_username_lower_uidx",
+          "columns": [
+            {
+              "expression": "lower(\"username\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "opds_users_user_id_users_id_fk": {
+          "name": "opds_users_user_id_users_id_fk",
+          "tableFrom": "opds_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "opds_users_username_unique": {
+          "name": "opds_users_username_unique",
+          "nullsNotDistinct": false,
+          "columns": ["username"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_book_entitlements": {
+      "name": "kobo_book_entitlements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "cover_image_id": {
+          "name": "cover_image_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "needs_legacy_numeric_removal": {
+          "name": "needs_legacy_numeric_removal",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_book_entitlements_user_id_idx": {
+          "name": "kobo_book_entitlements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kobo_book_entitlements_book_id_idx": {
+          "name": "kobo_book_entitlements_book_id_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_book_entitlements_user_id_users_id_fk": {
+          "name": "kobo_book_entitlements_user_id_users_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_book_entitlements_book_id_books_id_fk": {
+          "name": "kobo_book_entitlements_book_id_books_id_fk",
+          "tableFrom": "kobo_book_entitlements",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_book_entitlements_user_book_unique": {
+          "name": "kobo_book_entitlements_user_book_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        },
+        "kobo_book_entitlements_user_entitlement_unique": {
+          "name": "kobo_book_entitlements_user_entitlement_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "entitlement_id"]
+        },
+        "kobo_book_entitlements_user_cover_unique": {
+          "name": "kobo_book_entitlements_user_cover_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "cover_image_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_devices": {
+      "name": "kobo_devices",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_device_id": {
+          "name": "client_device_id",
+          "type": "varchar(128)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_seen_at": {
+          "name": "last_seen_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kobo_devices_user_id_idx": {
+          "name": "kobo_devices_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_devices_user_id_users_id_fk": {
+          "name": "kobo_devices_user_id_users_id_fk",
+          "tableFrom": "kobo_devices",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_devices_token_unique": {
+          "name": "kobo_devices_token_unique",
+          "nullsNotDistinct": false,
+          "columns": ["token"]
+        },
+        "kobo_devices_client_device_id_unique": {
+          "name": "kobo_devices_client_device_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["client_device_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_library_snapshots": {
+      "name": "kobo_library_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_library_snapshots_user_id_users_id_fk": {
+          "name": "kobo_library_snapshots_user_id_users_id_fk",
+          "tableFrom": "kobo_library_snapshots",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_library_snapshots_user_id_unique": {
+          "name": "kobo_library_snapshots_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_reading_states": {
+      "name": "kobo_reading_states",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entitlement_id": {
+          "name": "entitlement_id",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at_kobo": {
+          "name": "created_at_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_modified_kobo": {
+          "name": "last_modified_kobo",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "priority_timestamp": {
+          "name": "priority_timestamp",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "current_bookmark": {
+          "name": "current_bookmark",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "statistics": {
+          "name": "statistics",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_info": {
+          "name": "status_info",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_reading_states_user_id_users_id_fk": {
+          "name": "kobo_reading_states_user_id_users_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_reading_states_book_id_books_id_fk": {
+          "name": "kobo_reading_states_book_id_books_id_fk",
+          "tableFrom": "kobo_reading_states",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_reading_states_user_id_book_id_unique": {
+          "name": "kobo_reading_states_user_id_book_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_snapshot_books": {
+      "name": "kobo_snapshot_books",
+      "schema": "",
+      "columns": {
+        "snapshot_id": {
+          "name": "snapshot_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "synced": {
+          "name": "synced",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "pending_delete": {
+          "name": "pending_delete",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_new": {
+          "name": "is_new",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "removed_by_device": {
+          "name": "removed_by_device",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "delivery_hash": {
+          "name": "delivery_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_hash": {
+          "name": "metadata_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "kobo_snapshot_books_snapshot_synced_book_idx": {
+          "name": "kobo_snapshot_books_snapshot_synced_book_idx",
+          "columns": [
+            {
+              "expression": "snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "synced",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk": {
+          "name": "kobo_snapshot_books_snapshot_id_kobo_library_snapshots_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "kobo_library_snapshots",
+          "columnsFrom": ["snapshot_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "kobo_snapshot_books_book_id_books_id_fk": {
+          "name": "kobo_snapshot_books_book_id_books_id_fk",
+          "tableFrom": "kobo_snapshot_books",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "kobo_snapshot_books_snapshot_id_book_id_pk": {
+          "name": "kobo_snapshot_books_snapshot_id_book_id_pk",
+          "columns": ["snapshot_id", "book_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.kobo_sync_settings": {
+      "name": "kobo_sync_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reading_threshold": {
+          "name": "reading_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 1
+        },
+        "finished_threshold": {
+          "name": "finished_threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 99
+        },
+        "convert_to_kepub": {
+          "name": "convert_to_kepub",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "force_enable_hyphenation": {
+          "name": "force_enable_hyphenation",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "kepub_conversion_limit_mb": {
+          "name": "kepub_conversion_limit_mb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 100
+        },
+        "two_way_progress_sync": {
+          "name": "two_way_progress_sync",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sync_bookorbit_annotations_to_kobo": {
+          "name": "sync_bookorbit_annotations_to_kobo",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "kobo_sync_settings_user_id_users_id_fk": {
+          "name": "kobo_sync_settings_user_id_users_id_fk",
+          "tableFrom": "kobo_sync_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "kobo_sync_settings_user_id_unique": {
+          "name": "kobo_sync_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "kobo_sync_settings_reading_threshold_range_chk": {
+          "name": "kobo_sync_settings_reading_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"reading_threshold\" >= 0 and \"kobo_sync_settings\".\"reading_threshold\" <= 100"
+        },
+        "kobo_sync_settings_finished_threshold_range_chk": {
+          "name": "kobo_sync_settings_finished_threshold_range_chk",
+          "value": "\"kobo_sync_settings\".\"finished_threshold\" >= 0 and \"kobo_sync_settings\".\"finished_threshold\" <= 100"
+        },
+        "kobo_sync_settings_conversion_limit_nonnegative_chk": {
+          "name": "kobo_sync_settings_conversion_limit_nonnegative_chk",
+          "value": "\"kobo_sync_settings\".\"kepub_conversion_limit_mb\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_dock_files": {
+      "name": "book_dock_files",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "file_name": {
+          "name": "file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "absolute_path": {
+          "name": "absolute_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "embedded_metadata": {
+          "name": "embedded_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "selected_metadata": {
+          "name": "selected_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata": {
+          "name": "fetched_metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "cover_path": {
+          "name": "cover_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_library_id": {
+          "name": "target_library_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "target_folder_id": {
+          "name": "target_folder_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "fetched_metadata_sources": {
+          "name": "fetched_metadata_sources",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata_edited_at": {
+          "name": "metadata_edited_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uploaded_by": {
+          "name": "uploaded_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_dock_files_status_idx": {
+          "name": "book_dock_files_status_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_dock_files_uploaded_by_idx": {
+          "name": "book_dock_files_uploaded_by_idx",
+          "columns": [
+            {
+              "expression": "uploaded_by",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_dock_files_target_library_id_libraries_id_fk": {
+          "name": "book_dock_files_target_library_id_libraries_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "libraries",
+          "columnsFrom": ["target_library_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_target_folder_id_library_folders_id_fk": {
+          "name": "book_dock_files_target_folder_id_library_folders_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "library_folders",
+          "columnsFrom": ["target_folder_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "book_dock_files_uploaded_by_users_id_fk": {
+          "name": "book_dock_files_uploaded_by_users_id_fk",
+          "tableFrom": "book_dock_files",
+          "tableTo": "users",
+          "columnsFrom": ["uploaded_by"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "book_dock_files_absolute_path_unique": {
+          "name": "book_dock_files_absolute_path_unique",
+          "nullsNotDistinct": false,
+          "columns": ["absolute_path"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "book_dock_files_status_chk": {
+          "name": "book_dock_files_status_chk",
+          "value": "\"book_dock_files\".\"status\" in ('pending', 'extracting', 'fetching', 'ready', 'error')"
+        },
+        "book_dock_files_confidence_range_chk": {
+          "name": "book_dock_files_confidence_range_chk",
+          "value": "\"book_dock_files\".\"confidence\" is null or (\"book_dock_files\".\"confidence\" >= 0 and \"book_dock_files\".\"confidence\" <= 100)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.file_write_log": {
+      "name": "file_write_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fields_written": {
+          "name": "fields_written",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "triggered_by": {
+          "name": "triggered_by",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "written_at": {
+          "name": "written_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "fwl_book_id_written_at_idx": {
+          "name": "fwl_book_id_written_at_idx",
+          "columns": [
+            {
+              "expression": "book_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "written_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "file_write_log_book_id_books_id_fk": {
+          "name": "file_write_log_book_id_books_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "file_write_log_book_file_id_book_files_id_fk": {
+          "name": "file_write_log_book_file_id_book_files_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "file_write_log_user_id_users_id_fk": {
+          "name": "file_write_log_user_id_users_id_fk",
+          "tableFrom": "file_write_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "file_write_log_status_chk": {
+          "name": "file_write_log_status_chk",
+          "value": "\"file_write_log\".\"status\" in ('success', 'skipped', 'failed')"
+        },
+        "file_write_log_triggered_by_chk": {
+          "name": "file_write_log_triggered_by_chk",
+          "value": "\"file_write_log\".\"triggered_by\" in ('auto', 'sync')"
+        },
+        "file_write_log_duration_ms_nonnegative_chk": {
+          "name": "file_write_log_duration_ms_nonnegative_chk",
+          "value": "\"file_write_log\".\"duration_ms\" is null or \"file_write_log\".\"duration_ms\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_templates": {
+      "name": "email_templates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body_text": {
+          "name": "body_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system": {
+          "name": "is_system",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_templates_one_default_per_user_uidx": {
+          "name": "email_templates_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"is_default\" = true and \"email_templates\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_templates_system_name_unique": {
+          "name": "email_templates_system_name_unique",
+          "columns": [
+            {
+              "expression": "name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_templates\".\"user_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_templates_user_id_users_id_fk": {
+          "name": "email_templates_user_id_users_id_fk",
+          "tableFrom": "email_templates",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_templates_user_id_name_unique": {
+          "name": "email_templates_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_providers": {
+      "name": "email_providers",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "host": {
+          "name": "host",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "port": {
+          "name": "port",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password_enc": {
+          "name": "password_enc",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_name": {
+          "name": "from_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "from_address": {
+          "name": "from_address",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth": {
+          "name": "auth",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "ssl": {
+          "name": "ssl",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "start_tls": {
+          "name": "start_tls",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_shared": {
+          "name": "is_shared",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "is_system_provider": {
+          "name": "is_system_provider",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "tls_reject_unauthorized": {
+          "name": "tls_reject_unauthorized",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_providers_one_default_per_user_uidx": {
+          "name": "email_providers_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_default\" = true and \"email_providers\".\"user_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_providers_one_system_provider_uidx": {
+          "name": "email_providers_one_system_provider_uidx",
+          "columns": [
+            {
+              "expression": "is_system_provider",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_providers\".\"is_system_provider\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_providers_user_id_users_id_fk": {
+          "name": "email_providers_user_id_users_id_fk",
+          "tableFrom": "email_providers",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_providers_user_id_name_unique": {
+          "name": "email_providers_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_providers_id_user_id_unique": {
+          "name": "email_providers_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_providers_port_range_chk": {
+          "name": "email_providers_port_range_chk",
+          "value": "\"email_providers\".\"port\" >= 1 and \"email_providers\".\"port\" <= 65535"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_group_members": {
+      "name": "email_recipient_group_members",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "recipient_id": {
+          "name": "recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_group_members_user_id_users_id_fk": {
+          "name": "email_recipient_group_members_user_id_users_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_id_email_recipient_groups_id_fk": {
+          "name": "email_recipient_group_members_group_id_email_recipient_groups_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_id_email_recipients_id_fk": {
+          "name": "email_recipient_group_members_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_group_user_fk": {
+          "name": "email_recipient_group_members_group_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipient_groups",
+          "columnsFrom": ["group_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        },
+        "email_recipient_group_members_recipient_user_fk": {
+          "name": "email_recipient_group_members_recipient_user_fk",
+          "tableFrom": "email_recipient_group_members",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "email_recipient_group_members_group_id_recipient_id_pk": {
+          "name": "email_recipient_group_members_group_id_recipient_id_pk",
+          "columns": ["group_id", "recipient_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipient_groups": {
+      "name": "email_recipient_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_recipient_groups_user_id_users_id_fk": {
+          "name": "email_recipient_groups_user_id_users_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipient_groups_default_template_id_email_templates_id_fk": {
+          "name": "email_recipient_groups_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipient_groups",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipient_groups_user_id_name_unique": {
+          "name": "email_recipient_groups_user_id_name_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "name"]
+        },
+        "email_recipient_groups_id_user_id_unique": {
+          "name": "email_recipient_groups_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_recipients": {
+      "name": "email_recipients",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "is_default": {
+          "name": "is_default",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "device_type": {
+          "name": "device_type",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "preferred_format": {
+          "name": "preferred_format",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_recipients_user_email_lower_uidx": {
+          "name": "email_recipients_user_email_lower_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"email\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_recipients_one_default_per_user_uidx": {
+          "name": "email_recipients_one_default_per_user_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"email_recipients\".\"is_default\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_recipients_user_id_users_id_fk": {
+          "name": "email_recipients_user_id_users_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_recipients_default_template_id_email_templates_id_fk": {
+          "name": "email_recipients_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_recipients",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_recipients_user_id_email_unique": {
+          "name": "email_recipients_user_id_email_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "email"]
+        },
+        "email_recipients_id_user_id_unique": {
+          "name": "email_recipients_id_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["id", "user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "email_recipients_device_type_chk": {
+          "name": "email_recipients_device_type_chk",
+          "value": "\"email_recipients\".\"device_type\" is null or \"email_recipients\".\"device_type\" in ('kindle', 'kobo', 'other')"
+        },
+        "email_recipients_preferred_format_chk": {
+          "name": "email_recipients_preferred_format_chk",
+          "value": "\"email_recipients\".\"preferred_format\" is null or \"email_recipients\".\"preferred_format\" in ('epub', 'pdf', 'mobi', 'azw3', 'cbz', 'cbr')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.email_preferences": {
+      "name": "email_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "default_provider_id": {
+          "name": "default_provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_recipient_id": {
+          "name": "default_recipient_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "default_template_id": {
+          "name": "default_template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "email_preferences_user_id_users_id_fk": {
+          "name": "email_preferences_user_id_users_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_provider_id_email_providers_id_fk": {
+          "name": "email_preferences_default_provider_id_email_providers_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_providers",
+          "columnsFrom": ["default_provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_id_email_recipients_id_fk": {
+          "name": "email_preferences_default_recipient_id_email_recipients_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_template_id_email_templates_id_fk": {
+          "name": "email_preferences_default_template_id_email_templates_id_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_templates",
+          "columnsFrom": ["default_template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_preferences_default_recipient_owner_fk": {
+          "name": "email_preferences_default_recipient_owner_fk",
+          "tableFrom": "email_preferences",
+          "tableTo": "email_recipients",
+          "columnsFrom": ["default_recipient_id", "user_id"],
+          "columnsTo": ["id", "user_id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "email_preferences_user_id_unique": {
+          "name": "email_preferences_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.email_send_log": {
+      "name": "email_send_log",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "template_id": {
+          "name": "template_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "to_email": {
+          "name": "to_email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_name": {
+          "name": "to_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "attempt_count": {
+          "name": "attempt_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "email_send_log_user_created_at_idx": {
+          "name": "email_send_log_user_created_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_created_at_idx": {
+          "name": "email_send_log_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "email_send_log_status_next_retry_idx": {
+          "name": "email_send_log_status_next_retry_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "next_retry_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "email_send_log_user_id_users_id_fk": {
+          "name": "email_send_log_user_id_users_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_id_books_id_fk": {
+          "name": "email_send_log_book_id_books_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_book_file_id_book_files_id_fk": {
+          "name": "email_send_log_book_file_id_book_files_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_provider_id_email_providers_id_fk": {
+          "name": "email_send_log_provider_id_email_providers_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_providers",
+          "columnsFrom": ["provider_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "email_send_log_template_id_email_templates_id_fk": {
+          "name": "email_send_log_template_id_email_templates_id_fk",
+          "tableFrom": "email_send_log",
+          "tableTo": "email_templates",
+          "columnsFrom": ["template_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "email_send_log_status_chk": {
+          "name": "email_send_log_status_chk",
+          "value": "\"email_send_log\".\"status\" in ('pending', 'sent', 'failed')"
+        },
+        "email_send_log_attempt_count_nonnegative_chk": {
+          "name": "email_send_log_attempt_count_nonnegative_chk",
+          "value": "\"email_send_log\".\"attempt_count\" >= 0"
+        },
+        "email_send_log_sent_after_created_chk": {
+          "name": "email_send_log_sent_after_created_chk",
+          "value": "\"email_send_log\".\"sent_at\" is null or \"email_send_log\".\"sent_at\" >= \"email_send_log\".\"created_at\""
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "message": {
+          "name": "message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action_url": {
+          "name": "action_url",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "meta": {
+          "name": "meta",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "read": {
+          "name": "read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_id_idx": {
+          "name": "notifications_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_user_unread_idx": {
+          "name": "notifications_user_unread_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "read",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_created_at_idx": {
+          "name": "notifications_created_at_idx",
+          "columns": [
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "notifications_user_id_users_id_fk": {
+          "name": "notifications_user_id_users_id_fk",
+          "tableFrom": "notifications",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_duplicate_pairs": {
+      "name": "dismissed_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_duplicate_pairs_entity_a_idx": {
+          "name": "dismissed_duplicate_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_duplicate_pairs_entity_b_idx": {
+          "name": "dismissed_duplicate_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_duplicate_pairs_unique": {
+          "name": "dismissed_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.dismissed_inline_duplicate_pairs": {
+      "name": "dismissed_inline_duplicate_pairs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_a": {
+          "name": "value_a",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value_b": {
+          "name": "value_b",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dismissed_by": {
+          "name": "dismissed_by",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "dismissed_at": {
+          "name": "dismissed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "dismissed_inline_pairs_entity_a_idx": {
+          "name": "dismissed_inline_pairs_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "dismissed_inline_pairs_entity_b_idx": {
+          "name": "dismissed_inline_pairs_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "value_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk": {
+          "name": "dismissed_inline_duplicate_pairs_dismissed_by_users_id_fk",
+          "tableFrom": "dismissed_inline_duplicate_pairs",
+          "tableTo": "users",
+          "columnsFrom": ["dismissed_by"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "dismissed_inline_duplicate_pairs_unique": {
+          "name": "dismissed_inline_duplicate_pairs_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "value_a", "value_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_candidates": {
+      "name": "entity_duplicate_candidates",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_a": {
+          "name": "entity_id_a",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "entity_id_b": {
+          "name": "entity_id_b",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sim_score": {
+          "name": "sim_score",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "entity_dup_candidates_type_sim_idx": {
+          "name": "entity_dup_candidates_type_sim_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sim_score",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_a_idx": {
+          "name": "entity_dup_candidates_entity_a_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_a",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "entity_dup_candidates_entity_b_idx": {
+          "name": "entity_dup_candidates_entity_b_idx",
+          "columns": [
+            {
+              "expression": "entity_type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "entity_id_b",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "entity_duplicate_candidates_unique": {
+          "name": "entity_duplicate_candidates_unique",
+          "nullsNotDistinct": false,
+          "columns": ["entity_type", "entity_id_a", "entity_id_b"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.entity_duplicate_scan_status": {
+      "name": "entity_duplicate_scan_status",
+      "schema": "",
+      "columns": {
+        "entity_type": {
+          "name": "entity_type",
+          "type": "varchar(50)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "is_computing": {
+          "name": "is_computing",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "computed_at": {
+          "name": "computed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_pairs": {
+          "name": "total_pairs",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "processed_count": {
+          "name": "processed_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "total_count": {
+          "name": "total_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_fonts": {
+      "name": "user_fonts",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "family_name": {
+          "name": "family_name",
+          "type": "varchar(200)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_file_name": {
+          "name": "original_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "stored_file_name": {
+          "name": "stored_file_name",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "format": {
+          "name": "format",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "weight": {
+          "name": "weight",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 400
+        },
+        "style": {
+          "name": "style",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'normal'"
+        },
+        "file_size": {
+          "name": "file_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "uf_user_hash_uidx": {
+          "name": "uf_user_hash_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "uf_user_family_weight_style_uidx": {
+          "name": "uf_user_family_weight_style_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "family_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "weight",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "style",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_fonts_user_id_users_id_fk": {
+          "name": "user_fonts_user_id_users_id_fk",
+          "tableFrom": "user_fonts",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "user_fonts_format_chk": {
+          "name": "user_fonts_format_chk",
+          "value": "\"user_fonts\".\"format\" in ('ttf', 'otf', 'woff', 'woff2')"
+        },
+        "user_fonts_weight_chk": {
+          "name": "user_fonts_weight_chk",
+          "value": "\"user_fonts\".\"weight\" >= 100 and \"user_fonts\".\"weight\" <= 900 and \"user_fonts\".\"weight\" % 100 = 0"
+        },
+        "user_fonts_style_chk": {
+          "name": "user_fonts_style_chk",
+          "value": "\"user_fonts\".\"style\" in ('normal', 'italic')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.book_file_chapters": {
+      "name": "book_file_chapters",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "href": {
+          "name": "href",
+          "type": "varchar(1000)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "spine_index": {
+          "name": "spine_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "book_file_chapters_book_file_id_chapter_index_uidx": {
+          "name": "book_file_chapters_book_file_id_chapter_index_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "chapter_index",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_chapters_book_file_id_idx": {
+          "name": "book_file_chapters_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_chapters_book_file_id_book_files_id_fk": {
+          "name": "book_file_chapters_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_chapters",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.book_file_hash_history": {
+      "name": "book_file_hash_history",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "file_hash": {
+          "name": "file_hash",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "varchar(30)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "book_file_hash_history_book_file_id_file_hash_idx": {
+          "name": "book_file_hash_history_book_file_id_file_hash_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "book_file_hash_history_file_hash_idx": {
+          "name": "book_file_hash_history_file_hash_idx",
+          "columns": [
+            {
+              "expression": "file_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "book_file_hash_history_book_file_id_book_files_id_fk": {
+          "name": "book_file_hash_history_book_file_id_book_files_id_fk",
+          "tableFrom": "book_file_hash_history",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "book_file_hash_history_reason_chk": {
+          "name": "book_file_hash_history_reason_chk",
+          "value": "\"book_file_hash_history\".\"reason\" in ('file_write', 'external_change', 'rescan')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_progress": {
+      "name": "koreader_device_progress",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device": {
+          "name": "device",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "percentage": {
+          "name": "percentage",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "progress": {
+          "name": "progress",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "chapter_index": {
+          "name": "chapter_index",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_timestamp": {
+          "name": "sync_timestamp",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "orphaned": {
+          "name": "orphaned",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "orphaned_hash": {
+          "name": "orphaned_hash",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_device_progress_book_user_device_uidx": {
+          "name": "koreader_device_progress_book_user_device_uidx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"koreader_device_progress\".\"orphaned\" = false",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_orphaned_hash_idx": {
+          "name": "koreader_device_progress_orphaned_hash_idx",
+          "columns": [
+            {
+              "expression": "orphaned_hash",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"orphaned\" = true",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_user_updated_at_idx": {
+          "name": "koreader_device_progress_user_updated_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_device_progress_book_file_id_idx": {
+          "name": "koreader_device_progress_book_file_id_idx",
+          "columns": [
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"koreader_device_progress\".\"book_file_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_progress_book_file_id_book_files_id_fk": {
+          "name": "koreader_device_progress_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "koreader_device_progress_user_id_users_id_fk": {
+          "name": "koreader_device_progress_user_id_users_id_fk",
+          "tableFrom": "koreader_device_progress",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_device_progress_percentage_range_chk": {
+          "name": "koreader_device_progress_percentage_range_chk",
+          "value": "\"koreader_device_progress\".\"percentage\" is null or (\"koreader_device_progress\".\"percentage\" >= 0 and \"koreader_device_progress\".\"percentage\" <= 1)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_device_sweeps": {
+      "name": "koreader_device_sweeps",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_model": {
+          "name": "device_model",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'KOReader'"
+        },
+        "plugin_version": {
+          "name": "plugin_version",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_sweep_at": {
+          "name": "last_sweep_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_sweep_books_matched": {
+          "name": "last_sweep_books_matched",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_page_stats": {
+          "name": "last_sweep_page_stats",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_sweep_annotations": {
+          "name": "last_sweep_annotations",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kds_user_id_idx": {
+          "name": "kds_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_device_sweeps_user_id_users_id_fk": {
+          "name": "koreader_device_sweeps_user_id_users_id_fk",
+          "tableFrom": "koreader_device_sweeps",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "koreader_device_sweeps_user_id_device_id_pk": {
+          "name": "koreader_device_sweeps_user_id_device_id_pk",
+          "columns": ["user_id", "device_id"]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.koreader_page_stats": {
+      "name": "koreader_page_stats",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_file_id": {
+          "name": "book_file_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "device_id": {
+          "name": "device_id",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page": {
+          "name": "page",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "start_time": {
+          "name": "start_time",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "duration_seconds": {
+          "name": "duration_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "total_pages": {
+          "name": "total_pages",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "kps_user_file_device_page_start_uidx": {
+          "name": "kps_user_file_device_page_start_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "page",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_file_device_start_idx": {
+          "name": "kps_user_file_device_start_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "book_file_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "device_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "start_time",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "kps_user_id_idx": {
+          "name": "kps_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_page_stats_user_id_users_id_fk": {
+          "name": "koreader_page_stats_user_id_users_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "koreader_page_stats_book_file_id_book_files_id_fk": {
+          "name": "koreader_page_stats_book_file_id_book_files_id_fk",
+          "tableFrom": "koreader_page_stats",
+          "tableTo": "book_files",
+          "columnsFrom": ["book_file_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "koreader_page_stats_duration_nonnegative_chk": {
+          "name": "koreader_page_stats_duration_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"duration_seconds\" >= 0"
+        },
+        "koreader_page_stats_page_nonnegative_chk": {
+          "name": "koreader_page_stats_page_nonnegative_chk",
+          "value": "\"koreader_page_stats\".\"page\" >= 0"
+        },
+        "koreader_page_stats_total_pages_positive_chk": {
+          "name": "koreader_page_stats_total_pages_positive_chk",
+          "value": "\"koreader_page_stats\".\"total_pages\" > 0"
+        },
+        "koreader_page_stats_start_time_positive_chk": {
+          "name": "koreader_page_stats_start_time_positive_chk",
+          "value": "\"koreader_page_stats\".\"start_time\" > 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.koreader_users": {
+      "name": "koreader_users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "username": {
+          "name": "username",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_md5": {
+          "name": "password_md5",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_enabled": {
+          "name": "sync_enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "koreader_users_user_id_uidx": {
+          "name": "koreader_users_user_id_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "koreader_users_username_uidx": {
+          "name": "koreader_users_username_uidx",
+          "columns": [
+            {
+              "expression": "username",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "koreader_users_user_id_users_id_fk": {
+          "name": "koreader_users_user_id_users_id_fk",
+          "tableFrom": "koreader_users",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.achievements": {
+      "name": "achievements",
+      "schema": "",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "varchar(64)",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "group_key": {
+          "name": "group_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "category": {
+          "name": "category",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "varchar(500)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon_name": {
+          "name": "icon_name",
+          "type": "varchar(50)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "rarity": {
+          "name": "rarity",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "threshold": {
+          "name": "threshold",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hidden": {
+          "name": "hidden",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "achievements_category_sort_idx": {
+          "name": "achievements_category_sort_idx",
+          "columns": [
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "achievements_group_key_idx": {
+          "name": "achievements_group_key_idx",
+          "columns": [
+            {
+              "expression": "group_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "achievements_category_chk": {
+          "name": "achievements_category_chk",
+          "value": "\"achievements\".\"category\" in ('reading', 'library', 'exploration', 'dedication', 'devices')"
+        },
+        "achievements_rarity_chk": {
+          "name": "achievements_rarity_chk",
+          "value": "\"achievements\".\"rarity\" in ('common', 'rare', 'epic', 'legendary')"
+        },
+        "achievements_tier_chk": {
+          "name": "achievements_tier_chk",
+          "value": "\"achievements\".\"tier\" is null or (\"achievements\".\"tier\" >= 1 and \"achievements\".\"tier\" <= 4)"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.user_achievements": {
+      "name": "user_achievements",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "achievement_key": {
+          "name": "achievement_key",
+          "type": "varchar(64)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "awarded_at": {
+          "name": "awarded_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "context_json": {
+          "name": "context_json",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "user_achievements_user_key_uidx": {
+          "name": "user_achievements_user_key_uidx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "achievement_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_id_idx": {
+          "name": "user_achievements_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "user_achievements_user_awarded_at_idx": {
+          "name": "user_achievements_user_awarded_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "awarded_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_achievements_user_id_users_id_fk": {
+          "name": "user_achievements_user_id_users_id_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "user_achievements_achievement_key_achievements_key_fk": {
+          "name": "user_achievements_achievement_key_achievements_key_fk",
+          "tableFrom": "user_achievements",
+          "tableTo": "achievements",
+          "columnsFrom": ["achievement_key"],
+          "columnsTo": ["key"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_book_state": {
+      "name": "hardcover_book_state",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "book_id": {
+          "name": "book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "hardcover_book_id": {
+          "name": "hardcover_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_edition_id": {
+          "name": "hardcover_edition_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_user_book_id": {
+          "name": "hardcover_user_book_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "hardcover_read_id": {
+          "name": "hardcover_read_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_method": {
+          "name": "match_method",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "match_error": {
+          "name": "match_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_status": {
+          "name": "last_synced_status",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_progress": {
+          "name": "last_synced_progress",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_rating": {
+          "name": "last_synced_rating",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_started_at": {
+          "name": "last_synced_started_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_synced_finished_at": {
+          "name": "last_synced_finished_at",
+          "type": "varchar(10)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "sync_error": {
+          "name": "sync_error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "sync_excluded": {
+          "name": "sync_excluded",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "sync_override": {
+          "name": "sync_override",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_book_state_user_id_users_id_fk": {
+          "name": "hardcover_book_state_user_id_users_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "hardcover_book_state_book_id_books_id_fk": {
+          "name": "hardcover_book_state_book_id_books_id_fk",
+          "tableFrom": "hardcover_book_state",
+          "tableTo": "books",
+          "columnsFrom": ["book_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_book_state_user_book_uidx": {
+          "name": "hardcover_book_state_user_book_uidx",
+          "nullsNotDistinct": false,
+          "columns": ["user_id", "book_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.hardcover_user_settings": {
+      "name": "hardcover_user_settings",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "api_token": {
+          "name": "api_token",
+          "type": "varchar(2048)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enabled": {
+          "name": "enabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_status_change": {
+          "name": "auto_sync_on_status_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_progress_update": {
+          "name": "auto_sync_on_progress_update",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "auto_sync_on_rating_change": {
+          "name": "auto_sync_on_rating_change",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": true
+        },
+        "privacy_setting_id": {
+          "name": "privacy_setting_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 3
+        },
+        "last_synced_at": {
+          "name": "last_synced_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "book_sync_mode": {
+          "name": "book_sync_mode",
+          "type": "varchar(20)",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'all_eligible'"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "hardcover_user_settings_user_id_users_id_fk": {
+          "name": "hardcover_user_settings_user_id_users_id_fk",
+          "tableFrom": "hardcover_user_settings",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "hardcover_user_settings_user_id_unique": {
+          "name": "hardcover_user_settings_user_id_unique",
+          "nullsNotDistinct": false,
+          "columns": ["user_id"]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user_preferences": {
+      "name": "user_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "serial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "category": {
+          "name": "category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "data": {
+          "name": "data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "up_user_category_idx": {
+          "name": "up_user_category_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "category",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "user_preferences_user_id_users_id_fk": {
+          "name": "user_preferences_user_id_users_id_fk",
+          "tableFrom": "user_preferences",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.content_filter_type": {
+      "name": "content_filter_type",
+      "schema": "public",
+      "values": ["include", "exclude"]
+    },
+    "public.library_access_level": {
+      "name": "library_access_level",
+      "schema": "public",
+      "values": ["viewer", "editor", "owner"]
+    },
+    "public.user_avatar_source": {
+      "name": "user_avatar_source",
+      "schema": "public",
+      "values": ["none", "external", "uploaded"]
+    },
+    "public.opds_sort_order": {
+      "name": "opds_sort_order",
+      "schema": "public",
+      "values": ["recent", "title_asc", "title_desc", "author_asc", "author_desc", "series_asc", "series_desc"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
diff --git a/server/src/db/migrations/meta/_journal.json b/server/src/db/migrations/meta/_journal.json
index ea0c22ac6..85a6edb02 100644
--- a/server/src/db/migrations/meta/_journal.json
+++ b/server/src/db/migrations/meta/_journal.json
@@ -190,6 +190,41 @@
       "when": 1782421105729,
       "tag": "0026_add_book_community_ratings",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1781155643115,
+      "tag": "0027_consolidated-koreader-annotations",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1781162143195,
+      "tag": "0028_kobo-annotation-spoke",
+      "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1781199567205,
+      "tag": "0029_reading-session-source-book-id",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1781199578268,
+      "tag": "0030_backfill-reading-session-source-book-id",
+      "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "7",
+      "when": 1781199638250,
+      "tag": "0031_reading-session-book-id-not-null",
+      "breakpoints": true
     }
   ]
 }
diff --git a/server/src/db/schema/kobo.ts b/server/src/db/schema/kobo.ts
index f18a850e0..60674f980 100644
--- a/server/src/db/schema/kobo.ts
+++ b/server/src/db/schema/kobo.ts
@@ -13,10 +13,11 @@ export const koboDevices = pgTable(
       .references(() => users.id, { onDelete: 'cascade' }),
     name: varchar('name', { length: 255 }).notNull(),
     token: varchar('token', { length: 64 }).notNull().unique(),
+    clientDeviceId: varchar('client_device_id', { length: 128 }),
     lastSeenAt: timestamp('last_seen_at', { withTimezone: true }),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
   },
-  (t) => [index('kobo_devices_user_id_idx').on(t.userId)],
+  (t) => [index('kobo_devices_user_id_idx').on(t.userId), unique('kobo_devices_client_device_id_unique').on(t.clientDeviceId)],
 );
 
 export const koboSyncSettings = pgTable(
@@ -33,6 +34,7 @@ export const koboSyncSettings = pgTable(
     forceEnableHyphenation: boolean('force_enable_hyphenation').notNull().default(false),
     kepubConversionLimitMb: integer('kepub_conversion_limit_mb').notNull().default(100),
     twoWayProgressSync: boolean('two_way_progress_sync').notNull().default(false),
+    syncBookOrbitAnnotationsToKobo: boolean('sync_bookorbit_annotations_to_kobo').notNull().default(false),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
     updatedAt: timestamp('updated_at', { withTimezone: true })
       .defaultNow()
diff --git a/server/src/db/schema/koreader.ts b/server/src/db/schema/koreader.ts
index d9cc93d7d..37bd47a00 100644
--- a/server/src/db/schema/koreader.ts
+++ b/server/src/db/schema/koreader.ts
@@ -1,5 +1,19 @@
 import { sql } from 'drizzle-orm';
-import { bigint, boolean, check, index, integer, pgTable, real, serial, text, timestamp, uniqueIndex, varchar } from 'drizzle-orm/pg-core';
+import {
+  bigint,
+  boolean,
+  check,
+  index,
+  integer,
+  pgTable,
+  primaryKey,
+  real,
+  serial,
+  text,
+  timestamp,
+  uniqueIndex,
+  varchar,
+} from 'drizzle-orm/pg-core';
 
 import { bookFiles } from './books';
 import { users } from './auth';
@@ -108,3 +122,56 @@ export const bookFileChapters = pgTable(
 
 export type BookFileChapter = typeof bookFileChapters.$inferSelect;
 export type NewBookFileChapter = typeof bookFileChapters.$inferInsert;
+
+export const koreaderPageStats = pgTable(
+  'koreader_page_stats',
+  {
+    id: serial('id').primaryKey(),
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    bookFileId: integer('book_file_id')
+      .notNull()
+      .references(() => bookFiles.id, { onDelete: 'cascade' }),
+    deviceId: varchar('device_id', { length: 100 }).notNull(),
+    page: integer('page').notNull(),
+    // Device-reported unix seconds; part of the dedup key, stored verbatim (device clock accepted as-is).
+    startTime: bigint('start_time', { mode: 'number' }).notNull(),
+    durationSeconds: integer('duration_seconds').notNull(),
+    totalPages: integer('total_pages').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  (t) => [
+    uniqueIndex('kps_user_file_device_page_start_uidx').on(t.userId, t.bookFileId, t.deviceId, t.page, t.startTime),
+    index('kps_user_file_device_start_idx').on(t.userId, t.bookFileId, t.deviceId, t.startTime),
+    index('kps_user_id_idx').on(t.userId),
+    check('koreader_page_stats_duration_nonnegative_chk', sql`${t.durationSeconds} >= 0`),
+    check('koreader_page_stats_page_nonnegative_chk', sql`${t.page} >= 0`),
+    check('koreader_page_stats_total_pages_positive_chk', sql`${t.totalPages} > 0`),
+    check('koreader_page_stats_start_time_positive_chk', sql`${t.startTime} > 0`),
+  ],
+);
+
+export type KoreaderPageStat = typeof koreaderPageStats.$inferSelect;
+export type NewKoreaderPageStat = typeof koreaderPageStats.$inferInsert;
+
+export const koreaderDeviceSweeps = pgTable(
+  'koreader_device_sweeps',
+  {
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    deviceId: varchar('device_id', { length: 100 }).notNull(),
+    deviceModel: varchar('device_model', { length: 100 }).notNull().default('KOReader'),
+    pluginVersion: varchar('plugin_version', { length: 20 }),
+    lastSweepAt: timestamp('last_sweep_at', { withTimezone: true }).notNull(),
+    lastSweepBooksMatched: integer('last_sweep_books_matched').notNull().default(0),
+    lastSweepPageStats: integer('last_sweep_page_stats').notNull().default(0),
+    lastSweepAnnotations: integer('last_sweep_annotations').notNull().default(0),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.userId, t.deviceId] }), index('kds_user_id_idx').on(t.userId)],
+);
+
+export type KoreaderDeviceSweep = typeof koreaderDeviceSweeps.$inferSelect;
+export type NewKoreaderDeviceSweep = typeof koreaderDeviceSweeps.$inferInsert;
diff --git a/server/src/db/schema/reader.ts b/server/src/db/schema/reader.ts
index c3a2963e2..9d7a470db 100644
--- a/server/src/db/schema/reader.ts
+++ b/server/src/db/schema/reader.ts
@@ -1,13 +1,11 @@
 import { sql } from 'drizzle-orm';
 import { check, date, index, integer, jsonb, pgTable, primaryKey, real, serial, text, timestamp, uniqueIndex, varchar } from 'drizzle-orm/pg-core';
-import type { ReadStatus, ReadStatusSource } from '@bookorbit/types';
+import type { ReadStatus, ReadStatusSource, ReadingSessionSource } from '@bookorbit/types';
 
 import { bookFiles, books } from './books';
 import { libraries } from './libraries';
 import { users } from './auth';
 
-export type ReadingSessionSource = 'web' | 'kobo' | 'koreader';
-
 export const userBookStatus = pgTable(
   'user_book_status',
   {
@@ -126,11 +124,15 @@ export const readingSessions = pgTable(
     userId: integer('user_id')
       .notNull()
       .references(() => users.id, { onDelete: 'cascade' }),
-    bookFileId: integer('book_file_id')
+    // Nullable: manual sessions are book-level and have no file.
+    bookFileId: integer('book_file_id').references(() => bookFiles.id, { onDelete: 'cascade' }),
+    bookId: integer('book_id')
       .notNull()
-      .references(() => bookFiles.id, { onDelete: 'cascade' }),
+      .references(() => books.id, { onDelete: 'cascade' }),
     // Client-generated UUID; used for idempotent retries.
     sessionId: varchar('session_id', { length: 64 }).notNull(),
+    // 'web' (browser reader) | 'koreader' (page-stats derivation) | 'manual' (user-entered) | 'kobo' (future)
+    source: varchar('source', { length: 10 }).$type<ReadingSessionSource>(),
     startedAt: timestamp('started_at', { withTimezone: true }).notNull(),
     endedAt: timestamp('ended_at', { withTimezone: true }).notNull(),
     // Server-computed from endedAt - startedAt; client-provided timestamps are untrusted for duration.
@@ -138,16 +140,14 @@ export const readingSessions = pgTable(
     // Nullable: CBX with no percentage tracking may omit these.
     progressDelta: real('progress_delta'),
     endProgress: real('end_progress'),
-    // Which client produced the session. Kobo analytics also writes sessions here, so this is the only
-    // way to tell a genuine web-reader session apart from a device-origin one.
-    source: varchar('source', { length: 10 }).$type<ReadingSessionSource>().notNull().default('web'),
   },
   (t) => [
     uniqueIndex('rs_user_session_id_uidx').on(t.userId, t.sessionId),
     index('rs_user_started_at_idx').on(t.userId, t.startedAt),
     index('rs_book_file_started_at_idx').on(t.bookFileId, t.startedAt),
     index('rs_user_book_file_idx').on(t.userId, t.bookFileId),
-    check('reading_sessions_source_chk', sql`${t.source} in ('web', 'kobo', 'koreader')`),
+    index('rs_user_book_started_at_idx').on(t.userId, t.bookId, t.startedAt),
+    check('reading_sessions_source_chk', sql`${t.source} in ('web', 'koreader', 'manual', 'kobo')`),
     check('reading_sessions_duration_seconds_nonnegative_chk', sql`${t.durationSeconds} >= 0`),
     check('reading_sessions_end_progress_range_chk', sql`${t.endProgress} is null or (${t.endProgress} >= 0 and ${t.endProgress} <= 100)`),
     check('reading_sessions_ended_after_started_chk', sql`${t.endedAt} >= ${t.startedAt}`),
@@ -257,12 +257,20 @@ export const annotations = pgTable(
     bookId: integer('book_id')
       .notNull()
       .references(() => books.id, { onDelete: 'cascade' }),
-    cfi: varchar('cfi', { length: 2000 }).notNull(),
     text: text('text').notNull(),
     color: varchar('color', { length: 20 }).notNull().default('yellow'),
     style: varchar('style', { length: 20 }).notNull().default('highlight'),
     note: text('note'),
     chapterTitle: varchar('chapter_title', { length: 500 }),
+    origin: varchar('origin', { length: 10 }).$type<'web' | 'koreader' | 'kobo'>().notNull().default('web'),
+    // Bumped on every content mutation (edit, soft delete, restore, device position
+    // correction); annotation_sync_state.lastAppliedVersion tracks per-device delivery.
+    version: integer('version').notNull().default(1),
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
+    // Device-local "YYYY-MM-DD HH:MM:SS" strings stored verbatim (device has no timezone info).
+    // deviceCreatedAt doubles as the KOReader-side identity datetime for synced annotations.
+    deviceCreatedAt: varchar('device_created_at', { length: 19 }),
+    deviceUpdatedAt: varchar('device_updated_at', { length: 19 }),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
     updatedAt: timestamp('updated_at', { withTimezone: true })
       .notNull()
@@ -272,13 +280,94 @@ export const annotations = pgTable(
   (t) => [
     index('annotations_user_id_idx').on(t.userId),
     index('annotations_user_book_idx').on(t.userId, t.bookId),
-    check('annotations_style_chk', sql`${t.style} in ('highlight', 'underline', 'strikethrough', 'squiggly')`),
+    index('annotations_user_book_active_idx')
+      .on(t.userId, t.bookId)
+      .where(sql`${t.deletedAt} is null`),
+    check('annotations_style_chk', sql`${t.style} in ('highlight', 'underline', 'strikethrough', 'squiggly', 'invert')`),
+    check('annotations_origin_chk', sql`${t.origin} in ('web', 'koreader', 'kobo')`),
   ],
 );
 
 export type AnnotationRow = typeof annotations.$inferSelect;
 export type NewAnnotation = typeof annotations.$inferInsert;
 
+export const annotationPositions = pgTable(
+  'annotation_positions',
+  {
+    id: serial('id').primaryKey(),
+    annotationId: integer('annotation_id')
+      .notNull()
+      .references(() => annotations.id, { onDelete: 'cascade' }),
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    bookFileId: integer('book_file_id').references(() => bookFiles.id, { onDelete: 'set null' }),
+    format: varchar('format', { length: 12 }).$type<'cfi' | 'xpointer' | 'pdf' | 'kobo_span'>().notNull(),
+    pos0: text('pos0'),
+    pos1: text('pos1'),
+    // exact: structurally resolved and text-verified; repaired: re-anchored via text search;
+    // pending: generated but not yet verified by the target renderer; failed: no usable position.
+    status: varchar('status', { length: 10 }).$type<'exact' | 'repaired' | 'failed' | 'pending'>().notNull().default('exact'),
+    converterVersion: integer('converter_version'),
+    extras: jsonb('extras').$type<Record<string, unknown>>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [
+    uniqueIndex('annotation_positions_annotation_format_uidx').on(t.annotationId, t.format),
+    index('annotation_positions_user_idx').on(t.userId),
+    index('annotation_positions_format_status_idx').on(t.format, t.status),
+    check('annotation_positions_format_chk', sql`${t.format} in ('cfi', 'xpointer', 'pdf', 'kobo_span')`),
+    check('annotation_positions_status_chk', sql`${t.status} in ('exact', 'repaired', 'failed', 'pending')`),
+    check('annotation_positions_pos0_chk', sql`${t.status} in ('failed', 'pending') or ${t.pos0} is not null`),
+  ],
+);
+
+export type AnnotationPosition = typeof annotationPositions.$inferSelect;
+export type NewAnnotationPosition = typeof annotationPositions.$inferInsert;
+
+export const annotationSyncState = pgTable(
+  'annotation_sync_state',
+  {
+    id: serial('id').primaryKey(),
+    annotationId: integer('annotation_id')
+      .notNull()
+      .references(() => annotations.id, { onDelete: 'cascade' }),
+    userId: integer('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    source: varchar('source', { length: 10 }).$type<'koreader' | 'kobo'>().notNull(),
+    deviceId: varchar('device_id', { length: 100 }).notNull(),
+    // KOReader: md5 hex of `${deviceCreatedAt}|${pos0}` (device-format pos0).
+    externalKey: varchar('external_key', { length: 64 }).notNull(),
+    externalCreatedAt: varchar('external_created_at', { length: 19 }),
+    // 0 = row exists from device upload but nothing pushed yet; otherwise the canonical
+    // version this device has acknowledged. Only the exchange ack advances it.
+    lastAppliedVersion: integer('last_applied_version').notNull().default(0),
+    deleteAckedAt: timestamp('delete_acked_at', { withTimezone: true }),
+    firstSyncedAt: timestamp('first_synced_at', { withTimezone: true }).defaultNow().notNull(),
+    lastSyncedAt: timestamp('last_synced_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [
+    uniqueIndex('annotation_sync_state_annotation_source_device_uidx').on(t.annotationId, t.source, t.deviceId),
+    // Non-unique: the same external key can legitimately exist for two different books
+    // (the same file scanned into two libraries); lookups are book-scoped.
+    index('annotation_sync_state_user_source_device_key_idx').on(t.userId, t.source, t.deviceId, t.externalKey),
+    index('annotation_sync_state_user_key_idx').on(t.userId, t.externalKey),
+    index('annotation_sync_state_annotation_id_idx').on(t.annotationId),
+    check('annotation_sync_state_source_chk', sql`${t.source} in ('koreader', 'kobo')`),
+  ],
+);
+
+export type AnnotationSyncStateRow = typeof annotationSyncState.$inferSelect;
+export type NewAnnotationSyncState = typeof annotationSyncState.$inferInsert;
+
 export const readerDefaultPreferences = pgTable(
   'reader_default_preferences',
   {
diff --git a/server/src/main.ts b/server/src/main.ts
index f690ff52e..93782fb10 100644
--- a/server/src/main.ts
+++ b/server/src/main.ts
@@ -54,7 +54,7 @@ async function bootstrap() {
   app.useWebSocketAdapter(new IoAdapter(app));
 
   app.setGlobalPrefix('api/v1', {
-    exclude: ['api/kobo/:deviceToken/(.*)'],
+    exclude: ['api/kobo/:deviceToken/(.*)', 'api/v3/(.*)', 'api/UserStorage/(.*)'],
   });
 
   app.useGlobalPipes(
diff --git a/server/src/modules/achievement/achievement.repository.ts b/server/src/modules/achievement/achievement.repository.ts
index 867069578..b7894fe4b 100644
--- a/server/src/modules/achievement/achievement.repository.ts
+++ b/server/src/modules/achievement/achievement.repository.ts
@@ -123,8 +123,7 @@ export class AchievementRepository {
         value: sql<number>`coalesce(sum(${bookMetadata.pageCount} * least(greatest(coalesce(${readingSessions.progressDelta}, 0), 0), 100) / 100.0), 0)::float`,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(bookMetadata, eq(bookMetadata.bookId, bookFiles.bookId))
+      .innerJoin(bookMetadata, eq(bookMetadata.bookId, readingSessions.bookId))
       .where(
         and(
           eq(readingSessions.userId, userId),
diff --git a/server/src/modules/annotation/annotation-conversion.service.ts b/server/src/modules/annotation/annotation-conversion.service.ts
new file mode 100644
index 000000000..fa9869fbc
--- /dev/null
+++ b/server/src/modules/annotation/annotation-conversion.service.ts
@@ -0,0 +1,119 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { type AnnotationPosition } from '../../db/schema';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { PositionConverterService } from '../position-converter/position-converter.service';
+import { AnnotationPositionRepository } from './annotation-position.repository';
+import { AnnotationSyncService } from './annotation-sync.service';
+
+const EVENT = 'annotation.cfi_backfill';
+
+/**
+ * Lazily converts device xpointer positions to CFIs so the web reader can draw
+ * them. Runs bounded batches on reader load; rows whose conversion failed are
+ * retried only after a converter upgrade (converterVersion sweep).
+ */
+@Injectable()
+export class AnnotationConversionService {
+  private readonly logger = new Logger(AnnotationConversionService.name);
+
+  constructor(
+    private readonly positionRepo: AnnotationPositionRepository,
+    private readonly positionConverter: PositionConverterService,
+    private readonly annotationSync: AnnotationSyncService,
+  ) {}
+
+  async ensureCfiPositionsForBook(userId: number, bookId: number, limit = 25): Promise<number> {
+    const startedAtMs = Date.now();
+    try {
+      const candidates = await this.findCandidates(userId, bookId, limit);
+      if (candidates.length === 0) return 0;
+
+      let converted = 0;
+      let failed = 0;
+      for (const candidate of candidates) {
+        const outcome = await this.positionConverter.xpointerToCfi({
+          bookFileId: candidate.bookFileId,
+          pos0: candidate.pos0,
+          pos1: candidate.pos1,
+          text: candidate.text || null,
+        });
+        const chapterIndex = outcome.chapterIndex ?? null;
+        if (outcome.status === 'failed' || !outcome.cfi) {
+          failed += 1;
+          await this.annotationSync.upsertGeneratedPosition({
+            annotationId: candidate.annotationId,
+            userId,
+            bookFileId: candidate.bookFileId,
+            format: 'cfi',
+            pos0: null,
+            pos1: null,
+            status: 'failed',
+            converterVersion: this.positionConverter.version,
+            extras: { chapterIndex, reason: outcome.reason },
+          });
+        } else {
+          converted += 1;
+          await this.annotationSync.upsertGeneratedPosition({
+            annotationId: candidate.annotationId,
+            userId,
+            bookFileId: candidate.bookFileId,
+            format: 'cfi',
+            pos0: outcome.cfi,
+            pos1: null,
+            status: outcome.status,
+            converterVersion: this.positionConverter.version,
+            extras: { chapterIndex },
+          });
+        }
+      }
+
+      this.logger.log(
+        `[${EVENT}] [end] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} converted=${converted} failed=${failed} - cfi backfill completed`,
+      );
+      return converted;
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${EVENT}] [fail] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - cfi backfill failed`,
+      );
+      return 0;
+    }
+  }
+
+  private async findCandidates(
+    userId: number,
+    bookId: number,
+    limit: number,
+  ): Promise<{ annotationId: number; text: string; pos0: string; pos1: string | null; bookFileId: number }[]> {
+    const xpointerRows = await this.positionRepo.findXPointerRowsForBook(userId, bookId);
+
+    const usable = xpointerRows.filter((row) => row.pos0 != null && row.bookFileId != null && row.status !== 'failed');
+    if (usable.length === 0) return [];
+
+    const cfiRows = await this.annotationSync.findPositions(
+      usable.map((row) => row.annotationId),
+      ['cfi'],
+    );
+    const cfiByAnnotation = new Map<number, AnnotationPosition>();
+    for (const row of cfiRows) cfiByAnnotation.set(row.annotationId, row);
+
+    const version = this.positionConverter.version;
+    const needsConversion = (cfi: AnnotationPosition | undefined): boolean => {
+      if (!cfi) return true;
+      if (cfi.status === 'pending') return true;
+      return cfi.converterVersion != null && cfi.converterVersion < version;
+    };
+
+    return usable
+      .filter((row) => needsConversion(cfiByAnnotation.get(row.annotationId)))
+      .slice(0, limit)
+      .map((row) => ({
+        annotationId: row.annotationId,
+        text: row.text,
+        pos0: row.pos0!,
+        pos1: row.pos1,
+        bookFileId: row.bookFileId!,
+      }));
+  }
+}
diff --git a/server/src/modules/annotation/annotation-export.service.test.ts b/server/src/modules/annotation/annotation-export.service.test.ts
new file mode 100644
index 000000000..825f5020b
--- /dev/null
+++ b/server/src/modules/annotation/annotation-export.service.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { AnnotationExportService } from './annotation-export.service';
+import type { HubAnnotationRow } from './annotation.repository';
+
+function makeRow(overrides: Partial<HubAnnotationRow> = {}): HubAnnotationRow {
+  return {
+    id: 1,
+    userId: 7,
+    bookId: 20,
+    text: 'The quick brown fox',
+    color: '#FACC15',
+    style: 'highlight',
+    note: null,
+    chapterTitle: 'Chapter 1',
+    origin: 'web',
+    version: 1,
+    deletedAt: null,
+    deviceCreatedAt: null,
+    deviceUpdatedAt: null,
+    createdAt: new Date('2026-06-01T10:00:00Z'),
+    updatedAt: new Date('2026-06-01T10:00:00Z'),
+    cfi: 'epubcfi(/6/2!/4/2,/1:0,/1:5)',
+    cfiStatus: 'exact',
+    cfiExtras: null,
+    bookTitle: 'Test Book',
+    jumpFileId: 10,
+    pageno: null,
+    ...overrides,
+  } as HubAnnotationRow;
+}
+
+describe('AnnotationExportService', () => {
+  const service = new AnnotationExportService();
+
+  it('renders markdown grouped by book and chapter with quotes and notes', () => {
+    const rows = [
+      makeRow(),
+      makeRow({ id: 2, text: 'Second highlight', note: 'my note', chapterTitle: 'Chapter 2' }),
+      makeRow({ id: 3, bookTitle: 'Another Book', chapterTitle: null, text: 'Other book text', origin: 'koreader' }),
+    ];
+
+    const result = service.export(rows, 'md', 'library');
+
+    expect(result.contentType).toContain('markdown');
+    expect(result.filename).toMatch(/^library-annotations-\d{4}-\d{2}-\d{2}\.md$/);
+    expect(result.content).toContain('## Test Book');
+    expect(result.content).toContain('### Chapter 1');
+    expect(result.content).toContain('> The quick brown fox');
+    expect(result.content).toContain('Note: my note');
+    expect(result.content).toContain('## Another Book');
+    expect(result.content).toContain('koreader');
+  });
+
+  it('escapes CSV fields containing quotes, commas and newlines', () => {
+    const rows = [makeRow({ text: 'He said "hi", twice\nand left', note: 'plain' })];
+
+    const result = service.export(rows, 'csv', 'book-20');
+
+    expect(result.contentType).toContain('csv');
+    expect(result.content).toContain('"He said ""hi"", twice\nand left"');
+    expect(result.content.split('\r\n')[0]).toBe('book,chapter,text,note,color,style,origin,createdAt');
+  });
+
+  it('renders JSON with stable fields', () => {
+    const result = service.export([makeRow()], 'json', 'library');
+
+    const parsed = JSON.parse(result.content) as Array<Record<string, unknown>>;
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0]).toMatchObject({
+      id: 1,
+      bookTitle: 'Test Book',
+      text: 'The quick brown fox',
+      origin: 'web',
+      cfi: 'epubcfi(/6/2!/4/2,/1:0,/1:5)',
+    });
+  });
+});
diff --git a/server/src/modules/annotation/annotation-export.service.ts b/server/src/modules/annotation/annotation-export.service.ts
new file mode 100644
index 000000000..88a1d63dc
--- /dev/null
+++ b/server/src/modules/annotation/annotation-export.service.ts
@@ -0,0 +1,113 @@
+import { Injectable } from '@nestjs/common';
+
+import type { HubAnnotationRow } from './annotation.repository';
+
+export type AnnotationExportFormat = 'md' | 'csv' | 'json';
+
+export interface AnnotationExportResult {
+  content: string;
+  contentType: string;
+  filename: string;
+}
+
+@Injectable()
+export class AnnotationExportService {
+  export(rows: HubAnnotationRow[], format: AnnotationExportFormat, scopeLabel: string): AnnotationExportResult {
+    const stamp = new Date().toISOString().slice(0, 10);
+    const safeScope =
+      scopeLabel
+        .replace(/[^\w-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || 'annotations';
+    if (format === 'csv') {
+      return {
+        content: this.toCsv(rows),
+        contentType: 'text/csv; charset=utf-8',
+        filename: `${safeScope}-annotations-${stamp}.csv`,
+      };
+    }
+    if (format === 'json') {
+      return {
+        content: this.toJson(rows),
+        contentType: 'application/json; charset=utf-8',
+        filename: `${safeScope}-annotations-${stamp}.json`,
+      };
+    }
+    return {
+      content: this.toMarkdown(rows),
+      contentType: 'text/markdown; charset=utf-8',
+      filename: `${safeScope}-annotations-${stamp}.md`,
+    };
+  }
+
+  private toMarkdown(rows: HubAnnotationRow[]): string {
+    const lines: string[] = ['# Annotations', ''];
+    let currentBook: string | null = null;
+    let currentChapter: string | null = null;
+    for (const row of rows) {
+      const book = row.bookTitle ?? 'Unknown book';
+      if (book !== currentBook) {
+        currentBook = book;
+        currentChapter = null;
+        lines.push(`## ${book}`, '');
+      }
+      const chapter = row.chapterTitle ?? null;
+      if (chapter !== currentChapter) {
+        currentChapter = chapter;
+        if (chapter) lines.push(`### ${chapter}`, '');
+      }
+      const quote = row.text
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n');
+      lines.push(quote);
+      if (row.note) lines.push('', `Note: ${row.note}`);
+      lines.push('', `<sub>${row.style}, ${row.color}, ${row.origin}, ${row.createdAt.toISOString().slice(0, 10)}</sub>`, '');
+    }
+    return lines.join('\n');
+  }
+
+  private toCsv(rows: HubAnnotationRow[]): string {
+    const header = ['book', 'chapter', 'text', 'note', 'color', 'style', 'origin', 'createdAt'];
+    const escape = (value: string | null): string => {
+      const raw = value ?? '';
+      return /[",\n\r]/.test(raw) ? `"${raw.replace(/"/g, '""')}"` : raw;
+    };
+    const lines = [header.join(',')];
+    for (const row of rows) {
+      lines.push(
+        [
+          escape(row.bookTitle),
+          escape(row.chapterTitle),
+          escape(row.text),
+          escape(row.note),
+          escape(row.color),
+          escape(row.style),
+          escape(row.origin),
+          escape(row.createdAt.toISOString()),
+        ].join(','),
+      );
+    }
+    return lines.join('\r\n');
+  }
+
+  private toJson(rows: HubAnnotationRow[]): string {
+    return JSON.stringify(
+      rows.map((row) => ({
+        id: row.id,
+        bookId: row.bookId,
+        bookTitle: row.bookTitle,
+        chapterTitle: row.chapterTitle,
+        text: row.text,
+        note: row.note,
+        color: row.color,
+        style: row.style,
+        origin: row.origin,
+        cfi: row.cfi,
+        createdAt: row.createdAt.toISOString(),
+      })),
+      null,
+      2,
+    );
+  }
+}
diff --git a/server/src/modules/annotation/annotation-hub.controller.ts b/server/src/modules/annotation/annotation-hub.controller.ts
new file mode 100644
index 000000000..3dec43f22
--- /dev/null
+++ b/server/src/modules/annotation/annotation-hub.controller.ts
@@ -0,0 +1,75 @@
+import { Body, Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Post, Query, Res } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
+
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+import type { RequestUser } from '../../common/types/request-user';
+import { AnnotationHubService } from './annotation-hub.service';
+import {
+  AnnotationBulkDto,
+  AnnotationExportQueryDto,
+  AnnotationHubBooksQueryDto,
+  AnnotationHubQueryDto,
+  AnnotationPositionRetryDto,
+} from './dto/annotation-hub.dto';
+
+@Controller('annotations')
+export class AnnotationHubController {
+  constructor(private readonly hubService: AnnotationHubService) {}
+
+  @Get()
+  list(@CurrentUser() user: RequestUser, @Query() query: AnnotationHubQueryDto) {
+    return this.hubService.list(user.id, query);
+  }
+
+  @Get('books')
+  listBooks(@CurrentUser() user: RequestUser, @Query() query: AnnotationHubBooksQueryDto) {
+    return this.hubService.listBooks(user.id, {
+      status: query.status ?? 'active',
+      q: query.q,
+      limit: query.limit,
+      selectedId: query.selectedId,
+    });
+  }
+
+  @Post('bulk')
+  @HttpCode(200)
+  bulk(@CurrentUser() user: RequestUser, @Body() dto: AnnotationBulkDto) {
+    return this.hubService.bulk(user.id, dto);
+  }
+
+  @Post(':annotationId/restore')
+  @HttpCode(200)
+  restore(@CurrentUser() user: RequestUser, @Param('annotationId', ParseIntPipe) annotationId: number) {
+    return this.hubService.restore(user.id, annotationId);
+  }
+
+  @Get(':annotationId/sync-detail')
+  syncDetail(@CurrentUser() user: RequestUser, @Param('annotationId', ParseIntPipe) annotationId: number) {
+    return this.hubService.syncDetail(user.id, annotationId);
+  }
+
+  @Post(':annotationId/positions/retry')
+  @HttpCode(200)
+  retryPosition(
+    @CurrentUser() user: RequestUser,
+    @Param('annotationId', ParseIntPipe) annotationId: number,
+    @Body() dto: AnnotationPositionRetryDto,
+  ) {
+    return this.hubService.retryPosition(user.id, annotationId, dto.format);
+  }
+
+  @Delete(':annotationId')
+  @HttpCode(204)
+  async purge(@CurrentUser() user: RequestUser, @Param('annotationId', ParseIntPipe) annotationId: number) {
+    await this.hubService.purge(user.id, annotationId);
+  }
+
+  @Get('export')
+  async export(@CurrentUser() user: RequestUser, @Query() query: AnnotationExportQueryDto, @Res() reply: FastifyReply) {
+    const result = await this.hubService.export(user.id, query, query.bookId ? `book-${query.bookId}` : 'library');
+    return reply
+      .header('Content-Type', result.contentType)
+      .header('Content-Disposition', `attachment; filename="${result.filename}"`)
+      .send(result.content);
+  }
+}
diff --git a/server/src/modules/annotation/annotation-hub.service.test.ts b/server/src/modules/annotation/annotation-hub.service.test.ts
new file mode 100644
index 000000000..6acfa3e97
--- /dev/null
+++ b/server/src/modules/annotation/annotation-hub.service.test.ts
@@ -0,0 +1,375 @@
+import { ConflictException, NotFoundException } from '@nestjs/common';
+
+import { AnnotationHubService } from './annotation-hub.service';
+
+function makeHubRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 1,
+    bookId: 5,
+    cfi: 'epubcfi(/6/4!/4/2/1:0)',
+    cfiStatus: 'exact',
+    cfiExtras: { chapterIndex: 2 },
+    text: 'selected text',
+    color: 'yellow',
+    style: 'highlight',
+    note: 'a note',
+    chapterTitle: 'Chapter 1',
+    origin: 'web',
+    version: 1,
+    deletedAt: null,
+    deviceCreatedAt: null,
+    deviceUpdatedAt: null,
+    createdAt: new Date('2026-01-10T00:00:00Z'),
+    updatedAt: new Date('2026-01-10T00:00:00Z'),
+    bookTitle: 'A Book',
+    author: 'An Author',
+    jumpFileId: 9,
+    pageno: null,
+    ...overrides,
+  };
+}
+
+function makeService() {
+  const annotationRepo = {
+    findHubPaginated: vi.fn().mockResolvedValue({ items: [makeHubRow()], total: 1 }),
+    getHubStats: vi.fn().mockResolvedValue({ books: 1, withNotes: 1, web: 1, koreader: 0, kobo: 0 }),
+    findHubAll: vi.fn().mockResolvedValue([makeHubRow()]),
+    findHubBookFacets: vi.fn().mockResolvedValue([{ bookId: 5, bookTitle: 'A Book', author: 'An Author', count: 3 }]),
+    findHubBookFacet: vi.fn().mockResolvedValue(null),
+    bulkSetDeleted: vi.fn().mockResolvedValue(2),
+    bulkRestyle: vi.fn().mockResolvedValue(2),
+    restore: vi.fn().mockResolvedValue(makeHubRow({ deletedAt: null })),
+    findHubById: vi.fn().mockResolvedValue(makeHubRow()),
+    purge: vi.fn().mockResolvedValue('purged'),
+  };
+  const exportService = { export: vi.fn().mockResolvedValue({ contentType: 'text/markdown', filename: 'x.md', content: '#' }) };
+  const syncRepo = {
+    findAnnotationById: vi.fn().mockResolvedValue({ id: 1, bookId: 5, origin: 'web', version: 3, deletedAt: null }),
+    findPositionsByAnnotationIds: vi
+      .fn()
+      .mockResolvedValue([
+        { format: 'cfi', status: 'exact', extras: { reason: null }, converterVersion: 1, updatedAt: new Date('2026-01-10T00:00:00Z') },
+      ]),
+    findStatesByAnnotation: vi
+      .fn()
+      .mockResolvedValue([
+        { source: 'kobo', deviceId: '7', lastAppliedVersion: 2, deleteAckedAt: null, lastSyncedAt: new Date('2026-01-10T00:00:00Z') },
+      ]),
+    findKoboDeviceNames: vi.fn().mockResolvedValue(new Map([['7', 'Kobo Libra 2']])),
+    updatePosition: vi.fn().mockResolvedValue(undefined),
+  };
+  const conversionService = { ensureCfiPositionsForBook: vi.fn().mockResolvedValue(1) };
+  const service = new AnnotationHubService(annotationRepo as never, exportService as never, syncRepo as never, conversionService as never);
+  return { service, annotationRepo, exportService, syncRepo, conversionService };
+}
+
+describe('AnnotationHubService', () => {
+  describe('list', () => {
+    it('maps the date range to Date objects and the notes-only flag into repository filters', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, {
+        hasNote: true,
+        dateFrom: '2026-01-01T00:00:00.000Z',
+        dateTo: '2026-01-31T23:59:59.999Z',
+        page: 2,
+        pageSize: 50,
+      });
+
+      const [userId, filters, sort, page, pageSize] = annotationRepo.findHubPaginated.mock.calls[0];
+      expect(userId).toBe(10);
+      expect(filters.hasNote).toBe(true);
+      expect(filters.dateFrom).toBeInstanceOf(Date);
+      expect(filters.dateFrom.toISOString()).toBe('2026-01-01T00:00:00.000Z');
+      expect(filters.dateTo.toISOString()).toBe('2026-01-31T23:59:59.999Z');
+      expect(filters.status).toBe('active');
+      expect(sort).toEqual({ by: 'createdAt', dir: 'desc' });
+      expect(page).toBe(2);
+      expect(pageSize).toBe(50);
+      // stats query receives the same filters so the counts match the filtered list
+      expect(annotationRepo.getHubStats.mock.calls[0][1].hasNote).toBe(true);
+    });
+
+    it('omits the date range and notes-only filter when not provided', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, {});
+
+      const filters = annotationRepo.findHubPaginated.mock.calls[0][1];
+      expect(filters.hasNote).toBeUndefined();
+      expect(filters.dateFrom).toBeUndefined();
+      expect(filters.dateTo).toBeUndefined();
+    });
+
+    it('treats hasNote=false as no filter', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, { hasNote: false });
+
+      expect(annotationRepo.findHubPaginated.mock.calls[0][1].hasNote).toBeUndefined();
+    });
+
+    it('passes the book sort through to the repository', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, { sortBy: 'book', sortDir: 'asc' });
+
+      expect(annotationRepo.findHubPaginated.mock.calls[0][2]).toEqual({ by: 'book', dir: 'asc' });
+    });
+
+    it('splits comma-separated colors, styles and origins into arrays', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, { colors: '#FACC15, #4ADE80', styles: 'highlight,underline', origins: 'web , koreader' });
+
+      const filters = annotationRepo.findHubPaginated.mock.calls[0][1];
+      expect(filters.colors).toEqual(['#FACC15', '#4ADE80']);
+      expect(filters.styles).toEqual(['highlight', 'underline']);
+      expect(filters.origins).toEqual(['web', 'koreader']);
+    });
+
+    it('drops filter values that are empty after splitting', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.list(10, { colors: ' , , ' });
+
+      expect(annotationRepo.findHubPaginated.mock.calls[0][1].colors).toBeUndefined();
+    });
+
+    it('maps a trashed row with no cfi position to a null status, null chapter and a deletedAt timestamp', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.findHubPaginated.mockResolvedValueOnce({
+        items: [makeHubRow({ cfi: null, cfiStatus: null, cfiExtras: null, deletedAt: new Date('2026-01-05T00:00:00Z') })],
+        total: 1,
+      });
+
+      const result = await service.list(10, {});
+
+      expect(result.items[0].positionStatus).toBeNull();
+      expect(result.items[0].chapterIndex).toBeNull();
+      expect(result.items[0].deletedAt).toBe('2026-01-05T00:00:00.000Z');
+    });
+
+    it('returns mapped items and computed stats', async () => {
+      const { service } = makeService();
+
+      const result = await service.list(10, {});
+
+      expect(result.total).toBe(1);
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(25);
+      expect(result.items[0]).toMatchObject({ id: 1, bookId: 5, note: 'a note', chapterIndex: 2, positionStatus: 'exact' });
+      expect(result.stats.books).toBe(1);
+      expect(result.stats.withNotes).toBe(1);
+      expect(result.stats.originBreakdown).toEqual([{ origin: 'web', count: 1 }]);
+    });
+  });
+
+  describe('listBooks', () => {
+    it('maps book facets and forwards the default limit', async () => {
+      const { service, annotationRepo } = makeService();
+
+      const facets = await service.listBooks(10, { status: 'active' });
+
+      expect(annotationRepo.findHubBookFacets).toHaveBeenCalledWith(10, { status: 'active', q: undefined, limit: 20 });
+      expect(facets).toEqual([{ bookId: 5, bookTitle: 'A Book', author: 'An Author', count: 3 }]);
+    });
+
+    it('forwards the search term and a custom limit', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.listBooks(10, { status: 'trashed', q: 'dune', limit: 5 });
+
+      expect(annotationRepo.findHubBookFacets).toHaveBeenCalledWith(10, { status: 'trashed', q: 'dune', limit: 5 });
+    });
+
+    it('pins the selected book at the top when it is outside the returned facets', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.findHubBookFacet.mockResolvedValue({ bookId: 99, bookTitle: 'Pinned', author: null, count: 7 });
+
+      const facets = await service.listBooks(10, { status: 'active', selectedId: 99 });
+
+      expect(annotationRepo.findHubBookFacet).toHaveBeenCalledWith(10, 'active', 99);
+      expect(facets[0]).toEqual({ bookId: 99, bookTitle: 'Pinned', author: null, count: 7 });
+      expect(facets).toHaveLength(2);
+    });
+
+    it('does not re-fetch or duplicate the selected book when it is already present', async () => {
+      const { service, annotationRepo } = makeService();
+
+      const facets = await service.listBooks(10, { status: 'active', selectedId: 5 });
+
+      expect(annotationRepo.findHubBookFacet).not.toHaveBeenCalled();
+      expect(facets).toHaveLength(1);
+    });
+  });
+
+  describe('bulk', () => {
+    it('trashes the given ids', async () => {
+      const { service, annotationRepo } = makeService();
+
+      const result = await service.bulk(10, { ids: [1, 2], action: 'trash' });
+
+      expect(annotationRepo.bulkSetDeleted).toHaveBeenCalledWith(10, [1, 2], true);
+      expect(result).toEqual({ affected: 2 });
+    });
+
+    it('restores the given ids', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.bulk(10, { ids: [1], action: 'restore' });
+
+      expect(annotationRepo.bulkSetDeleted).toHaveBeenCalledWith(10, [1], false);
+    });
+
+    it('restyles the given ids with color and style', async () => {
+      const { service, annotationRepo } = makeService();
+
+      await service.bulk(10, { ids: [1], action: 'restyle', color: '#38BDF8', style: 'underline' });
+
+      expect(annotationRepo.bulkRestyle).toHaveBeenCalledWith(10, [1], { color: '#38BDF8', style: 'underline' });
+    });
+  });
+
+  describe('restore', () => {
+    it('restores and returns the refreshed hub item', async () => {
+      const { service } = makeService();
+
+      const result = await service.restore(10, 1);
+
+      expect(result).toMatchObject({ id: 1, bookId: 5 });
+    });
+
+    it('throws NotFoundException when the annotation is not in trash', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.restore.mockResolvedValueOnce(null);
+
+      await expect(service.restore(10, 1)).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('falls back to the restored row when the hub re-read misses', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.findHubById.mockResolvedValueOnce(null);
+
+      const result = await service.restore(10, 1);
+
+      expect(result).toMatchObject({ id: 1, cfi: null });
+    });
+  });
+
+  describe('purge', () => {
+    it('resolves when the annotation is purged', async () => {
+      const { service } = makeService();
+
+      await expect(service.purge(10, 1)).resolves.toBeUndefined();
+    });
+
+    it('throws ConflictException when a device still has it queued', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.purge.mockResolvedValueOnce('pending_device_sync');
+
+      await expect(service.purge(10, 1)).rejects.toBeInstanceOf(ConflictException);
+    });
+
+    it('throws NotFoundException when nothing matched', async () => {
+      const { service, annotationRepo } = makeService();
+      annotationRepo.purge.mockResolvedValueOnce('not_found');
+
+      await expect(service.purge(10, 1)).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
+
+  describe('syncDetail', () => {
+    it('returns positions and per-device sync info with kobo display names', async () => {
+      const { service } = makeService();
+
+      const detail = await service.syncDetail(10, 1);
+
+      expect(detail.annotationId).toBe(1);
+      expect(detail.version).toBe(3);
+      expect(detail.positions[0]).toMatchObject({ format: 'cfi', status: 'exact', reason: null });
+      expect(detail.devices[0]).toMatchObject({ source: 'kobo', deviceName: 'Kobo Libra 2', upToDate: false });
+    });
+
+    it('marks a deleted annotation up to date once the device acknowledged the deletion', async () => {
+      const { service, syncRepo } = makeService();
+      syncRepo.findAnnotationById.mockResolvedValueOnce({
+        id: 1,
+        bookId: 5,
+        origin: 'koreader',
+        version: 3,
+        deletedAt: new Date('2026-01-05T00:00:00Z'),
+      });
+      syncRepo.findStatesByAnnotation.mockResolvedValueOnce([
+        {
+          source: 'koreader',
+          deviceId: 'kdev',
+          lastAppliedVersion: 1,
+          deleteAckedAt: new Date('2026-01-06T00:00:00Z'),
+          lastSyncedAt: new Date('2026-01-06T00:00:00Z'),
+        },
+      ]);
+
+      const detail = await service.syncDetail(10, 1);
+
+      expect(detail.devices[0].upToDate).toBe(true);
+      expect(detail.devices[0].deleteAckedAt).toBe('2026-01-06T00:00:00.000Z');
+      expect(detail.devices[0].deviceName).toBeNull();
+    });
+
+    it('throws NotFoundException for an unknown annotation', async () => {
+      const { service, syncRepo } = makeService();
+      syncRepo.findAnnotationById.mockResolvedValueOnce(null);
+
+      await expect(service.syncDetail(10, 99)).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
+
+  describe('retryPosition', () => {
+    it('marks the cfi position pending and recomputes it immediately', async () => {
+      const { service, syncRepo, conversionService } = makeService();
+
+      await service.retryPosition(10, 1, 'cfi');
+
+      expect(syncRepo.updatePosition).toHaveBeenCalledWith(1, 'cfi', { status: 'pending', converterVersion: null });
+      expect(conversionService.ensureCfiPositionsForBook).toHaveBeenCalledWith(10, 5);
+    });
+
+    it('does not run cfi conversion for device formats', async () => {
+      const { service, conversionService } = makeService();
+
+      await service.retryPosition(10, 1, 'xpointer');
+
+      expect(conversionService.ensureCfiPositionsForBook).not.toHaveBeenCalled();
+    });
+
+    it('throws NotFoundException for an unknown annotation', async () => {
+      const { service, syncRepo } = makeService();
+      syncRepo.findAnnotationById.mockResolvedValueOnce(null);
+
+      await expect(service.retryPosition(10, 99, 'cfi')).rejects.toBeInstanceOf(NotFoundException);
+    });
+  });
+
+  describe('export', () => {
+    it('forwards the notes-only and date filters to the repository and the export service', async () => {
+      const { service, annotationRepo, exportService } = makeService();
+
+      const result = await service.export(10, { hasNote: true, dateFrom: '2026-01-01T00:00:00.000Z', format: 'csv' }, 'library');
+
+      const filters = annotationRepo.findHubAll.mock.calls[0][1];
+      expect(filters.hasNote).toBe(true);
+      expect(filters.dateFrom).toBeInstanceOf(Date);
+      expect(exportService.export).toHaveBeenCalledWith([makeHubRow()], 'csv', 'library');
+      expect(result.filename).toBe('x.md');
+    });
+
+    it('defaults the export format to markdown when omitted', async () => {
+      const { service, exportService } = makeService();
+
+      await service.export(10, {}, 'library');
+
+      expect(exportService.export.mock.calls[0][1]).toBe('md');
+    });
+  });
+});
diff --git a/server/src/modules/annotation/annotation-hub.service.ts b/server/src/modules/annotation/annotation-hub.service.ts
new file mode 100644
index 000000000..281d0297a
--- /dev/null
+++ b/server/src/modules/annotation/annotation-hub.service.ts
@@ -0,0 +1,219 @@
+import { ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+
+import type {
+  AnnotationDeviceSyncInfo,
+  AnnotationHubBookFacet,
+  AnnotationHubItem,
+  AnnotationHubResponse,
+  AnnotationHubStats,
+  AnnotationPositionFormat,
+  AnnotationPositionInfo,
+  AnnotationSyncDetail,
+} from '@bookorbit/types';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { AnnotationConversionService } from './annotation-conversion.service';
+import { AnnotationExportService, type AnnotationExportFormat, type AnnotationExportResult } from './annotation-export.service';
+import { AnnotationSyncRepository } from './annotation-sync.repository';
+import { AnnotationRepository, type HubAnnotationRow, type HubFilters, type HubSort } from './annotation.repository';
+import type { AnnotationBulkDto, AnnotationExportQueryDto, AnnotationHubQueryDto } from './dto/annotation-hub.dto';
+
+const BULK_EVENT = 'annotation.bulk';
+const RETRY_EVENT = 'annotation.position_retry';
+const DEFAULT_BOOK_FACET_LIMIT = 20;
+
+function toBookFacet(row: { bookId: number; bookTitle: string | null; author: string | null; count: number }): AnnotationHubBookFacet {
+  return { bookId: row.bookId, bookTitle: row.bookTitle, author: row.author, count: Number(row.count) };
+}
+
+@Injectable()
+export class AnnotationHubService {
+  private readonly logger = new Logger(AnnotationHubService.name);
+
+  constructor(
+    private readonly annotationRepo: AnnotationRepository,
+    private readonly exportService: AnnotationExportService,
+    private readonly syncRepo: AnnotationSyncRepository,
+    private readonly conversionService: AnnotationConversionService,
+  ) {}
+
+  async list(userId: number, query: AnnotationHubQueryDto): Promise<AnnotationHubResponse> {
+    const page = query.page ?? 1;
+    const pageSize = query.pageSize ?? 25;
+    const filters = this.buildFilters(query);
+    const [{ items, total }, statsRow] = await Promise.all([
+      this.annotationRepo.findHubPaginated(userId, filters, this.buildSort(query), page, pageSize),
+      this.annotationRepo.getHubStats(userId, filters),
+    ]);
+    const stats: AnnotationHubStats = {
+      books: Number(statsRow?.books ?? 0),
+      withNotes: Number(statsRow?.withNotes ?? 0),
+      originBreakdown: (
+        [
+          { origin: 'web', count: Number(statsRow?.web ?? 0) },
+          { origin: 'koreader', count: Number(statsRow?.koreader ?? 0) },
+          { origin: 'kobo', count: Number(statsRow?.kobo ?? 0) },
+        ] as AnnotationHubStats['originBreakdown']
+      ).filter((entry) => entry.count > 0),
+    };
+    return { items: items.map((row) => this.toHubItem(row)), total, page, pageSize, stats };
+  }
+
+  async listBooks(
+    userId: number,
+    params: { status: 'active' | 'trashed'; q?: string; limit?: number; selectedId?: number },
+  ): Promise<AnnotationHubBookFacet[]> {
+    const limit = params.limit ?? DEFAULT_BOOK_FACET_LIMIT;
+    const rows = await this.annotationRepo.findHubBookFacets(userId, { status: params.status, q: params.q, limit });
+    const facets = rows.map(toBookFacet);
+    if (params.selectedId && !facets.some((facet) => facet.bookId === params.selectedId)) {
+      const selected = await this.annotationRepo.findHubBookFacet(userId, params.status, params.selectedId);
+      if (selected) facets.unshift(toBookFacet(selected));
+    }
+    return facets;
+  }
+
+  async bulk(userId: number, dto: AnnotationBulkDto): Promise<{ affected: number }> {
+    const startedAtMs = Date.now();
+    let affected: number;
+    if (dto.action === 'trash') {
+      affected = await this.annotationRepo.bulkSetDeleted(userId, dto.ids, true);
+    } else if (dto.action === 'restore') {
+      affected = await this.annotationRepo.bulkSetDeleted(userId, dto.ids, false);
+    } else {
+      affected = await this.annotationRepo.bulkRestyle(userId, dto.ids, { color: dto.color, style: dto.style });
+    }
+    this.logger.log(
+      `[${BULK_EVENT}] [end] userId=${userId} action=${dto.action} requested=${dto.ids.length} affected=${affected} durationMs=${Date.now() - startedAtMs} - bulk annotation action applied`,
+    );
+    return { affected };
+  }
+
+  async restore(userId: number, annotationId: number): Promise<AnnotationHubItem> {
+    const restored = await this.annotationRepo.restore(annotationId, userId);
+    if (!restored) throw new NotFoundException(`Annotation ${annotationId} not found in trash`);
+    const row = await this.annotationRepo.findHubById(userId, annotationId);
+    return this.toHubItem(
+      row ?? { ...restored, cfi: null, cfiStatus: null, cfiExtras: null, bookTitle: null, author: null, jumpFileId: null, pageno: null },
+    );
+  }
+
+  /** Hard delete; blocked until every synced device acknowledged the deletion. */
+  async purge(userId: number, annotationId: number): Promise<void> {
+    const result = await this.annotationRepo.purge(annotationId, userId);
+    if (result === 'not_found') throw new NotFoundException(`Annotation ${annotationId} not found in trash`);
+    if (result === 'pending_device_sync') {
+      throw new ConflictException('This annotation is still queued for deletion on a synced device. Sync the device first or keep it in trash.');
+    }
+  }
+
+  async export(userId: number, query: AnnotationExportQueryDto, scopeLabel: string): Promise<AnnotationExportResult> {
+    const format: AnnotationExportFormat = query.format ?? 'md';
+    const rows = await this.annotationRepo.findHubAll(userId, this.buildFilters(query));
+    this.logger.log(
+      `[annotation.export] [end] userId=${userId} format=${format} rows=${rows.length} scope="${sanitizeLogValue(scopeLabel)}" - annotations exported`,
+    );
+    return this.exportService.export(rows, format, scopeLabel);
+  }
+
+  async syncDetail(userId: number, annotationId: number): Promise<AnnotationSyncDetail> {
+    const annotation = await this.syncRepo.findAnnotationById(annotationId, userId);
+    if (!annotation) throw new NotFoundException(`Annotation ${annotationId} not found`);
+
+    const [positionRows, stateRows] = await Promise.all([
+      this.syncRepo.findPositionsByAnnotationIds([annotationId], ['cfi', 'xpointer', 'pdf', 'kobo_span']),
+      this.syncRepo.findStatesByAnnotation(annotationId, userId),
+    ]);
+
+    const koboDeviceIds = stateRows.filter((state) => state.source === 'kobo' && /^\d+$/.test(state.deviceId)).map((state) => Number(state.deviceId));
+    const koboNames = await this.syncRepo.findKoboDeviceNames(koboDeviceIds);
+
+    const positions: AnnotationPositionInfo[] = positionRows.map((row) => ({
+      format: row.format as AnnotationPositionFormat,
+      status: row.status as AnnotationPositionInfo['status'],
+      reason: typeof (row.extras as { reason?: unknown } | null)?.reason === 'string' ? ((row.extras as { reason: string }).reason ?? null) : null,
+      converterVersion: row.converterVersion,
+      updatedAt: row.updatedAt.toISOString(),
+    }));
+
+    const devices: AnnotationDeviceSyncInfo[] = stateRows.map((state) => ({
+      source: state.source as AnnotationDeviceSyncInfo['source'],
+      deviceId: state.deviceId,
+      deviceName: state.source === 'kobo' ? (koboNames.get(state.deviceId) ?? null) : null,
+      lastAppliedVersion: state.lastAppliedVersion,
+      upToDate: annotation.deletedAt ? state.deleteAckedAt != null : state.lastAppliedVersion >= annotation.version,
+      deleteAckedAt: state.deleteAckedAt ? state.deleteAckedAt.toISOString() : null,
+      lastSyncedAt: state.lastSyncedAt.toISOString(),
+    }));
+
+    return { annotationId, origin: annotation.origin as AnnotationSyncDetail['origin'], version: annotation.version, positions, devices };
+  }
+
+  /**
+   * Resets a position to pending so converters recompute it. cfi recomputes
+   * immediately; device formats recompute on that device type's next sync.
+   */
+  async retryPosition(userId: number, annotationId: number, format: AnnotationPositionFormat): Promise<AnnotationSyncDetail> {
+    const annotation = await this.syncRepo.findAnnotationById(annotationId, userId);
+    if (!annotation) throw new NotFoundException(`Annotation ${annotationId} not found`);
+
+    await this.syncRepo.updatePosition(annotationId, format, { status: 'pending', converterVersion: null });
+    let converted = 0;
+    if (format === 'cfi') {
+      converted = await this.conversionService.ensureCfiPositionsForBook(userId, annotation.bookId);
+    }
+    this.logger.log(
+      `[${RETRY_EVENT}] [end] userId=${userId} annotationId=${annotationId} format=${format} converted=${converted} - position retry applied`,
+    );
+    return this.syncDetail(userId, annotationId);
+  }
+
+  private toHubItem(row: HubAnnotationRow): AnnotationHubItem {
+    const chapterIndex = (row.cfiExtras as { chapterIndex?: number } | null)?.chapterIndex;
+    return {
+      id: row.id,
+      bookId: row.bookId,
+      cfi: row.cfi,
+      text: row.text,
+      color: row.color,
+      style: row.style,
+      note: row.note,
+      chapterTitle: row.chapterTitle,
+      origin: row.origin,
+      positionStatus: (row.cfi != null || row.cfiStatus != null ? (row.cfiStatus ?? 'exact') : null) as AnnotationHubItem['positionStatus'],
+      chapterIndex: typeof chapterIndex === 'number' ? chapterIndex : null,
+      createdAt: row.createdAt.toISOString(),
+      bookTitle: row.bookTitle,
+      author: row.author,
+      deletedAt: row.deletedAt ? row.deletedAt.toISOString() : null,
+      jumpFileId: row.jumpFileId,
+      pageno: row.pageno,
+    };
+  }
+
+  private buildFilters(query: AnnotationHubQueryDto): HubFilters {
+    const split = (value: string | undefined): string[] | undefined => {
+      if (!value) return undefined;
+      const parts = value
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+      return parts.length > 0 ? parts : undefined;
+    };
+    return {
+      bookId: query.bookId,
+      colors: split(query.colors),
+      styles: split(query.styles),
+      origins: split(query.origins),
+      chapter: query.chapter || undefined,
+      search: query.search || undefined,
+      dateFrom: query.dateFrom ? new Date(query.dateFrom) : undefined,
+      dateTo: query.dateTo ? new Date(query.dateTo) : undefined,
+      hasNote: query.hasNote || undefined,
+      status: query.status ?? 'active',
+    };
+  }
+
+  private buildSort(query: AnnotationHubQueryDto): HubSort {
+    return { by: query.sortBy ?? 'createdAt', dir: query.sortDir ?? 'desc' };
+  }
+}
diff --git a/server/src/modules/annotation/annotation-position.repository.ts b/server/src/modules/annotation/annotation-position.repository.ts
new file mode 100644
index 000000000..09f3b0b89
--- /dev/null
+++ b/server/src/modules/annotation/annotation-position.repository.ts
@@ -0,0 +1,75 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../db';
+import * as schema from '../../db/schema';
+import { annotationPositions, annotations, AnnotationPosition, NewAnnotationPosition } from '../../db/schema';
+import type { AnnotationPositionFormat } from './annotation.constants';
+
+type Db = NodePgDatabase<typeof schema>;
+
+@Injectable()
+export class AnnotationPositionRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async upsert(position: NewAnnotationPosition): Promise<AnnotationPosition> {
+    const [row] = await this.db
+      .insert(annotationPositions)
+      .values(position)
+      .onConflictDoUpdate({
+        target: [annotationPositions.annotationId, annotationPositions.format],
+        set: {
+          pos0: sql`excluded.pos0`,
+          pos1: sql`excluded.pos1`,
+          status: sql`excluded.status`,
+          converterVersion: sql`excluded.converter_version`,
+          extras: sql`excluded.extras`,
+          bookFileId: sql`excluded.book_file_id`,
+          updatedAt: new Date(),
+        },
+      })
+      .returning();
+    return row;
+  }
+
+  async findByAnnotationIds(annotationIds: number[]): Promise<AnnotationPosition[]> {
+    if (annotationIds.length === 0) return [];
+    return this.db.select().from(annotationPositions).where(inArray(annotationPositions.annotationId, annotationIds));
+  }
+
+  async findByAnnotationId(annotationId: number, format?: AnnotationPositionFormat): Promise<AnnotationPosition[]> {
+    const conditions = [eq(annotationPositions.annotationId, annotationId)];
+    if (format) conditions.push(eq(annotationPositions.format, format));
+    return this.db
+      .select()
+      .from(annotationPositions)
+      .where(and(...conditions));
+  }
+
+  /** Active annotations of a book joined with their device xpointer position. */
+  async findXPointerRowsForBook(
+    userId: number,
+    bookId: number,
+  ): Promise<{ annotationId: number; text: string; pos0: string | null; pos1: string | null; bookFileId: number | null; status: string }[]> {
+    return this.db
+      .select({
+        annotationId: annotations.id,
+        text: annotations.text,
+        pos0: annotationPositions.pos0,
+        pos1: annotationPositions.pos1,
+        bookFileId: annotationPositions.bookFileId,
+        status: annotationPositions.status,
+      })
+      .from(annotations)
+      .innerJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'xpointer')))
+      .where(and(eq(annotations.userId, userId), eq(annotations.bookId, bookId), isNull(annotations.deletedAt)));
+  }
+
+  async markPending(annotationId: number, format: AnnotationPositionFormat): Promise<void> {
+    await this.db
+      .update(annotationPositions)
+      .set({ status: 'pending', updatedAt: sql`now()` })
+      .where(and(eq(annotationPositions.annotationId, annotationId), eq(annotationPositions.format, format)));
+  }
+}
diff --git a/server/src/modules/annotation/annotation-style-map.test.ts b/server/src/modules/annotation/annotation-style-map.test.ts
new file mode 100644
index 000000000..7c402c065
--- /dev/null
+++ b/server/src/modules/annotation/annotation-style-map.test.ts
@@ -0,0 +1,144 @@
+import {
+  applyDeviceColor,
+  applyDeviceStyle,
+  drawerFromStyle,
+  hexFromKoboColor,
+  hexFromKoreaderColor,
+  koboColorFromHex,
+  koreaderColorFromHex,
+  styleFromDrawer,
+} from './annotation-style-map';
+
+describe('annotation-style-map', () => {
+  describe('styleFromDrawer / drawerFromStyle', () => {
+    it('maps each drawer to its canonical style', () => {
+      expect(styleFromDrawer('lighten')).toBe('highlight');
+      expect(styleFromDrawer('underscore')).toBe('underline');
+      expect(styleFromDrawer('strikeout')).toBe('strikethrough');
+      expect(styleFromDrawer('invert')).toBe('invert');
+    });
+
+    it('falls back to highlight for unknown drawers', () => {
+      expect(styleFromDrawer('wavy')).toBe('highlight');
+      expect(styleFromDrawer(null)).toBe('highlight');
+    });
+
+    it('maps canonical styles to drawers with squiggly degrading to underscore', () => {
+      expect(drawerFromStyle('highlight')).toBe('lighten');
+      expect(drawerFromStyle('underline')).toBe('underscore');
+      expect(drawerFromStyle('strikethrough')).toBe('strikeout');
+      expect(drawerFromStyle('squiggly')).toBe('underscore');
+      expect(drawerFromStyle('invert')).toBe('invert');
+    });
+
+    it('round-trips every drawer through canonical and back', () => {
+      for (const drawer of ['lighten', 'underscore', 'strikeout', 'invert'] as const) {
+        expect(drawerFromStyle(styleFromDrawer(drawer))).toBe(drawer);
+      }
+    });
+  });
+
+  describe('hexFromKoreaderColor', () => {
+    it('maps KOReader named colors to BookOrbit equivalents', () => {
+      expect(hexFromKoreaderColor('yellow')).toBe('#FACC15');
+      expect(hexFromKoreaderColor('olive')).toBe('#84CC16');
+      expect(hexFromKoreaderColor('cyan')).toBe('#22D3EE');
+      expect(hexFromKoreaderColor('GRAY')).toBe('#9CA3AF');
+    });
+
+    it('maps exact KOReader hex values to BookOrbit equivalents', () => {
+      expect(hexFromKoreaderColor('#ffff33')).toBe('#FACC15');
+      expect(hexFromKoreaderColor('88ff77')).toBe('#84CC16');
+    });
+
+    it('passes through unknown hex values, normalizing case and prefix', () => {
+      expect(hexFromKoreaderColor('#abc123')).toBe('#ABC123');
+      expect(hexFromKoreaderColor('facc15')).toBe('#FACC15');
+    });
+
+    it('defaults to yellow for null or junk', () => {
+      expect(hexFromKoreaderColor(null)).toBe('#FACC15');
+      expect(hexFromKoreaderColor('not-a-color')).toBe('#FACC15');
+    });
+  });
+
+  describe('koreaderColorFromHex', () => {
+    it('returns the exact name for known hex values', () => {
+      expect(koreaderColorFromHex('#FFFF33')).toBe('yellow');
+      expect(koreaderColorFromHex('#0066FF')).toBe('blue');
+    });
+
+    it('picks the nearest named color for arbitrary hex', () => {
+      expect(koreaderColorFromHex('#FACC15')).toBe('yellow');
+      expect(koreaderColorFromHex('#F472B6')).toBe('purple');
+      expect(koreaderColorFromHex('#84CC16')).toBe('olive');
+      expect(koreaderColorFromHex('#22D3EE')).toBe('cyan');
+      expect(koreaderColorFromHex('#C084FC')).toBe('purple');
+      expect(koreaderColorFromHex('#9CA3AF')).toBe('gray');
+      expect(koreaderColorFromHex('#111111')).toBe('gray');
+    });
+
+    it('defaults to yellow for unparsable input', () => {
+      expect(koreaderColorFromHex('nope')).toBe('yellow');
+      expect(koreaderColorFromHex(null)).toBe('yellow');
+    });
+  });
+
+  describe('applyDeviceStyle (projection rule)', () => {
+    it('keeps canonical squiggly when the device echoes its projected underscore', () => {
+      expect(applyDeviceStyle('squiggly', 'underscore')).toBe('squiggly');
+    });
+
+    it('applies a genuinely different drawer', () => {
+      expect(applyDeviceStyle('squiggly', 'lighten')).toBe('highlight');
+      expect(applyDeviceStyle('highlight', 'strikeout')).toBe('strikethrough');
+    });
+
+    it('keeps the canonical style when drawer is missing', () => {
+      expect(applyDeviceStyle('underline', null)).toBe('underline');
+    });
+  });
+
+  describe('applyDeviceColor (projection rule)', () => {
+    it('keeps a custom web hex when the device echoes its projected named color', () => {
+      expect(applyDeviceColor('#FACC15', 'yellow')).toBe('#FACC15');
+    });
+
+    it('applies a genuinely different named color', () => {
+      expect(applyDeviceColor('#FACC15', 'blue')).toBe('#38BDF8');
+    });
+
+    it('applies exact device hex colors as BookOrbit equivalents', () => {
+      expect(applyDeviceColor('#FACC15', '#00AA66')).toBe('#4ADE80');
+    });
+
+    it('keeps the canonical color when the device sends none', () => {
+      expect(applyDeviceColor('#FACC15', null)).toBe('#FACC15');
+    });
+  });
+
+  describe('Kobo color mapping', () => {
+    it('maps Kobo colors into BookOrbit equivalents', () => {
+      expect(hexFromKoboColor('#F6F3B3')).toBe('#FACC15');
+      expect(hexFromKoboColor('#E8AFCF')).toBe('#F472B6');
+    });
+
+    it('uses explicit Kobo fallbacks for BookOrbit colors', () => {
+      expect(koboColorFromHex('#F87171')).toBe('#E8AFCF');
+      expect(koboColorFromHex('#FB923C')).toBe('#F6F3B3');
+      expect(koboColorFromHex('#84CC16')).toBe('#C6E09E');
+      expect(koboColorFromHex('#22D3EE')).toBe('#B2E1E8');
+      expect(koboColorFromHex('#C084FC')).toBe('#E8AFCF');
+      expect(koboColorFromHex('#9CA3AF')).toBe('#F6F3B3');
+    });
+
+    it('uses explicit Kobo fallbacks for exact KOReader colors', () => {
+      expect(koboColorFromHex('#FF3300')).toBe('#E8AFCF');
+      expect(koboColorFromHex('#FF8800')).toBe('#F6F3B3');
+      expect(koboColorFromHex('#FFFF33')).toBe('#F6F3B3');
+      expect(koboColorFromHex('#00FFEE')).toBe('#B2E1E8');
+      expect(koboColorFromHex('#EE00FF')).toBe('#E8AFCF');
+      expect(koboColorFromHex('#808080')).toBe('#F6F3B3');
+    });
+  });
+});
diff --git a/server/src/modules/annotation/annotation-style-map.ts b/server/src/modules/annotation/annotation-style-map.ts
new file mode 100644
index 000000000..9957571b4
--- /dev/null
+++ b/server/src/modules/annotation/annotation-style-map.ts
@@ -0,0 +1,187 @@
+import {
+  ANNOTATION_HIGHLIGHT_COLORS,
+  KOBO_HIGHLIGHT_COLORS,
+  KOREADER_HIGHLIGHT_COLORS,
+  type KoboHighlightColorName,
+  type KoreaderHighlightColorName,
+} from '@bookorbit/types';
+import type { AnnotationStyle } from './annotation.constants';
+
+export const KOREADER_DRAWERS = ['lighten', 'underscore', 'strikeout', 'invert'] as const;
+export type KoreaderDrawer = (typeof KOREADER_DRAWERS)[number];
+
+const DRAWER_TO_STYLE: Record<KoreaderDrawer, AnnotationStyle> = {
+  lighten: 'highlight',
+  underscore: 'underline',
+  strikeout: 'strikethrough',
+  invert: 'invert',
+};
+
+// squiggly has no KOReader equivalent and degrades to underscore on the device.
+const STYLE_TO_DRAWER: Record<AnnotationStyle, KoreaderDrawer> = {
+  highlight: 'lighten',
+  underline: 'underscore',
+  strikethrough: 'strikeout',
+  squiggly: 'underscore',
+  invert: 'invert',
+};
+
+type AnnotationHighlightColor = (typeof ANNOTATION_HIGHLIGHT_COLORS)[number];
+type KoreaderHighlightColor = (typeof KOREADER_HIGHLIGHT_COLORS)[number];
+
+const APP_COLOR_BY_HEX = Object.fromEntries(ANNOTATION_HIGHLIGHT_COLORS.map((color) => [color.hex, color])) as Record<
+  string,
+  AnnotationHighlightColor
+>;
+const KOREADER_BY_NAME = Object.fromEntries(KOREADER_HIGHLIGHT_COLORS.map((color) => [color.name, color])) as Record<string, KoreaderHighlightColor>;
+const KOREADER_BY_HEX = Object.fromEntries(KOREADER_HIGHLIGHT_COLORS.map((color) => [color.hex, color])) as Record<string, KoreaderHighlightColor>;
+
+// Hex values mirror KOReader's BlitBuffer.HIGHLIGHT_COLORS. Gray has no entry there
+// because it renders through dimming, so a neutral mid-gray represents it here.
+export const KOREADER_COLOR_HEX = Object.fromEntries(KOREADER_HIGHLIGHT_COLORS.map((color) => [color.name, color.hex])) as Record<
+  KoreaderHighlightColorName,
+  string
+>;
+
+export const DEFAULT_KOREADER_COLOR_HEX = KOREADER_BY_NAME.yellow.hex;
+export const DEFAULT_ANNOTATION_COLOR_HEX = KOREADER_BY_NAME.yellow.appHex;
+
+export function styleFromDrawer(drawer: string | null | undefined): AnnotationStyle {
+  return DRAWER_TO_STYLE[drawer as KoreaderDrawer] ?? 'highlight';
+}
+
+export function drawerFromStyle(style: string | null | undefined): KoreaderDrawer {
+  return STYLE_TO_DRAWER[style as AnnotationStyle] ?? 'lighten';
+}
+
+export function hexFromKoreaderColor(color: string | null | undefined): string {
+  if (!color) return DEFAULT_ANNOTATION_COLOR_HEX;
+  const named = KOREADER_BY_NAME[color.trim().toLowerCase()];
+  if (named) return named.appHex;
+  const normalized = normalizeHex(color);
+  if (!normalized) return DEFAULT_ANNOTATION_COLOR_HEX;
+  return KOREADER_BY_HEX[normalized]?.appHex ?? normalized;
+}
+
+export function koreaderColorFromHex(hex: string | null | undefined): string {
+  const normalized = normalizeHex(hex);
+  if (!normalized) return 'yellow';
+  const appColor = APP_COLOR_BY_HEX[normalized];
+  if (appColor) return appColor.koreaderFallback;
+  const exactKoreaderColor = KOREADER_BY_HEX[normalized];
+  if (exactKoreaderColor) return exactKoreaderColor.name;
+
+  const rgb = parseHex(normalized);
+  if (!rgb) return 'yellow';
+  // Raw RGB distance misjudges grayness in both directions (desaturated pinks land on
+  // gray, near-blacks land on green), so saturation decides gray membership outright.
+  const isChromatic = Math.max(rgb.r, rgb.g, rgb.b) - Math.min(rgb.r, rgb.g, rgb.b) >= 40;
+  if (!isChromatic) return 'gray';
+  let best = 'yellow';
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const color of KOREADER_HIGHLIGHT_COLORS) {
+    if (color.name === 'gray') continue;
+    const named = parseHex(color.hex)!;
+    const distance = (rgb.r - named.r) ** 2 + (rgb.g - named.g) ** 2 + (rgb.b - named.b) ** 2;
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = color.name;
+    }
+  }
+  return best;
+}
+
+/**
+ * Round-trip stability: a device echoing back the projected view of a canonical field must
+ * not overwrite it (canonical `squiggly` survives a device echo of `underscore`). Only a
+ * genuinely different device value up-maps and replaces the canonical one.
+ */
+export function applyDeviceStyle(currentStyle: AnnotationStyle, incomingDrawer: string | null | undefined): AnnotationStyle {
+  if (!incomingDrawer) return currentStyle;
+  if (drawerFromStyle(currentStyle) === incomingDrawer) return currentStyle;
+  return styleFromDrawer(incomingDrawer);
+}
+
+export function applyDeviceColor(currentHex: string, incomingColor: string | null | undefined): string {
+  if (!incomingColor) return currentHex;
+  const incoming = incomingColor.trim().toLowerCase();
+  const named = KOREADER_BY_NAME[incoming];
+  if (named) {
+    if (koreaderColorFromHex(currentHex) === incoming) return currentHex;
+    return named.appHex;
+  }
+  return hexFromKoreaderColor(incomingColor);
+}
+
+/** Kobo firmware's four fixed highlight colors. */
+export const KOBO_COLOR_HEX = Object.fromEntries(KOBO_HIGHLIGHT_COLORS.map((color) => [color.name, color.hex])) as Record<
+  KoboHighlightColorName,
+  string
+>;
+
+export const DEFAULT_KOBO_COLOR_HEX = KOBO_COLOR_HEX.yellow;
+
+const KOBO_TO_APP_COLOR: Record<string, string> = {
+  [KOBO_COLOR_HEX.yellow]: '#FACC15',
+  [KOBO_COLOR_HEX.green]: '#4ADE80',
+  [KOBO_COLOR_HEX.blue]: '#38BDF8',
+  [KOBO_COLOR_HEX.pink]: '#F472B6',
+};
+
+const APP_TO_KOBO_COLOR = Object.fromEntries([
+  ...ANNOTATION_HIGHLIGHT_COLORS.map((color) => [color.hex, KOBO_COLOR_HEX[color.koboFallback]]),
+  ...KOREADER_HIGHLIGHT_COLORS.map((color) => [color.hex, KOBO_COLOR_HEX[color.koboFallback]]),
+]) as Record<string, string>;
+
+export function hexFromKoboColor(color: string | null | undefined): string {
+  const normalized = normalizeHex(color);
+  if (!normalized) return KOBO_TO_APP_COLOR[DEFAULT_KOBO_COLOR_HEX];
+  return KOBO_TO_APP_COLOR[normalized] ?? KOBO_TO_APP_COLOR[koboColorFromHex(normalized)];
+}
+
+export function koboColorFromHex(hex: string | null | undefined): string {
+  const normalized = normalizeHex(hex);
+  if (!normalized) return DEFAULT_KOBO_COLOR_HEX;
+  if (Object.values(KOBO_COLOR_HEX).includes(normalized)) return normalized;
+  const direct = APP_TO_KOBO_COLOR[normalized];
+  if (direct) return direct;
+  const rgb = parseHex(normalized);
+  if (!rgb) return DEFAULT_KOBO_COLOR_HEX;
+  let best = DEFAULT_KOBO_COLOR_HEX;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const koboHex of Object.values(KOBO_COLOR_HEX)) {
+    const named = parseHex(koboHex)!;
+    const distance = (rgb.r - named.r) ** 2 + (rgb.g - named.g) ** 2 + (rgb.b - named.b) ** 2;
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = koboHex;
+    }
+  }
+  return best;
+}
+
+/** Same round-trip stability rule as applyDeviceColor, over Kobo's palette. */
+export function applyKoboDeviceColor(currentHex: string, incomingKoboColor: string | null | undefined): string {
+  const incoming = normalizeHex(incomingKoboColor);
+  if (!incoming) return currentHex;
+  if (koboColorFromHex(currentHex) === incoming) return currentHex;
+  return hexFromKoboColor(incoming);
+}
+
+function normalizeHex(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const match = /^#?([0-9a-f]{6})$/i.exec(value.trim());
+  return match ? `#${match[1].toUpperCase()}` : null;
+}
+
+function parseHex(hex: string | null | undefined): { r: number; g: number; b: number } | null {
+  if (!hex) return null;
+  const match = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!match) return null;
+  const value = match[1];
+  return {
+    r: parseInt(value.slice(0, 2), 16),
+    g: parseInt(value.slice(2, 4), 16),
+    b: parseInt(value.slice(4, 6), 16),
+  };
+}
diff --git a/server/src/modules/annotation/annotation-sync.repository.ts b/server/src/modules/annotation/annotation-sync.repository.ts
new file mode 100644
index 000000000..b5c439352
--- /dev/null
+++ b/server/src/modules/annotation/annotation-sync.repository.ts
@@ -0,0 +1,530 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, asc, eq, getTableColumns, inArray, isNotNull, isNull, notExists, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../db';
+import * as schema from '../../db/schema';
+import {
+  annotationPositions,
+  annotationSyncState,
+  annotations,
+  koboDevices,
+  AnnotationPosition,
+  AnnotationRow,
+  AnnotationSyncStateRow,
+  NewAnnotation,
+  NewAnnotationPosition,
+  NewAnnotationSyncState,
+} from '../../db/schema';
+import type { AnnotationPositionFormat, AnnotationSyncSource } from './annotation.constants';
+
+type Db = NodePgDatabase<typeof schema>;
+export type DbTx = Parameters<Parameters<Db['transaction']>[0]>[0];
+type Executor = Db | DbTx;
+
+export interface CanonicalWithPosition {
+  annotation: AnnotationRow;
+  position: AnnotationPosition | null;
+}
+
+@Injectable()
+export class AnnotationSyncRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  transaction<T>(fn: (tx: DbTx) => Promise<T>): Promise<T> {
+    return this.db.transaction(fn);
+  }
+
+  async findStateByDeviceKey(
+    userId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    bookId: number,
+    externalKey: string,
+    ex: Executor = this.db,
+  ): Promise<AnnotationSyncStateRow | null> {
+    const [row] = await ex
+      .select({ state: annotationSyncState })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          eq(annotationSyncState.externalKey, externalKey),
+          eq(annotations.bookId, bookId),
+        ),
+      )
+      .limit(1);
+    return row?.state ?? null;
+  }
+
+  async findStateByKeyAnyDevice(
+    userId: number,
+    source: AnnotationSyncSource,
+    externalKey: string,
+    bookId: number,
+    ex: Executor = this.db,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow } | null> {
+    const [row] = await ex
+      .select({ state: annotationSyncState, annotation: annotations })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.externalKey, externalKey),
+          eq(annotations.bookId, bookId),
+        ),
+      )
+      .orderBy(asc(annotationSyncState.id))
+      .limit(1);
+    return row ?? null;
+  }
+
+  async findAnnotationById(annotationId: number, userId: number, ex: Executor = this.db): Promise<AnnotationRow | null> {
+    const [row] = await ex
+      .select()
+      .from(annotations)
+      .where(and(eq(annotations.id, annotationId), eq(annotations.userId, userId)))
+      .limit(1);
+    return row ?? null;
+  }
+
+  async findDevicePosition(annotationId: number, format: AnnotationPositionFormat, ex: Executor = this.db): Promise<AnnotationPosition | null> {
+    const [row] = await ex
+      .select()
+      .from(annotationPositions)
+      .where(and(eq(annotationPositions.annotationId, annotationId), eq(annotationPositions.format, format)))
+      .limit(1);
+    return row ?? null;
+  }
+
+  /**
+   * Canonical annotations carrying the given device-creation datetime, with their
+   * device-format position. Matches both koreader-origin rows (datetime from the device)
+   * and web-origin rows whose datetime was minted for device push.
+   */
+  async findCanonicalByDeviceDatetime(
+    userId: number,
+    bookId: number,
+    datetime: string,
+    format: AnnotationPositionFormat,
+    ex: Executor = this.db,
+  ): Promise<CanonicalWithPosition[]> {
+    const rows = await ex
+      .select({ annotation: annotations, position: annotationPositions })
+      .from(annotations)
+      .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, format)))
+      .where(and(eq(annotations.userId, userId), eq(annotations.bookId, bookId), eq(annotations.deviceCreatedAt, datetime)));
+    return rows;
+  }
+
+  async insertState(state: NewAnnotationSyncState, ex: Executor = this.db): Promise<AnnotationSyncStateRow> {
+    const [row] = await ex
+      .insert(annotationSyncState)
+      .values(state)
+      .onConflictDoUpdate({
+        target: [annotationSyncState.annotationId, annotationSyncState.source, annotationSyncState.deviceId],
+        set: {
+          externalKey: sql`excluded.external_key`,
+          externalCreatedAt: sql`excluded.external_created_at`,
+          lastAppliedVersion: sql`excluded.last_applied_version`,
+          deleteAckedAt: sql`excluded.delete_acked_at`,
+          lastSyncedAt: new Date(),
+        },
+      })
+      .returning();
+    return row;
+  }
+
+  async updateState(
+    stateId: number,
+    patch: Partial<Pick<AnnotationSyncStateRow, 'externalKey' | 'externalCreatedAt' | 'lastAppliedVersion' | 'deleteAckedAt'>>,
+    ex: Executor = this.db,
+  ): Promise<void> {
+    await ex
+      .update(annotationSyncState)
+      .set({ ...patch, lastSyncedAt: sql`now()` })
+      .where(eq(annotationSyncState.id, stateId));
+  }
+
+  async touchState(stateId: number, ex: Executor = this.db): Promise<void> {
+    await ex
+      .update(annotationSyncState)
+      .set({ lastSyncedAt: sql`now()` })
+      .where(eq(annotationSyncState.id, stateId));
+  }
+
+  async createCanonical(
+    annotation: NewAnnotation,
+    position: Omit<NewAnnotationPosition, 'annotationId' | 'userId'>,
+    state: Omit<NewAnnotationSyncState, 'annotationId' | 'userId'>,
+    ex: Executor = this.db,
+  ): Promise<AnnotationRow> {
+    const [row] = await ex.insert(annotations).values(annotation).returning();
+    await ex.insert(annotationPositions).values({ ...position, annotationId: row.id, userId: row.userId });
+    await ex.insert(annotationSyncState).values({ ...state, annotationId: row.id, userId: row.userId });
+    return row;
+  }
+
+  /** Applies a content patch and bumps the version; returns the new version. */
+  async applyContentPatch(
+    annotationId: number,
+    patch: Partial<Pick<AnnotationRow, 'text' | 'note' | 'color' | 'style' | 'chapterTitle' | 'deviceUpdatedAt' | 'deviceCreatedAt'>>,
+    ex: Executor = this.db,
+  ): Promise<number> {
+    const [row] = await ex
+      .update(annotations)
+      .set({ ...patch, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(eq(annotations.id, annotationId))
+      .returning({ version: annotations.version });
+    return row.version;
+  }
+
+  async updatePosition(
+    annotationId: number,
+    format: AnnotationPositionFormat,
+    patch: Partial<Pick<AnnotationPosition, 'pos0' | 'pos1' | 'status' | 'converterVersion' | 'extras' | 'bookFileId'>>,
+    ex: Executor = this.db,
+  ): Promise<void> {
+    await ex
+      .update(annotationPositions)
+      .set({ ...patch, updatedAt: sql`now()` })
+      .where(and(eq(annotationPositions.annotationId, annotationId), eq(annotationPositions.format, format)));
+  }
+
+  async markPositionPending(annotationId: number, format: AnnotationPositionFormat, ex: Executor = this.db): Promise<void> {
+    await ex
+      .update(annotationPositions)
+      .set({ status: 'pending', updatedAt: sql`now()` })
+      .where(and(eq(annotationPositions.annotationId, annotationId), eq(annotationPositions.format, format)));
+  }
+
+  /** Unacked sync states for one device and book, used for device-deletion detection. */
+  async findStatesForDeviceBook(
+    userId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    bookId: number,
+    ex: Executor = this.db,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return ex
+      .select({ state: annotationSyncState, annotation: annotations })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          eq(annotations.bookId, bookId),
+        ),
+      );
+  }
+
+  /** Active annotations of the book with no sync state for this device (push-down adds). */
+  async findAddCandidates(userId: number, source: AnnotationSyncSource, deviceId: string, bookId: number, limit: number): Promise<AnnotationRow[]> {
+    return this.db
+      .select(getTableColumns(annotations))
+      .from(annotations)
+      .where(
+        and(
+          eq(annotations.userId, userId),
+          eq(annotations.bookId, bookId),
+          isNull(annotations.deletedAt),
+          notExists(
+            this.db
+              .select({ one: sql`1` })
+              .from(annotationSyncState)
+              .where(
+                and(
+                  eq(annotationSyncState.annotationId, annotations.id),
+                  eq(annotationSyncState.source, source),
+                  eq(annotationSyncState.deviceId, deviceId),
+                ),
+              ),
+          ),
+        ),
+      )
+      .orderBy(asc(annotations.id))
+      .limit(limit);
+  }
+
+  /** Active annotations whose version is ahead of what this device acknowledged (edits). */
+  async findEditCandidates(
+    userId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    bookId: number,
+    limit: number,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return this.db
+      .select({ state: annotationSyncState, annotation: annotations })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          eq(annotations.bookId, bookId),
+          isNull(annotations.deletedAt),
+          sql`${annotations.version} > ${annotationSyncState.lastAppliedVersion}`,
+        ),
+      )
+      .orderBy(asc(annotations.id))
+      .limit(limit);
+  }
+
+  /** Soft-deleted annotations this device has not acknowledged deleting yet. */
+  async findDeleteCandidates(
+    userId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    bookId: number,
+    limit: number,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return this.db
+      .select({ state: annotationSyncState, annotation: annotations })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          eq(annotations.bookId, bookId),
+          isNotNull(annotations.deletedAt),
+          isNull(annotationSyncState.deleteAckedAt),
+        ),
+      )
+      .orderBy(asc(annotations.id))
+      .limit(limit);
+  }
+
+  async listDeviceCreatedAtsForBook(userId: number, bookId: number, ex: Executor = this.db): Promise<Set<string>> {
+    const rows = await ex
+      .select({ deviceCreatedAt: annotations.deviceCreatedAt })
+      .from(annotations)
+      .where(and(eq(annotations.userId, userId), eq(annotations.bookId, bookId), isNotNull(annotations.deviceCreatedAt)));
+    return new Set(rows.map((row) => row.deviceCreatedAt).filter((value): value is string => value != null));
+  }
+
+  /** Bookkeeping writes that must NOT bump the version (no device-visible change). */
+  async setDeviceIdentitySilent(annotationId: number, deviceCreatedAt: string, ex: Executor = this.db): Promise<void> {
+    await ex.update(annotations).set({ deviceCreatedAt }).where(eq(annotations.id, annotationId));
+  }
+
+  async setDeviceUpdatedAtSilent(annotationId: number, deviceUpdatedAt: string | null, ex: Executor = this.db): Promise<void> {
+    await ex.update(annotations).set({ deviceUpdatedAt }).where(eq(annotations.id, annotationId));
+  }
+
+  async bumpVersion(annotationId: number, ex: Executor = this.db): Promise<number> {
+    const [row] = await ex
+      .update(annotations)
+      .set({ version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(eq(annotations.id, annotationId))
+      .returning({ version: annotations.version });
+    return row.version;
+  }
+
+  async softDeleteById(annotationId: number, ex: Executor = this.db): Promise<void> {
+    await ex
+      .update(annotations)
+      .set({ deletedAt: sql`now()`, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(and(eq(annotations.id, annotationId), isNull(annotations.deletedAt)));
+  }
+
+  async setDeleteAcked(stateId: number, ex: Executor = this.db): Promise<void> {
+    await ex
+      .update(annotationSyncState)
+      .set({ deleteAckedAt: sql`now()`, lastSyncedAt: sql`now()` })
+      .where(eq(annotationSyncState.id, stateId));
+  }
+
+  async findStateByAnnotationAndDevice(
+    annotationId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    ex: Executor = this.db,
+  ): Promise<AnnotationSyncStateRow | null> {
+    const [row] = await ex
+      .select()
+      .from(annotationSyncState)
+      .where(
+        and(eq(annotationSyncState.annotationId, annotationId), eq(annotationSyncState.source, source), eq(annotationSyncState.deviceId, deviceId)),
+      )
+      .limit(1);
+    return row ?? null;
+  }
+
+  async upsertPosition(position: NewAnnotationPosition, ex: Executor = this.db): Promise<void> {
+    await ex
+      .insert(annotationPositions)
+      .values(position)
+      .onConflictDoUpdate({
+        target: [annotationPositions.annotationId, annotationPositions.format],
+        set: {
+          pos0: sql`excluded.pos0`,
+          pos1: sql`excluded.pos1`,
+          status: sql`excluded.status`,
+          converterVersion: sql`excluded.converter_version`,
+          extras: sql`excluded.extras`,
+          bookFileId: sql`excluded.book_file_id`,
+          updatedAt: new Date(),
+        },
+      });
+  }
+
+  async findPositionsByAnnotationIds(
+    annotationIds: number[],
+    formats: AnnotationPositionFormat[],
+    ex: Executor = this.db,
+  ): Promise<AnnotationPosition[]> {
+    if (annotationIds.length === 0) return [];
+    return ex
+      .select()
+      .from(annotationPositions)
+      .where(and(inArray(annotationPositions.annotationId, annotationIds), inArray(annotationPositions.format, formats)));
+  }
+
+  async findActiveByBook(userId: number, bookId: number, ex: Executor = this.db): Promise<AnnotationRow[]> {
+    return ex
+      .select()
+      .from(annotations)
+      .where(and(eq(annotations.userId, userId), eq(annotations.bookId, bookId), isNull(annotations.deletedAt)))
+      .orderBy(asc(annotations.id));
+  }
+
+  async findStatesByAnnotation(annotationId: number, userId: number, ex: Executor = this.db): Promise<AnnotationSyncStateRow[]> {
+    return ex
+      .select()
+      .from(annotationSyncState)
+      .where(and(eq(annotationSyncState.annotationId, annotationId), eq(annotationSyncState.userId, userId)))
+      .orderBy(asc(annotationSyncState.id));
+  }
+
+  /** Display names for kobo device ids (sync-state deviceId holds the numeric id as text). */
+  async findKoboDeviceNames(deviceIds: number[], ex: Executor = this.db): Promise<Map<string, string>> {
+    if (deviceIds.length === 0) return new Map();
+    const rows = await ex.select({ id: koboDevices.id, name: koboDevices.name }).from(koboDevices).where(inArray(koboDevices.id, deviceIds));
+    return new Map(rows.map((row) => [String(row.id), row.name]));
+  }
+
+  /** Earliest external key any device of the source holds for this annotation. */
+  async findExternalKeyForAnnotation(annotationId: number, source: AnnotationSyncSource, ex: Executor = this.db): Promise<string | null> {
+    const [row] = await ex
+      .select({ externalKey: annotationSyncState.externalKey })
+      .from(annotationSyncState)
+      .where(and(eq(annotationSyncState.annotationId, annotationId), eq(annotationSyncState.source, source)))
+      .orderBy(asc(annotationSyncState.id))
+      .limit(1);
+    return row?.externalKey ?? null;
+  }
+
+  /** All sync states of a source for one book, across devices, with their annotations. */
+  async findStatesBySourceForBook(
+    userId: number,
+    source: AnnotationSyncSource,
+    bookId: number,
+    ex: Executor = this.db,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return ex
+      .select({ state: annotationSyncState, annotation: annotations })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(and(eq(annotationSyncState.userId, userId), eq(annotationSyncState.source, source), eq(annotations.bookId, bookId)));
+  }
+
+  /**
+   * Book ids with annotation changes a Kobo device has not seen: unacked deletions,
+   * edits past the acked version, and unserved additions. Additions exclude
+   * annotations whose kobo_span conversion already failed at the current resolver
+   * version, or checkforchanges would report them forever.
+   */
+  async findBookIdsWithPendingKoboChanges(
+    userId: number,
+    deviceId: string,
+    opts: { includeAllOrigins: boolean; resolverVersion: number },
+  ): Promise<number[]> {
+    const source: AnnotationSyncSource = 'kobo';
+    const bookIds = new Set<number>();
+
+    const tombstones = await this.db
+      .selectDistinct({ bookId: annotations.bookId })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          isNotNull(annotations.deletedAt),
+          isNull(annotationSyncState.deleteAckedAt),
+        ),
+      );
+    for (const row of tombstones) bookIds.add(row.bookId);
+
+    const edits = await this.db
+      .selectDistinct({ bookId: annotations.bookId })
+      .from(annotationSyncState)
+      .innerJoin(annotations, eq(annotations.id, annotationSyncState.annotationId))
+      .where(
+        and(
+          eq(annotationSyncState.userId, userId),
+          eq(annotationSyncState.source, source),
+          eq(annotationSyncState.deviceId, deviceId),
+          isNull(annotations.deletedAt),
+          sql`${annotations.version} > ${annotationSyncState.lastAppliedVersion}`,
+        ),
+      );
+    for (const row of edits) bookIds.add(row.bookId);
+
+    const notServedToThisDevice = notExists(
+      this.db
+        .select({ one: sql`1` })
+        .from(annotationSyncState)
+        .where(
+          and(
+            eq(annotationSyncState.annotationId, annotations.id),
+            eq(annotationSyncState.source, source),
+            eq(annotationSyncState.deviceId, deviceId),
+          ),
+        ),
+    );
+
+    const addConditions = opts.includeAllOrigins
+      ? and(
+          eq(annotations.userId, userId),
+          isNull(annotations.deletedAt),
+          notServedToThisDevice,
+          notExists(
+            this.db
+              .select({ one: sql`1` })
+              .from(annotationPositions)
+              .where(
+                and(
+                  eq(annotationPositions.annotationId, annotations.id),
+                  eq(annotationPositions.format, 'kobo_span'),
+                  eq(annotationPositions.status, 'failed'),
+                  eq(annotationPositions.converterVersion, opts.resolverVersion),
+                ),
+              ),
+          ),
+        )
+      : and(
+          eq(annotations.userId, userId),
+          isNull(annotations.deletedAt),
+          notServedToThisDevice,
+          sql`exists (select 1 from ${annotationSyncState} other where other.annotation_id = ${annotations.id} and other.source = ${source})`,
+        );
+
+    const adds = await this.db.selectDistinct({ bookId: annotations.bookId }).from(annotations).where(addConditions);
+    for (const row of adds) bookIds.add(row.bookId);
+
+    return [...bookIds];
+  }
+}
diff --git a/server/src/modules/annotation/annotation-sync.service.test.ts b/server/src/modules/annotation/annotation-sync.service.test.ts
new file mode 100644
index 000000000..ddac2ec0d
--- /dev/null
+++ b/server/src/modules/annotation/annotation-sync.service.test.ts
@@ -0,0 +1,709 @@
+import { Logger } from '@nestjs/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { AnnotationSyncRepository } from './annotation-sync.repository';
+import { AnnotationSyncService, buildAnnotationKey, type IncomingDeviceAnnotation } from './annotation-sync.service';
+
+const USER_ID = 7;
+const BOOK_ID = 20;
+const BOOK_FILE_ID = 10;
+const DEVICE_ID = 'device-aaaa-bbbb';
+const TX = Symbol('tx');
+
+function makeIncoming(overrides: Partial<IncomingDeviceAnnotation> = {}): IncomingDeviceAnnotation {
+  return {
+    datetime: '2026-06-01 21:14:03',
+    datetimeUpdated: null,
+    drawer: 'lighten',
+    color: 'yellow',
+    text: 'highlighted text',
+    note: null,
+    chapter: 'Chapter 1',
+    pageno: 12,
+    posFormat: 'xpointer',
+    pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+    pos1: '/body/DocFragment[8]/body/p[12]/text().57',
+    ...overrides,
+  };
+}
+
+function makeAnnotationRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 100,
+    userId: USER_ID,
+    bookId: BOOK_ID,
+    text: 'highlighted text',
+    color: '#FACC15',
+    style: 'highlight',
+    note: null,
+    chapterTitle: 'Chapter 1',
+    origin: 'koreader',
+    version: 1,
+    deletedAt: null,
+    deviceCreatedAt: '2026-06-01 21:14:03',
+    deviceUpdatedAt: null,
+    createdAt: new Date('2026-06-01T21:14:03Z'),
+    updatedAt: new Date('2026-06-01T21:14:03Z'),
+    ...overrides,
+  };
+}
+
+function makePositionRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 500,
+    annotationId: 100,
+    userId: USER_ID,
+    bookFileId: BOOK_FILE_ID,
+    format: 'xpointer',
+    pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+    pos1: '/body/DocFragment[8]/body/p[12]/text().57',
+    status: 'exact',
+    converterVersion: null,
+    extras: { pageno: 12 },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function makeStateRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 900,
+    annotationId: 100,
+    userId: USER_ID,
+    source: 'koreader',
+    deviceId: DEVICE_ID,
+    externalKey: buildAnnotationKey('2026-06-01 21:14:03', '/body/DocFragment[8]/body/p[12]/text().0'),
+    externalCreatedAt: '2026-06-01 21:14:03',
+    lastAppliedVersion: 1,
+    deleteAckedAt: null,
+    firstSyncedAt: new Date(),
+    lastSyncedAt: new Date(),
+    ...overrides,
+  };
+}
+
+type RepoMock = Record<keyof AnnotationSyncRepository, ReturnType<typeof vi.fn>>;
+
+function makeRepo(): RepoMock {
+  return {
+    transaction: vi.fn().mockImplementation(async (fn: (tx: unknown) => Promise<unknown>) => fn(TX)),
+    findStateByDeviceKey: vi.fn().mockResolvedValue(null),
+    findStateByKeyAnyDevice: vi.fn().mockResolvedValue(null),
+    findAnnotationById: vi.fn().mockResolvedValue(null),
+    findDevicePosition: vi.fn().mockResolvedValue(null),
+    findCanonicalByDeviceDatetime: vi.fn().mockResolvedValue([]),
+    insertState: vi.fn().mockImplementation((state: Record<string, unknown>) => Promise.resolve(makeStateRow(state))),
+    updateState: vi.fn().mockResolvedValue(undefined),
+    touchState: vi.fn().mockResolvedValue(undefined),
+    createCanonical: vi.fn().mockImplementation((annotation: Record<string, unknown>) => Promise.resolve(makeAnnotationRow(annotation))),
+    applyContentPatch: vi.fn().mockResolvedValue(2),
+    updatePosition: vi.fn().mockResolvedValue(undefined),
+    markPositionPending: vi.fn().mockResolvedValue(undefined),
+    findStatesForDeviceBook: vi.fn().mockResolvedValue([]),
+    findAddCandidates: vi.fn().mockResolvedValue([]),
+    findEditCandidates: vi.fn().mockResolvedValue([]),
+    findDeleteCandidates: vi.fn().mockResolvedValue([]),
+    listDeviceCreatedAtsForBook: vi.fn().mockResolvedValue(new Set<string>()),
+    setDeviceIdentitySilent: vi.fn().mockResolvedValue(undefined),
+    setDeviceUpdatedAtSilent: vi.fn().mockResolvedValue(undefined),
+    bumpVersion: vi.fn().mockResolvedValue(5),
+    softDeleteById: vi.fn().mockResolvedValue(undefined),
+    setDeleteAcked: vi.fn().mockResolvedValue(undefined),
+    findStateByAnnotationAndDevice: vi.fn().mockResolvedValue(null),
+    upsertPosition: vi.fn().mockResolvedValue(undefined),
+    findPositionsByAnnotationIds: vi.fn().mockResolvedValue([]),
+    findExternalKeyForAnnotation: vi.fn().mockResolvedValue(null),
+    findStatesBySourceForBook: vi.fn().mockResolvedValue([]),
+    findBookIdsWithPendingKoboChanges: vi.fn().mockResolvedValue([]),
+  } as unknown as RepoMock;
+}
+
+function makeService(repo: RepoMock) {
+  return new AnnotationSyncService(repo as unknown as AnnotationSyncRepository);
+}
+
+function ingest(service: AnnotationSyncService, annotations: IncomingDeviceAnnotation[]) {
+  return service.ingestDeviceAnnotations({
+    userId: USER_ID,
+    source: 'koreader',
+    deviceId: DEVICE_ID,
+    bookId: BOOK_ID,
+    bookFileId: BOOK_FILE_ID,
+    annotations,
+  });
+}
+
+describe('AnnotationSyncService', () => {
+  let repo: RepoMock;
+  let service: AnnotationSyncService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+    repo = makeRepo();
+    service = makeService(repo);
+  });
+
+  describe('buildAnnotationKey', () => {
+    it('is stable and sensitive to both datetime and pos0', () => {
+      const key = buildAnnotationKey('2026-06-01 21:14:03', '/pos');
+      expect(key).toMatch(/^[0-9a-f]{32}$/);
+      expect(buildAnnotationKey('2026-06-01 21:14:03', '/pos')).toBe(key);
+      expect(buildAnnotationKey('2026-06-01 21:14:04', '/pos')).not.toBe(key);
+      expect(buildAnnotationKey('2026-06-01 21:14:03', '/other')).not.toBe(key);
+    });
+  });
+
+  describe('create path', () => {
+    it('creates canonical row, device position and sync state for an unknown annotation', async () => {
+      const result = await ingest(service, [makeIncoming({ color: 'olive', drawer: 'underscore' })]);
+
+      expect(result).toMatchObject({ created: 1, updated: 0, moved: 0, unchanged: 0, skippedDeleted: 0 });
+      const [annotation, position, state] = repo.createCanonical.mock.calls[0] as [
+        Record<string, unknown>,
+        Record<string, unknown>,
+        Record<string, unknown>,
+      ];
+      expect(annotation).toMatchObject({
+        userId: USER_ID,
+        bookId: BOOK_ID,
+        origin: 'koreader',
+        style: 'underline',
+        color: '#84CC16',
+        version: 1,
+        deviceCreatedAt: '2026-06-01 21:14:03',
+      });
+      expect(position).toMatchObject({
+        bookFileId: BOOK_FILE_ID,
+        format: 'xpointer',
+        pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+        status: 'exact',
+        extras: { pageno: 12 },
+      });
+      expect(state).toMatchObject({ source: 'koreader', deviceId: DEVICE_ID, lastAppliedVersion: 1 });
+    });
+
+    it('dedupes identical keys within one batch', async () => {
+      const result = await ingest(service, [makeIncoming({ note: 'first' }), makeIncoming({ note: 'second' })]);
+
+      expect(result.created).toBe(1);
+      expect(repo.createCanonical).toHaveBeenCalledTimes(1);
+      const [annotation] = repo.createCanonical.mock.calls[0] as [Record<string, unknown>];
+      expect(annotation.note).toBe('second');
+    });
+  });
+
+  describe('device-key match path', () => {
+    it('treats a re-upload with no new edit as unchanged and only touches state', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow());
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming()]);
+
+      expect(result).toMatchObject({ unchanged: 1, updated: 0, created: 0 });
+      expect(repo.touchState).toHaveBeenCalled();
+      expect(repo.applyContentPatch).not.toHaveBeenCalled();
+    });
+
+    it('does not clobber web edits when the device re-sends an old payload', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ note: 'web note', color: '#FACC15' }));
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming({ note: null, color: 'yellow' })]);
+
+      expect(result.unchanged).toBe(1);
+      expect(repo.applyContentPatch).not.toHaveBeenCalled();
+    });
+
+    it('applies a newer device edit with projected style and color', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ style: 'squiggly', color: '#FACC15' }));
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [
+        makeIncoming({ datetimeUpdated: '2026-06-02 08:00:00', note: 'device note', drawer: 'underscore', color: 'yellow' }),
+      ]);
+
+      expect(result.updated).toBe(1);
+      const patch = repo.applyContentPatch.mock.calls[0][1] as Record<string, unknown>;
+      expect(patch).toMatchObject({ note: 'device note', deviceUpdatedAt: '2026-06-02 08:00:00' });
+      // projection: underscore echoes squiggly, yellow echoes #FACC15 - neither overwrites
+      expect(patch).not.toHaveProperty('style');
+      expect(patch).not.toHaveProperty('color');
+      expect(repo.updateState).toHaveBeenCalledWith(900, { lastAppliedVersion: 2 }, TX);
+    });
+
+    it('updates pos1 and marks the cfi position pending on highlight extension with same pos0', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow());
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming({ pos1: '/body/DocFragment[8]/body/p[13]/text().20' })]);
+
+      expect(result.updated).toBe(1);
+      expect(repo.updatePosition).toHaveBeenCalledWith(
+        100,
+        'xpointer',
+        expect.objectContaining({ pos1: '/body/DocFragment[8]/body/p[13]/text().20' }),
+        TX,
+      );
+      expect(repo.markPositionPending).toHaveBeenCalledWith(100, 'cfi', TX);
+    });
+
+    it('skips tombstoned annotations without resurrecting them', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ deletedAt: new Date() }));
+
+      const result = await ingest(service, [makeIncoming({ datetimeUpdated: '2026-06-05 10:00:00', note: 'edit after delete' })]);
+
+      expect(result.skippedDeleted).toBe(1);
+      expect(repo.applyContentPatch).not.toHaveBeenCalled();
+      expect(repo.createCanonical).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('cross-device and derived matches', () => {
+    it('links a second device to an existing annotation via the shared key', async () => {
+      repo.findStateByKeyAnyDevice.mockResolvedValue({
+        state: makeStateRow({ deviceId: 'other-device' }),
+        annotation: makeAnnotationRow({ version: 3 }),
+      });
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming()]);
+
+      expect(result.unchanged).toBe(1);
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ deviceId: DEVICE_ID, lastAppliedVersion: 3 }), TX);
+      expect(repo.createCanonical).not.toHaveBeenCalled();
+    });
+
+    it('arms deletion push for a tombstone matched cross-device', async () => {
+      repo.findStateByKeyAnyDevice.mockResolvedValue({
+        state: makeStateRow({ deviceId: 'other-device' }),
+        annotation: makeAnnotationRow({ deletedAt: new Date(), version: 4 }),
+      });
+
+      const result = await ingest(service, [makeIncoming()]);
+
+      expect(result.skippedDeleted).toBe(1);
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ deviceId: DEVICE_ID }), TX);
+    });
+
+    it('reconnects a migrated annotation by datetime plus pos0 without creating a duplicate', async () => {
+      repo.findCanonicalByDeviceDatetime.mockResolvedValue([{ annotation: makeAnnotationRow(), position: makePositionRow() }]);
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming()]);
+
+      expect(result.unchanged).toBe(1);
+      expect(repo.createCanonical).not.toHaveBeenCalled();
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ deviceId: DEVICE_ID, lastAppliedVersion: 1 }), TX);
+    });
+
+    it('treats a known datetime with a different pos0 as a move, not a delete or duplicate', async () => {
+      const oldPos = makePositionRow();
+      repo.findCanonicalByDeviceDatetime.mockResolvedValue([{ annotation: makeAnnotationRow(), position: oldPos }]);
+      repo.findDevicePosition.mockResolvedValue(makePositionRow({ pos0: '/body/DocFragment[8]/body/p[14]/text().5' }));
+      const moved = makeIncoming({ pos0: '/body/DocFragment[8]/body/p[14]/text().5', pos1: '/body/DocFragment[8]/body/p[15]/text().9' });
+
+      const result = await ingest(service, [moved]);
+
+      expect(result.moved).toBe(1);
+      expect(repo.updatePosition).toHaveBeenCalledWith(
+        100,
+        'xpointer',
+        expect.objectContaining({ pos0: '/body/DocFragment[8]/body/p[14]/text().5', status: 'exact' }),
+        TX,
+      );
+      expect(repo.markPositionPending).toHaveBeenCalledWith(100, 'cfi', TX);
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ externalKey: buildAnnotationKey(moved.datetime, moved.pos0) }), TX);
+      expect(repo.createCanonical).not.toHaveBeenCalled();
+    });
+
+    it('creates a new annotation when multiple same-datetime candidates are ambiguous', async () => {
+      repo.findCanonicalByDeviceDatetime.mockResolvedValue([
+        { annotation: makeAnnotationRow({ id: 100 }), position: makePositionRow({ pos0: '/a' }) },
+        { annotation: makeAnnotationRow({ id: 101 }), position: makePositionRow({ pos0: '/b' }) },
+      ]);
+
+      const result = await ingest(service, [makeIncoming({ pos0: '/c' })]);
+
+      expect(result.created).toBe(1);
+      expect(repo.createCanonical).toHaveBeenCalled();
+    });
+  });
+
+  describe('push echo handling', () => {
+    it('records a bumped device timestamp without bumping the version when content is unchanged', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow());
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow());
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ingest(service, [makeIncoming({ datetimeUpdated: '2026-06-09 12:00:00' })]);
+
+      expect(result.unchanged).toBe(1);
+      expect(repo.applyContentPatch).not.toHaveBeenCalled();
+      expect(repo.setDeviceUpdatedAtSilent).toHaveBeenCalledWith(100, '2026-06-09 12:00:00', TX);
+    });
+  });
+
+  describe('detectDeviceDeletions', () => {
+    const detect = (presentKeys: { k: string; dt: string }[]) =>
+      service.detectDeviceDeletions({ userId: USER_ID, source: 'koreader', deviceId: DEVICE_ID, bookId: BOOK_ID, presentKeys });
+
+    it('soft-deletes annotations missing from the device key set and acks this device', async () => {
+      repo.findStatesForDeviceBook.mockResolvedValue([{ state: makeStateRow(), annotation: makeAnnotationRow() }]);
+
+      const deleted = await detect([{ k: 'f'.repeat(32), dt: '2026-06-05 00:00:00' }]);
+
+      expect(deleted).toBe(1);
+      expect(repo.softDeleteById).toHaveBeenCalledWith(100, TX);
+      expect(repo.setDeleteAcked).toHaveBeenCalledWith(900, TX);
+    });
+
+    it('keeps annotations whose key is still present', async () => {
+      const state = makeStateRow();
+      repo.findStatesForDeviceBook.mockResolvedValue([{ state, annotation: makeAnnotationRow() }]);
+
+      const deleted = await detect([{ k: state.externalKey as string, dt: state.externalCreatedAt as string }]);
+
+      expect(deleted).toBe(0);
+      expect(repo.softDeleteById).not.toHaveBeenCalled();
+    });
+
+    it('treats a known datetime under a changed key as a move, not a delete', async () => {
+      repo.findStatesForDeviceBook.mockResolvedValue([{ state: makeStateRow(), annotation: makeAnnotationRow() }]);
+
+      const deleted = await detect([{ k: 'a'.repeat(32), dt: '2026-06-01 21:14:03' }]);
+
+      expect(deleted).toBe(0);
+      expect(repo.softDeleteById).not.toHaveBeenCalled();
+    });
+
+    it('ignores already-deleted annotations', async () => {
+      repo.findStatesForDeviceBook.mockResolvedValue([{ state: makeStateRow(), annotation: makeAnnotationRow({ deletedAt: new Date() }) }]);
+
+      const deleted = await detect([]);
+
+      expect(deleted).toBe(0);
+    });
+  });
+
+  describe('computePushDown', () => {
+    it('orders deletes before edits before adds within the limit', async () => {
+      repo.findDeleteCandidates.mockResolvedValue([{ state: makeStateRow({ id: 1 }), annotation: makeAnnotationRow({ id: 11 }) }]);
+      repo.findEditCandidates.mockResolvedValue([{ state: makeStateRow({ id: 2 }), annotation: makeAnnotationRow({ id: 12 }) }]);
+      repo.findAddCandidates.mockResolvedValue([makeAnnotationRow({ id: 13 })]);
+
+      const result = await service.computePushDown(USER_ID, 'koreader', DEVICE_ID, BOOK_ID, 10);
+
+      expect(result.deletes).toHaveLength(1);
+      expect(result.edits).toHaveLength(1);
+      expect(result.adds).toHaveLength(1);
+      expect(result.more).toBe(false);
+      expect(repo.findEditCandidates).toHaveBeenCalledWith(USER_ID, 'koreader', DEVICE_ID, BOOK_ID, 10);
+      expect(repo.findAddCandidates).toHaveBeenCalledWith(USER_ID, 'koreader', DEVICE_ID, BOOK_ID, 9);
+    });
+
+    it('reports more when a category overflows the remaining budget', async () => {
+      repo.findDeleteCandidates.mockResolvedValue([
+        { state: makeStateRow({ id: 1 }), annotation: makeAnnotationRow({ id: 11 }) },
+        { state: makeStateRow({ id: 2 }), annotation: makeAnnotationRow({ id: 12 }) },
+      ]);
+
+      const result = await service.computePushDown(USER_ID, 'koreader', DEVICE_ID, BOOK_ID, 1);
+
+      expect(result.deletes).toHaveLength(1);
+      expect(result.edits).toHaveLength(0);
+      expect(result.adds).toHaveLength(0);
+      expect(result.more).toBe(true);
+    });
+  });
+
+  describe('ensureDeviceCreatedAt', () => {
+    it('returns the existing identity datetime untouched', async () => {
+      const annotation = makeAnnotationRow();
+      const result = await service.ensureDeviceCreatedAt(USER_ID, BOOK_ID, annotation as never);
+      expect(result).toBe('2026-06-01 21:14:03');
+      expect(repo.setDeviceIdentitySilent).not.toHaveBeenCalled();
+    });
+
+    it('mints a unique UTC datetime from createdAt, skipping collisions', async () => {
+      const annotation = makeAnnotationRow({ deviceCreatedAt: null, createdAt: new Date('2026-06-08T10:00:00Z') });
+      repo.listDeviceCreatedAtsForBook.mockResolvedValue(new Set(['2026-06-08 10:00:00', '2026-06-08 10:00:01']));
+
+      const result = await service.ensureDeviceCreatedAt(USER_ID, BOOK_ID, annotation as never);
+
+      expect(result).toBe('2026-06-08 10:00:02');
+      expect(repo.setDeviceIdentitySilent).toHaveBeenCalledWith(100, '2026-06-08 10:00:02');
+    });
+  });
+
+  describe('applyExchangeAck', () => {
+    const ack = (
+      applied: Partial<Parameters<AnnotationSyncService['applyExchangeAck']>[0]['applied'][number]>[],
+      deleted: { serverId: number; status: 'applied' | 'failed' }[] = [],
+    ) =>
+      service.applyExchangeAck({
+        userId: USER_ID,
+        source: 'koreader',
+        deviceId: DEVICE_ID,
+        bookFileId: BOOK_FILE_ID,
+        applied: applied as never,
+        deleted,
+        converterVersion: 1,
+      });
+
+    it('advances lastAppliedVersion and verifies the position on a clean apply', async () => {
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ version: 3 }));
+      repo.findDevicePosition.mockResolvedValue(makePositionRow());
+
+      const result = await ack([{ serverId: 100, version: 3, status: 'applied', verified: true, datetimeUpdated: '2026-06-08 10:00:00' }]);
+
+      expect(result.acked).toBe(1);
+      expect(repo.updatePosition).toHaveBeenCalledWith(100, 'xpointer', { status: 'exact' }, TX);
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ lastAppliedVersion: 3, deviceId: DEVICE_ID }), TX);
+      expect(repo.setDeviceUpdatedAtSilent).toHaveBeenCalledWith(100, '2026-06-08 10:00:00', TX);
+      expect(repo.bumpVersion).not.toHaveBeenCalled();
+    });
+
+    it('stores corrected positions, rewrites the key and bumps the version for other devices', async () => {
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ version: 3 }));
+      repo.bumpVersion.mockResolvedValue(4);
+
+      const result = await ack([
+        {
+          serverId: 100,
+          version: 3,
+          status: 'applied',
+          verified: true,
+          corrected: true,
+          pos0: '/corrected/pos0',
+          pos1: '/corrected/pos1',
+          pageno: 7,
+        },
+      ]);
+
+      expect(result.acked).toBe(1);
+      expect(repo.upsertPosition).toHaveBeenCalledWith(
+        expect.objectContaining({ format: 'xpointer', pos0: '/corrected/pos0', pos1: '/corrected/pos1', status: 'repaired' }),
+        TX,
+      );
+      expect(repo.bumpVersion).toHaveBeenCalledWith(100, TX);
+      expect(repo.insertState).toHaveBeenCalledWith(
+        expect.objectContaining({
+          lastAppliedVersion: 4,
+          externalKey: buildAnnotationKey('2026-06-01 21:14:03', '/corrected/pos0'),
+        }),
+        TX,
+      );
+    });
+
+    it('marks the position failed without creating device state on a failed apply', async () => {
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow());
+
+      const result = await ack([{ serverId: 100, version: 3, status: 'failed' }]);
+
+      expect(result.acked).toBe(1);
+      expect(repo.updatePosition).toHaveBeenCalledWith(100, 'xpointer', { status: 'failed' }, TX);
+      expect(repo.insertState).not.toHaveBeenCalled();
+    });
+
+    it('acks deletions by setting deleteAckedAt', async () => {
+      repo.findStateByAnnotationAndDevice.mockResolvedValue(makeStateRow());
+
+      const result = await ack([], [{ serverId: 100, status: 'applied' }]);
+
+      expect(result.acked).toBe(1);
+      expect(repo.setDeleteAcked).toHaveBeenCalledWith(900, TX);
+    });
+
+    it('ignores acks for annotations the user does not own', async () => {
+      repo.findAnnotationById.mockResolvedValue(null);
+
+      const result = await ack([{ serverId: 999, version: 1, status: 'applied' }]);
+
+      expect(result.acked).toBe(0);
+      expect(repo.insertState).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('kobo external-key identity', () => {
+    const KOBO_UUID = '11111111-2222-3333-4444-555555555555';
+
+    function makeKoboIncoming(overrides: Partial<IncomingDeviceAnnotation> = {}): IncomingDeviceAnnotation {
+      return {
+        externalKey: KOBO_UUID,
+        datetime: '2026-06-01 21:14:03',
+        datetimeUpdated: null,
+        color: '#F6F3B3',
+        colorSpace: 'kobo',
+        style: 'highlight',
+        text: 'highlighted text',
+        note: null,
+        chapter: 'Chapter 1',
+        posFormat: 'kobo_span',
+        pos0: 'kobo.3.1:0',
+        pos1: 'kobo.3.1:16',
+        posExtras: { koboLocation: { span: { startPath: 'span#kobo\\.3\\.1' } } },
+        ...overrides,
+      };
+    }
+
+    function ingestKobo(annotations: IncomingDeviceAnnotation[]) {
+      return service.ingestDeviceAnnotations({
+        userId: USER_ID,
+        source: 'kobo',
+        deviceId: '42',
+        bookId: BOOK_ID,
+        bookFileId: BOOK_FILE_ID,
+        annotations,
+      });
+    }
+
+    it('creates a canonical annotation with kobo color mapping and location extras', async () => {
+      const result = await ingestKobo([makeKoboIncoming()]);
+
+      expect(result.created).toBe(1);
+      expect(repo.findCanonicalByDeviceDatetime).not.toHaveBeenCalled();
+      const [annotation, position, state] = repo.createCanonical.mock.calls[0];
+      expect(annotation).toMatchObject({ color: '#FACC15', style: 'highlight', origin: 'kobo' });
+      expect(position).toMatchObject({
+        format: 'kobo_span',
+        pos0: 'kobo.3.1:0',
+        pos1: 'kobo.3.1:16',
+        extras: { koboLocation: { span: { startPath: 'span#kobo\\.3\\.1' } } },
+      });
+      expect(state).toMatchObject({ externalKey: KOBO_UUID });
+    });
+
+    it('dedupes incoming batches by the external key', async () => {
+      const result = await ingestKobo([makeKoboIncoming({ text: 'first' }), makeKoboIncoming({ text: 'second' })]);
+      expect(result.created).toBe(1);
+      expect(repo.createCanonical).toHaveBeenCalledTimes(1);
+      expect(repo.createCanonical.mock.calls[0][0]).toMatchObject({ text: 'second' });
+    });
+
+    it('updates the position and invalidates siblings when pos0 changes under the same key', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow({ externalKey: KOBO_UUID, source: 'kobo', deviceId: '42' }));
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ origin: 'kobo', color: '#FACC15' }));
+      repo.findDevicePosition.mockResolvedValue(makePositionRow({ format: 'kobo_span', pos0: 'kobo.2.1:0', pos1: 'kobo.2.1:9' }));
+
+      const result = await ingestKobo([makeKoboIncoming()]);
+
+      expect(result.updated).toBe(1);
+      expect(repo.updatePosition).toHaveBeenCalledWith(
+        100,
+        'kobo_span',
+        expect.objectContaining({ pos0: 'kobo.3.1:0', pos1: 'kobo.3.1:16', status: 'exact' }),
+        TX,
+      );
+      expect(repo.markPositionPending).toHaveBeenCalledWith(100, 'cfi', TX);
+      expect(repo.markPositionPending).toHaveBeenCalledWith(100, 'xpointer', TX);
+    });
+
+    it('keeps the canonical color when the device echoes the projected kobo color', async () => {
+      repo.findStateByDeviceKey.mockResolvedValue(makeStateRow({ externalKey: KOBO_UUID, source: 'kobo', deviceId: '42' }));
+      repo.findAnnotationById.mockResolvedValue(makeAnnotationRow({ origin: 'web', color: '#FB923C' }));
+      repo.findDevicePosition.mockResolvedValue(makePositionRow({ format: 'kobo_span', pos0: 'kobo.3.1:0', pos1: 'kobo.3.1:16' }));
+
+      // Orange projects to kobo yellow; the echo of that yellow must not overwrite orange.
+      const result = await ingestKobo([makeKoboIncoming({ datetimeUpdated: '2026-06-02 08:00:00', note: 'new note' })]);
+
+      expect(result.updated).toBe(1);
+      const patch = repo.applyContentPatch.mock.calls[0][1];
+      expect(patch.note).toBe('new note');
+      expect(patch.color).toBeUndefined();
+    });
+  });
+
+  describe('applyDeviceDeletes', () => {
+    const KOBO_UUID = '99999999-8888-7777-6666-555555555555';
+
+    it('soft-deletes by any-device key and acks the reporting device', async () => {
+      const state = makeStateRow({ externalKey: KOBO_UUID, source: 'kobo', deviceId: '42' });
+      repo.findStateByKeyAnyDevice.mockResolvedValue({ state, annotation: makeAnnotationRow() });
+
+      const deleted = await service.applyDeviceDeletes({
+        userId: USER_ID,
+        source: 'kobo',
+        deviceId: '42',
+        bookId: BOOK_ID,
+        deletes: [{ externalKey: KOBO_UUID }],
+      });
+
+      expect(deleted).toBe(1);
+      expect(repo.softDeleteById).toHaveBeenCalledWith(100, TX);
+      expect(repo.setDeleteAcked).toHaveBeenCalledWith(900, TX);
+    });
+
+    it('inserts an acked state when another device reported the deletion', async () => {
+      const state = makeStateRow({ externalKey: KOBO_UUID, source: 'kobo', deviceId: '42' });
+      repo.findStateByKeyAnyDevice.mockResolvedValue({ state, annotation: makeAnnotationRow() });
+      repo.findStateByAnnotationAndDevice.mockResolvedValue(null);
+
+      await service.applyDeviceDeletes({
+        userId: USER_ID,
+        source: 'kobo',
+        deviceId: '77',
+        bookId: BOOK_ID,
+        deletes: [{ externalKey: KOBO_UUID }],
+      });
+
+      expect(repo.insertState).toHaveBeenCalledWith(expect.objectContaining({ deviceId: '77', externalKey: KOBO_UUID }), TX);
+      expect(repo.setDeleteAcked).toHaveBeenCalled();
+    });
+
+    it('ignores unknown keys', async () => {
+      repo.findStateByKeyAnyDevice.mockResolvedValue(null);
+      const deleted = await service.applyDeviceDeletes({
+        userId: USER_ID,
+        source: 'kobo',
+        deviceId: '42',
+        bookId: BOOK_ID,
+        deletes: [{ externalKey: KOBO_UUID }],
+      });
+      expect(deleted).toBe(0);
+      expect(repo.softDeleteById).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('markServedApplied', () => {
+    it('upserts served states and acks omitted tombstones', async () => {
+      await service.markServedApplied({
+        userId: USER_ID,
+        source: 'kobo',
+        deviceId: '42',
+        entries: [{ annotationId: 100, version: 4, externalKey: 'uuid-1', externalCreatedAt: '2026-06-01 21:14:03' }],
+        tombstoneStateIds: [901, 902],
+      });
+
+      expect(repo.insertState).toHaveBeenCalledWith(
+        expect.objectContaining({ annotationId: 100, lastAppliedVersion: 4, externalKey: 'uuid-1', deviceId: '42' }),
+        TX,
+      );
+      expect(repo.setDeleteAcked).toHaveBeenCalledWith(901, TX);
+      expect(repo.setDeleteAcked).toHaveBeenCalledWith(902, TX);
+    });
+
+    it('does nothing on empty input', async () => {
+      await service.markServedApplied({ userId: USER_ID, source: 'kobo', deviceId: '42', entries: [], tombstoneStateIds: [] });
+      expect(repo.transaction).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('ensureExternalKey', () => {
+    it('returns the existing key when one device already holds it', async () => {
+      repo.findExternalKeyForAnnotation.mockResolvedValue('existing-uuid');
+      expect(await service.ensureExternalKey(100, 'kobo', () => 'minted')).toBe('existing-uuid');
+    });
+
+    it('mints a new key otherwise', async () => {
+      expect(await service.ensureExternalKey(100, 'kobo', () => 'minted')).toBe('minted');
+    });
+  });
+});
diff --git a/server/src/modules/annotation/annotation-sync.service.ts b/server/src/modules/annotation/annotation-sync.service.ts
new file mode 100644
index 000000000..4f7c2d302
--- /dev/null
+++ b/server/src/modules/annotation/annotation-sync.service.ts
@@ -0,0 +1,709 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { createHash } from 'crypto';
+
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import type { AnnotationRow, AnnotationSyncStateRow } from '../../db/schema';
+import type { AnnotationPositionFormat, AnnotationStyle, AnnotationSyncSource } from './annotation.constants';
+import {
+  applyDeviceColor,
+  applyDeviceStyle,
+  applyKoboDeviceColor,
+  hexFromKoboColor,
+  hexFromKoreaderColor,
+  styleFromDrawer,
+} from './annotation-style-map';
+import { AnnotationSyncRepository, type DbTx } from './annotation-sync.repository';
+
+const INGEST_EVENT = 'annotation.sync_ingest';
+
+export interface IncomingDeviceAnnotation {
+  /**
+   * Device-authoritative identity (Kobo annotation UUID). When present it replaces the
+   * datetime|pos0 dedup key and disables the datetime-based reconcile heuristics.
+   */
+  externalKey?: string;
+  datetime: string;
+  datetimeUpdated?: string | null;
+  drawer?: string;
+  color?: string | null;
+  /** Palette the incoming color belongs to; picks the projection mapping. */
+  colorSpace?: 'koreader' | 'kobo';
+  style?: AnnotationStyle;
+  text?: string | null;
+  note?: string | null;
+  chapter?: string | null;
+  pageno?: number | null;
+  posFormat: 'xpointer' | 'pdf' | 'kobo_span';
+  pos0: string;
+  pos1?: string | null;
+  posExtras?: Record<string, unknown> | null;
+}
+
+export interface IngestParams {
+  userId: number;
+  source: AnnotationSyncSource;
+  deviceId: string;
+  bookId: number;
+  bookFileId: number;
+  annotations: IncomingDeviceAnnotation[];
+}
+
+export interface IngestResult {
+  created: number;
+  updated: number;
+  moved: number;
+  unchanged: number;
+  skippedDeleted: number;
+}
+
+export function buildAnnotationKey(deviceCreatedAt: string, pos0: string): string {
+  return createHash('md5').update(`${deviceCreatedAt}|${pos0}`).digest('hex'); // codeql[js/weak-cryptographic-algorithm] - non-security dedup key
+}
+
+function keyOf(incoming: IncomingDeviceAnnotation): string {
+  return incoming.externalKey ?? buildAnnotationKey(incoming.datetime, incoming.pos0);
+}
+
+/** Other position formats that go stale when this device format moves. */
+function siblingFormatsOf(posFormat: IncomingDeviceAnnotation['posFormat']): AnnotationPositionFormat[] {
+  if (posFormat === 'xpointer') return ['cfi', 'kobo_span'];
+  if (posFormat === 'kobo_span') return ['cfi', 'xpointer'];
+  return ['cfi'];
+}
+
+@Injectable()
+export class AnnotationSyncService {
+  private readonly logger = new Logger(AnnotationSyncService.name);
+
+  constructor(private readonly syncRepo: AnnotationSyncRepository) {}
+
+  /**
+   * Ingests a batch of device annotations for one book. Identity is the external key
+   * md5(datetime|pos0); a known datetime with a changed position is a move, never a
+   * delete or a duplicate. Tombstoned (soft-deleted) matches are never resurrected.
+   */
+  async ingestDeviceAnnotations(params: IngestParams): Promise<IngestResult> {
+    const startedAtMs = Date.now();
+    const result: IngestResult = { created: 0, updated: 0, moved: 0, unchanged: 0, skippedDeleted: 0 };
+
+    try {
+      await this.syncRepo.transaction(async (tx) => {
+        for (const incoming of this.dedupeByKey(params.annotations)) {
+          await this.ingestOne(params, incoming, result, tx);
+        }
+      });
+      this.logger.log(
+        `[${INGEST_EVENT}] [end] userId=${params.userId} bookId=${params.bookId} deviceId=${params.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} created=${result.created} updated=${result.updated} moved=${result.moved} unchanged=${result.unchanged} skippedDeleted=${result.skippedDeleted} - device annotations ingested`,
+      );
+      return result;
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${INGEST_EVENT}] [fail] userId=${params.userId} bookId=${params.bookId} deviceId=${params.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - device annotations ingest failed`,
+      );
+      throw error;
+    }
+  }
+
+  private dedupeByKey(annotations: IncomingDeviceAnnotation[]): IncomingDeviceAnnotation[] {
+    const byKey = new Map<string, IncomingDeviceAnnotation>();
+    for (const annotation of annotations) {
+      byKey.set(keyOf(annotation), annotation);
+    }
+    return [...byKey.values()];
+  }
+
+  private async ingestOne(params: IngestParams, incoming: IncomingDeviceAnnotation, result: IngestResult, tx: DbTx): Promise<void> {
+    const { userId, source, deviceId, bookId, bookFileId } = params;
+    const key = keyOf(incoming);
+
+    const deviceState = await this.syncRepo.findStateByDeviceKey(userId, source, deviceId, bookId, key, tx);
+    if (deviceState) {
+      const annotation = await this.syncRepo.findAnnotationById(deviceState.annotationId, userId, tx);
+      if (!annotation) return;
+      if (annotation.deletedAt) {
+        await this.syncRepo.touchState(deviceState.id, tx);
+        result.skippedDeleted += 1;
+        return;
+      }
+      const changed = await this.applyIncomingContent(annotation, incoming, bookFileId, tx);
+      if (changed) {
+        await this.syncRepo.updateState(deviceState.id, { lastAppliedVersion: changed.newVersion }, tx);
+        result.updated += 1;
+      } else {
+        await this.syncRepo.touchState(deviceState.id, tx);
+        result.unchanged += 1;
+      }
+      return;
+    }
+
+    const crossDevice = await this.syncRepo.findStateByKeyAnyDevice(userId, source, key, bookId, tx);
+    if (crossDevice) {
+      if (crossDevice.annotation.deletedAt) {
+        await this.syncRepo.insertState(
+          {
+            annotationId: crossDevice.annotation.id,
+            userId,
+            source,
+            deviceId,
+            externalKey: key,
+            externalCreatedAt: incoming.datetime,
+            lastAppliedVersion: crossDevice.annotation.version,
+          },
+          tx,
+        );
+        result.skippedDeleted += 1;
+        return;
+      }
+      const state = await this.syncRepo.insertState(
+        {
+          annotationId: crossDevice.annotation.id,
+          userId,
+          source,
+          deviceId,
+          externalKey: key,
+          externalCreatedAt: incoming.datetime,
+          lastAppliedVersion: crossDevice.annotation.version,
+        },
+        tx,
+      );
+      const changed = await this.applyIncomingContent(crossDevice.annotation, incoming, bookFileId, tx);
+      if (changed) {
+        await this.syncRepo.updateState(state.id, { lastAppliedVersion: changed.newVersion }, tx);
+        result.updated += 1;
+      } else {
+        result.unchanged += 1;
+      }
+      return;
+    }
+
+    // UUID-keyed sources have authoritative identity; the datetime heuristics below
+    // exist only for the datetime|pos0 key scheme where a move changes the key.
+    const byDatetime = incoming.externalKey
+      ? []
+      : await this.syncRepo.findCanonicalByDeviceDatetime(userId, bookId, incoming.datetime, incoming.posFormat, tx);
+    const exact = byDatetime.find((c) => c.position?.pos0 === incoming.pos0);
+    const candidate = exact ?? (byDatetime.length === 1 ? byDatetime[0] : undefined);
+    if (candidate) {
+      const { annotation, position } = candidate;
+      if (annotation.deletedAt) {
+        await this.syncRepo.insertState(
+          {
+            annotationId: annotation.id,
+            userId,
+            source,
+            deviceId,
+            externalKey: key,
+            externalCreatedAt: incoming.datetime,
+            lastAppliedVersion: annotation.version,
+          },
+          tx,
+        );
+        result.skippedDeleted += 1;
+        return;
+      }
+
+      const isMove = !exact && position != null && position.pos0 !== incoming.pos0;
+      let version = annotation.version;
+      if (isMove) {
+        await this.syncRepo.updatePosition(
+          annotation.id,
+          incoming.posFormat,
+          { pos0: incoming.pos0, pos1: incoming.pos1 ?? null, status: 'exact', bookFileId },
+          tx,
+        );
+        for (const sibling of siblingFormatsOf(incoming.posFormat)) {
+          await this.syncRepo.markPositionPending(annotation.id, sibling, tx);
+        }
+        version = await this.syncRepo.applyContentPatch(annotation.id, { deviceUpdatedAt: incoming.datetimeUpdated ?? null }, tx);
+      }
+      const state = await this.syncRepo.insertState(
+        {
+          annotationId: annotation.id,
+          userId,
+          source,
+          deviceId,
+          externalKey: key,
+          externalCreatedAt: incoming.datetime,
+          lastAppliedVersion: version,
+        },
+        tx,
+      );
+      const changed = await this.applyIncomingContent({ ...annotation, version }, incoming, bookFileId, tx);
+      if (changed) {
+        await this.syncRepo.updateState(state.id, { lastAppliedVersion: changed.newVersion }, tx);
+      }
+      result[isMove ? 'moved' : changed ? 'updated' : 'unchanged'] += 1;
+      return;
+    }
+
+    await this.syncRepo.createCanonical(
+      {
+        userId,
+        bookId,
+        text: incoming.text ?? '',
+        color: incoming.colorSpace === 'kobo' ? hexFromKoboColor(incoming.color) : hexFromKoreaderColor(incoming.color),
+        style: incoming.style ?? styleFromDrawer(incoming.drawer),
+        note: incoming.note ?? null,
+        chapterTitle: incoming.chapter ?? null,
+        origin: source,
+        version: 1,
+        deviceCreatedAt: incoming.datetime,
+        deviceUpdatedAt: incoming.datetimeUpdated ?? null,
+      },
+      {
+        bookFileId,
+        format: incoming.posFormat,
+        pos0: incoming.pos0,
+        pos1: incoming.pos1 ?? null,
+        status: 'exact',
+        extras: this.buildPositionExtras(incoming),
+      },
+      {
+        source,
+        deviceId,
+        externalKey: key,
+        externalCreatedAt: incoming.datetime,
+        lastAppliedVersion: 1,
+      },
+      tx,
+    );
+    result.created += 1;
+  }
+
+  /**
+   * Applies device content only when the device actually made a new edit since the last
+   * one we ingested (device-clock comparison, no cross-clock skew). Style and color use
+   * the projection rule: a device echo of the projected view never overwrites canonical.
+   */
+  private async applyIncomingContent(
+    annotation: AnnotationRow,
+    incoming: IncomingDeviceAnnotation,
+    bookFileId: number,
+    tx: DbTx,
+  ): Promise<{ newVersion: number } | null> {
+    const storedEffective = annotation.deviceUpdatedAt ?? annotation.deviceCreatedAt ?? '';
+    const incomingEffective = incoming.datetimeUpdated ?? incoming.datetime;
+    const hasNewEdit = incomingEffective > storedEffective;
+
+    const position = await this.syncRepo.findDevicePosition(annotation.id, incoming.posFormat, tx);
+    // pos0 can only change under UUID identity; with the datetime|pos0 key a changed
+    // pos0 is a different key and lands in the move path instead.
+    const pos0Changed = incoming.externalKey != null && position != null && position.pos0 !== incoming.pos0;
+    const pos1Changed = position != null && (position.pos1 ?? null) !== (incoming.pos1 ?? null);
+    const posChanged = pos0Changed || pos1Changed;
+    const pagenoChanged = incoming.pageno != null && (position?.extras as { pageno?: number } | null)?.pageno !== incoming.pageno && position != null;
+
+    if (!hasNewEdit && !posChanged) {
+      if (pagenoChanged) {
+        await this.syncRepo.updatePosition(
+          annotation.id,
+          incoming.posFormat,
+          { extras: { ...(position?.extras ?? {}), pageno: incoming.pageno } },
+          tx,
+        );
+      }
+      return null;
+    }
+
+    const patch: Partial<Pick<AnnotationRow, 'text' | 'note' | 'color' | 'style' | 'chapterTitle'>> = {};
+    if (hasNewEdit) {
+      const nextText = incoming.text ?? '';
+      const nextNote = incoming.note ?? null;
+      const nextStyle = applyDeviceStyle(annotation.style as Parameters<typeof applyDeviceStyle>[0], incoming.drawer);
+      const nextColor =
+        incoming.colorSpace === 'kobo' ? applyKoboDeviceColor(annotation.color, incoming.color) : applyDeviceColor(annotation.color, incoming.color);
+      if (nextText !== annotation.text) patch.text = nextText;
+      if (nextNote !== annotation.note) patch.note = nextNote;
+      if (nextStyle !== annotation.style) patch.style = nextStyle;
+      if (nextColor !== annotation.color) patch.color = nextColor;
+      if ((incoming.chapter ?? null) !== annotation.chapterTitle && incoming.chapter != null) patch.chapterTitle = incoming.chapter;
+    }
+
+    if (posChanged || pagenoChanged) {
+      await this.syncRepo.updatePosition(
+        annotation.id,
+        incoming.posFormat,
+        {
+          ...(pos0Changed ? { pos0: incoming.pos0, status: 'exact' as const } : {}),
+          pos1: incoming.pos1 ?? null,
+          bookFileId,
+          ...(incoming.pageno != null ? { extras: { ...(position?.extras ?? {}), pageno: incoming.pageno } } : {}),
+        },
+        tx,
+      );
+      if (posChanged) {
+        for (const sibling of siblingFormatsOf(incoming.posFormat)) {
+          await this.syncRepo.markPositionPending(annotation.id, sibling, tx);
+        }
+      }
+    }
+
+    const hasContentChanges = Object.keys(patch).length > 0;
+    if (!hasContentChanges && !posChanged) {
+      // A bumped device timestamp without content changes (e.g. the echo of an edit we
+      // pushed down) is bookkeeping only and must not bump the version, or the same
+      // no-op edit would ping-pong between server and device forever.
+      if (hasNewEdit) {
+        await this.syncRepo.setDeviceUpdatedAtSilent(annotation.id, incoming.datetimeUpdated ?? null, tx);
+      }
+      return null;
+    }
+
+    const newVersion = await this.syncRepo.applyContentPatch(
+      annotation.id,
+      { ...patch, ...(hasNewEdit ? { deviceUpdatedAt: incoming.datetimeUpdated ?? null } : {}) },
+      tx,
+    );
+    return { newVersion };
+  }
+
+  private buildPositionExtras(incoming: IncomingDeviceAnnotation): Record<string, unknown> | null {
+    const extras: Record<string, unknown> = { ...(incoming.posExtras ?? {}) };
+    if (incoming.pageno != null) extras.pageno = incoming.pageno;
+    return Object.keys(extras).length > 0 ? extras : null;
+  }
+
+  /**
+   * Applies explicit device delete operations (Kobo PATCH ops). Identity is the
+   * device-side external key; any device's state row of the source matches, so a
+   * deletion propagates even when reported by a device that did not create it.
+   */
+  async applyDeviceDeletes(params: {
+    userId: number;
+    source: AnnotationSyncSource;
+    deviceId: string;
+    bookId: number;
+    deletes: { externalKey: string }[];
+  }): Promise<number> {
+    if (params.deletes.length === 0) return 0;
+    let deleted = 0;
+
+    await this.syncRepo.transaction(async (tx) => {
+      for (const entry of params.deletes) {
+        const match = await this.syncRepo.findStateByKeyAnyDevice(params.userId, params.source, entry.externalKey, params.bookId, tx);
+        if (!match) continue;
+        if (!match.annotation.deletedAt) {
+          await this.syncRepo.softDeleteById(match.annotation.id, tx);
+          deleted += 1;
+        }
+        const reporterState =
+          match.state.deviceId === params.deviceId
+            ? match.state
+            : await this.syncRepo.findStateByAnnotationAndDevice(match.annotation.id, params.source, params.deviceId, tx);
+        if (reporterState) {
+          await this.syncRepo.setDeleteAcked(reporterState.id, tx);
+        } else {
+          const inserted = await this.syncRepo.insertState(
+            {
+              annotationId: match.annotation.id,
+              userId: params.userId,
+              source: params.source,
+              deviceId: params.deviceId,
+              externalKey: entry.externalKey,
+              externalCreatedAt: match.state.externalCreatedAt,
+              lastAppliedVersion: match.annotation.version,
+            },
+            tx,
+          );
+          await this.syncRepo.setDeleteAcked(inserted.id, tx);
+        }
+      }
+    });
+
+    if (deleted > 0) {
+      this.logger.log(
+        `[annotation.sync_delete_ops] [end] userId=${params.userId} bookId=${params.bookId} deviceId=${params.deviceId.slice(0, 8)} deleted=${deleted} - device delete operations applied`,
+      );
+    }
+    return deleted;
+  }
+
+  /**
+   * Marks annotations as applied on a device after they were served in a pull-style
+   * response (Kobo GET). This is the serve-side counterpart of applyExchangeAck:
+   * lastAppliedVersion advances to the served version, and deletions that propagated
+   * by omission are acked for this device.
+   */
+  async markServedApplied(params: {
+    userId: number;
+    source: AnnotationSyncSource;
+    deviceId: string;
+    entries: { annotationId: number; version: number; externalKey: string; externalCreatedAt: string | null }[];
+    tombstoneStateIds: number[];
+  }): Promise<void> {
+    if (params.entries.length === 0 && params.tombstoneStateIds.length === 0) return;
+    await this.syncRepo.transaction(async (tx) => {
+      for (const entry of params.entries) {
+        await this.syncRepo.insertState(
+          {
+            annotationId: entry.annotationId,
+            userId: params.userId,
+            source: params.source,
+            deviceId: params.deviceId,
+            externalKey: entry.externalKey,
+            externalCreatedAt: entry.externalCreatedAt,
+            lastAppliedVersion: entry.version,
+          },
+          tx,
+        );
+      }
+      for (const stateId of params.tombstoneStateIds) {
+        await this.syncRepo.setDeleteAcked(stateId, tx);
+      }
+    });
+  }
+
+  /**
+   * The stable device-side key for an annotation within a source, minting one when the
+   * annotation has never been served (Kobo ids are store-global, so every device of the
+   * user must see the same id).
+   */
+  async ensureExternalKey(annotationId: number, source: AnnotationSyncSource, mint: () => string): Promise<string> {
+    const existing = await this.syncRepo.findExternalKeyForAnnotation(annotationId, source);
+    return existing ?? mint();
+  }
+
+  async listActiveForBook(userId: number, bookId: number): Promise<AnnotationRow[]> {
+    return this.syncRepo.findActiveByBook(userId, bookId);
+  }
+
+  async listStatesBySourceForBook(
+    userId: number,
+    source: AnnotationSyncSource,
+    bookId: number,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return this.syncRepo.findStatesBySourceForBook(userId, source, bookId);
+  }
+
+  async listDeleteCandidates(
+    userId: number,
+    source: AnnotationSyncSource,
+    deviceId: string,
+    bookId: number,
+    limit: number,
+  ): Promise<{ state: AnnotationSyncStateRow; annotation: AnnotationRow }[]> {
+    return this.syncRepo.findDeleteCandidates(userId, source, deviceId, bookId, limit);
+  }
+
+  async listPendingKoboChangeBookIds(userId: number, deviceId: string, opts: { includeAllOrigins: boolean; resolverVersion: number }) {
+    return this.syncRepo.findBookIdsWithPendingKoboChanges(userId, deviceId, opts);
+  }
+
+  async setDeviceIdentity(annotationId: number, deviceCreatedAt: string): Promise<void> {
+    await this.syncRepo.setDeviceIdentitySilent(annotationId, deviceCreatedAt);
+  }
+
+  /**
+   * Soft-deletes annotations this device previously synced but no longer reports in its
+   * full key set. A known datetime with a changed key is a move (already reconciled by
+   * ingest), never a delete. The reporting device's state is acked immediately; other
+   * devices receive the deletion through their own push-down.
+   */
+  async detectDeviceDeletions(params: {
+    userId: number;
+    source: AnnotationSyncSource;
+    deviceId: string;
+    bookId: number;
+    presentKeys: DeviceKeyEntry[];
+  }): Promise<number> {
+    const present = new Set(params.presentKeys.map((entry) => entry.k));
+    const presentDatetimes = new Set(params.presentKeys.map((entry) => entry.dt));
+    let deletedCount = 0;
+
+    await this.syncRepo.transaction(async (tx) => {
+      const states = await this.syncRepo.findStatesForDeviceBook(params.userId, params.source, params.deviceId, params.bookId, tx);
+      for (const { state, annotation } of states) {
+        if (annotation.deletedAt) continue;
+        if (present.has(state.externalKey)) continue;
+        if (state.externalCreatedAt && presentDatetimes.has(state.externalCreatedAt)) continue;
+        await this.syncRepo.softDeleteById(annotation.id, tx);
+        await this.syncRepo.setDeleteAcked(state.id, tx);
+        deletedCount += 1;
+      }
+    });
+
+    if (deletedCount > 0) {
+      this.logger.log(
+        `[annotation.sync_delete_detect] [end] userId=${params.userId} bookId=${params.bookId} deviceId=${params.deviceId.slice(0, 8)} deleted=${deletedCount} - device deletions applied`,
+      );
+    }
+    return deletedCount;
+  }
+
+  /** Pending changes for a device and book, capped at limit entries across all kinds. */
+  async computePushDown(userId: number, source: AnnotationSyncSource, deviceId: string, bookId: number, limit: number): Promise<PushDownSets> {
+    const deletesRaw = await this.syncRepo.findDeleteCandidates(userId, source, deviceId, bookId, limit + 1);
+    const deletes = deletesRaw.slice(0, limit);
+    let remaining = limit - deletes.length;
+
+    const editsRaw = remaining > 0 ? await this.syncRepo.findEditCandidates(userId, source, deviceId, bookId, remaining + 1) : [];
+    const edits = editsRaw.slice(0, Math.max(remaining, 0));
+    remaining -= edits.length;
+
+    const addsRaw = remaining > 0 ? await this.syncRepo.findAddCandidates(userId, source, deviceId, bookId, remaining + 1) : [];
+    const adds = addsRaw.slice(0, Math.max(remaining, 0));
+
+    const more = deletesRaw.length > deletes.length || editsRaw.length > edits.length || addsRaw.length > adds.length;
+    return { adds, edits, deletes, more };
+  }
+
+  /**
+   * Returns the annotation's device identity datetime, minting a unique one per
+   * (user, book) on first push (KOReader treats the datetime as identity).
+   * Device datetimes are wall-clock local with no timezone; the offset shifts the
+   * minted value into the device's clock frame so it never lands in its future.
+   */
+  async ensureDeviceCreatedAt(userId: number, bookId: number, annotation: AnnotationRow, deviceClockOffsetMs = 0): Promise<string> {
+    if (annotation.deviceCreatedAt) return annotation.deviceCreatedAt;
+    const existing = await this.syncRepo.listDeviceCreatedAtsForBook(userId, bookId);
+    let candidate = formatDeviceDatetime(new Date(annotation.createdAt.getTime() + deviceClockOffsetMs));
+    while (existing.has(candidate)) {
+      candidate = addSeconds(candidate, 1);
+    }
+    await this.syncRepo.setDeviceIdentitySilent(annotation.id, candidate);
+    return candidate;
+  }
+
+  async findDevicePositionFor(annotationId: number, format: AnnotationPositionFormat) {
+    return this.syncRepo.findDevicePosition(annotationId, format);
+  }
+
+  async findPositions(annotationIds: number[], formats: AnnotationPositionFormat[]) {
+    return this.syncRepo.findPositionsByAnnotationIds(annotationIds, formats);
+  }
+
+  /**
+   * Applies a device's acknowledgment of pushed changes. Only here do
+   * lastAppliedVersion and deleteAckedAt advance; corrected positions are stored and
+   * bump the version so other devices receive the fix.
+   */
+  async applyExchangeAck(params: {
+    userId: number;
+    source: AnnotationSyncSource;
+    deviceId: string;
+    bookFileId: number;
+    applied: AckAppliedEntry[];
+    deleted: AckDeletedEntry[];
+    converterVersion: number;
+  }): Promise<{ acked: number }> {
+    const { userId, source, deviceId, bookFileId } = params;
+    let acked = 0;
+
+    await this.syncRepo.transaction(async (tx) => {
+      for (const entry of params.applied) {
+        const annotation = await this.syncRepo.findAnnotationById(entry.serverId, userId, tx);
+        if (!annotation) continue;
+
+        if (entry.status === 'failed') {
+          await this.syncRepo.updatePosition(annotation.id, 'xpointer', { status: 'failed' }, tx);
+          acked += 1;
+          continue;
+        }
+
+        let versionForState = entry.version;
+        if (entry.corrected && entry.pos0) {
+          await this.syncRepo.upsertPosition(
+            {
+              annotationId: annotation.id,
+              userId,
+              bookFileId,
+              format: 'xpointer',
+              pos0: entry.pos0,
+              pos1: entry.pos1 ?? null,
+              status: entry.verified ? 'repaired' : 'pending',
+              converterVersion: params.converterVersion,
+              extras: entry.pageno != null ? { pageno: entry.pageno } : null,
+            },
+            tx,
+          );
+          versionForState = await this.syncRepo.bumpVersion(annotation.id, tx);
+        } else if (entry.verified) {
+          await this.syncRepo.updatePosition(annotation.id, 'xpointer', { status: 'exact' }, tx);
+        }
+
+        const pos0 = entry.pos0 ?? (await this.syncRepo.findDevicePosition(annotation.id, 'xpointer', tx))?.pos0 ?? '';
+        const externalKey = buildAnnotationKey(annotation.deviceCreatedAt ?? '', pos0);
+        await this.syncRepo.insertState(
+          {
+            annotationId: annotation.id,
+            userId,
+            source,
+            deviceId,
+            externalKey,
+            externalCreatedAt: annotation.deviceCreatedAt ?? null,
+            lastAppliedVersion: versionForState,
+          },
+          tx,
+        );
+        if (entry.datetimeUpdated !== undefined) {
+          await this.syncRepo.setDeviceUpdatedAtSilent(annotation.id, entry.datetimeUpdated, tx);
+        }
+        acked += 1;
+      }
+
+      for (const entry of params.deleted) {
+        if (entry.status !== 'applied') continue;
+        const state = await this.syncRepo.findStateByAnnotationAndDevice(entry.serverId, source, deviceId, tx);
+        if (!state || state.userId !== userId) continue;
+        await this.syncRepo.setDeleteAcked(state.id, tx);
+        acked += 1;
+      }
+    });
+
+    return { acked };
+  }
+
+  async upsertGeneratedPosition(position: {
+    annotationId: number;
+    userId: number;
+    bookFileId: number;
+    format: 'xpointer' | 'cfi' | 'kobo_span';
+    pos0: string | null;
+    pos1: string | null;
+    status: 'exact' | 'repaired' | 'failed' | 'pending';
+    converterVersion: number;
+    extras?: Record<string, unknown> | null;
+  }): Promise<void> {
+    await this.syncRepo.upsertPosition({ ...position, extras: position.extras ?? null });
+  }
+}
+
+export interface DeviceKeyEntry {
+  k: string;
+  dt: string;
+}
+
+export interface PushDownSets {
+  adds: AnnotationRow[];
+  edits: { state: AnnotationSyncStateRow; annotation: AnnotationRow }[];
+  deletes: { state: AnnotationSyncStateRow; annotation: AnnotationRow }[];
+  more: boolean;
+}
+
+export interface AckAppliedEntry {
+  serverId: number;
+  version: number;
+  status: 'applied' | 'failed';
+  verified?: boolean;
+  corrected?: boolean;
+  pos0?: string | null;
+  pos1?: string | null;
+  pageno?: number | null;
+  datetimeUpdated?: string | null;
+}
+
+export interface AckDeletedEntry {
+  serverId: number;
+  status: 'applied' | 'failed';
+}
+
+export function formatDeviceDatetime(date: Date): string {
+  return date.toISOString().slice(0, 19).replace('T', ' ');
+}
+
+function addSeconds(deviceDatetime: string, seconds: number): string {
+  const date = new Date(`${deviceDatetime.replace(' ', 'T')}Z`);
+  date.setUTCSeconds(date.getUTCSeconds() + seconds);
+  return formatDeviceDatetime(date);
+}
diff --git a/server/src/modules/annotation/annotation.constants.ts b/server/src/modules/annotation/annotation.constants.ts
index 4ee22a896..2890dac05 100644
--- a/server/src/modules/annotation/annotation.constants.ts
+++ b/server/src/modules/annotation/annotation.constants.ts
@@ -1,4 +1,16 @@
 export const DEFAULT_ANNOTATION_COLOR = 'yellow';
 export const DEFAULT_ANNOTATION_STYLE = 'highlight';
-export const ANNOTATION_STYLES = ['highlight', 'underline', 'strikethrough', 'squiggly'] as const;
+export const ANNOTATION_STYLES = ['highlight', 'underline', 'strikethrough', 'squiggly', 'invert'] as const;
 export type AnnotationStyle = (typeof ANNOTATION_STYLES)[number];
+
+export const ANNOTATION_ORIGINS = ['web', 'koreader', 'kobo'] as const;
+export type AnnotationOrigin = (typeof ANNOTATION_ORIGINS)[number];
+
+export const ANNOTATION_POSITION_FORMATS = ['cfi', 'xpointer', 'pdf', 'kobo_span'] as const;
+export type AnnotationPositionFormat = (typeof ANNOTATION_POSITION_FORMATS)[number];
+
+export const ANNOTATION_POSITION_STATUSES = ['exact', 'repaired', 'failed', 'pending'] as const;
+export type AnnotationPositionStatus = (typeof ANNOTATION_POSITION_STATUSES)[number];
+
+export const ANNOTATION_SYNC_SOURCES = ['koreader', 'kobo'] as const;
+export type AnnotationSyncSource = (typeof ANNOTATION_SYNC_SOURCES)[number];
diff --git a/server/src/modules/annotation/annotation.module.test.ts b/server/src/modules/annotation/annotation.module.test.ts
index 3c44778e0..cb60b5d57 100644
--- a/server/src/modules/annotation/annotation.module.test.ts
+++ b/server/src/modules/annotation/annotation.module.test.ts
@@ -4,9 +4,12 @@ import { MODULE_METADATA } from '@nestjs/common/constants';
 
 import { BookModule } from '../book/book.module';
 import { AnnotationController } from './annotation.controller';
+import { AnnotationHubController } from './annotation-hub.controller';
+import { AnnotationHubService } from './annotation-hub.service';
 import { AnnotationModule } from './annotation.module';
 import { AnnotationRepository } from './annotation.repository';
 import { AnnotationService } from './annotation.service';
+import { AnnotationSyncService } from './annotation-sync.service';
 
 describe('AnnotationModule', () => {
   it('registers expected imports, controller, and providers', () => {
@@ -15,7 +18,7 @@ describe('AnnotationModule', () => {
     const providers = Reflect.getMetadata(MODULE_METADATA.PROVIDERS, AnnotationModule);
 
     expect(imports).toEqual(expect.arrayContaining([BookModule]));
-    expect(controllers).toEqual([AnnotationController]);
-    expect(providers).toEqual(expect.arrayContaining([AnnotationService, AnnotationRepository]));
+    expect(controllers).toEqual([AnnotationController, AnnotationHubController]);
+    expect(providers).toEqual(expect.arrayContaining([AnnotationService, AnnotationRepository, AnnotationSyncService, AnnotationHubService]));
   });
 });
diff --git a/server/src/modules/annotation/annotation.module.ts b/server/src/modules/annotation/annotation.module.ts
index 76cb24f0b..73ba88ddb 100644
--- a/server/src/modules/annotation/annotation.module.ts
+++ b/server/src/modules/annotation/annotation.module.ts
@@ -2,13 +2,31 @@ import { Module } from '@nestjs/common';
 
 import { BookModule } from '../book/book.module';
 import { AchievementModule } from '../achievement/achievement.module';
+import { PositionConverterModule } from '../position-converter/position-converter.module';
 import { AnnotationController } from './annotation.controller';
+import { AnnotationExportService } from './annotation-export.service';
+import { AnnotationHubController } from './annotation-hub.controller';
+import { AnnotationHubService } from './annotation-hub.service';
+import { AnnotationConversionService } from './annotation-conversion.service';
+import { AnnotationPositionRepository } from './annotation-position.repository';
 import { AnnotationRepository } from './annotation.repository';
 import { AnnotationService } from './annotation.service';
+import { AnnotationSyncRepository } from './annotation-sync.repository';
+import { AnnotationSyncService } from './annotation-sync.service';
 
 @Module({
-  imports: [BookModule, AchievementModule],
-  controllers: [AnnotationController],
-  providers: [AnnotationService, AnnotationRepository],
+  imports: [BookModule, AchievementModule, PositionConverterModule],
+  controllers: [AnnotationController, AnnotationHubController],
+  providers: [
+    AnnotationService,
+    AnnotationRepository,
+    AnnotationPositionRepository,
+    AnnotationSyncRepository,
+    AnnotationSyncService,
+    AnnotationConversionService,
+    AnnotationExportService,
+    AnnotationHubService,
+  ],
+  exports: [AnnotationSyncService],
 })
 export class AnnotationModule {}
diff --git a/server/src/modules/annotation/annotation.repository.test.ts b/server/src/modules/annotation/annotation.repository.test.ts
index c1e2abdba..becd70323 100644
--- a/server/src/modules/annotation/annotation.repository.test.ts
+++ b/server/src/modules/annotation/annotation.repository.test.ts
@@ -6,159 +6,100 @@ function makeRow(overrides?: Record<string, unknown>) {
     userId: 10,
     bookId: 5,
     cfi: 'epubcfi(/6/4!/4/2/1:0)',
+    cfiStatus: 'exact',
     text: 'selected text',
     color: 'yellow',
     style: 'highlight',
     note: null,
     chapterTitle: null,
+    origin: 'web',
+    version: 1,
+    deletedAt: null,
+    deviceCreatedAt: null,
+    deviceUpdatedAt: null,
     createdAt: new Date('2026-01-01T00:00:00Z'),
     updatedAt: new Date('2026-01-01T00:00:00Z'),
     ...overrides,
   };
 }
 
-function makeDb() {
-  const selectResult = { from: vi.fn() };
-  const fromResult = { where: vi.fn() };
-  const whereResult = { orderBy: vi.fn() };
+type ChainQuery = Record<string, ReturnType<typeof vi.fn>> & {
+  then: (resolve: (value: unknown) => unknown, reject?: (error: unknown) => unknown) => Promise<unknown>;
+};
 
-  selectResult.from.mockReturnValue(fromResult);
-  fromResult.where.mockReturnValue(whereResult);
-  whereResult.orderBy.mockResolvedValue([]);
-
-  const insertResult = { values: vi.fn() };
-  const valuesResult = { returning: vi.fn() };
-  insertResult.values.mockReturnValue(valuesResult);
-  valuesResult.returning.mockResolvedValue([]);
-
-  const updateResult = { set: vi.fn() };
-  const setResult = { where: vi.fn() };
-  const updateWhereResult = { returning: vi.fn() };
-  updateResult.set.mockReturnValue(setResult);
-  setResult.where.mockReturnValue(updateWhereResult);
-  updateWhereResult.returning.mockResolvedValue([]);
-
-  const deleteResult = { where: vi.fn() };
-  const deleteWhereResult = { returning: vi.fn() };
-  deleteResult.where.mockReturnValue(deleteWhereResult);
-  deleteWhereResult.returning.mockResolvedValue([]);
+function mockQuery(result: unknown): ChainQuery {
+  const query = {} as ChainQuery;
+  const methods = [
+    'from',
+    'leftJoin',
+    'innerJoin',
+    'where',
+    'orderBy',
+    'limit',
+    'offset',
+    'groupBy',
+    'values',
+    'set',
+    'returning',
+    'onConflictDoUpdate',
+  ];
+  for (const method of methods) {
+    query[method] = vi.fn().mockReturnValue(query);
+  }
+  query.then = (resolve, reject) => Promise.resolve(result).then(resolve, reject);
+  return query;
+}
 
+function makeDb(...results: unknown[]) {
+  const queue = [...results];
+  const queries: ChainQuery[] = [];
+  const next = () => {
+    const query = mockQuery(queue.length > 0 ? queue.shift() : []);
+    queries.push(query);
+    return query;
+  };
   const db = {
-    select: vi.fn().mockReturnValue(selectResult),
-    insert: vi.fn().mockReturnValue(insertResult),
-    update: vi.fn().mockReturnValue(updateResult),
-    delete: vi.fn().mockReturnValue(deleteResult),
-    _select: selectResult,
-    _from: fromResult,
-    _where: whereResult,
-    _insert: insertResult,
-    _values: valuesResult,
-    _update: updateResult,
-    _set: setResult,
-    _updateWhere: updateWhereResult,
-    _delete: deleteResult,
-    _deleteWhere: deleteWhereResult,
+    select: vi.fn().mockImplementation(next),
+    selectDistinct: vi.fn().mockImplementation(next),
+    insert: vi.fn().mockImplementation(next),
+    update: vi.fn().mockImplementation(next),
+    delete: vi.fn().mockImplementation(next),
+    transaction: vi.fn().mockImplementation(async (fn: (tx: unknown) => Promise<unknown>) => fn(db)),
+    _queries: queries,
   };
   return db;
 }
 
-function makeRepository() {
-  const db = makeDb();
-  const repo = new AnnotationRepository(db as never);
-  return { repo, db };
-}
-
-function makePaginatedDb(items: ReturnType<typeof makeRow>[], total: number) {
-  const offsetFn = vi.fn().mockResolvedValue(items);
-  const limitFn = vi.fn().mockReturnValue({ offset: offsetFn });
-  const orderByFn = vi.fn().mockReturnValue({ limit: limitFn });
-  const whereFn = vi
-    .fn()
-    .mockReturnValueOnce({ orderBy: orderByFn })
-    .mockReturnValueOnce([{ count: total }]);
-  const fromFn = vi.fn().mockReturnValue({ where: whereFn });
-  const selectFn = vi.fn().mockReturnValue({ from: fromFn });
-
-  return {
-    select: selectFn,
-    _offset: offsetFn,
-  };
-}
-
-function makeStatsDb(
-  aggregate: { totalHighlights: number; chaptersWithHighlights: number; highlightsWithNotes: number },
-  colorBreakdown: { color: string; count: number }[],
-) {
-  let callCount = 0;
-  const selectFn = vi.fn().mockImplementation(() => {
-    callCount++;
-    if (callCount === 1) {
-      return {
-        from: vi.fn().mockReturnValue({
-          where: vi.fn().mockResolvedValue([aggregate]),
-        }),
-      };
-    }
-    return {
-      from: vi.fn().mockReturnValue({
-        where: vi.fn().mockReturnValue({
-          groupBy: vi.fn().mockReturnValue({
-            orderBy: vi.fn().mockResolvedValue(colorBreakdown),
-          }),
-        }),
-      }),
-    };
-  });
-
-  return { select: selectFn };
-}
-
-function makeDistinctChaptersDb(chapters: (string | null)[]) {
-  const orderByFn = vi.fn().mockResolvedValue(chapters.map((c) => ({ chapterTitle: c })));
-  const whereFn = vi.fn().mockReturnValue({ orderBy: orderByFn });
-  const fromFn = vi.fn().mockReturnValue({ where: whereFn });
-  const selectDistinctFn = vi.fn().mockReturnValue({ from: fromFn });
-
-  return { selectDistinct: selectDistinctFn };
-}
-
 describe('AnnotationRepository', () => {
   describe('findByBookId', () => {
-    it('queries with bookId and userId filters and applies createdAt ordering', async () => {
-      const { repo, db } = makeRepository();
+    it('queries with filters and returns the joined rows', async () => {
       const rows = [makeRow(), makeRow({ id: 2 })];
-      db._where.orderBy.mockResolvedValue(rows);
+      const db = makeDb(rows);
+      const repo = new AnnotationRepository(db as never);
 
       const result = await repo.findByBookId(5, 10);
 
       expect(db.select).toHaveBeenCalled();
+      expect(db._queries[0].leftJoin).toHaveBeenCalled();
+      expect(db._queries[0].orderBy).toHaveBeenCalled();
       expect(result).toEqual(rows);
     });
 
     it('returns empty array when no annotations match', async () => {
-      const { repo, db } = makeRepository();
-      db._where.orderBy.mockResolvedValue([]);
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
 
       const result = await repo.findByBookId(5, 10);
 
       expect(result).toEqual([]);
     });
-
-    it('calls orderBy on the query chain', async () => {
-      const { repo, db } = makeRepository();
-      db._where.orderBy.mockResolvedValue([]);
-
-      await repo.findByBookId(5, 10);
-
-      expect(db._where.orderBy).toHaveBeenCalled();
-    });
   });
 
   describe('create', () => {
-    it('inserts a new annotation and returns the created row', async () => {
-      const { repo, db } = makeRepository();
+    it('inserts the annotation and its cfi position in a transaction', async () => {
       const row = makeRow();
-      db._values.returning.mockResolvedValue([row]);
+      const db = makeDb([row], []);
+      const repo = new AnnotationRepository(db as never);
 
       const result = await repo.create({
         userId: 10,
@@ -171,16 +112,18 @@ describe('AnnotationRepository', () => {
         chapterTitle: null,
       });
 
-      expect(db.insert).toHaveBeenCalled();
-      expect(result).toEqual(row);
+      expect(db.transaction).toHaveBeenCalled();
+      expect(db.insert).toHaveBeenCalledTimes(2);
+      const positionValues = db._queries[1].values.mock.calls[0][0] as Record<string, unknown>;
+      expect(positionValues).toMatchObject({ annotationId: 1, format: 'cfi', pos0: 'epubcfi(/6/4!/4/2/1:0)', status: 'exact' });
+      expect(result).toMatchObject({ ...row, cfi: 'epubcfi(/6/4!/4/2/1:0)', cfiStatus: 'exact' });
     });
 
-    it('stores note value when provided', async () => {
-      const { repo, db } = makeRepository();
-      const row = makeRow({ note: 'my note' });
-      db._values.returning.mockResolvedValue([row]);
+    it('does not leak the cfi into the annotations insert payload', async () => {
+      const db = makeDb([makeRow()], []);
+      const repo = new AnnotationRepository(db as never);
 
-      const result = await repo.create({
+      await repo.create({
         userId: 10,
         bookId: 5,
         cfi: 'epubcfi(/6/4)',
@@ -191,74 +134,120 @@ describe('AnnotationRepository', () => {
         chapterTitle: null,
       });
 
-      expect(result.note).toBe('my note');
+      const annotationValues = db._queries[0].values.mock.calls[0][0] as Record<string, unknown>;
+      expect(annotationValues).not.toHaveProperty('cfi');
+      expect(annotationValues).toMatchObject({ note: 'my note' });
     });
   });
 
   describe('update', () => {
-    it('updates and returns the row when found', async () => {
-      const { repo, db } = makeRepository();
-      const row = makeRow({ note: 'updated' });
-      db._updateWhere.returning.mockResolvedValue([row]);
+    it('bumps the version and re-reads the row with its position', async () => {
+      const updated = makeRow({ note: 'updated', version: 2 });
+      const db = makeDb([{ id: 1 }], [updated]);
+      const repo = new AnnotationRepository(db as never);
 
       const result = await repo.update(5, 1, 10, { note: 'updated' });
 
-      expect(result).toEqual(row);
+      const setCall = db._queries[0].set.mock.calls[0][0] as Record<string, unknown>;
+      expect(setCall).toHaveProperty('version');
+      expect(setCall).toHaveProperty('updatedAt');
+      expect(result).toEqual(updated);
     });
 
     it('returns null when annotation does not exist or belongs to different user/book', async () => {
-      const { repo, db } = makeRepository();
-      db._updateWhere.returning.mockResolvedValue([]);
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
 
       const result = await repo.update(5, 99, 10, { note: 'x' });
 
       expect(result).toBeNull();
     });
-
-    it('sets updatedAt via sql expression', async () => {
-      const { repo, db } = makeRepository();
-      db._updateWhere.returning.mockResolvedValue([makeRow()]);
-
-      await repo.update(5, 1, 10, { color: '#FACC15' });
-
-      const setCall = db._update.set.mock.calls[0][0];
-      expect(setCall).toHaveProperty('updatedAt');
-    });
-
-    it('clears note when null is passed', async () => {
-      const { repo, db } = makeRepository();
-      const row = makeRow({ note: null });
-      db._updateWhere.returning.mockResolvedValue([row]);
-
-      const result = await repo.update(5, 1, 10, { note: null });
-
-      expect(result!.note).toBeNull();
-    });
   });
 
-  describe('delete', () => {
-    it('returns true when annotation is deleted', async () => {
-      const { repo, db } = makeRepository();
-      db._deleteWhere.returning.mockResolvedValue([{ id: 1 }]);
+  describe('softDelete', () => {
+    it('marks the row deleted instead of removing it', async () => {
+      const db = makeDb([{ id: 1 }]);
+      const repo = new AnnotationRepository(db as never);
 
-      const result = await repo.delete(5, 1, 10);
+      const result = await repo.softDelete(5, 1, 10);
 
+      expect(db.update).toHaveBeenCalled();
+      expect(db.delete).not.toHaveBeenCalled();
+      const setCall = db._queries[0].set.mock.calls[0][0] as Record<string, unknown>;
+      expect(setCall).toHaveProperty('deletedAt');
+      expect(setCall).toHaveProperty('version');
       expect(result).toBe(true);
     });
 
-    it('returns false when annotation does not exist or belongs to different user/book', async () => {
-      const { repo, db } = makeRepository();
-      db._deleteWhere.returning.mockResolvedValue([]);
+    it('returns false when nothing matched', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
 
-      const result = await repo.delete(5, 99, 10);
+      const result = await repo.softDelete(5, 99, 10);
 
       expect(result).toBe(false);
     });
   });
 
+  describe('restore', () => {
+    it('clears deletedAt and bumps the version', async () => {
+      const restored = makeRow({ version: 3 });
+      const db = makeDb([restored]);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.restore(1, 10);
+
+      const setCall = db._queries[0].set.mock.calls[0][0] as Record<string, unknown>;
+      expect(setCall).toMatchObject({ deletedAt: null });
+      expect(setCall).toHaveProperty('version');
+      expect(result).toEqual(restored);
+    });
+
+    it('returns null when the annotation is not trashed', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.restore(1, 10);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  // purge calls db.delete first, then builds the notExists subquery via db.select
+  // inside .where(), so the second queued result belongs to that subquery builder.
+  describe('purge', () => {
+    it('hard-deletes when every device acked the deletion', async () => {
+      const db = makeDb([{ id: 1 }], []);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.purge(1, 10);
+
+      expect(db.delete).toHaveBeenCalled();
+      expect(result).toBe('purged');
+    });
+
+    it('reports pending_device_sync when unacked device state blocks the purge', async () => {
+      const db = makeDb([], [], [{ id: 1 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.purge(1, 10);
+
+      expect(result).toBe('pending_device_sync');
+    });
+
+    it('reports not_found when no trashed row exists', async () => {
+      const db = makeDb([], [], []);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.purge(1, 10);
+
+      expect(result).toBe('not_found');
+    });
+  });
+
   describe('findPaginated', () => {
     it('returns items and total count', async () => {
-      const db = makePaginatedDb([makeRow()], 1);
+      const db = makeDb([makeRow()], [{ count: 1 }]);
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.findPaginated(5, 10, {}, { by: 'position', dir: 'asc' }, 1, 25);
@@ -268,7 +257,7 @@ describe('AnnotationRepository', () => {
     });
 
     it('returns empty result when no annotations match', async () => {
-      const db = makePaginatedDb([], 0);
+      const db = makeDb([], [{ count: 0 }]);
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.findPaginated(5, 10, {}, { by: 'position', dir: 'asc' }, 1, 25);
@@ -278,21 +267,28 @@ describe('AnnotationRepository', () => {
     });
 
     it('applies offset based on page and pageSize', async () => {
-      const db = makePaginatedDb([], 0);
+      const db = makeDb([], [{ count: 0 }]);
       const repo = new AnnotationRepository(db as never);
 
       await repo.findPaginated(5, 10, {}, { by: 'position', dir: 'asc' }, 3, 10);
 
-      expect(db._offset).toHaveBeenCalledWith(20);
+      expect(db._queries[0].offset).toHaveBeenCalledWith(20);
     });
   });
 
   describe('getStats', () => {
     it('returns aggregated stats', async () => {
-      const db = makeStatsDb({ totalHighlights: 5, chaptersWithHighlights: 2, highlightsWithNotes: 3 }, [
-        { color: 'yellow', count: 3 },
-        { color: '#4ADE80', count: 2 },
-      ]);
+      const db = makeDb(
+        [{ totalHighlights: 5, chaptersWithHighlights: 2, highlightsWithNotes: 3 }],
+        [
+          { color: 'yellow', count: 3 },
+          { color: '#4ADE80', count: 2 },
+        ],
+        [
+          { origin: 'web', count: 4 },
+          { origin: 'koreader', count: 1 },
+        ],
+      );
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.getStats(5, 10, {});
@@ -304,22 +300,27 @@ describe('AnnotationRepository', () => {
         { color: 'yellow', count: 3 },
         { color: '#4ADE80', count: 2 },
       ]);
+      expect(result.originBreakdown).toEqual([
+        { origin: 'web', count: 4 },
+        { origin: 'koreader', count: 1 },
+      ]);
     });
 
     it('returns zero stats when no annotations exist', async () => {
-      const db = makeStatsDb({ totalHighlights: 0, chaptersWithHighlights: 0, highlightsWithNotes: 0 }, []);
+      const db = makeDb([{ totalHighlights: 0, chaptersWithHighlights: 0, highlightsWithNotes: 0 }], [], []);
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.getStats(5, 10, {});
 
       expect(result.totalHighlights).toBe(0);
       expect(result.colorBreakdown).toEqual([]);
+      expect(result.originBreakdown).toEqual([]);
     });
   });
 
   describe('getDistinctChapters', () => {
     it('returns distinct chapter titles', async () => {
-      const db = makeDistinctChaptersDb(['Chapter 1', 'Chapter 2']);
+      const db = makeDb([{ chapterTitle: 'Chapter 1' }, { chapterTitle: 'Chapter 2' }]);
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.getDistinctChapters(5, 10);
@@ -327,17 +328,8 @@ describe('AnnotationRepository', () => {
       expect(result).toEqual(['Chapter 1', 'Chapter 2']);
     });
 
-    it('returns empty array when no chapters exist', async () => {
-      const db = makeDistinctChaptersDb([]);
-      const repo = new AnnotationRepository(db as never);
-
-      const result = await repo.getDistinctChapters(5, 10);
-
-      expect(result).toEqual([]);
-    });
-
     it('filters out null chapter titles', async () => {
-      const db = makeDistinctChaptersDb([null, 'Chapter 1']);
+      const db = makeDb([{ chapterTitle: null }, { chapterTitle: 'Chapter 1' }]);
       const repo = new AnnotationRepository(db as never);
 
       const result = await repo.getDistinctChapters(5, 10);
@@ -345,4 +337,227 @@ describe('AnnotationRepository', () => {
       expect(result).toEqual(['Chapter 1']);
     });
   });
+
+  describe('findHubPaginated', () => {
+    it('returns hub items and total while applying the notes-only and date filters', async () => {
+      const db = makeDb([makeRow({ bookTitle: 'Book', author: 'Author', jumpFileId: 1, pageno: null })], [{ count: 1 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.findHubPaginated(
+        10,
+        {
+          status: 'active',
+          hasNote: true,
+          dateFrom: new Date('2026-01-01T00:00:00Z'),
+          dateTo: new Date('2026-02-01T00:00:00Z'),
+          colors: ['yellow'],
+          styles: ['highlight'],
+          origins: ['web'],
+          chapter: 'Chapter 1',
+          search: 'foo',
+          bookId: 5,
+        },
+        { by: 'createdAt', dir: 'desc' },
+        1,
+        25,
+      );
+
+      expect(result.total).toBe(1);
+      expect(result.items).toHaveLength(1);
+      expect(db._queries[0].where).toHaveBeenCalled();
+    });
+
+    it('orders by book title when sort.by is book', async () => {
+      const db = makeDb([], [{ count: 0 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      await repo.findHubPaginated(10, { status: 'active' }, { by: 'book', dir: 'asc' }, 1, 25);
+
+      expect(db._queries[0].orderBy).toHaveBeenCalled();
+    });
+  });
+
+  describe('getHubStats', () => {
+    it('returns the aggregate row including the notes-only filter', async () => {
+      const db = makeDb([{ books: 2, withNotes: 1, web: 1, koreader: 1, kobo: 0 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const row = await repo.getHubStats(10, { status: 'active', hasNote: true });
+
+      expect(row).toMatchObject({ books: 2, withNotes: 1 });
+    });
+  });
+
+  describe('findHubAll', () => {
+    it('returns every matching hub row for export', async () => {
+      const db = makeDb([makeRow(), makeRow({ id: 2 })]);
+      const repo = new AnnotationRepository(db as never);
+
+      const rows = await repo.findHubAll(10, { status: 'active', hasNote: true, dateTo: new Date('2026-02-01T00:00:00Z') });
+
+      expect(rows).toHaveLength(2);
+    });
+  });
+
+  describe('findHubById', () => {
+    it('returns the hub row when found', async () => {
+      const db = makeDb([makeRow({ bookTitle: 'Book' })]);
+      const repo = new AnnotationRepository(db as never);
+
+      const row = await repo.findHubById(10, 1);
+
+      expect(row).toMatchObject({ id: 1 });
+    });
+
+    it('returns null when not found', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
+
+      expect(await repo.findHubById(10, 99)).toBeNull();
+    });
+  });
+
+  describe('findHubBookFacets', () => {
+    it('returns book facets with counts for active annotations and applies the limit', async () => {
+      const db = makeDb([{ bookId: 5, bookTitle: 'Book', author: 'Author', count: 3 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const rows = await repo.findHubBookFacets(10, { status: 'active', limit: 20 });
+
+      expect(rows).toEqual([{ bookId: 5, bookTitle: 'Book', author: 'Author', count: 3 }]);
+      expect(db._queries[0].orderBy).toHaveBeenCalled();
+      expect(db._queries[0].limit).toHaveBeenCalledWith(20);
+    });
+
+    it('queries the trashed set when status is trashed', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
+
+      await repo.findHubBookFacets(10, { status: 'trashed', limit: 20 });
+
+      expect(db._queries[0].where).toHaveBeenCalled();
+    });
+
+    it('adds a search filter and forwards a custom limit when a term is provided', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
+
+      await repo.findHubBookFacets(10, { status: 'active', q: 'dune', limit: 10 });
+
+      expect(db._queries[0].where).toHaveBeenCalled();
+      expect(db._queries[0].limit).toHaveBeenCalledWith(10);
+    });
+  });
+
+  describe('findHubBookFacet', () => {
+    it('returns the single pinned facet row', async () => {
+      const db = makeDb([{ bookId: 99, bookTitle: 'Pinned', author: null, count: 7 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      expect(await repo.findHubBookFacet(10, 'active', 99)).toEqual({ bookId: 99, bookTitle: 'Pinned', author: null, count: 7 });
+    });
+
+    it('returns null when the book has no annotations for the status', async () => {
+      const db = makeDb([]);
+      const repo = new AnnotationRepository(db as never);
+
+      expect(await repo.findHubBookFacet(10, 'active', 99)).toBeNull();
+    });
+  });
+
+  describe('bulkSetDeleted', () => {
+    it('returns 0 for an empty id list without querying', async () => {
+      const db = makeDb();
+      const repo = new AnnotationRepository(db as never);
+
+      expect(await repo.bulkSetDeleted(10, [], true)).toBe(0);
+      expect(db.update).not.toHaveBeenCalled();
+    });
+
+    it('soft-deletes the given ids and returns the affected count', async () => {
+      const db = makeDb([{ id: 1 }, { id: 2 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const affected = await repo.bulkSetDeleted(10, [1, 2], true);
+
+      expect(affected).toBe(2);
+      expect(db._queries[0].set.mock.calls[0][0]).toHaveProperty('deletedAt');
+    });
+
+    it('restores when deleted is false', async () => {
+      const db = makeDb([{ id: 1 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const affected = await repo.bulkSetDeleted(10, [1], false);
+
+      expect(affected).toBe(1);
+      expect(db._queries[0].set.mock.calls[0][0]).toMatchObject({ deletedAt: null });
+    });
+  });
+
+  describe('bulkRestyle', () => {
+    it('returns 0 when there are no ids or no patch fields', async () => {
+      const db = makeDb();
+      const repo = new AnnotationRepository(db as never);
+
+      expect(await repo.bulkRestyle(10, [], { color: 'yellow' })).toBe(0);
+      expect(await repo.bulkRestyle(10, [1], {})).toBe(0);
+      expect(db.update).not.toHaveBeenCalled();
+    });
+
+    it('applies the restyle patch and returns the affected count', async () => {
+      const db = makeDb([{ id: 1 }, { id: 2 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const affected = await repo.bulkRestyle(10, [1, 2], { color: '#38BDF8', style: 'underline' });
+
+      expect(affected).toBe(2);
+      expect(db._queries[0].set.mock.calls[0][0]).toMatchObject({ color: '#38BDF8', style: 'underline' });
+    });
+  });
+
+  describe('findTrashed', () => {
+    it('returns trashed rows filtered by book', async () => {
+      const db = makeDb([makeRow({ deletedAt: new Date('2026-01-02T00:00:00Z') })]);
+      const repo = new AnnotationRepository(db as never);
+
+      const rows = await repo.findTrashed(10, 5);
+
+      expect(rows).toHaveLength(1);
+    });
+  });
+
+  describe('findPaginated with filters', () => {
+    it('applies color, search, chapter and date filters with position sort', async () => {
+      const db = makeDb([makeRow()], [{ count: 1 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      const result = await repo.findPaginated(
+        5,
+        10,
+        {
+          colors: ['yellow'],
+          search: 'foo',
+          chapter: 'Chapter 1',
+          dateFrom: new Date('2026-01-01T00:00:00Z'),
+          dateTo: new Date('2026-02-01T00:00:00Z'),
+        },
+        { by: 'position', dir: 'desc' },
+        1,
+        25,
+      );
+
+      expect(result.total).toBe(1);
+      expect(result.items).toHaveLength(1);
+    });
+
+    it('orders by createdAt when sort.by is createdAt', async () => {
+      const db = makeDb([], [{ count: 0 }]);
+      const repo = new AnnotationRepository(db as never);
+
+      await repo.findPaginated(5, 10, {}, { by: 'createdAt', dir: 'asc' }, 1, 25);
+
+      expect(db._queries[0].orderBy).toHaveBeenCalled();
+    });
+  });
 });
diff --git a/server/src/modules/annotation/annotation.repository.ts b/server/src/modules/annotation/annotation.repository.ts
index 3f1061551..10610f95b 100644
--- a/server/src/modules/annotation/annotation.repository.ts
+++ b/server/src/modules/annotation/annotation.repository.ts
@@ -1,13 +1,69 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { SQL, and, asc, count, countDistinct, desc, eq, gte, ilike, isNotNull, lte, inArray, or, sql } from 'drizzle-orm';
+import {
+  SQL,
+  and,
+  asc,
+  count,
+  countDistinct,
+  desc,
+  eq,
+  getTableColumns,
+  gte,
+  ilike,
+  isNotNull,
+  isNull,
+  lte,
+  inArray,
+  max,
+  notExists,
+  or,
+  sql,
+} from 'drizzle-orm';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 import { DB } from '../../db';
 import * as schema from '../../db/schema';
-import { annotations, NewAnnotation } from '../../db/schema';
+import {
+  annotationPositions,
+  annotationSyncState,
+  annotations,
+  authors,
+  bookAuthors,
+  bookMetadata,
+  books,
+  AnnotationRow,
+  NewAnnotation,
+} from '../../db/schema';
 
 type Db = NodePgDatabase<typeof schema>;
 
+export type AnnotationWithCfi = AnnotationRow & {
+  cfi: string | null;
+  cfiStatus: string | null;
+  cfiExtras: Record<string, unknown> | null;
+  jumpFileId: number | null;
+  pageno: number | null;
+};
+export type HubAnnotationRow = AnnotationWithCfi & { bookTitle: string | null; author: string | null };
+
+export interface HubFilters {
+  bookId?: number;
+  colors?: string[];
+  styles?: string[];
+  origins?: string[];
+  chapter?: string;
+  search?: string;
+  dateFrom?: Date;
+  dateTo?: Date;
+  hasNote?: boolean;
+  status: 'active' | 'trashed';
+}
+
+export interface HubSort {
+  by: 'createdAt' | 'book';
+  dir: 'asc' | 'desc';
+}
+
 export interface AnnotationFilters {
   colors?: string[];
   search?: string;
@@ -22,13 +78,14 @@ export interface AnnotationSort {
 }
 
 export interface PaginatedAnnotations {
-  items: (typeof annotations.$inferSelect)[];
+  items: AnnotationWithCfi[];
   total: number;
 }
 
 export interface AnnotationStatsResult {
   totalHighlights: number;
   colorBreakdown: { color: string; count: number }[];
+  originBreakdown: { origin: AnnotationRow['origin']; count: number }[];
   chaptersWithHighlights: number;
   highlightsWithNotes: number;
 }
@@ -37,14 +94,57 @@ export interface AnnotationStatsResult {
 export class AnnotationRepository {
   constructor(@Inject(DB) private readonly db: Db) {}
 
-  async findByBookId(bookId: number, userId: number) {
+  private hubColumns() {
+    return {
+      ...getTableColumns(annotations),
+      cfi: annotationPositions.pos0,
+      cfiStatus: annotationPositions.status,
+      cfiExtras: annotationPositions.extras,
+      bookTitle: bookMetadata.title,
+      author: sql<
+        string | null
+      >`(select string_agg(${authors.name}, ', ' order by ${bookAuthors.displayOrder}) from ${bookAuthors} inner join ${authors} on ${authors.id} = ${bookAuthors.authorId} where ${bookAuthors.bookId} = ${annotations.bookId})`,
+      jumpFileId: sql<
+        number | null
+      >`coalesce(${annotationPositions.bookFileId}, (select ap2.book_file_id from annotation_positions ap2 where ap2.annotation_id = ${annotations.id} and ap2.format in ('xpointer', 'pdf') limit 1), ${books.primaryFileId})`,
+      pageno: sql<
+        number | null
+      >`(select (ap3.extras ->> 'pageno')::int from annotation_positions ap3 where ap3.annotation_id = ${annotations.id} and ap3.format in ('xpointer', 'pdf') limit 1)`,
+    };
+  }
+
+  private selectWithCfi() {
     return this.db
-      .select()
+      .select({
+        ...getTableColumns(annotations),
+        cfi: annotationPositions.pos0,
+        cfiStatus: annotationPositions.status,
+        cfiExtras: annotationPositions.extras,
+        jumpFileId: sql<
+          number | null
+        >`coalesce(${annotationPositions.bookFileId}, (select ap2.book_file_id from annotation_positions ap2 where ap2.annotation_id = ${annotations.id} and ap2.format in ('xpointer', 'pdf') limit 1), ${books.primaryFileId})`,
+        pageno: sql<
+          number | null
+        >`(select (ap3.extras ->> 'pageno')::int from annotation_positions ap3 where ap3.annotation_id = ${annotations.id} and ap3.format in ('xpointer', 'pdf') limit 1)`,
+      })
       .from(annotations)
-      .where(and(eq(annotations.bookId, bookId), eq(annotations.userId, userId)))
+      .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi')))
+      .leftJoin(books, eq(books.id, annotations.bookId));
+  }
+
+  async findByBookId(bookId: number, userId: number): Promise<AnnotationWithCfi[]> {
+    return this.selectWithCfi()
+      .where(and(...this.baseConditions(bookId, userId)))
       .orderBy(asc(annotations.createdAt));
   }
 
+  async findById(bookId: number, annotationId: number, userId: number): Promise<AnnotationWithCfi | null> {
+    const [row] = await this.selectWithCfi()
+      .where(and(eq(annotations.id, annotationId), ...this.baseConditions(bookId, userId)))
+      .limit(1);
+    return row ?? null;
+  }
+
   async findPaginated(
     bookId: number,
     userId: number,
@@ -58,9 +158,7 @@ export class AnnotationRepository {
     const offset = (page - 1) * pageSize;
 
     const [items, totalResult] = await Promise.all([
-      this.db
-        .select()
-        .from(annotations)
+      this.selectWithCfi()
         .where(and(...conditions))
         .orderBy(...orderBy)
         .limit(pageSize)
@@ -68,6 +166,7 @@ export class AnnotationRepository {
       this.db
         .select({ count: count() })
         .from(annotations)
+        .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi')))
         .where(and(...conditions)),
     ]);
 
@@ -76,8 +175,9 @@ export class AnnotationRepository {
 
   async getStats(bookId: number, userId: number, filters: AnnotationFilters): Promise<AnnotationStatsResult> {
     const conditions = this.buildConditions(bookId, userId, filters);
+    const cfiJoin = and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi'));
 
-    const [aggregateResult, colorResult] = await Promise.all([
+    const [aggregateResult, colorResult, originResult] = await Promise.all([
       this.db
         .select({
           totalHighlights: count(),
@@ -85,6 +185,7 @@ export class AnnotationRepository {
           highlightsWithNotes: count(sql`case when ${annotations.note} is not null and ${annotations.note} != '' then 1 end`),
         })
         .from(annotations)
+        .leftJoin(annotationPositions, cfiJoin)
         .where(and(...conditions)),
       this.db
         .select({
@@ -92,9 +193,20 @@ export class AnnotationRepository {
           count: count(),
         })
         .from(annotations)
+        .leftJoin(annotationPositions, cfiJoin)
         .where(and(...conditions))
         .groupBy(annotations.color)
         .orderBy(desc(count())),
+      this.db
+        .select({
+          origin: annotations.origin,
+          count: count(),
+        })
+        .from(annotations)
+        .leftJoin(annotationPositions, cfiJoin)
+        .where(and(...conditions))
+        .groupBy(annotations.origin)
+        .orderBy(desc(count())),
     ]);
 
     const agg = aggregateResult[0];
@@ -104,6 +216,7 @@ export class AnnotationRepository {
       chaptersWithHighlights: agg?.chaptersWithHighlights ?? 0,
       highlightsWithNotes: agg?.highlightsWithNotes ?? 0,
       colorBreakdown: colorResult.map((r) => ({ color: r.color, count: r.count })),
+      originBreakdown: originResult.map((r) => ({ origin: r.origin, count: r.count })),
     };
   }
 
@@ -111,36 +224,280 @@ export class AnnotationRepository {
     const rows = await this.db
       .selectDistinct({ chapterTitle: annotations.chapterTitle })
       .from(annotations)
-      .where(and(eq(annotations.bookId, bookId), eq(annotations.userId, userId), isNotNull(annotations.chapterTitle)))
+      .where(and(...this.baseConditions(bookId, userId), isNotNull(annotations.chapterTitle)))
       .orderBy(asc(annotations.chapterTitle));
 
     return rows.map((r) => r.chapterTitle).filter((t): t is string => t != null);
   }
 
-  async create(data: NewAnnotation) {
-    const [row] = await this.db.insert(annotations).values(data).returning();
-    return row;
+  async create(data: NewAnnotation & { cfi: string; bookFileId?: number | null }): Promise<AnnotationWithCfi> {
+    const { cfi, bookFileId, ...annotationData } = data;
+    return this.db.transaction(async (tx) => {
+      const [row] = await tx.insert(annotations).values(annotationData).returning();
+      await tx.insert(annotationPositions).values({
+        annotationId: row.id,
+        userId: row.userId,
+        bookFileId: bookFileId ?? null,
+        format: 'cfi',
+        pos0: cfi,
+        status: 'exact',
+      });
+      return { ...row, cfi, cfiStatus: 'exact', cfiExtras: null, jumpFileId: bookFileId ?? null, pageno: null };
+    });
   }
 
-  async update(bookId: number, annotationId: number, userId: number, data: Partial<Pick<NewAnnotation, 'note' | 'color' | 'style'>>) {
+  async update(
+    bookId: number,
+    annotationId: number,
+    userId: number,
+    data: Partial<Pick<NewAnnotation, 'note' | 'color' | 'style'>>,
+  ): Promise<AnnotationWithCfi | null> {
     const [row] = await this.db
       .update(annotations)
-      .set({ ...data, updatedAt: sql`now()` })
-      .where(and(eq(annotations.id, annotationId), eq(annotations.bookId, bookId), eq(annotations.userId, userId)))
+      .set({ ...data, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(and(eq(annotations.id, annotationId), ...this.baseConditions(bookId, userId)))
       .returning();
-    return row ?? null;
+    if (!row) return null;
+    return this.findById(bookId, annotationId, userId);
   }
 
-  async delete(bookId: number, annotationId: number, userId: number) {
+  async softDelete(bookId: number, annotationId: number, userId: number): Promise<boolean> {
     const result = await this.db
-      .delete(annotations)
-      .where(and(eq(annotations.id, annotationId), eq(annotations.bookId, bookId), eq(annotations.userId, userId)))
+      .update(annotations)
+      .set({ deletedAt: sql`now()`, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(and(eq(annotations.id, annotationId), ...this.baseConditions(bookId, userId)))
       .returning({ id: annotations.id });
     return result.length > 0;
   }
 
+  async restore(annotationId: number, userId: number): Promise<AnnotationRow | null> {
+    const [row] = await this.db
+      .update(annotations)
+      .set({ deletedAt: null, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(and(eq(annotations.id, annotationId), eq(annotations.userId, userId), isNotNull(annotations.deletedAt)))
+      .returning();
+    return row ?? null;
+  }
+
+  /**
+   * Hard delete, allowed only once every device that ever synced the annotation has
+   * acknowledged its deletion (otherwise an unaware device would re-upload it as new).
+   */
+  async purge(annotationId: number, userId: number): Promise<'purged' | 'pending_device_sync' | 'not_found'> {
+    const result = await this.db
+      .delete(annotations)
+      .where(
+        and(
+          eq(annotations.id, annotationId),
+          eq(annotations.userId, userId),
+          isNotNull(annotations.deletedAt),
+          notExists(
+            this.db
+              .select({ one: sql`1` })
+              .from(annotationSyncState)
+              .where(and(eq(annotationSyncState.annotationId, annotations.id), isNull(annotationSyncState.deleteAckedAt))),
+          ),
+        ),
+      )
+      .returning({ id: annotations.id });
+    if (result.length > 0) return 'purged';
+
+    const [existing] = await this.db
+      .select({ id: annotations.id })
+      .from(annotations)
+      .where(and(eq(annotations.id, annotationId), eq(annotations.userId, userId), isNotNull(annotations.deletedAt)))
+      .limit(1);
+    return existing ? 'pending_device_sync' : 'not_found';
+  }
+
+  async findHubPaginated(userId: number, filters: HubFilters, sort: HubSort, page: number, pageSize: number) {
+    const conditions = this.buildHubConditions(userId, filters);
+    const direction = sort.dir === 'desc' ? desc : asc;
+    const orderBy =
+      sort.by === 'book'
+        ? [direction(bookMetadata.title), desc(annotations.createdAt), desc(annotations.id)]
+        : [direction(annotations.createdAt), direction(annotations.id)];
+    const offset = (page - 1) * pageSize;
+
+    const [items, totalResult] = await Promise.all([
+      this.db
+        .select(this.hubColumns())
+        .from(annotations)
+        .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi')))
+        .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+        .leftJoin(books, eq(books.id, annotations.bookId))
+        .where(and(...conditions))
+        .orderBy(...orderBy)
+        .limit(pageSize)
+        .offset(offset),
+      this.db
+        .select({ count: count() })
+        .from(annotations)
+        .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+        .leftJoin(books, eq(books.id, annotations.bookId))
+        .where(and(...conditions)),
+    ]);
+
+    return { items: items as HubAnnotationRow[], total: totalResult[0]?.count ?? 0 };
+  }
+
+  async findHubById(userId: number, annotationId: number): Promise<HubAnnotationRow | null> {
+    const [row] = await this.db
+      .select(this.hubColumns())
+      .from(annotations)
+      .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi')))
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+      .leftJoin(books, eq(books.id, annotations.bookId))
+      .where(and(eq(annotations.id, annotationId), eq(annotations.userId, userId)))
+      .limit(1);
+    return (row as HubAnnotationRow | undefined) ?? null;
+  }
+
+  async findHubAll(userId: number, filters: HubFilters, limit = 5000): Promise<HubAnnotationRow[]> {
+    const conditions = this.buildHubConditions(userId, filters);
+    const rows = await this.db
+      .select(this.hubColumns())
+      .from(annotations)
+      .leftJoin(annotationPositions, and(eq(annotationPositions.annotationId, annotations.id), eq(annotationPositions.format, 'cfi')))
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+      .leftJoin(books, eq(books.id, annotations.bookId))
+      .where(and(...conditions))
+      .orderBy(asc(bookMetadata.title), asc(annotations.chapterTitle), asc(annotations.createdAt))
+      .limit(limit);
+    return rows as HubAnnotationRow[];
+  }
+
+  async getHubStats(userId: number, filters: HubFilters) {
+    const conditions = this.buildHubConditions(userId, filters);
+    const [row] = await this.db
+      .select({
+        books: countDistinct(annotations.bookId),
+        withNotes: sql<number>`count(*) filter (where ${annotations.note} is not null and ${annotations.note} <> '')`,
+        web: sql<number>`count(*) filter (where ${annotations.origin} = 'web')`,
+        koreader: sql<number>`count(*) filter (where ${annotations.origin} = 'koreader')`,
+        kobo: sql<number>`count(*) filter (where ${annotations.origin} = 'kobo')`,
+      })
+      .from(annotations)
+      .where(and(...conditions));
+    return row;
+  }
+
+  private bookFacetAuthorSql() {
+    return sql<
+      string | null
+    >`(select string_agg(${authors.name}, ', ' order by ${bookAuthors.displayOrder}) from ${bookAuthors} inner join ${authors} on ${authors.id} = ${bookAuthors.authorId} where ${bookAuthors.bookId} = ${annotations.bookId})`;
+  }
+
+  async findHubBookFacets(userId: number, params: { status: 'active' | 'trashed'; q?: string; limit: number }) {
+    const conditions: SQL[] = [
+      eq(annotations.userId, userId),
+      params.status === 'trashed' ? isNotNull(annotations.deletedAt) : isNull(annotations.deletedAt),
+    ];
+    const term = params.q?.trim();
+    if (term) {
+      const pattern = `%${term}%`;
+      conditions.push(
+        or(
+          ilike(bookMetadata.title, pattern),
+          sql`exists (select 1 from ${bookAuthors} inner join ${authors} on ${authors.id} = ${bookAuthors.authorId} where ${bookAuthors.bookId} = ${annotations.bookId} and ${authors.name} ilike ${pattern})`,
+        )!,
+      );
+    }
+    return this.db
+      .select({
+        bookId: annotations.bookId,
+        bookTitle: bookMetadata.title,
+        author: this.bookFacetAuthorSql(),
+        count: count(),
+      })
+      .from(annotations)
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+      .where(and(...conditions))
+      .groupBy(annotations.bookId, bookMetadata.title)
+      .orderBy(desc(max(annotations.createdAt)), asc(bookMetadata.title))
+      .limit(params.limit);
+  }
+
+  async findHubBookFacet(userId: number, status: 'active' | 'trashed', bookId: number) {
+    const rows = await this.db
+      .select({
+        bookId: annotations.bookId,
+        bookTitle: bookMetadata.title,
+        author: this.bookFacetAuthorSql(),
+        count: count(),
+      })
+      .from(annotations)
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, annotations.bookId))
+      .where(
+        and(
+          eq(annotations.userId, userId),
+          eq(annotations.bookId, bookId),
+          status === 'trashed' ? isNotNull(annotations.deletedAt) : isNull(annotations.deletedAt),
+        ),
+      )
+      .groupBy(annotations.bookId, bookMetadata.title)
+      .limit(1);
+    return rows[0] ?? null;
+  }
+
+  async bulkSetDeleted(userId: number, ids: number[], deleted: boolean): Promise<number> {
+    if (ids.length === 0) return 0;
+    const result = await this.db
+      .update(annotations)
+      .set({
+        deletedAt: deleted ? sql`now()` : null,
+        version: sql`${annotations.version} + 1`,
+        updatedAt: sql`now()`,
+      })
+      .where(
+        and(inArray(annotations.id, ids), eq(annotations.userId, userId), deleted ? isNull(annotations.deletedAt) : isNotNull(annotations.deletedAt)),
+      )
+      .returning({ id: annotations.id });
+    return result.length;
+  }
+
+  async bulkRestyle(userId: number, ids: number[], patch: { color?: string; style?: string }): Promise<number> {
+    if (ids.length === 0 || (patch.color === undefined && patch.style === undefined)) return 0;
+    const result = await this.db
+      .update(annotations)
+      .set({ ...patch, version: sql`${annotations.version} + 1`, updatedAt: sql`now()` })
+      .where(and(inArray(annotations.id, ids), eq(annotations.userId, userId), isNull(annotations.deletedAt)))
+      .returning({ id: annotations.id });
+    return result.length;
+  }
+
+  private buildHubConditions(userId: number, filters: HubFilters): SQL[] {
+    const conditions: SQL[] = [eq(annotations.userId, userId)];
+    conditions.push(filters.status === 'trashed' ? isNotNull(annotations.deletedAt) : isNull(annotations.deletedAt));
+    if (filters.bookId !== undefined) conditions.push(eq(annotations.bookId, filters.bookId));
+    if (filters.colors && filters.colors.length > 0) conditions.push(inArray(annotations.color, filters.colors));
+    if (filters.styles && filters.styles.length > 0) conditions.push(inArray(annotations.style, filters.styles));
+    if (filters.origins && filters.origins.length > 0) conditions.push(inArray(annotations.origin, filters.origins as AnnotationRow['origin'][]));
+    if (filters.chapter) conditions.push(eq(annotations.chapterTitle, filters.chapter));
+    if (filters.search) {
+      const pattern = `%${filters.search}%`;
+      conditions.push(or(ilike(annotations.text, pattern), ilike(annotations.note, pattern))!);
+    }
+    if (filters.hasNote) conditions.push(sql`${annotations.note} is not null and ${annotations.note} <> ''`);
+    if (filters.dateFrom) conditions.push(gte(annotations.createdAt, filters.dateFrom));
+    if (filters.dateTo) conditions.push(lte(annotations.createdAt, filters.dateTo));
+    return conditions;
+  }
+
+  async findTrashed(userId: number, bookId?: number): Promise<AnnotationWithCfi[]> {
+    const conditions = [eq(annotations.userId, userId), isNotNull(annotations.deletedAt)];
+    if (bookId !== undefined) conditions.push(eq(annotations.bookId, bookId));
+    return this.selectWithCfi()
+      .where(and(...conditions))
+      .orderBy(desc(annotations.deletedAt));
+  }
+
+  private baseConditions(bookId: number, userId: number): SQL[] {
+    return [eq(annotations.bookId, bookId), eq(annotations.userId, userId), isNull(annotations.deletedAt)];
+  }
+
   private buildConditions(bookId: number, userId: number, filters: AnnotationFilters): SQL[] {
-    const conditions: SQL[] = [eq(annotations.bookId, bookId), eq(annotations.userId, userId)];
+    const conditions = this.baseConditions(bookId, userId);
 
     if (filters.colors && filters.colors.length > 0) {
       conditions.push(inArray(annotations.color, filters.colors));
@@ -165,7 +522,7 @@ export class AnnotationRepository {
   private buildOrderBy(sort: AnnotationSort) {
     const direction = sort.dir === 'desc' ? desc : asc;
     if (sort.by === 'position') {
-      return [direction(annotations.cfi), direction(annotations.id)];
+      return [sql`${annotationPositions.pos0} ${sql.raw(sort.dir === 'desc' ? 'desc' : 'asc')} nulls last`, direction(annotations.id)];
     }
     return [direction(annotations.createdAt), direction(annotations.id)];
   }
diff --git a/server/src/modules/annotation/annotation.service.test.ts b/server/src/modules/annotation/annotation.service.test.ts
index 8db6164cd..3d9632704 100644
--- a/server/src/modules/annotation/annotation.service.test.ts
+++ b/server/src/modules/annotation/annotation.service.test.ts
@@ -35,11 +35,20 @@ function makeAnnotationRow(overrides?: Record<string, unknown>) {
     userId: 1,
     bookId: 5,
     cfi: 'epubcfi(/6/4!/4/2/1:0)',
+    cfiStatus: 'exact',
+    cfiExtras: null,
+    jumpFileId: 50,
+    pageno: null,
     text: 'selected text',
     color: 'yellow',
     style: 'highlight',
     note: null,
     chapterTitle: null,
+    origin: 'web',
+    version: 1,
+    deletedAt: null,
+    deviceCreatedAt: null,
+    deviceUpdatedAt: null,
     createdAt: new Date('2026-01-01T00:00:00Z'),
     updatedAt: new Date('2026-01-01T00:00:00Z'),
     ...overrides,
@@ -54,7 +63,7 @@ function makeService() {
     getDistinctChapters: vi.fn(),
     create: vi.fn(),
     update: vi.fn(),
-    delete: vi.fn(),
+    softDelete: vi.fn(),
   };
   const bookService = {
     verifyBookAccess: vi.fn().mockResolvedValue(undefined),
@@ -62,8 +71,9 @@ function makeService() {
   const achievementEvents = {
     emit: vi.fn(),
   };
-  const service = new AnnotationService(annotationRepo as never, bookService as never, achievementEvents as never);
-  return { service, annotationRepo, bookService };
+  const conversionService = { ensureCfiPositionsForBook: vi.fn().mockResolvedValue(0) };
+  const service = new AnnotationService(annotationRepo as never, bookService as never, achievementEvents as never, conversionService as never);
+  return { service, annotationRepo, bookService, conversionService };
 }
 
 describe('AnnotationService', () => {
@@ -291,29 +301,29 @@ describe('AnnotationService', () => {
   describe('deleteAnnotation', () => {
     it('deletes annotation successfully', async () => {
       const { service, annotationRepo } = makeService();
-      annotationRepo.delete.mockResolvedValue(true);
+      annotationRepo.softDelete.mockResolvedValue(true);
 
       await expect(service.deleteAnnotation(5, 10, makeUser())).resolves.toBeUndefined();
-      expect(annotationRepo.delete).toHaveBeenCalledWith(5, 10, 1);
+      expect(annotationRepo.softDelete).toHaveBeenCalledWith(5, 10, 1);
     });
 
     it('throws NotFoundException when annotation is not found', async () => {
       const { service, annotationRepo } = makeService();
-      annotationRepo.delete.mockResolvedValue(false);
+      annotationRepo.softDelete.mockResolvedValue(false);
 
       await expect(service.deleteAnnotation(5, 99, makeUser())).rejects.toThrow(NotFoundException);
     });
 
     it('NotFoundException message includes bookId and annotationId', async () => {
       const { service, annotationRepo } = makeService();
-      annotationRepo.delete.mockResolvedValue(false);
+      annotationRepo.softDelete.mockResolvedValue(false);
 
       await expect(service.deleteAnnotation(5, 99, makeUser())).rejects.toThrow('Annotation 99 not found for book 5');
     });
 
     it('verifies book access before deleting', async () => {
       const { service, annotationRepo, bookService } = makeService();
-      annotationRepo.delete.mockResolvedValue(true);
+      annotationRepo.softDelete.mockResolvedValue(true);
 
       await service.deleteAnnotation(5, 10, makeUser());
 
@@ -325,7 +335,7 @@ describe('AnnotationService', () => {
       bookService.verifyBookAccess.mockRejectedValue(new ForbiddenException());
 
       await expect(service.deleteAnnotation(5, 10, makeUser())).rejects.toThrow(ForbiddenException);
-      expect(annotationRepo.delete).not.toHaveBeenCalled();
+      expect(annotationRepo.softDelete).not.toHaveBeenCalled();
     });
 
     it('propagates NotFoundException when book does not exist', async () => {
@@ -384,6 +394,7 @@ describe('AnnotationService', () => {
           { color: 'yellow', count: 2 },
           { color: '#4ADE80', count: 1 },
         ],
+        originBreakdown: [{ origin: 'web', count: 3 }],
         chaptersWithHighlights: 2,
         highlightsWithNotes: 1,
         ...overrides,
diff --git a/server/src/modules/annotation/annotation.service.ts b/server/src/modules/annotation/annotation.service.ts
index a979d3b13..3c51908cd 100644
--- a/server/src/modules/annotation/annotation.service.ts
+++ b/server/src/modules/annotation/annotation.service.ts
@@ -5,6 +5,7 @@ import type { RequestUser } from '../../common/types/request-user';
 import { BookService } from '../book/book.service';
 import { AchievementEventsService, ACHIEVEMENT_EVENT_ANNOTATION_CREATED } from '../achievement/achievement-events.service';
 import { DEFAULT_ANNOTATION_COLOR, DEFAULT_ANNOTATION_STYLE } from './annotation.constants';
+import { AnnotationConversionService } from './annotation-conversion.service';
 import { AnnotationRepository, type AnnotationFilters, type AnnotationSort } from './annotation.repository';
 import { AnnotationResponseDto } from './dto/annotation-response.dto';
 import { CreateAnnotationDto } from './dto/create-annotation.dto';
@@ -17,10 +18,12 @@ export class AnnotationService {
     private readonly annotationRepo: AnnotationRepository,
     private readonly bookService: BookService,
     private readonly achievementEvents: AchievementEventsService,
+    private readonly conversionService: AnnotationConversionService,
   ) {}
 
   async getAnnotations(bookId: number, user: RequestUser): Promise<AnnotationResponseDto[]> {
     await this.bookService.verifyBookAccess(bookId, user);
+    await this.conversionService.ensureCfiPositionsForBook(user.id, bookId);
     const rows = await this.annotationRepo.findByBookId(bookId, user.id);
     return rows.map((row) => AnnotationResponseDto.from(row));
   }
@@ -46,11 +49,16 @@ export class AnnotationService {
           id: dto.id,
           bookId: dto.bookId,
           cfi: dto.cfi,
+          jumpFileId: dto.jumpFileId,
+          pageno: dto.pageno,
           text: dto.text,
           color: dto.color,
           style: dto.style,
           note: dto.note,
           chapterTitle: dto.chapterTitle,
+          origin: dto.origin as 'web' | 'koreader' | 'kobo',
+          positionStatus: dto.positionStatus as AnnotationListResponse['items'][number]['positionStatus'],
+          chapterIndex: dto.chapterIndex,
           createdAt: dto.createdAt instanceof Date ? dto.createdAt.toISOString() : String(dto.createdAt),
         };
       }),
@@ -70,6 +78,7 @@ export class AnnotationService {
       userId: user.id,
       bookId,
       cfi: dto.cfi,
+      bookFileId: dto.bookFileId ?? null,
       text: dto.text,
       color: dto.color ?? DEFAULT_ANNOTATION_COLOR,
       style: dto.style ?? DEFAULT_ANNOTATION_STYLE,
@@ -97,7 +106,7 @@ export class AnnotationService {
 
   async deleteAnnotation(bookId: number, annotationId: number, user: RequestUser): Promise<void> {
     await this.bookService.verifyBookAccess(bookId, user);
-    const deleted = await this.annotationRepo.delete(bookId, annotationId, user.id);
+    const deleted = await this.annotationRepo.softDelete(bookId, annotationId, user.id);
     if (!deleted) throw new NotFoundException(this.notFoundMessage(bookId, annotationId));
   }
 
diff --git a/server/src/modules/annotation/dto/annotation-dto-validation.test.ts b/server/src/modules/annotation/dto/annotation-dto-validation.test.ts
index edc0221e0..573106de9 100644
--- a/server/src/modules/annotation/dto/annotation-dto-validation.test.ts
+++ b/server/src/modules/annotation/dto/annotation-dto-validation.test.ts
@@ -3,6 +3,13 @@ import 'reflect-metadata';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 
+import {
+  AnnotationBulkDto,
+  AnnotationExportQueryDto,
+  AnnotationHubBooksQueryDto,
+  AnnotationHubQueryDto,
+  AnnotationPositionRetryDto,
+} from './annotation-hub.dto';
 import { CreateAnnotationDto } from './create-annotation.dto';
 import { UpdateAnnotationDto } from './update-annotation.dto';
 
@@ -47,3 +54,107 @@ describe('Annotation DTO validation', () => {
     expect((await errorsFor(UpdateAnnotationDto, { style: 'invalid' })).length).toBeGreaterThan(0);
   });
 });
+
+describe('AnnotationHubQueryDto validation', () => {
+  it('coerces a hasNote "true" string to boolean and accepts an ISO date range', async () => {
+    const dto = plainToInstance(AnnotationHubQueryDto, {
+      hasNote: 'true',
+      dateFrom: '2026-01-01T00:00:00.000Z',
+      dateTo: '2026-01-31',
+    });
+
+    expect(await validate(dto)).toHaveLength(0);
+    expect(dto.hasNote).toBe(true);
+  });
+
+  it('coerces a hasNote "false" string to boolean false', async () => {
+    const dto = plainToInstance(AnnotationHubQueryDto, { hasNote: 'false' });
+
+    expect(dto.hasNote).toBe(false);
+    expect(await validate(dto)).toHaveLength(0);
+  });
+
+  it('leaves hasNote undefined when it is absent', async () => {
+    const dto = plainToInstance(AnnotationHubQueryDto, {});
+
+    expect(dto.hasNote).toBeUndefined();
+    expect(await validate(dto)).toHaveLength(0);
+  });
+
+  it('rejects a non-boolean hasNote and a malformed date', async () => {
+    expect((await errorsFor(AnnotationHubQueryDto, { hasNote: 'maybe' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationHubQueryDto, { dateFrom: 'not-a-date' })).length).toBeGreaterThan(0);
+  });
+
+  it('accepts a fully populated query and coerces numeric fields', async () => {
+    const dto = plainToInstance(AnnotationHubQueryDto, {
+      page: '2',
+      pageSize: '50',
+      bookId: '5',
+      search: 'foo',
+      chapter: 'Chapter 1',
+      colors: '#FACC15,#4ADE80',
+      styles: 'highlight,underline',
+      origins: 'web,koreader',
+      dateFrom: '2026-01-01',
+      dateTo: '2026-01-31',
+      hasNote: 'true',
+      status: 'active',
+      sortBy: 'book',
+      sortDir: 'asc',
+    });
+
+    expect(await validate(dto)).toHaveLength(0);
+    expect(dto.page).toBe(2);
+    expect(dto.bookId).toBe(5);
+  });
+
+  it('rejects out-of-range pagination and bad enum values', async () => {
+    expect((await errorsFor(AnnotationHubQueryDto, { page: '0' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationHubQueryDto, { pageSize: '101' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationHubQueryDto, { status: 'archived' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationHubQueryDto, { sortBy: 'color' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationHubQueryDto, { search: 'x'.repeat(201) })).length).toBeGreaterThan(0);
+  });
+});
+
+describe('AnnotationBulkDto validation', () => {
+  it('accepts a trash action and a restyle with color and style', async () => {
+    expect(await errorsFor(AnnotationBulkDto, { ids: [1, 2], action: 'trash' })).toHaveLength(0);
+    expect(await errorsFor(AnnotationBulkDto, { ids: [1], action: 'restyle', color: '#FACC15', style: 'underline' })).toHaveLength(0);
+  });
+
+  it('normalizes an empty color string to undefined', () => {
+    const dto = plainToInstance(AnnotationBulkDto, { ids: [1], action: 'restyle', color: '' });
+    expect(dto.color).toBeUndefined();
+  });
+
+  it('rejects an empty id list, unknown action, oversize color and bad style', async () => {
+    expect((await errorsFor(AnnotationBulkDto, { ids: [], action: 'trash' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationBulkDto, { ids: [1], action: 'explode' })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationBulkDto, { ids: [1], action: 'restyle', color: 'x'.repeat(21) })).length).toBeGreaterThan(0);
+    expect((await errorsFor(AnnotationBulkDto, { ids: [1], action: 'restyle', style: 'nope' })).length).toBeGreaterThan(0);
+  });
+});
+
+describe('AnnotationPositionRetryDto validation', () => {
+  it('accepts a known format and rejects an unknown one', async () => {
+    expect(await errorsFor(AnnotationPositionRetryDto, { format: 'cfi' })).toHaveLength(0);
+    expect((await errorsFor(AnnotationPositionRetryDto, { format: 'mobi' })).length).toBeGreaterThan(0);
+  });
+});
+
+describe('AnnotationExportQueryDto validation', () => {
+  it('accepts a known export format and rejects an unknown one', async () => {
+    expect(await errorsFor(AnnotationExportQueryDto, { format: 'csv' })).toHaveLength(0);
+    expect((await errorsFor(AnnotationExportQueryDto, { format: 'pdf' })).length).toBeGreaterThan(0);
+  });
+});
+
+describe('AnnotationHubBooksQueryDto validation', () => {
+  it('accepts active and trashed but rejects other statuses', async () => {
+    expect(await errorsFor(AnnotationHubBooksQueryDto, { status: 'active' })).toHaveLength(0);
+    expect(await errorsFor(AnnotationHubBooksQueryDto, { status: 'trashed' })).toHaveLength(0);
+    expect((await errorsFor(AnnotationHubBooksQueryDto, { status: 'gone' })).length).toBeGreaterThan(0);
+  });
+});
diff --git a/server/src/modules/annotation/dto/annotation-hub.dto.ts b/server/src/modules/annotation/dto/annotation-hub.dto.ts
new file mode 100644
index 000000000..41b6766e4
--- /dev/null
+++ b/server/src/modules/annotation/dto/annotation-hub.dto.ts
@@ -0,0 +1,140 @@
+import { Transform, Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsBoolean, IsIn, IsInt, IsISO8601, IsOptional, IsString, Max, MaxLength, Min } from 'class-validator';
+
+import { ANNOTATION_POSITION_FORMATS, ANNOTATION_STYLES, type AnnotationPositionFormat } from '../annotation.constants';
+
+export class AnnotationHubQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  pageSize?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  bookId?: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(200)
+  search?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  chapter?: string;
+
+  /** Comma-separated hex colors. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(300)
+  colors?: string;
+
+  /** Comma-separated styles. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  styles?: string;
+
+  /** Comma-separated origins (web, koreader, kobo). */
+  @IsOptional()
+  @IsString()
+  @MaxLength(60)
+  origins?: string;
+
+  @IsOptional()
+  @IsISO8601()
+  dateFrom?: string;
+
+  @IsOptional()
+  @IsISO8601()
+  dateTo?: string;
+
+  /** When true, only annotations that carry a note are returned. */
+  @IsOptional()
+  @Transform(({ value }) => (value === 'true' ? true : value === 'false' ? false : value))
+  @IsBoolean()
+  hasNote?: boolean;
+
+  @IsOptional()
+  @IsIn(['active', 'trashed'])
+  status?: 'active' | 'trashed';
+
+  @IsOptional()
+  @IsIn(['createdAt', 'book'])
+  sortBy?: 'createdAt' | 'book';
+
+  @IsOptional()
+  @IsIn(['asc', 'desc'])
+  sortDir?: 'asc' | 'desc';
+}
+
+export class AnnotationHubBooksQueryDto {
+  @IsOptional()
+  @IsIn(['active', 'trashed'])
+  status?: 'active' | 'trashed';
+
+  /** Typeahead term matched against book title and author name. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(200)
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  q?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(50)
+  limit?: number;
+
+  /** A book id whose facet is always included in the response, even outside the limit/search. */
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  selectedId?: number;
+}
+
+export class AnnotationExportQueryDto extends AnnotationHubQueryDto {
+  @IsOptional()
+  @IsIn(['md', 'csv', 'json'])
+  format?: 'md' | 'csv' | 'json';
+}
+
+export class AnnotationBulkDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(500)
+  @Type(() => Number)
+  @IsInt({ each: true })
+  @Min(1, { each: true })
+  ids!: number[];
+
+  @IsIn(['trash', 'restore', 'restyle'])
+  action!: 'trash' | 'restore' | 'restyle';
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  @Transform(({ value }) => (value === '' ? undefined : (value as string)))
+  color?: string;
+
+  @IsOptional()
+  @IsIn(ANNOTATION_STYLES)
+  style?: string;
+}
+
+export class AnnotationPositionRetryDto {
+  @IsIn(ANNOTATION_POSITION_FORMATS)
+  format!: AnnotationPositionFormat;
+}
diff --git a/server/src/modules/annotation/dto/annotation-response.dto.ts b/server/src/modules/annotation/dto/annotation-response.dto.ts
index 034324737..597398d25 100644
--- a/server/src/modules/annotation/dto/annotation-response.dto.ts
+++ b/server/src/modules/annotation/dto/annotation-response.dto.ts
@@ -1,26 +1,37 @@
-import type { AnnotationRow } from '../../../db/schema';
+import type { AnnotationWithCfi } from '../annotation.repository';
 
 export class AnnotationResponseDto {
   id!: number;
   bookId!: number;
-  cfi!: string;
+  cfi!: string | null;
+  jumpFileId!: number | null;
+  pageno!: number | null;
   text!: string;
   color!: string;
   style!: string;
   note!: string | null;
   chapterTitle!: string | null;
+  origin!: string;
+  positionStatus!: string | null;
+  chapterIndex!: number | null;
   createdAt!: Date;
 
-  static from(row: AnnotationRow): AnnotationResponseDto {
+  static from(row: AnnotationWithCfi): AnnotationResponseDto {
     const dto = new AnnotationResponseDto();
     dto.id = row.id;
     dto.bookId = row.bookId;
     dto.cfi = row.cfi;
+    dto.jumpFileId = row.jumpFileId;
+    dto.pageno = row.pageno;
     dto.text = row.text;
     dto.color = row.color;
     dto.style = row.style;
     dto.note = row.note ?? null;
     dto.chapterTitle = row.chapterTitle ?? null;
+    dto.origin = row.origin;
+    dto.positionStatus = row.cfi != null || row.cfiStatus != null ? (row.cfiStatus ?? 'exact') : null;
+    const chapterIndex = (row.cfiExtras as { chapterIndex?: number } | null)?.chapterIndex;
+    dto.chapterIndex = typeof chapterIndex === 'number' ? chapterIndex : null;
     dto.createdAt = row.createdAt;
     return dto;
   }
diff --git a/server/src/modules/annotation/dto/create-annotation.dto.ts b/server/src/modules/annotation/dto/create-annotation.dto.ts
index 61bb3b478..fbcfa8b5e 100644
--- a/server/src/modules/annotation/dto/create-annotation.dto.ts
+++ b/server/src/modules/annotation/dto/create-annotation.dto.ts
@@ -1,4 +1,5 @@
-import { IsIn, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+import { IsIn, IsInt, IsNotEmpty, IsOptional, IsString, MaxLength, Min } from 'class-validator';
+import { Type } from 'class-transformer';
 
 import { ANNOTATION_STYLES } from '../annotation.constants';
 
@@ -8,6 +9,12 @@ export class CreateAnnotationDto {
   @MaxLength(2000)
   cfi!: string;
 
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  bookFileId?: number;
+
   @IsString()
   @IsNotEmpty()
   text!: string;
diff --git a/server/src/modules/architecture/architecture-boundaries.test.ts b/server/src/modules/architecture/architecture-boundaries.test.ts
index 0abaee1c9..ddbed9034 100644
--- a/server/src/modules/architecture/architecture-boundaries.test.ts
+++ b/server/src/modules/architecture/architecture-boundaries.test.ts
@@ -59,6 +59,7 @@ describe('Architecture boundaries', () => {
       'src/modules/kobo/services/kobo-sync.service.ts',
       'src/modules/koreader/koreader-chapter-extractor.service.ts',
       'src/modules/metadata/metadata.service.ts',
+      'src/modules/position-converter/epub-dom.service.ts',
       'src/modules/metadata-preferences/metadata-preferences.service.ts',
       'src/modules/metadata-preferences/provider-config.service.ts',
       'src/modules/migration/planner/matching.service.ts',
diff --git a/server/src/modules/book/book-read.service.ts b/server/src/modules/book/book-read.service.ts
index ba6967a5c..3c6135364 100644
--- a/server/src/modules/book/book-read.service.ts
+++ b/server/src/modules/book/book-read.service.ts
@@ -19,6 +19,10 @@ export class BookReadService {
     return this.bookRepo.findPrimaryFilesByBookIds(bookIds);
   }
 
+  findPrimaryReaderFilesByBookIds(bookIds: number[]) {
+    return this.bookRepo.findPrimaryReaderFilesByBookIds(bookIds);
+  }
+
   findCards(opts: { where: SQL | undefined; orderBy: SQL[]; limit: number; offset: number; userId: number }) {
     return this.bookRepo.findCards(opts);
   }
@@ -43,6 +47,14 @@ export class BookReadService {
     return this.bookRepo.findById(id);
   }
 
+  findProgressByBook(userId: number, bookId: number) {
+    return this.bookRepo.findProgressByBook(userId, bookId);
+  }
+
+  findProgressByBooks(userId: number, bookIds: number[]) {
+    return this.bookRepo.findProgressByBooks(userId, bookIds);
+  }
+
   checkBookPassesContentFilters(bookId: number, contentFilters: import('@bookorbit/types').ContentFilterRules) {
     return this.bookRepo.checkBookPassesContentFilters(bookId, contentFilters);
   }
diff --git a/server/src/modules/book/book.repository.test.ts b/server/src/modules/book/book.repository.test.ts
index d6f589798..f42ac6ac3 100644
--- a/server/src/modules/book/book.repository.test.ts
+++ b/server/src/modules/book/book.repository.test.ts
@@ -810,18 +810,54 @@ describe('BookRepository', () => {
     expect(insertedBookmark).not.toHaveProperty('ContentSourceProgressPercent');
   });
 
-  it('does not overwrite Kobo reading state without an exact KoboSpan location', async () => {
+  it('advances Kobo reading state percent-only without a KoboSpan location, preserving the existing Location', async () => {
     const insertChain = makeInsertChain();
+    const existingState = {
+      entitlementId: 'ent-1',
+      createdAtKobo: '2026-06-01T00:00:00.000Z',
+      currentBookmark: { ProgressPercent: 40, Location: { Source: 'OEBPS/old.xhtml', Type: 'KoboSpan', Value: 'kobo.5.1' } },
+      statistics: null,
+      statusInfo: null,
+    };
     const db = {
-      select: vi.fn().mockReturnValueOnce(makeSelectChain('limit', [{ bookId: 10, primaryFileId: 9, format: 'epub' }])),
+      select: vi
+        .fn()
+        .mockReturnValueOnce(makeSelectChain('limit', [{ bookId: 10, primaryFileId: 9, format: 'epub' }]))
+        .mockReturnValueOnce(makeSelectChain('limit', [existingState])),
       insert: vi.fn().mockReturnValue(insertChain),
       execute: vi.fn().mockResolvedValue(undefined),
     };
     const repo = new BookRepository(db as never);
 
-    await expect(repo.syncKoboReadingStateFromProgress(5, 9, 80, 'OEBPS/ch14.xhtml', null, null, 33.5)).resolves.toBe(false);
+    await expect(repo.syncKoboReadingStateFromProgress(5, 9, 80, 'OEBPS/ch14.xhtml', null, null, 33.5)).resolves.toBe(true);
+
+    expect(db.insert).toHaveBeenCalledTimes(1);
+    const inserted = insertChain.values.mock.calls[0][0] as { currentBookmark: Record<string, unknown> };
+    expect(inserted.currentBookmark.ProgressPercent).toBe(80);
+    expect(inserted.currentBookmark.Location).toEqual({ Source: 'OEBPS/old.xhtml', Type: 'KoboSpan', Value: 'kobo.5.1' });
+    expect(db.execute).toHaveBeenCalled();
+  });
+
+  it('skips the percent-only Kobo reading state write when the bookmark percent is current', async () => {
+    const existingState = {
+      entitlementId: 'ent-1',
+      createdAtKobo: '2026-06-01T00:00:00.000Z',
+      currentBookmark: { ProgressPercent: 80 },
+      statistics: null,
+      statusInfo: null,
+    };
+    const db = {
+      select: vi
+        .fn()
+        .mockReturnValueOnce(makeSelectChain('limit', [{ bookId: 10, primaryFileId: 9, format: 'epub' }]))
+        .mockReturnValueOnce(makeSelectChain('limit', [existingState])),
+      insert: vi.fn(),
+      execute: vi.fn(),
+    };
+    const repo = new BookRepository(db as never);
+
+    await expect(repo.syncKoboReadingStateFromProgress(5, 9, 80, null, null, null, null)).resolves.toBe(true);
 
-    expect(db.select).toHaveBeenCalledTimes(1);
     expect(db.insert).not.toHaveBeenCalled();
     expect(db.execute).not.toHaveBeenCalled();
   });
diff --git a/server/src/modules/book/book.repository.ts b/server/src/modules/book/book.repository.ts
index bb67776f3..59ad2d57d 100644
--- a/server/src/modules/book/book.repository.ts
+++ b/server/src/modules/book/book.repository.ts
@@ -915,6 +915,21 @@ export class BookRepository {
       .orderBy(asc(bookFiles.sortOrder), asc(bookFiles.id));
   }
 
+  async findProgressByBooks(userId: number, bookIds: number[]) {
+    if (bookIds.length === 0) return [];
+    return this.db
+      .select({
+        bookId: bookFiles.bookId,
+        fileId: bookFiles.id,
+        percentage: readingProgress.percentage,
+        koreaderProgress: readingProgress.koreaderProgress,
+        updatedAt: readingProgress.updatedAt,
+      })
+      .from(bookFiles)
+      .innerJoin(readingProgress, and(eq(readingProgress.bookFileId, bookFiles.id), eq(readingProgress.userId, userId)))
+      .where(inArray(bookFiles.bookId, bookIds));
+  }
+
   async findKoboReadingState(userId: number, bookId: number) {
     const [row] = await this.db
       .select({
@@ -1189,6 +1204,25 @@ export class BookRepository {
       .orderBy(asc(books.id));
   }
 
+  async findPrimaryReaderFilesByBookIds(
+    bookIds: number[],
+  ): Promise<{ id: number; bookId: number; absolutePath: string; format: string | null; fileHash: string | null; sizeBytes: number | null }[]> {
+    if (bookIds.length === 0) return [];
+    return this.db
+      .select({
+        id: bookFiles.id,
+        bookId: books.id,
+        absolutePath: bookFiles.absolutePath,
+        format: bookFiles.format,
+        fileHash: bookFiles.fileHash,
+        sizeBytes: bookFiles.sizeBytes,
+      })
+      .from(books)
+      .innerJoin(bookFiles, eq(bookFiles.id, books.primaryFileId))
+      .where(inArray(books.id, bookIds))
+      .orderBy(asc(books.id));
+  }
+
   async findAllFilesByBookIds(
     bookIds: number[],
   ): Promise<{ bookId: number; absolutePath: string; format: string | null; sizeBytes: number | null; sortOrder: number }[]> {
@@ -1423,7 +1457,9 @@ export class BookRepository {
     const normalizedKoboLocationType = this.normalizeKoboLocationPart(koboLocationType);
     const normalizedKoboLocationValue = this.normalizeKoboLocationPart(koboLocationValue);
     const normalizedKoboContentSourceProgressPercent = this.clampNullableProgressPercentage(koboContentSourceProgressPercent);
-    if (!normalizedKoboLocationSource || normalizedKoboLocationType !== 'KoboSpan' || !normalizedKoboLocationValue) return false;
+    // Location values are optional: without them the bookmark advances percent-wise
+    // and the precise KoboSpan Location is computed server-side at delivery time.
+    const hasLocation = Boolean(normalizedKoboLocationSource && normalizedKoboLocationType === 'KoboSpan' && normalizedKoboLocationValue);
 
     const now = new Date();
     const nowIso = now.toISOString();
@@ -1442,6 +1478,7 @@ export class BookRepository {
 
     const existingBookmark = this.asJsonObj(existing?.currentBookmark);
     if (
+      hasLocation &&
       this.isKoboBookmarkCurrent(
         existingBookmark,
         clampedPercentage,
@@ -1453,20 +1490,27 @@ export class BookRepository {
     ) {
       return true;
     }
+    if (!hasLocation && this.isKoboBookmarkPercentCurrent(existingBookmark, clampedPercentage)) {
+      return true;
+    }
 
     const currentBookmark: JsonObj = {
       ...(existingBookmark ?? {}),
       LastModified: nowIso,
       ProgressPercent: clampedPercentage,
-      Location: {
-        Source: normalizedKoboLocationSource,
-        Type: normalizedKoboLocationType,
-        Value: normalizedKoboLocationValue,
-      },
+      ...(hasLocation
+        ? {
+            Location: {
+              Source: normalizedKoboLocationSource,
+              Type: normalizedKoboLocationType,
+              Value: normalizedKoboLocationValue,
+            },
+          }
+        : {}),
     };
-    if (normalizedKoboContentSourceProgressPercent !== null) {
+    if (hasLocation && normalizedKoboContentSourceProgressPercent !== null) {
       currentBookmark.ContentSourceProgressPercent = normalizedKoboContentSourceProgressPercent;
-    } else {
+    } else if (hasLocation) {
       delete currentBookmark.ContentSourceProgressPercent;
     }
     const statusInfo = {
@@ -1606,6 +1650,11 @@ export class BookRepository {
     return Object.keys(bookmark).some((key) => key !== 'LastModified' && key !== 'ProgressPercent');
   }
 
+  private isKoboBookmarkPercentCurrent(bookmark: JsonObj | null, percentage: number): boolean {
+    const existingPercent = this.extractKoboPercent(bookmark);
+    return existingPercent !== null && Math.abs(existingPercent - percentage) < PROGRESS_EPSILON;
+  }
+
   private deriveKoboStatus(percentage: number): string {
     if (percentage >= 100) return 'Finished';
     return percentage > 0 ? 'Reading' : 'ReadyToRead';
diff --git a/server/src/modules/book/book.service.ts b/server/src/modules/book/book.service.ts
index 78659c5ad..0c77ed9a0 100644
--- a/server/src/modules/book/book.service.ts
+++ b/server/src/modules/book/book.service.ts
@@ -1836,6 +1836,16 @@ export class BookService {
       .catch((err: Error) => this.logger.warn(`Auto status update failed for book ${bookId}: ${err.message}`));
   }
 
+  /**
+   * Advances the Kobo bookmark for progress reported by non-web readers (KOReader).
+   * Percent-only: the precise KoboSpan Location is computed at delivery time by the
+   * Kobo reading-state pull path.
+   */
+  async syncKoboReadingStateForExternalProgress(userId: number, fileId: number, percentage: number): Promise<void> {
+    if (!(await this.bookRepo.isKoboTwoWayProgressSyncEnabled(userId))) return;
+    await this.bookRepo.syncKoboReadingStateFromProgress(userId, fileId, percentage, null, null, null, null);
+  }
+
   async saveProgress(userId: number, fileId: number, dto: SaveProgressDto, user: RequestUser) {
     const file = await this.verifyFileAccess(fileId, user);
     await this.bookRepo.upsertProgress(
diff --git a/server/src/modules/dashboard/dashboard-widget.repository.ts b/server/src/modules/dashboard/dashboard-widget.repository.ts
index 1305d927d..251548216 100644
--- a/server/src/modules/dashboard/dashboard-widget.repository.ts
+++ b/server/src/modules/dashboard/dashboard-widget.repository.ts
@@ -449,8 +449,7 @@ export class DashboardWidgetRepository {
           total: sql<number>`floor(coalesce(sum(coalesce(${bookMetadata.pageCount}, 0) * least(greatest(coalesce(${readingSessions.progressDelta}, 0), 0), 100) / 100.0), 0))::int`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
         .innerJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
         .where(
           and(
@@ -468,8 +467,7 @@ export class DashboardWidgetRepository {
           totalProgress: sql<number>`coalesce(sum(least(greatest(coalesce(${readingSessions.progressDelta}, 0), 0), 100)), 0)::float`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
         .innerJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
         .where(
           and(
@@ -743,8 +741,7 @@ export class DashboardWidgetRepository {
           total: sql<number>`sum(${readingSessions.durationSeconds})::int`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
         .where(and(eq(readingSessions.userId, userId), libFilter, presentFilter, ...cfClauses))
         .groupBy(sql`extract(hour from ${readingSessions.startedAt})`)
         .orderBy(desc(sql`sum(${readingSessions.durationSeconds})`))
@@ -755,8 +752,7 @@ export class DashboardWidgetRepository {
           totalSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::float`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
         .innerJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
         .where(
           and(
@@ -779,8 +775,7 @@ export class DashboardWidgetRepository {
           totalSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::float`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
         .innerJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
         .where(
           and(
diff --git a/server/src/modules/kobo/dto/update-settings.dto.ts b/server/src/modules/kobo/dto/update-settings.dto.ts
index 656ca87a5..1521645db 100644
--- a/server/src/modules/kobo/dto/update-settings.dto.ts
+++ b/server/src/modules/kobo/dto/update-settings.dto.ts
@@ -25,6 +25,10 @@ export class UpdateSettingsDto {
   @IsBoolean()
   twoWayProgressSync?: boolean;
 
+  @IsOptional()
+  @IsBoolean()
+  syncBookOrbitAnnotationsToKobo?: boolean;
+
   @IsOptional()
   @IsInt()
   @Min(1)
diff --git a/server/src/modules/kobo/guards/kobo-token.guard.ts b/server/src/modules/kobo/guards/kobo-token.guard.ts
index b136d3e35..3545dd0fd 100644
--- a/server/src/modules/kobo/guards/kobo-token.guard.ts
+++ b/server/src/modules/kobo/guards/kobo-token.guard.ts
@@ -1,5 +1,5 @@
 import { CanActivate, ExecutionContext, Inject, Injectable, UnauthorizedException } from '@nestjs/common';
-import { eq } from 'drizzle-orm';
+import { and, eq, ne } from 'drizzle-orm';
 import type { FastifyRequest } from 'fastify';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
@@ -25,26 +25,36 @@ export class KoboTokenGuard implements CanActivate {
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest<FastifyRequest>();
-    const deviceToken = (request.params as Record<string, string>).deviceToken;
+    const deviceToken = (request.params as Record<string, string | undefined>).deviceToken;
+    const clientDeviceId = this.readHeader(request.headers?.['x-kobo-deviceid']);
 
-    if (!deviceToken) throw new UnauthorizedException('Missing device token');
+    if (!deviceToken && !clientDeviceId) throw new UnauthorizedException('Missing device token');
 
-    const device = await this.db.query.koboDevices.findFirst({
-      where: eq(schema.koboDevices.token, deviceToken),
-    });
+    let device: typeof schema.koboDevices.$inferSelect | undefined;
+    if (deviceToken) {
+      device = await this.db.query.koboDevices.findFirst({
+        where: eq(schema.koboDevices.token, deviceToken),
+      });
+    } else {
+      if (!clientDeviceId) throw new UnauthorizedException('Missing device token');
+      device = await this.db.query.koboDevices.findFirst({
+        where: eq(schema.koboDevices.clientDeviceId, clientDeviceId),
+      });
+    }
 
-    if (!device) throw new UnauthorizedException('Invalid device token');
+    if (!device) throw new UnauthorizedException(deviceToken ? 'Invalid device token' : 'Unknown Kobo device');
 
     const user = await this.userService.findByIdWithPermissions(device.userId);
     if (!user || !user.active) throw new UnauthorizedException('Account not found or disabled');
     if (!this.permissionService.userHas(user, Permission.KoboSync)) throw new UnauthorizedException('Kobo sync permission revoked');
 
-    // Update last seen asynchronously so it doesn't block the request
-    this.db
-      .update(schema.koboDevices)
-      .set({ lastSeenAt: new Date() })
-      .where(eq(schema.koboDevices.id, device.id))
-      .catch(() => undefined);
+    // Tokened calls learn the device's hardware id so token-less Reading Services
+    // calls (no :deviceToken in the path) can be attributed to the same device.
+    if (clientDeviceId) {
+      await this.touchDevice(device.id, clientDeviceId).catch(() => undefined);
+    } else {
+      this.touchDevice(device.id, null).catch(() => undefined);
+    }
 
     (request as unknown as Record<string, unknown>).user = user;
     (request as unknown as Record<string, unknown>).koboDevice = {
@@ -55,4 +65,25 @@ export class KoboTokenGuard implements CanActivate {
 
     return true;
   }
+
+  private async touchDevice(deviceId: number, clientDeviceId: string | null): Promise<void> {
+    if (clientDeviceId) {
+      await this.db
+        .update(schema.koboDevices)
+        .set({ clientDeviceId: null })
+        .where(and(eq(schema.koboDevices.clientDeviceId, clientDeviceId), ne(schema.koboDevices.id, deviceId)));
+    }
+
+    await this.db
+      .update(schema.koboDevices)
+      .set({ lastSeenAt: new Date(), ...(clientDeviceId && { clientDeviceId }) })
+      .where(eq(schema.koboDevices.id, deviceId));
+  }
+
+  private readHeader(value: string | string[] | undefined): string | null {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (!raw) return null;
+    const normalized = raw.trim();
+    return normalized.length > 0 && normalized.length <= 128 ? normalized : null;
+  }
 }
diff --git a/server/src/modules/kobo/kobo-reading-services.controller.ts b/server/src/modules/kobo/kobo-reading-services.controller.ts
new file mode 100644
index 000000000..f4c78b5e4
--- /dev/null
+++ b/server/src/modules/kobo/kobo-reading-services.controller.ts
@@ -0,0 +1,66 @@
+import { Body, Controller, Get, Headers, HttpCode, HttpStatus, Param, Patch, Post, Res, UseGuards, UsePipes, ValidationPipe } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
+
+import { Public } from '../../common/decorators/public.decorator';
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+import type { RequestUser } from '../../common/types/request-user';
+import { KoboDevice } from './decorators/kobo-device.decorator';
+import type { KoboDeviceContext } from './guards/kobo-token.guard';
+import { KoboTokenGuard } from './guards/kobo-token.guard';
+import { KoboAnnotationExchangeService } from './services/kobo-annotation-exchange.service';
+
+@Controller(['kobo/:deviceToken', ''])
+@Public()
+@UseGuards(KoboTokenGuard)
+export class KoboReadingServicesController {
+  constructor(private readonly exchangeService: KoboAnnotationExchangeService) {}
+
+  @Get('api/v3/content/:contentId/annotations')
+  async getAnnotations(
+    @Param('contentId') contentId: string,
+    @Headers('if-none-match') ifNoneMatch: string | undefined,
+    @CurrentUser() user: RequestUser,
+    @KoboDevice() device: KoboDeviceContext,
+    @Res() reply: FastifyReply,
+  ) {
+    const result = await this.exchangeService.getContentAnnotations(user.id, contentId, device.deviceId, ifNoneMatch);
+    reply.header('ETag', result.etag);
+
+    // This Kobo firmware never echoes our ETag back (it always sends If-None-Match: W/"0" and drives
+    // sync via checkforchanges), so the 304 path is never reached. Mark the content seen once the
+    // response is flushed on both 200 and 304, otherwise checkforchanges reports every annotated book
+    // as changed on every sync and the device never converges (downloads run detached and never apply).
+    reply.raw.once('finish', () => {
+      void this.exchangeService.markServedSeen(user.id, device.deviceId, result.servedAck).catch(() => undefined);
+    });
+
+    if (result.notModified) {
+      reply.status(HttpStatus.NOT_MODIFIED).send();
+      return;
+    }
+    reply.send(result.response);
+  }
+
+  @Patch('api/v3/content/:contentId/annotations')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @UsePipes(new ValidationPipe({ transform: false, whitelist: false }))
+  async patchAnnotations(
+    @Param('contentId') contentId: string,
+    @Body() body: unknown,
+    @CurrentUser() user: RequestUser,
+    @KoboDevice() device: KoboDeviceContext,
+  ) {
+    await this.exchangeService.patchContentAnnotations(user.id, contentId, body, device.deviceId);
+  }
+
+  @Post('api/v3/content/checkforchanges')
+  @HttpCode(HttpStatus.OK)
+  async checkForChanges(@CurrentUser() user: RequestUser, @KoboDevice() device: KoboDeviceContext) {
+    return this.exchangeService.getChangedContentIds(user.id, device.deviceId);
+  }
+
+  @Get('api/UserStorage/Metadata')
+  getUserStorageMetadata() {
+    return { continuationToken: null, metadata: [] };
+  }
+}
diff --git a/server/src/modules/kobo/kobo-sync.controller.ts b/server/src/modules/kobo/kobo-sync.controller.ts
index cbd2650d6..6b68fa595 100644
--- a/server/src/modules/kobo/kobo-sync.controller.ts
+++ b/server/src/modules/kobo/kobo-sync.controller.ts
@@ -32,17 +32,21 @@ import { KoboProxyService } from './services/kobo-proxy.service';
 import { KOBO_STORE_RESOURCES } from './kobo-store-resources';
 import { KoboBookIdentityService } from './services/kobo-book-identity.service';
 
+function readHeaderValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
 function buildBaseUrl(req: FastifyRequest): string {
-  const fwdHost = req.headers['x-forwarded-host'];
-  const fwdPort = req.headers['x-forwarded-port'];
-  const fwdProto = req.headers['x-forwarded-proto'];
+  const fwdHost = readHeaderValue(req.headers['x-forwarded-host']);
+  const fwdPort = readHeaderValue(req.headers['x-forwarded-port']);
+  const fwdProto = readHeaderValue(req.headers['x-forwarded-proto']);
   const hasForwarded = fwdHost || fwdPort || fwdProto;
-  const proto = (fwdProto as string | undefined) ?? req.protocol;
-  const headerHost = fwdHost ?? req.headers.host;
-  let host = headerHost ? (Array.isArray(headerHost) ? headerHost[0] : headerHost) : req.hostname;
+  const proto = fwdProto ?? req.protocol;
+  const headerHost = fwdHost ?? readHeaderValue(req.headers.host);
+  let host = headerHost ?? req.hostname;
 
   if (!host.includes(':')) {
-    const port = fwdPort ? (Array.isArray(fwdPort) ? fwdPort[0] : fwdPort) : null;
+    const port = fwdPort ?? null;
     if (port) {
       const isDefault = (proto === 'http' && port === '80') || (proto === 'https' && port === '443');
       if (!isDefault) host = host + ':' + port;
@@ -56,6 +60,19 @@ function buildBaseUrl(req: FastifyRequest): string {
   return proto + '://' + host;
 }
 
+function buildReadingServicesBaseUrl(req: FastifyRequest, baseUrl: string): string {
+  const localPort = req.socket?.localPort;
+  if (!localPort) return baseUrl;
+
+  const url = new URL(baseUrl);
+  if (url.port !== '5173') return baseUrl;
+
+  const proto = readHeaderValue(req.headers['x-forwarded-proto']) ?? req.protocol;
+  url.protocol = proto + ':';
+  url.port = String(localPort);
+  return url.toString().replace(/\/$/, '');
+}
+
 @Controller('kobo/:deviceToken')
 @Public()
 @UseGuards(KoboTokenGuard)
@@ -74,6 +91,7 @@ export class KoboSyncController {
   @Header('x-kobo-apitoken', 'e30=')
   initialization(@KoboDevice() device: KoboDeviceContext, @Req() req: FastifyRequest) {
     const baseUrl = buildBaseUrl(req);
+    const readingServicesBaseUrl = buildReadingServicesBaseUrl(req, baseUrl);
     const t = device.deviceToken;
     return {
       Resources: {
@@ -82,6 +100,7 @@ export class KoboSyncController {
         image_url_template: `${baseUrl}/api/v1/kobo/${t}/v1/books/{ImageId}/thumbnail/{Width}/{Height}/false/image.jpg`,
         image_url_quality_template: `${baseUrl}/api/v1/kobo/${t}/v1/books/{ImageId}/thumbnail/{Width}/{Height}/{Quality}/{IsGreyscale}/image.jpg`,
         library_sync: `${baseUrl}/api/v1/kobo/${t}/v1/library/sync`,
+        reading_services_host: readingServicesBaseUrl,
       },
     };
   }
diff --git a/server/src/modules/kobo/kobo.module.test.ts b/server/src/modules/kobo/kobo.module.test.ts
index 243979c85..c2ccf18c3 100644
--- a/server/src/modules/kobo/kobo.module.test.ts
+++ b/server/src/modules/kobo/kobo.module.test.ts
@@ -5,15 +5,20 @@ import { MODULE_METADATA } from '@nestjs/common/constants';
 import { KoboAuthController } from './kobo-auth.controller';
 import { KoboDeviceController } from './kobo-device.controller';
 import { KoboModule } from './kobo.module';
+import { KoboReadingServicesController } from './kobo-reading-services.controller';
 import { KoboSyncController } from './kobo-sync.controller';
 import { KoboUserController } from './kobo-user.controller';
 import { KoboTokenGuard } from './guards/kobo-token.guard';
 import { KepubConversionService } from './services/kepub-conversion.service';
 import { KepubifyBinaryService } from './services/kepubify-binary.service';
+import { KoboAnnotationExchangeService } from './services/kobo-annotation-exchange.service';
+import { KoboAnnotationMaterializerService } from './services/kobo-annotation-materializer.service';
 import { KoboBookAccessService } from './services/kobo-book-access.service';
 import { KoboBookIdentityService } from './services/kobo-book-identity.service';
 import { KoboDeviceService } from './services/kobo-device.service';
 import { KoboDownloadService } from './services/kobo-download.service';
+import { KoboKepubContextService } from './services/kobo-kepub-context.service';
+import { KoboProgressBridgeService } from './services/kobo-progress-bridge.service';
 import { KoboProxyService } from './services/kobo-proxy.service';
 import { KoboReadingStateService } from './services/kobo-reading-state.service';
 import { KoboSettingsService } from './services/kobo-settings.service';
@@ -21,7 +26,9 @@ import { KoboSyncService } from './services/kobo-sync.service';
 import { KoboThumbnailService } from './services/kobo-thumbnail.service';
 import { KoboAnalyticsResolverService } from './services/kobo-analytics-resolver.service';
 import { KoboAnalyticsService } from './services/kobo-analytics.service';
+import { AnnotationModule } from '../annotation/annotation.module';
 import { BookModule } from '../book/book.module';
+import { PositionConverterModule } from '../position-converter/position-converter.module';
 import { ReadingSessionModule } from '../reading-session/reading-session.module';
 
 describe('KoboModule', () => {
@@ -32,7 +39,9 @@ describe('KoboModule', () => {
 
     expect(imports).toContain(BookModule);
     expect(imports).toContain(ReadingSessionModule);
-    expect(controllers).toEqual([KoboUserController, KoboAuthController, KoboSyncController, KoboDeviceController]);
+    expect(imports).toContain(AnnotationModule);
+    expect(imports).toContain(PositionConverterModule);
+    expect(controllers).toEqual([KoboUserController, KoboAuthController, KoboSyncController, KoboDeviceController, KoboReadingServicesController]);
     expect(providers).toEqual([
       KoboTokenGuard,
       KepubifyBinaryService,
@@ -42,6 +51,10 @@ describe('KoboModule', () => {
       KoboBookAccessService,
       KoboSyncService,
       KoboBookIdentityService,
+      KoboKepubContextService,
+      KoboProgressBridgeService,
+      KoboAnnotationMaterializerService,
+      KoboAnnotationExchangeService,
       KoboReadingStateService,
       KoboThumbnailService,
       KoboDownloadService,
diff --git a/server/src/modules/kobo/kobo.module.ts b/server/src/modules/kobo/kobo.module.ts
index 8d2b8e068..8f53c94ad 100644
--- a/server/src/modules/kobo/kobo.module.ts
+++ b/server/src/modules/kobo/kobo.module.ts
@@ -2,20 +2,27 @@ import { Module } from '@nestjs/common';
 
 import { CommonModule } from '../../common/common.module';
 import { AchievementModule } from '../achievement/achievement.module';
+import { AnnotationModule } from '../annotation/annotation.module';
 import { BookModule } from '../book/book.module';
+import { PositionConverterModule } from '../position-converter/position-converter.module';
 import { ReadingSessionModule } from '../reading-session/reading-session.module';
 import { UserModule } from '../user/user.module';
 import { UserBookStatusModule } from '../user-book-status/user-book-status.module';
 import { KoboAuthController } from './kobo-auth.controller';
 import { KoboDeviceController } from './kobo-device.controller';
+import { KoboReadingServicesController } from './kobo-reading-services.controller';
 import { KoboSyncController } from './kobo-sync.controller';
 import { KoboUserController } from './kobo-user.controller';
 import { KoboTokenGuard } from './guards/kobo-token.guard';
 import { KepubConversionService } from './services/kepub-conversion.service';
 import { KoboBookAccessService } from './services/kobo-book-access.service';
 import { KepubifyBinaryService } from './services/kepubify-binary.service';
+import { KoboAnnotationExchangeService } from './services/kobo-annotation-exchange.service';
+import { KoboAnnotationMaterializerService } from './services/kobo-annotation-materializer.service';
 import { KoboDeviceService } from './services/kobo-device.service';
 import { KoboDownloadService } from './services/kobo-download.service';
+import { KoboKepubContextService } from './services/kobo-kepub-context.service';
+import { KoboProgressBridgeService } from './services/kobo-progress-bridge.service';
 import { KoboProxyService } from './services/kobo-proxy.service';
 import { KoboBookIdentityService } from './services/kobo-book-identity.service';
 import { KoboReadingStateService } from './services/kobo-reading-state.service';
@@ -26,8 +33,17 @@ import { KoboAnalyticsResolverService } from './services/kobo-analytics-resolver
 import { KoboAnalyticsService } from './services/kobo-analytics.service';
 
 @Module({
-  imports: [CommonModule, AchievementModule, BookModule, UserModule, UserBookStatusModule, ReadingSessionModule],
-  controllers: [KoboUserController, KoboAuthController, KoboSyncController, KoboDeviceController],
+  imports: [
+    CommonModule,
+    AchievementModule,
+    AnnotationModule,
+    BookModule,
+    PositionConverterModule,
+    UserModule,
+    UserBookStatusModule,
+    ReadingSessionModule,
+  ],
+  controllers: [KoboUserController, KoboAuthController, KoboSyncController, KoboDeviceController, KoboReadingServicesController],
   providers: [
     KoboTokenGuard,
     KepubifyBinaryService,
@@ -37,6 +53,10 @@ import { KoboAnalyticsService } from './services/kobo-analytics.service';
     KoboBookAccessService,
     KoboSyncService,
     KoboBookIdentityService,
+    KoboKepubContextService,
+    KoboProgressBridgeService,
+    KoboAnnotationMaterializerService,
+    KoboAnnotationExchangeService,
     KoboReadingStateService,
     KoboThumbnailService,
     KoboDownloadService,
diff --git a/server/src/modules/kobo/services/kepubify-binary.service.ts b/server/src/modules/kobo/services/kepubify-binary.service.ts
index 17b084486..6c1fd600c 100644
--- a/server/src/modules/kobo/services/kepubify-binary.service.ts
+++ b/server/src/modules/kobo/services/kepubify-binary.service.ts
@@ -1,12 +1,18 @@
+import { execFile } from 'child_process';
 import { chmod, stat } from 'fs/promises';
 import { join } from 'path';
+import { promisify } from 'util';
 
 import { Injectable } from '@nestjs/common';
 
+const execFileAsync = promisify(execFile);
+const VERSION_TIMEOUT_MS = 5_000;
+
 @Injectable()
 export class KepubifyBinaryService {
   private readonly bundledBinDir = join(process.cwd(), 'bin', 'kepubify');
   private cachedBinaryPath: string | null = null;
+  private cachedVersion: string | null = null;
 
   async getBinaryPath(): Promise<string> {
     if (this.cachedBinaryPath) return this.cachedBinaryPath;
@@ -16,6 +22,24 @@ export class KepubifyBinaryService {
     return binaryPath;
   }
 
+  /** Reported binary version (e.g. "v4-dev"), or "unknown" when the probe fails. */
+  async getVersion(): Promise<string> {
+    if (this.cachedVersion) return this.cachedVersion;
+    try {
+      const binaryPath = await this.getBinaryPath();
+      const { stdout } = await execFileAsync(binaryPath, ['--version'], { timeout: VERSION_TIMEOUT_MS });
+      const version = stdout
+        .trim()
+        .split('\n')[0]
+        ?.replace(/^kepubify\s+/i, '')
+        .trim();
+      this.cachedVersion = version || 'unknown';
+    } catch {
+      this.cachedVersion = 'unknown';
+    }
+    return this.cachedVersion;
+  }
+
   private async resolveBinaryPath(binaryName: string): Promise<string> {
     const bundledPath = join(this.bundledBinDir, binaryName);
     await stat(bundledPath);
diff --git a/server/src/modules/kobo/services/kobo-analytics.service.test.ts b/server/src/modules/kobo/services/kobo-analytics.service.test.ts
index fbc551f12..d4b1bd994 100644
--- a/server/src/modules/kobo/services/kobo-analytics.service.test.ts
+++ b/server/src/modules/kobo/services/kobo-analytics.service.test.ts
@@ -91,6 +91,26 @@ describe('KoboAnalyticsService', () => {
     );
   });
 
+  it('tags Kobo reading sessions with the kobo source', async () => {
+    await makeService().ingest(
+      {
+        Events: [
+          {
+            Id: 'kobo-src',
+            EventType: 'LeaveContent',
+            Timestamp: '2026-06-01T00:00:20Z',
+            Metrics: { SecondsRead: 20 },
+            Attributes: { volumeid: '1', progress: '5' },
+          },
+        ],
+      },
+      user,
+      device,
+    );
+
+    expect(readingSessionService.save).toHaveBeenCalledWith(100, expect.objectContaining({ sessionId: 'kobo-src' }), user, 'kobo');
+  });
+
   it('pairs OpenContent and LeaveContent to save progress delta and active duration', async () => {
     await makeService().ingest(
       {
diff --git a/server/src/modules/kobo/services/kobo-annotation-exchange.service.ts b/server/src/modules/kobo/services/kobo-annotation-exchange.service.ts
new file mode 100644
index 000000000..4035e0be8
--- /dev/null
+++ b/server/src/modules/kobo/services/kobo-annotation-exchange.service.ts
@@ -0,0 +1,289 @@
+import { randomUUID } from 'crypto';
+
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
+
+import type { AnnotationPosition, AnnotationRow, AnnotationSyncStateRow } from '../../../db/schema';
+import { sanitizeLogValue } from '../../../common/utils/log-sanitize.utils';
+import { AnnotationSyncService, formatDeviceDatetime, type IncomingDeviceAnnotation } from '../../annotation/annotation-sync.service';
+import { KoboSpanConverterService, serializeKoboSpanPos } from '../../position-converter/kobo-span-converter.service';
+import { parseSpanSelector } from '../../position-converter/kobo-span.core';
+import { KoboBookIdentityService } from './kobo-book-identity.service';
+import { KoboAnnotationMaterializerService } from './kobo-annotation-materializer.service';
+import { KoboKepubContextService } from './kobo-kepub-context.service';
+import { KoboSettingsService } from './kobo-settings.service';
+import {
+  extractKoboAnnotationOperations,
+  toKoboReadingServiceAnnotation,
+  type IncomingUpsert,
+  type KoboReadingServiceAnnotationsResponse,
+  type ServeAnnotation,
+} from './kobo-annotation-payload';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const GET_EVENT = 'kobo.annotation_get';
+const PATCH_EVENT = 'kobo.annotation_patch';
+
+export interface ServedAckPlan {
+  entries: { annotationId: number; version: number; externalKey: string; externalCreatedAt: string | null }[];
+  tombstoneStateIds: number[];
+}
+
+export interface KoboContentAnnotationsResult {
+  etag: string;
+  notModified: boolean;
+  response?: KoboReadingServiceAnnotationsResponse;
+  servedAck: ServedAckPlan;
+}
+
+@Injectable()
+export class KoboAnnotationExchangeService {
+  private readonly logger = new Logger(KoboAnnotationExchangeService.name);
+
+  constructor(
+    private readonly annotationSync: AnnotationSyncService,
+    private readonly bookIdentityService: KoboBookIdentityService,
+    private readonly kepubContextService: KoboKepubContextService,
+    private readonly materializer: KoboAnnotationMaterializerService,
+    private readonly koboSpanConverter: KoboSpanConverterService,
+    private readonly settingsService: KoboSettingsService,
+  ) {}
+
+  async getContentAnnotations(
+    userId: number,
+    contentId: string,
+    deviceId: number,
+    ifNoneMatch: string | undefined,
+  ): Promise<KoboContentAnnotationsResult> {
+    const startedAtMs = Date.now();
+    const bookId = await this.resolveBookIdByContentId(userId, contentId);
+    if (bookId === null) throw new NotFoundException(`Kobo content ${contentId} not found`);
+
+    const kepub = await this.kepubContextService.resolveForBook(userId, bookId);
+    const includeAllOrigins = kepub.settings?.syncBookOrbitAnnotationsToKobo ?? false;
+    if (kepub.ok) {
+      await this.materializer.ensureKoboSpanPositionsForBook(userId, bookId, kepub.file, kepub.ctx, { includeAllOrigins });
+    }
+
+    const annotations = await this.annotationSync.listActiveForBook(userId, bookId);
+    const stateRows = await this.annotationSync.listStatesBySourceForBook(userId, 'kobo', bookId);
+    const externalKeyByAnnotation = this.pickStableExternalKeys(stateRows);
+
+    const positions = new Map<number, AnnotationPosition>();
+    for (const row of await this.annotationSync.findPositions(
+      annotations.map((annotation) => annotation.id),
+      ['kobo_span'],
+    )) {
+      positions.set(row.annotationId, row);
+    }
+
+    const served: ServeAnnotation[] = [];
+    const ackEntries: ServedAckPlan['entries'] = [];
+    let skippedNoLocation = 0;
+
+    for (const annotation of annotations) {
+      const known = externalKeyByAnnotation.get(annotation.id);
+      if (!known && !includeAllOrigins) continue;
+
+      const position = positions.get(annotation.id);
+      const location = this.usableLocation(position);
+      if (!location) {
+        if (known || includeAllOrigins) skippedNoLocation += 1;
+        continue;
+      }
+
+      const externalKey = known?.externalKey ?? (await this.annotationSync.ensureExternalKey(annotation.id, 'kobo', () => randomUUID()));
+      const deviceCreatedAt = await this.annotationSync.ensureDeviceCreatedAt(userId, bookId, annotation);
+      served.push({
+        externalKey,
+        clientLastModifiedUtc: toIsoUtc(annotation.deviceUpdatedAt ?? deviceCreatedAt),
+        colorHex: annotation.color,
+        text: annotation.text,
+        note: annotation.note,
+        hasNote: annotation.note != null && annotation.note !== '',
+        location,
+      });
+      ackEntries.push({
+        annotationId: annotation.id,
+        version: annotation.version,
+        externalKey,
+        externalCreatedAt: known?.externalCreatedAt ?? deviceCreatedAt,
+      });
+    }
+
+    // Deletions propagate by omission: the device reconciles its local annotations
+    // against the active set returned here, removing anything absent. Tombstone
+    // flags do not work - the device keeps any annotation still present in the
+    // response and ignores deleted markers.
+    const tombstones = await this.annotationSync.listDeleteCandidates(userId, 'kobo', String(deviceId), bookId, 500);
+    const servedAck: ServedAckPlan = { entries: ackEntries, tombstoneStateIds: tombstones.map((row) => row.state.id) };
+
+    const etag = this.buildEtag(served.length, ackEntries);
+    const notModified = this.etagMatches(ifNoneMatch, etag);
+
+    this.logger.log(
+      `[${GET_EVENT}] [end] userId=${userId} bookId=${bookId} deviceId=${deviceId} durationMs=${Date.now() - startedAtMs} served=${served.length} tombstones=${servedAck.tombstoneStateIds.length} skippedNoLocation=${skippedNoLocation} notModified=${notModified} - kobo annotations served`,
+    );
+
+    if (notModified) return { etag, notModified: true, servedAck };
+    return {
+      etag,
+      notModified: false,
+      servedAck,
+      response: {
+        annotations: served.map((row) => toKoboReadingServiceAnnotation(row)),
+        nextPageOffsetToken: null,
+      },
+    };
+  }
+
+  /** Called on response flush; the only place served versions and tombstones get acked. */
+  async markServedSeen(userId: number, deviceId: number, ack: ServedAckPlan): Promise<void> {
+    await this.annotationSync.markServedApplied({
+      userId,
+      source: 'kobo',
+      deviceId: String(deviceId),
+      entries: ack.entries,
+      tombstoneStateIds: ack.tombstoneStateIds,
+    });
+  }
+
+  async patchContentAnnotations(userId: number, contentId: string, body: unknown, deviceId: number): Promise<void> {
+    const startedAtMs = Date.now();
+    const bookId = await this.resolveBookIdByContentId(userId, contentId);
+    if (bookId === null) throw new NotFoundException(`Kobo content ${contentId} not found`);
+
+    const operations = extractKoboAnnotationOperations(body);
+    if (operations.length === 0) return;
+
+    const upserts = operations.filter((operation): operation is IncomingUpsert => operation.kind === 'upsert');
+    const deletes = operations.filter((operation) => operation.kind === 'delete');
+
+    const file = await this.kepubContextService.resolveReaderFile(bookId);
+    if (!file) throw new NotFoundException(`Kobo content ${contentId} has no reader file`);
+    const kepub = await this.kepubContextService.resolveForBook(userId, bookId);
+
+    const incoming = upserts.map((operation) => this.toIncomingAnnotation(operation));
+    const result = await this.annotationSync.ingestDeviceAnnotations({
+      userId,
+      source: 'kobo',
+      deviceId: String(deviceId),
+      bookId,
+      bookFileId: file.id,
+      annotations: incoming,
+    });
+
+    const deletedCount = await this.annotationSync.applyDeviceDeletes({
+      userId,
+      source: 'kobo',
+      deviceId: String(deviceId),
+      bookId,
+      deletes: deletes.map((operation) => ({ externalKey: operation.id })),
+    });
+
+    if (kepub.ok && upserts.length > 0) {
+      await this.materializer.convertIncomingForBook(
+        userId,
+        bookId,
+        kepub.file,
+        kepub.ctx,
+        upserts.map((operation) => operation.id),
+      );
+    }
+
+    this.logger.log(
+      `[${PATCH_EVENT}] [end] userId=${userId} bookId=${bookId} deviceId=${deviceId} durationMs=${Date.now() - startedAtMs} created=${result.created} updated=${result.updated} unchanged=${result.unchanged} deleted=${deletedCount} kepubReady=${kepub.ok} - kobo annotation operations applied`,
+    );
+  }
+
+  async getChangedContentIds(userId: number, deviceId: number): Promise<string[]> {
+    const settings = await this.settingsService.getSettings(userId);
+    const bookIds = await this.annotationSync.listPendingKoboChangeBookIds(userId, String(deviceId), {
+      includeAllOrigins: settings.syncBookOrbitAnnotationsToKobo,
+      resolverVersion: this.koboSpanConverter.version,
+    });
+    if (bookIds.length === 0) return [];
+    const identities = await this.bookIdentityService.findByBookIds(userId, bookIds);
+    return [...identities.values()].map((identity) => identity.entitlementId);
+  }
+
+  private toIncomingAnnotation(operation: IncomingUpsert): IncomingDeviceAnnotation {
+    const datetime = formatDeviceDatetime(operation.clientModifiedAt);
+    const span = this.parseLocationSpans(operation.location);
+    return {
+      externalKey: operation.id,
+      datetime,
+      datetimeUpdated: datetime,
+      color: operation.color,
+      colorSpace: 'kobo',
+      style: 'highlight',
+      text: operation.text,
+      note: operation.note,
+      chapter: operation.chapterTitle,
+      posFormat: 'kobo_span',
+      pos0: span?.pos0 ?? 'invalid:0',
+      pos1: span?.pos1 ?? null,
+      posExtras: { koboLocation: operation.location },
+    };
+  }
+
+  private parseLocationSpans(location: unknown): { pos0: string; pos1: string } | null {
+    if (!location || typeof location !== 'object') return null;
+    const span = (location as Record<string, unknown>).span;
+    if (!span || typeof span !== 'object') return null;
+    const raw = span as Record<string, unknown>;
+    if (typeof raw.startPath !== 'string' || typeof raw.endPath !== 'string') return null;
+    const startId = parseSpanSelector(raw.startPath);
+    const endId = parseSpanSelector(raw.endPath);
+    const startChar = typeof raw.startChar === 'number' && Number.isInteger(raw.startChar) && raw.startChar >= 0 ? raw.startChar : null;
+    const endChar = typeof raw.endChar === 'number' && Number.isInteger(raw.endChar) && raw.endChar >= 0 ? raw.endChar : null;
+    if (!startId || !endId || startChar == null || endChar == null) return null;
+    return { pos0: serializeKoboSpanPos(startId, startChar), pos1: serializeKoboSpanPos(endId, endChar) };
+  }
+
+  private usableLocation(position: AnnotationPosition | undefined): unknown | null {
+    if (!position || position.status === 'failed' || position.status === 'pending') return null;
+    const location = (position.extras as { koboLocation?: unknown } | null)?.koboLocation;
+    return location ?? null;
+  }
+
+  private pickStableExternalKeys(
+    stateRows: { state: AnnotationSyncStateRow; annotation: AnnotationRow }[],
+  ): Map<number, { externalKey: string; externalCreatedAt: string | null }> {
+    const byAnnotation = new Map<number, { stateId: number; externalKey: string; externalCreatedAt: string | null }>();
+    for (const { state } of stateRows) {
+      const existing = byAnnotation.get(state.annotationId);
+      if (!existing || state.id < existing.stateId) {
+        byAnnotation.set(state.annotationId, { stateId: state.id, externalKey: state.externalKey, externalCreatedAt: state.externalCreatedAt });
+      }
+    }
+    return new Map([...byAnnotation.entries()].map(([annotationId, entry]) => [annotationId, entry]));
+  }
+
+  private async resolveBookIdByContentId(userId: number, contentId: string): Promise<number | null> {
+    if (!UUID_RE.test(contentId)) return null;
+    try {
+      return await this.bookIdentityService.resolveBookIdByEntitlementId(userId, contentId);
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(`[${GET_EVENT}] [fail] contentId=${sanitizeLogValue(contentId)} errorClass=${errorClass} - kobo content resolution failed`);
+      return null;
+    }
+  }
+
+  private buildEtag(count: number, entries: ServedAckPlan['entries']): string {
+    const maxVersion = entries.reduce((max, entry) => Math.max(max, entry.version), 0);
+    return `W/"${maxVersion}-${count}"`;
+  }
+
+  private etagMatches(ifNoneMatch: string | undefined, etag: string): boolean {
+    if (!ifNoneMatch) return false;
+    return ifNoneMatch
+      .split(',')
+      .map((value) => value.trim())
+      .some((value) => value === etag);
+  }
+}
+
+function toIsoUtc(deviceDatetime: string): string {
+  return `${deviceDatetime.replace(' ', 'T')}Z`;
+}
diff --git a/server/src/modules/kobo/services/kobo-annotation-materializer.service.ts b/server/src/modules/kobo/services/kobo-annotation-materializer.service.ts
new file mode 100644
index 000000000..dcab8285f
--- /dev/null
+++ b/server/src/modules/kobo/services/kobo-annotation-materializer.service.ts
@@ -0,0 +1,332 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import type { AnnotationPosition, AnnotationRow } from '../../../db/schema';
+import { sanitizeLogValue } from '../../../common/utils/log-sanitize.utils';
+import { AnnotationSyncService } from '../../annotation/annotation-sync.service';
+import { KepubContext, KoboSpanConverterService } from '../../position-converter/kobo-span-converter.service';
+import { PositionConverterService } from '../../position-converter/position-converter.service';
+import type { KepubReaderFile } from './kobo-kepub-context.service';
+
+const MATERIALIZE_EVENT = 'kobo.annotation_materialize';
+const CONVERT_EVENT = 'kobo.annotation_convert_incoming';
+const DEFAULT_LIMIT = 200;
+
+interface PositionsByFormat {
+  koboSpan?: AnnotationPosition;
+  cfi?: AnnotationPosition;
+  xpointer?: AnnotationPosition;
+}
+
+/**
+ * Lazily materializes kobo_span positions for hub annotations when a Kobo device
+ * syncs a book (the kepub artifact exists by then), and conversely converts freshly
+ * uploaded Kobo positions to canonical cfi+xpointer. Mirrors the cfi backfill
+ * pattern of AnnotationConversionService.
+ */
+@Injectable()
+export class KoboAnnotationMaterializerService {
+  private readonly logger = new Logger(KoboAnnotationMaterializerService.name);
+
+  constructor(
+    private readonly annotationSync: AnnotationSyncService,
+    private readonly koboSpanConverter: KoboSpanConverterService,
+    private readonly positionConverter: PositionConverterService,
+  ) {}
+
+  /** Computes kobo_span positions for serve-scope annotations that lack a current one. */
+  async ensureKoboSpanPositionsForBook(
+    userId: number,
+    bookId: number,
+    file: KepubReaderFile,
+    ctx: KepubContext,
+    opts: { includeAllOrigins: boolean; limit?: number },
+  ): Promise<{ generated: number; failed: number }> {
+    const startedAtMs = Date.now();
+    const result = { generated: 0, failed: 0 };
+    try {
+      const renditionHash = await this.koboSpanConverter.computeRenditionHash(ctx);
+      const annotations = await this.annotationSync.listActiveForBook(userId, bookId);
+      if (annotations.length === 0) return result;
+
+      const koboKnownIds = new Set(
+        (await this.annotationSync.listStatesBySourceForBook(userId, 'kobo', bookId)).map((row) => row.state.annotationId),
+      );
+      const scope = opts.includeAllOrigins ? annotations : annotations.filter((annotation) => koboKnownIds.has(annotation.id));
+      if (scope.length === 0) return result;
+
+      const positions = this.groupPositions(
+        await this.annotationSync.findPositions(
+          scope.map((annotation) => annotation.id),
+          ['kobo_span', 'cfi', 'xpointer'],
+        ),
+      );
+
+      const candidates = scope.filter((annotation) => this.needsMaterialization(positions.get(annotation.id)?.koboSpan, renditionHash));
+      const limit = opts.limit ?? DEFAULT_LIMIT;
+      for (const annotation of candidates.slice(0, limit)) {
+        const outcome = await this.materializeOne(userId, annotation, positions.get(annotation.id) ?? {}, file, ctx);
+        result[outcome ? 'generated' : 'failed'] += 1;
+      }
+
+      if (result.generated > 0 || result.failed > 0) {
+        this.logger.log(
+          `[${MATERIALIZE_EVENT}] [end] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} generated=${result.generated} failed=${result.failed} candidates=${candidates.length} - kobo span positions materialized`,
+        );
+      }
+      return result;
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${MATERIALIZE_EVENT}] [fail] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - kobo span materialization failed`,
+      );
+      return result;
+    }
+  }
+
+  /** Converts freshly ingested Kobo positions (by external key) to cfi + xpointer. */
+  async convertIncomingForBook(userId: number, bookId: number, file: KepubReaderFile, ctx: KepubContext, externalKeys: string[]): Promise<void> {
+    if (externalKeys.length === 0) return;
+    const startedAtMs = Date.now();
+    try {
+      const wanted = new Set(externalKeys);
+      const states = (await this.annotationSync.listStatesBySourceForBook(userId, 'kobo', bookId)).filter(
+        (row) => wanted.has(row.state.externalKey) && row.annotation.deletedAt === null,
+      );
+      if (states.length === 0) return;
+
+      const positions = this.groupPositions(
+        await this.annotationSync.findPositions(
+          states.map((row) => row.annotation.id),
+          ['kobo_span', 'cfi', 'xpointer'],
+        ),
+      );
+
+      let converted = 0;
+      let failed = 0;
+      for (const { annotation } of states) {
+        const formats = positions.get(annotation.id);
+        const koboSpan = formats?.koboSpan;
+        if (!koboSpan?.pos0) continue;
+        if (!this.needsCanonical(formats?.cfi) && !this.needsCanonical(formats?.xpointer)) continue;
+
+        const location = (koboSpan.extras as { koboLocation?: unknown } | null)?.koboLocation;
+        const outcome = await this.koboSpanConverter.koboSpanToCanonical({
+          bookFileId: file.id,
+          ctx,
+          location,
+          text: annotation.text || null,
+        });
+
+        // The device's own position belongs to the current rendition by definition;
+        // stamping the hash keeps the materializer from re-synthesizing the verbatim
+        // location the device uploaded.
+        if (outcome.renditionHash) {
+          await this.annotationSync.upsertGeneratedPosition({
+            annotationId: annotation.id,
+            userId,
+            bookFileId: file.id,
+            format: 'kobo_span',
+            pos0: koboSpan.pos0,
+            pos1: koboSpan.pos1,
+            status: koboSpan.status as 'exact' | 'repaired' | 'failed' | 'pending',
+            converterVersion: this.koboSpanConverter.version,
+            extras: { ...(koboSpan.extras ?? {}), chapterIndex: outcome.chapterIndex, renditionHash: outcome.renditionHash },
+          });
+        }
+
+        if (outcome.status === 'failed' || !outcome.cfi || !outcome.xpointerPos0) {
+          failed += 1;
+          await this.storeFailure(userId, annotation.id, file.id, 'cfi', outcome.chapterIndex ?? null, outcome.reason ?? 'conversion_failed');
+          await this.storeFailure(userId, annotation.id, file.id, 'xpointer', outcome.chapterIndex ?? null, outcome.reason ?? 'conversion_failed');
+          continue;
+        }
+
+        converted += 1;
+        await this.annotationSync.upsertGeneratedPosition({
+          annotationId: annotation.id,
+          userId,
+          bookFileId: file.id,
+          format: 'cfi',
+          pos0: outcome.cfi,
+          pos1: null,
+          status: outcome.status,
+          converterVersion: this.positionConverter.version,
+          extras: { chapterIndex: outcome.chapterIndex },
+        });
+        await this.annotationSync.upsertGeneratedPosition({
+          annotationId: annotation.id,
+          userId,
+          bookFileId: file.id,
+          format: 'xpointer',
+          pos0: outcome.xpointerPos0,
+          pos1: outcome.xpointerPos1 ?? null,
+          status: outcome.status,
+          converterVersion: this.positionConverter.version,
+          extras: { chapterIndex: outcome.chapterIndex },
+        });
+      }
+
+      if (converted > 0 || failed > 0) {
+        this.logger.log(
+          `[${CONVERT_EVENT}] [end] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} converted=${converted} failed=${failed} - incoming kobo positions converted`,
+        );
+      }
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${CONVERT_EVENT}] [fail] userId=${userId} bookId=${bookId} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - incoming kobo position conversion failed`,
+      );
+    }
+  }
+
+  private async materializeOne(
+    userId: number,
+    annotation: AnnotationRow,
+    formats: PositionsByFormat,
+    file: KepubReaderFile,
+    ctx: KepubContext,
+  ): Promise<boolean> {
+    const cfi = await this.resolveSourceCfi(userId, annotation, formats, file);
+    if (!cfi) {
+      await this.storeKoboSpanFailure(userId, annotation.id, file.id, ctx, 'no_source_position');
+      return false;
+    }
+
+    const outcome = await this.koboSpanConverter.canonicalToKoboSpan({
+      bookFileId: file.id,
+      ctx,
+      cfi,
+      text: annotation.text || null,
+      chapterTitle: annotation.chapterTitle,
+    });
+
+    if (outcome.status === 'failed' || !outcome.pos0 || !outcome.pos1 || !outcome.location) {
+      await this.storeKoboSpanFailure(userId, annotation.id, file.id, ctx, outcome.reason ?? 'conversion_failed', outcome.chapterIndex ?? null);
+      return false;
+    }
+
+    await this.annotationSync.upsertGeneratedPosition({
+      annotationId: annotation.id,
+      userId,
+      bookFileId: file.id,
+      format: 'kobo_span',
+      pos0: outcome.pos0,
+      pos1: outcome.pos1,
+      status: outcome.status,
+      converterVersion: this.koboSpanConverter.version,
+      extras: {
+        chapterIndex: outcome.chapterIndex,
+        chapterFilename: outcome.location.span.chapterFilename,
+        chapterProgress: outcome.location.span.chapterProgress,
+        renditionHash: outcome.renditionHash,
+        koboLocation: outcome.location,
+      },
+    });
+    return true;
+  }
+
+  /** Source CFI for projection: the stored cfi row, else a fresh xpointer conversion. */
+  private async resolveSourceCfi(
+    userId: number,
+    annotation: AnnotationRow,
+    formats: PositionsByFormat,
+    file: KepubReaderFile,
+  ): Promise<string | null> {
+    const cfiRow = formats.cfi;
+    if (cfiRow?.pos0 && cfiRow.status !== 'failed' && cfiRow.status !== 'pending') return cfiRow.pos0;
+
+    const xpointer = formats.xpointer;
+    if (!xpointer?.pos0 || xpointer.status === 'failed') return null;
+
+    const outcome = await this.positionConverter.xpointerToCfi({
+      bookFileId: xpointer.bookFileId ?? file.id,
+      pos0: xpointer.pos0,
+      pos1: xpointer.pos1,
+      text: annotation.text || null,
+    });
+    if (outcome.status === 'failed' || !outcome.cfi) return null;
+
+    await this.annotationSync.upsertGeneratedPosition({
+      annotationId: annotation.id,
+      userId,
+      bookFileId: xpointer.bookFileId ?? file.id,
+      format: 'cfi',
+      pos0: outcome.cfi,
+      pos1: null,
+      status: outcome.status,
+      converterVersion: this.positionConverter.version,
+      extras: { chapterIndex: outcome.chapterIndex },
+    });
+    return outcome.cfi;
+  }
+
+  private needsMaterialization(koboSpan: AnnotationPosition | undefined, renditionHash: string | null): boolean {
+    if (!koboSpan) return true;
+    if (koboSpan.status === 'pending') return true;
+    const extras = koboSpan.extras as { renditionHash?: string } | null;
+    if (renditionHash && extras?.renditionHash !== renditionHash) return true;
+    if (koboSpan.converterVersion != null && koboSpan.converterVersion < this.koboSpanConverter.version) return true;
+    return false;
+  }
+
+  private needsCanonical(position: AnnotationPosition | undefined): boolean {
+    if (!position) return true;
+    if (position.status === 'pending') return true;
+    return position.converterVersion != null && position.converterVersion < this.positionConverter.version;
+  }
+
+  private async storeKoboSpanFailure(
+    userId: number,
+    annotationId: number,
+    bookFileId: number,
+    ctx: KepubContext,
+    reason: string,
+    chapterIndex: number | null = null,
+  ): Promise<void> {
+    const renditionHash = await this.koboSpanConverter.computeRenditionHash(ctx);
+    await this.annotationSync.upsertGeneratedPosition({
+      annotationId,
+      userId,
+      bookFileId,
+      format: 'kobo_span',
+      pos0: null,
+      pos1: null,
+      status: 'failed',
+      converterVersion: this.koboSpanConverter.version,
+      extras: { reason, chapterIndex, renditionHash },
+    });
+  }
+
+  private async storeFailure(
+    userId: number,
+    annotationId: number,
+    bookFileId: number,
+    format: 'cfi' | 'xpointer',
+    chapterIndex: number | null,
+    reason: string,
+  ): Promise<void> {
+    await this.annotationSync.upsertGeneratedPosition({
+      annotationId,
+      userId,
+      bookFileId,
+      format,
+      pos0: null,
+      pos1: null,
+      status: 'failed',
+      converterVersion: this.positionConverter.version,
+      extras: { reason, chapterIndex },
+    });
+  }
+
+  private groupPositions(rows: AnnotationPosition[]): Map<number, PositionsByFormat> {
+    const byAnnotation = new Map<number, PositionsByFormat>();
+    for (const row of rows) {
+      const group = byAnnotation.get(row.annotationId) ?? {};
+      if (row.format === 'kobo_span') group.koboSpan = row;
+      else if (row.format === 'cfi') group.cfi = row;
+      else if (row.format === 'xpointer') group.xpointer = row;
+      byAnnotation.set(row.annotationId, group);
+    }
+    return byAnnotation;
+  }
+}
diff --git a/server/src/modules/kobo/services/kobo-annotation-payload.ts b/server/src/modules/kobo/services/kobo-annotation-payload.ts
new file mode 100644
index 000000000..50509312a
--- /dev/null
+++ b/server/src/modules/kobo/services/kobo-annotation-payload.ts
@@ -0,0 +1,170 @@
+import { koboColorFromHex } from '../../annotation/annotation-style-map';
+
+export interface KoboReadingServiceAnnotation {
+  attachments: Record<string, never>;
+  clientLastModifiedUtc: string;
+  context: null;
+  highlightColor: string;
+  highlightedText: string;
+  id: string;
+  location: unknown;
+  noteText?: string;
+  type: string;
+}
+
+export interface KoboReadingServiceAnnotationsResponse {
+  annotations: KoboReadingServiceAnnotation[];
+  nextPageOffsetToken: null;
+}
+
+export type IncomingUpsert = {
+  kind: 'upsert';
+  id: string;
+  deleted: boolean;
+  type: string;
+  color: string;
+  text: string;
+  note: string | null;
+  chapterTitle: string | null;
+  location: unknown;
+  clientModifiedAt: Date;
+};
+
+export type IncomingDelete = {
+  kind: 'delete';
+  id: string;
+  clientModifiedAt: Date;
+};
+
+export type IncomingOperation = IncomingUpsert | IncomingDelete;
+
+/** Annotation projected from a canonical hub row into the Reading Services shape. */
+export interface ServeAnnotation {
+  externalKey: string;
+  clientLastModifiedUtc: string;
+  colorHex: string;
+  text: string;
+  note: string | null;
+  hasNote: boolean;
+  location: unknown;
+}
+
+export function toKoboReadingServiceAnnotation(row: ServeAnnotation): KoboReadingServiceAnnotation {
+  return {
+    attachments: {},
+    clientLastModifiedUtc: row.clientLastModifiedUtc,
+    context: null,
+    highlightColor: koboColorFromHex(row.colorHex),
+    highlightedText: row.text,
+    id: row.externalKey,
+    location: row.location,
+    ...(row.note ? { noteText: row.note } : {}),
+    type: row.hasNote ? 'note' : 'highlight',
+  };
+}
+
+export function extractKoboAnnotationOperations(body: unknown): IncomingOperation[] {
+  if (!isRecord(body)) return [];
+
+  const updated = [...asArray(body.updatedAnnotations), ...asArray(body.annotations)]
+    .map((value) => parseUpsert(value))
+    .filter((value): value is IncomingUpsert => value !== null);
+
+  const deleted = [
+    ...extractDeletedArray(body.deletedAnnotations),
+    ...extractDeletedArray(body.deletedAnnotationIds),
+    ...extractDeletedArray(body.removedAnnotations),
+    ...updated
+      .filter((operation) => operation.deleted)
+      .map((operation) => ({ kind: 'delete' as const, id: operation.id, clientModifiedAt: operation.clientModifiedAt })),
+  ];
+
+  return mergeOperations([...updated.filter((operation) => !operation.deleted), ...deleted]);
+}
+
+function parseUpsert(value: unknown): IncomingUpsert | null {
+  if (!isRecord(value)) return null;
+  const id = readTrimmedString(value.id);
+  if (!id) return null;
+
+  const note = readNullableString(value.noteText);
+  const location = value.location ?? {};
+  const type = readTrimmedString(value.type) ?? (note ? 'note' : 'highlight');
+  return {
+    kind: 'upsert',
+    id,
+    deleted: value.deleted === true || value.isDeleted === true || value.isRemoved === true || value._deleted === true,
+    type,
+    color: koboColorFromHex(readTrimmedString(value.highlightColor)),
+    text: readString(value.highlightedText) ?? '',
+    note,
+    chapterTitle: readChapterTitle(location),
+    location,
+    clientModifiedAt: parseClientModifiedAt(value.clientLastModifiedUtc),
+  };
+}
+
+function extractDeletedArray(value: unknown): IncomingDelete[] {
+  return asArray(value)
+    .map((item) => {
+      if (typeof item === 'string' && item.trim()) {
+        return { kind: 'delete' as const, id: item.trim(), clientModifiedAt: new Date() };
+      }
+      if (!isRecord(item)) return null;
+      const id = readTrimmedString(item.id);
+      if (!id) return null;
+      return {
+        kind: 'delete' as const,
+        id,
+        clientModifiedAt: parseClientModifiedAt(item.clientLastModifiedUtc ?? item.deletedAtUtc ?? item.lastModifiedUtc),
+      };
+    })
+    .filter((item): item is IncomingDelete => item !== null);
+}
+
+function mergeOperations(operations: IncomingOperation[]): IncomingOperation[] {
+  const byId = new Map<string, IncomingOperation>();
+  for (const operation of operations) {
+    const existing = byId.get(operation.id);
+    if (!existing || operation.clientModifiedAt.getTime() >= existing.clientModifiedAt.getTime()) {
+      byId.set(operation.id, operation);
+    }
+  }
+  return [...byId.values()];
+}
+
+function readChapterTitle(location: unknown): string | null {
+  if (!isRecord(location)) return null;
+  const span = location.span;
+  if (!isRecord(span)) return null;
+  return readString(span.chapterTitle);
+}
+
+function parseClientModifiedAt(value: unknown): Date {
+  const raw = readTrimmedString(value);
+  if (!raw) return new Date();
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? new Date() : parsed;
+}
+
+function readNullableString(value: unknown): string | null {
+  if (value === null) return null;
+  return readString(value);
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+
+function readTrimmedString(value: unknown): string | null {
+  const raw = readString(value);
+  return raw?.trim() ?? null;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
diff --git a/server/src/modules/kobo/services/kobo-kepub-context.service.ts b/server/src/modules/kobo/services/kobo-kepub-context.service.ts
new file mode 100644
index 000000000..804526ae0
--- /dev/null
+++ b/server/src/modules/kobo/services/kobo-kepub-context.service.ts
@@ -0,0 +1,78 @@
+import { Injectable } from '@nestjs/common';
+
+import { KepubContext } from '../../position-converter/kobo-span-converter.service';
+import { BookReadService } from '../../book/book-read.service';
+import { KepubConversionService } from './kepub-conversion.service';
+import { KepubifyBinaryService } from './kepubify-binary.service';
+import { KoboSettingsService, type KoboSettings } from './kobo-settings.service';
+
+export interface KepubReaderFile {
+  id: number;
+  bookId: number;
+  absolutePath: string;
+  format: string | null;
+  fileHash: string | null;
+  sizeBytes: number | null;
+}
+
+export type KepubContextResult =
+  | { ok: true; ctx: KepubContext; file: KepubReaderFile; settings: KoboSettings }
+  | { ok: false; reason: string; settings: KoboSettings | null };
+
+/**
+ * Resolves the kepub artifact context for a book: the primary reader file, the
+ * user's conversion settings, and the cached (or regenerated) kepub path. Every
+ * Kobo position conversion goes through this so the codec always sees the same
+ * artifact the device downloaded.
+ */
+@Injectable()
+export class KoboKepubContextService {
+  constructor(
+    private readonly bookReadService: BookReadService,
+    private readonly koboSettingsService: KoboSettingsService,
+    private readonly kepubConversionService: KepubConversionService,
+    private readonly kepubifyBinaryService: KepubifyBinaryService,
+  ) {}
+
+  async resolveReaderFile(bookId: number): Promise<KepubReaderFile | null> {
+    const [file] = await this.bookReadService.findPrimaryReaderFilesByBookIds([bookId]);
+    return file ?? null;
+  }
+
+  async resolveForBook(userId: number, bookId: number): Promise<KepubContextResult> {
+    const file = await this.resolveReaderFile(bookId);
+    if (!file) return { ok: false, reason: 'no_reader_file', settings: null };
+
+    const settings = await this.koboSettingsService.getSettings(userId);
+    const readiness = this.getKepubReadinessFailure(file, settings);
+    if (readiness) return { ok: false, reason: readiness, settings };
+
+    let kepubPath: string;
+    try {
+      kepubPath = await this.kepubConversionService.getKepubPath({
+        sourcePath: file.absolutePath,
+        fileHash: file.fileHash,
+        bookId,
+        hyphenate: settings.forceEnableHyphenation,
+      });
+    } catch {
+      return { ok: false, reason: 'conversion_failed', settings };
+    }
+
+    const kepubifyVersion = await this.kepubifyBinaryService.getVersion();
+    return {
+      ok: true,
+      file,
+      settings,
+      ctx: { kepubPath, fileHash: file.fileHash, hyphenate: settings.forceEnableHyphenation, kepubifyVersion },
+    };
+  }
+
+  private getKepubReadinessFailure(file: KepubReaderFile, settings: KoboSettings): string | null {
+    if (file.format !== 'epub') return 'kepub_required';
+    if (!settings.convertToKepub) return 'kepub_required';
+    const limitBytes = settings.kepubConversionLimitMb * 1024 * 1024;
+    if (file.sizeBytes && file.sizeBytes > limitBytes) return 'kepub_too_large';
+    return null;
+  }
+}
diff --git a/server/src/modules/kobo/services/kobo-progress-bridge.service.ts b/server/src/modules/kobo/services/kobo-progress-bridge.service.ts
new file mode 100644
index 000000000..b5575ec2a
--- /dev/null
+++ b/server/src/modules/kobo/services/kobo-progress-bridge.service.ts
@@ -0,0 +1,79 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { sanitizeLogValue } from '../../../common/utils/log-sanitize.utils';
+import { KoboSpanConverterService } from '../../position-converter/kobo-span-converter.service';
+import { KoboKepubContextService } from './kobo-kepub-context.service';
+
+const EVENT = 'kobo.progress_bridge';
+
+export interface CanonicalProgressPoint {
+  cfi: string;
+  xpointer: string;
+}
+
+export interface KoboBookmarkPoint {
+  source: string;
+  value: string;
+  contentSourceProgressPercent: number | null;
+}
+
+/**
+ * Converts reading positions between Kobo KoboSpan bookmarks and canonical
+ * cfi/xpointer points through the kepub span codec. Returns null instead of
+ * failing so progress sync always degrades to percent.
+ */
+@Injectable()
+export class KoboProgressBridgeService {
+  private readonly logger = new Logger(KoboProgressBridgeService.name);
+
+  constructor(
+    private readonly kepubContextService: KoboKepubContextService,
+    private readonly koboSpanConverter: KoboSpanConverterService,
+  ) {}
+
+  async koboBookmarkToCanonical(userId: number, bookId: number, source: string, spanValue: string): Promise<CanonicalProgressPoint | null> {
+    try {
+      const kepub = await this.kepubContextService.resolveForBook(userId, bookId);
+      if (!kepub.ok) return null;
+
+      const outcome = await this.koboSpanConverter.koboBookmarkToPositions({
+        bookFileId: kepub.file.id,
+        ctx: kepub.ctx,
+        chapterFilename: source,
+        spanId: spanValue,
+      });
+      if (outcome.status === 'failed' || !outcome.cfi || !outcome.xpointer) return null;
+      return { cfi: outcome.cfi, xpointer: outcome.xpointer };
+    } catch (error) {
+      this.logWarn('bookmark_to_canonical', userId, bookId, error);
+      return null;
+    }
+  }
+
+  async cfiToKoboBookmark(userId: number, bookId: number, cfi: string): Promise<KoboBookmarkPoint | null> {
+    try {
+      const kepub = await this.kepubContextService.resolveForBook(userId, bookId);
+      if (!kepub.ok) return null;
+
+      const outcome = await this.koboSpanConverter.cfiPointToKoboBookmark({ bookFileId: kepub.file.id, ctx: kepub.ctx, cfi });
+      if (outcome.status === 'failed' || !outcome.spanId || !outcome.chapterFilename) return null;
+      return {
+        source: outcome.chapterFilename,
+        value: outcome.spanId,
+        contentSourceProgressPercent: outcome.contentSourceProgressPercent ?? null,
+      };
+    } catch (error) {
+      this.logWarn('cfi_to_bookmark', userId, bookId, error);
+      return null;
+    }
+  }
+
+  private logWarn(operation: string, userId: number, bookId: number, error: unknown): void {
+    const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+    this.logger.warn(
+      `[${EVENT}] [fail] op=${operation} userId=${userId} bookId=${bookId} errorClass=${errorClass} error="${sanitizeLogValue(
+        error instanceof Error ? error.message : 'unknown error',
+      )}" - kobo progress conversion failed`,
+    );
+  }
+}
diff --git a/server/src/modules/kobo/services/kobo-reading-state.service.test.ts b/server/src/modules/kobo/services/kobo-reading-state.service.test.ts
index 3e871fb89..74165449d 100644
--- a/server/src/modules/kobo/services/kobo-reading-state.service.test.ts
+++ b/server/src/modules/kobo/services/kobo-reading-state.service.test.ts
@@ -38,6 +38,8 @@ describe('KoboReadingStateService', () => {
   const bookAccessService = { assertBookAccessible: vi.fn() };
   const userBookStatusService = { autoUpdate: vi.fn() };
   const bookIdentityService = { ensureForBook: vi.fn() };
+  const progressBridge = { koboBookmarkToCanonical: vi.fn(), cfiToKoboBookmark: vi.fn() };
+  const settingsService = { getSettings: vi.fn() };
   const achievementEvents = { emit: vi.fn() };
 
   function makeService(db: ReturnType<typeof makeDb>) {
@@ -46,6 +48,8 @@ describe('KoboReadingStateService', () => {
       bookAccessService as never,
       userBookStatusService as never,
       bookIdentityService as never,
+      progressBridge as never,
+      settingsService as never,
       achievementEvents as never,
     );
   }
@@ -54,6 +58,9 @@ describe('KoboReadingStateService', () => {
     vi.clearAllMocks();
     bookAccessService.assertBookAccessible.mockResolvedValue(undefined);
     userBookStatusService.autoUpdate.mockResolvedValue(undefined);
+    progressBridge.koboBookmarkToCanonical.mockResolvedValue(null);
+    progressBridge.cfiToKoboBookmark.mockResolvedValue(null);
+    settingsService.getSettings.mockResolvedValue({ twoWayProgressSync: false });
     bookIdentityService.ensureForBook.mockImplementation((_userId: number, bookId: number) => ({
       bookId,
       entitlementId: `entitlement-${bookId}`,
@@ -135,6 +142,63 @@ describe('KoboReadingStateService', () => {
     });
   });
 
+  it('does not regress envelope timestamps below a newer hub-refreshed bookmark on device re-push', async () => {
+    const db = makeDb();
+    const stateInsert = makeInsertChain();
+    db.insert.mockReturnValue(stateInsert);
+    db.query.books.findFirst.mockResolvedValue({ id: 12 });
+    db.query.koboReadingStates.findFirst
+      .mockResolvedValueOnce({
+        lastModifiedKobo: '2026-06-11T15:49:30.355Z',
+        priorityTimestamp: '2026-06-11T15:49:30.355Z',
+        currentBookmark: {
+          LastModified: '2026-06-11T15:49:30.355Z',
+          ProgressPercent: 84.94,
+          Location: { Source: 'index_split_012.html', Type: 'KoboSpan', Value: 'kobo.1.1' },
+        },
+      })
+      .mockResolvedValueOnce({
+        entitlementId: '12',
+        createdAtKobo: '2026-06-11T15:42:12.729Z',
+        lastModifiedKobo: '2026-06-11T15:49:30.355Z',
+        priorityTimestamp: '2026-06-11T15:49:30.355Z',
+        currentBookmark: { ProgressPercent: 84.94 },
+      });
+
+    await makeService(db).upsertState(
+      3,
+      12,
+      {
+        LastModified: '2026-06-11T15:49:20Z',
+        PriorityTimestamp: '2026-06-11T15:49:20Z',
+        CurrentBookmark: {
+          LastModified: '2026-06-11T15:49:20Z',
+          ProgressPercent: 21,
+          Location: { Source: 'index_split_012.html', Type: 'KoboSpan', Value: 'kobo.1.1' },
+        },
+      },
+      1,
+      99,
+      false,
+    );
+
+    expect(stateInsert.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        lastModifiedKobo: '2026-06-11T15:49:30.355Z',
+        priorityTimestamp: '2026-06-11T15:49:30.355Z',
+        currentBookmark: expect.objectContaining({ ProgressPercent: 84.94, LastModified: '2026-06-11T15:49:30.355Z' }),
+      }),
+    );
+    expect(stateInsert.onConflictDoUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        set: expect.objectContaining({
+          lastModifiedKobo: '2026-06-11T15:49:30.355Z',
+          priorityTimestamp: '2026-06-11T15:49:30.355Z',
+        }),
+      }),
+    );
+  });
+
   it('calls autoUpdate with merged percent and thresholds when bookmark has ProgressPercent', async () => {
     const db = makeDb();
     const stateInsert = makeInsertChain();
diff --git a/server/src/modules/kobo/services/kobo-reading-state.service.ts b/server/src/modules/kobo/services/kobo-reading-state.service.ts
index 3c9881eb0..07d01ba41 100644
--- a/server/src/modules/kobo/services/kobo-reading-state.service.ts
+++ b/server/src/modules/kobo/services/kobo-reading-state.service.ts
@@ -8,6 +8,8 @@ import { UserBookStatusService } from '../../user-book-status/user-book-status.s
 import { AchievementEventsService, ACHIEVEMENT_EVENT_BOOK_PROGRESS_CHANGED } from '../../achievement/achievement-events.service';
 import { KoboBookAccessService } from './kobo-book-access.service';
 import { KoboBookIdentityService } from './kobo-book-identity.service';
+import { KoboProgressBridgeService } from './kobo-progress-bridge.service';
+import { KoboSettingsService } from './kobo-settings.service';
 
 type Db = NodePgDatabase<typeof schema>;
 type JsonObj = Record<string, unknown>;
@@ -22,6 +24,26 @@ function mergeSubObject(incoming: JsonObj | null | undefined, existing: JsonObj
   return a >= b ? incoming : existing;
 }
 
+/**
+ * Returns the chronologically latest of the given timestamps, preserving the original
+ * string. The Kobo device resolves reading-state conflicts on the envelope LastModified/
+ * PriorityTimestamp, so these must never regress below the bookmark they wrap: a device
+ * re-push of its older state must not lower an envelope that already carries a newer
+ * hub-refreshed bookmark, or the device keeps rejecting the hub progress forever.
+ */
+function maxIsoTimestamp(...values: (string | null | undefined)[]): string | null {
+  let best: string | null = null;
+  let bestMs = Number.NEGATIVE_INFINITY;
+  for (const value of values) {
+    if (!value) continue;
+    const ms = new Date(value).getTime();
+    if (Number.isNaN(ms) || ms <= bestMs) continue;
+    bestMs = ms;
+    best = value;
+  }
+  return best;
+}
+
 @Injectable()
 export class KoboReadingStateService {
   constructor(
@@ -29,6 +51,8 @@ export class KoboReadingStateService {
     private readonly bookAccessService: KoboBookAccessService,
     private readonly userBookStatusService: UserBookStatusService,
     private readonly bookIdentityService: KoboBookIdentityService,
+    private readonly progressBridge: KoboProgressBridgeService,
+    private readonly settingsService: KoboSettingsService,
     private readonly achievementEvents: AchievementEventsService,
   ) {}
 
@@ -82,6 +106,10 @@ export class KoboReadingStateService {
     const mergedStats = mergeSubObject(incomingStats, existing?.statistics as JsonObj | null);
     const mergedStatus = mergeSubObject(incomingStatus, existing?.statusInfo as JsonObj | null);
 
+    const bookmarkModified = typeof mergedBookmark?.LastModified === 'string' ? mergedBookmark.LastModified : undefined;
+    const effectiveLastModified = maxIsoTimestamp(lastModified, existing?.lastModifiedKobo, bookmarkModified) ?? lastModified;
+    const effectivePriority = maxIsoTimestamp(priorityTimestamp, existing?.priorityTimestamp, bookmarkModified) ?? priorityTimestamp;
+
     await this.db
       .insert(schema.koboReadingStates)
       .values({
@@ -89,8 +117,8 @@ export class KoboReadingStateService {
         bookId,
         entitlementId,
         createdAtKobo: created,
-        lastModifiedKobo: lastModified,
-        priorityTimestamp,
+        lastModifiedKobo: effectiveLastModified,
+        priorityTimestamp: effectivePriority,
         currentBookmark: mergedBookmark,
         statistics: mergedStats,
         statusInfo: mergedStatus,
@@ -99,8 +127,8 @@ export class KoboReadingStateService {
       .onConflictDoUpdate({
         target: [schema.koboReadingStates.userId, schema.koboReadingStates.bookId],
         set: {
-          lastModifiedKobo: lastModified,
-          priorityTimestamp,
+          lastModifiedKobo: effectiveLastModified,
+          priorityTimestamp: effectivePriority,
           currentBookmark: sql`excluded.current_bookmark`,
           statistics: sql`excluded.statistics`,
           statusInfo: sql`excluded.status_info`,
@@ -111,15 +139,27 @@ export class KoboReadingStateService {
     const percent = this.extractPercent(mergedBookmark);
     if (percent !== null) {
       if (twoWayProgressSync) {
+        const locationSource = this.extractKoboLocationSource(mergedBookmark);
+        const locationType = this.extractKoboLocationType(mergedBookmark);
+        const locationValue = this.extractKoboLocationValue(mergedBookmark);
+
+        // KoboSpan bookmarks convert to precise canonical points; web and KOReader
+        // resume at the same paragraph instead of a percent approximation.
+        const precise =
+          locationType === 'KoboSpan' && locationSource && locationValue
+            ? await this.progressBridge.koboBookmarkToCanonical(userId, bookId, locationSource, locationValue)
+            : null;
+
         await this.syncPercentToInternalProgress(
           userId,
           bookId,
           percent,
           this.extractProgressModifiedAt(mergedBookmark, lastModified),
-          this.extractKoboLocationSource(mergedBookmark),
-          this.extractKoboLocationType(mergedBookmark),
-          this.extractKoboLocationValue(mergedBookmark),
+          locationSource,
+          locationType,
+          locationValue,
           this.extractContentSourceProgressPercent(mergedBookmark),
+          precise,
         );
         await this.markSnapshotBookUnsynced(userId, bookId);
       }
@@ -150,17 +190,105 @@ export class KoboReadingStateService {
 
     if (!row) return null;
 
+    const refreshed = await this.refreshBookmarkFromHub(userId, bookId, this.asJsonObj(row.currentBookmark)).catch(() => null);
+
     return {
       EntitlementId: (await this.bookIdentityService.ensureForBook(userId, bookId, await this.hasLibrarySnapshot(userId))).entitlementId,
       Created: row.createdAtKobo,
-      LastModified: row.lastModifiedKobo,
-      PriorityTimestamp: row.priorityTimestamp,
-      CurrentBookmark: row.currentBookmark,
+      LastModified: refreshed?.lastModifiedKobo ?? row.lastModifiedKobo,
+      PriorityTimestamp: refreshed?.lastModifiedKobo ?? row.priorityTimestamp,
+      CurrentBookmark: refreshed?.bookmark ?? row.currentBookmark,
       Statistics: row.statistics,
       StatusInfo: row.statusInfo,
     };
   }
 
+  /**
+   * Computes a precise KoboSpan Location for the bookmark when the hub position moved
+   * since the device last reported. readingProgress.koboLocationValue is set only by
+   * device-originated progress (or a previous refresh), so a present cfi with a null
+   * value means the web reader or KOReader owns the current position.
+   */
+  private async refreshBookmarkFromHub(
+    userId: number,
+    bookId: number,
+    bookmark: JsonObj | null,
+  ): Promise<{ bookmark: JsonObj; lastModifiedKobo: string } | null> {
+    const settings = await this.settingsService.getSettings(userId);
+    if (!settings.twoWayProgressSync) return null;
+
+    const [primaryFile] = await this.db
+      .select({ fileId: schema.bookFiles.id })
+      .from(schema.books)
+      .innerJoin(schema.bookFiles, eq(schema.bookFiles.id, schema.books.primaryFileId))
+      .where(and(eq(schema.books.id, bookId), eq(schema.bookFiles.format, 'epub')))
+      .limit(1);
+    if (!primaryFile) return null;
+
+    const [progress] = await this.db
+      .select({
+        cfi: schema.readingProgress.cfi,
+        percentage: schema.readingProgress.percentage,
+        koboLocationValue: schema.readingProgress.koboLocationValue,
+      })
+      .from(schema.readingProgress)
+      .where(and(eq(schema.readingProgress.userId, userId), eq(schema.readingProgress.bookFileId, primaryFile.fileId)))
+      .limit(1);
+    if (!progress?.cfi || progress.koboLocationValue) return null;
+
+    const point = await this.progressBridge.cfiToKoboBookmark(userId, bookId, progress.cfi);
+    if (!point) return null;
+
+    const existingLocation = this.asJsonObj(bookmark?.Location ?? null);
+    const sameLocation = existingLocation?.Value === point.value && existingLocation?.Source === point.source;
+    const samePercent = typeof bookmark?.ProgressPercent === 'number' && Math.abs(bookmark.ProgressPercent - progress.percentage) < PROGRESS_EPSILON;
+    if (sameLocation && samePercent) {
+      await this.stampProgressLocation(userId, primaryFile.fileId, point);
+      return null;
+    }
+
+    const nowIso = new Date().toISOString();
+    const merged: JsonObj = {
+      ...(bookmark ?? {}),
+      LastModified: nowIso,
+      ProgressPercent: progress.percentage,
+      Location: { Source: point.source, Type: 'KoboSpan', Value: point.value },
+    };
+    if (point.contentSourceProgressPercent != null) merged.ContentSourceProgressPercent = point.contentSourceProgressPercent;
+    else delete merged.ContentSourceProgressPercent;
+
+    await this.db
+      .update(schema.koboReadingStates)
+      .set({ currentBookmark: merged, lastModifiedKobo: nowIso, priorityTimestamp: nowIso, updatedAt: new Date() })
+      .where(and(eq(schema.koboReadingStates.userId, userId), eq(schema.koboReadingStates.bookId, bookId)));
+    await this.stampProgressLocation(userId, primaryFile.fileId, point);
+
+    return { bookmark: merged, lastModifiedKobo: nowIso };
+  }
+
+  /** Records which Location the bookmark reflects; deliberately keeps updatedAt untouched. */
+  private async stampProgressLocation(
+    userId: number,
+    fileId: number,
+    point: { source: string; value: string; contentSourceProgressPercent: number | null },
+  ): Promise<void> {
+    await this.db
+      .update(schema.readingProgress)
+      .set({
+        koboLocationSource: point.source,
+        koboLocationType: 'KoboSpan',
+        koboLocationValue: point.value,
+        koboContentSourceProgressPercent: point.contentSourceProgressPercent,
+        updatedAt: sql`"reading_progress"."updated_at"`,
+      })
+      .where(and(eq(schema.readingProgress.userId, userId), eq(schema.readingProgress.bookFileId, fileId)));
+  }
+
+  private asJsonObj(value: unknown): JsonObj | null {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    return value as JsonObj;
+  }
+
   private extractPercent(bookmark: JsonObj | null): number | null {
     if (!bookmark) return null;
     const pct = bookmark.ProgressPercent;
@@ -216,6 +344,7 @@ export class KoboReadingStateService {
     koboLocationType: string | null,
     koboLocationValue: string | null,
     koboContentSourceProgressPercent: number | null,
+    precise: { cfi: string; xpointer: string } | null,
   ): Promise<void> {
     const [primaryFile] = await this.db
       .select({ fileId: schema.bookFiles.id })
@@ -252,7 +381,8 @@ export class KoboReadingStateService {
     ) {
       return;
     }
-    const nextCfi = samePercent ? (existing?.cfi ?? null) : null;
+    const nextCfi = precise?.cfi ?? (samePercent ? (existing?.cfi ?? null) : null);
+    const nextXpointer = precise?.xpointer ?? null;
 
     await this.db
       .insert(schema.readingProgress)
@@ -267,6 +397,7 @@ export class KoboReadingStateService {
         koboLocationType,
         koboLocationValue,
         koboContentSourceProgressPercent,
+        koreaderProgress: nextXpointer,
         updatedAt: sourceUpdatedAt,
       })
       .onConflictDoUpdate({
@@ -280,6 +411,7 @@ export class KoboReadingStateService {
           koboLocationType,
           koboLocationValue,
           koboContentSourceProgressPercent,
+          ...(nextXpointer != null ? { koreaderProgress: nextXpointer } : {}),
           updatedAt: sourceUpdatedAt,
         },
       });
diff --git a/server/src/modules/kobo/services/kobo-settings.service.ts b/server/src/modules/kobo/services/kobo-settings.service.ts
index 5b08ac109..caf7b5029 100644
--- a/server/src/modules/kobo/services/kobo-settings.service.ts
+++ b/server/src/modules/kobo/services/kobo-settings.service.ts
@@ -14,6 +14,7 @@ export interface KoboSettings {
   forceEnableHyphenation: boolean;
   kepubConversionLimitMb: number;
   twoWayProgressSync: boolean;
+  syncBookOrbitAnnotationsToKobo: boolean;
 }
 
 @Injectable()
@@ -31,7 +32,7 @@ export class KoboSettingsService {
     }
 
     if (!row) throw new InternalServerErrorException('Failed to create kobo settings row');
-    if (row.twoWayProgressSync && !row.convertToKepub) {
+    if ((row.twoWayProgressSync || row.syncBookOrbitAnnotationsToKobo) && !row.convertToKepub) {
       const [updated] = await this.db
         .update(schema.koboSyncSettings)
         .set({ convertToKepub: true, updatedAt: sql`now()` })
@@ -48,6 +49,7 @@ export class KoboSettingsService {
       forceEnableHyphenation: row.forceEnableHyphenation,
       kepubConversionLimitMb: row.kepubConversionLimitMb,
       twoWayProgressSync: row.twoWayProgressSync,
+      syncBookOrbitAnnotationsToKobo: row.syncBookOrbitAnnotationsToKobo,
     };
   }
 
@@ -57,7 +59,8 @@ export class KoboSettingsService {
     const newReading = patch.readingThreshold ?? current.readingThreshold;
     const newFinished = patch.finishedThreshold ?? current.finishedThreshold;
     const newTwoWayProgressSync = patch.twoWayProgressSync ?? current.twoWayProgressSync;
-    const newConvertToKepub = newTwoWayProgressSync ? true : (patch.convertToKepub ?? current.convertToKepub);
+    const newAnnotationSync = patch.syncBookOrbitAnnotationsToKobo ?? current.syncBookOrbitAnnotationsToKobo;
+    const newConvertToKepub = newTwoWayProgressSync || newAnnotationSync ? true : (patch.convertToKepub ?? current.convertToKepub);
 
     if (newReading >= newFinished) {
       throw new BadRequestException('Reading threshold must be less than finished threshold');
@@ -72,6 +75,7 @@ export class KoboSettingsService {
         forceEnableHyphenation: patch.forceEnableHyphenation ?? current.forceEnableHyphenation,
         kepubConversionLimitMb: patch.kepubConversionLimitMb ?? current.kepubConversionLimitMb,
         twoWayProgressSync: newTwoWayProgressSync,
+        syncBookOrbitAnnotationsToKobo: newAnnotationSync,
         updatedAt: sql`now()`,
       })
       .where(eq(schema.koboSyncSettings.userId, userId))
@@ -92,6 +96,7 @@ export class KoboSettingsService {
       forceEnableHyphenation: updated.forceEnableHyphenation,
       kepubConversionLimitMb: updated.kepubConversionLimitMb,
       twoWayProgressSync: updated.twoWayProgressSync,
+      syncBookOrbitAnnotationsToKobo: updated.syncBookOrbitAnnotationsToKobo,
     };
   }
 
diff --git a/server/src/modules/koreader/dto/index.ts b/server/src/modules/koreader/dto/index.ts
index ba736b3bd..1c3ceaa08 100644
--- a/server/src/modules/koreader/dto/index.ts
+++ b/server/src/modules/koreader/dto/index.ts
@@ -1,2 +1,6 @@
+export * from './koreader-catalog-query.dto';
+export * from './koreader-exchange.dto';
+export * from './koreader-package.dto';
+export * from './koreader-plugin.dto';
 export * from './koreader-progress.dto';
 export * from './koreader-user.dto';
diff --git a/server/src/modules/koreader/dto/koreader-catalog-query.dto.ts b/server/src/modules/koreader/dto/koreader-catalog-query.dto.ts
new file mode 100644
index 000000000..b89634532
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-catalog-query.dto.ts
@@ -0,0 +1,142 @@
+import { Transform, Type } from 'class-transformer';
+import { ArrayMaxSize, IsArray, IsIn, IsInt, IsNumber, IsOptional, IsString, Max, MaxLength, Min } from 'class-validator';
+
+import type {
+  KoreaderCatalogReadStatusFilter,
+  KoreaderCatalogSettableReadStatus,
+  KoreaderCatalogSort,
+  KoreaderCatalogSortOrder,
+} from '@bookorbit/types';
+
+export const KOREADER_CATALOG_SORTS = [
+  'title',
+  'author',
+  'recently_added',
+  'recently_updated',
+  'recently_read',
+  'series',
+] as const satisfies readonly KoreaderCatalogSort[];
+
+export const KOREADER_CATALOG_SORT_ORDERS = ['asc', 'desc'] as const satisfies readonly KoreaderCatalogSortOrder[];
+
+export const KOREADER_CATALOG_READ_STATUS_FILTERS = ['unread', 'reading', 'finished'] as const satisfies readonly KoreaderCatalogReadStatusFilter[];
+
+export const KOREADER_CATALOG_SETTABLE_READ_STATUSES = [
+  'want_to_read',
+  'reading',
+  'on_hold',
+  'read',
+  'abandoned',
+] as const satisfies readonly KoreaderCatalogSettableReadStatus[];
+
+function parseIdList(value: unknown): number[] | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  let raw: unknown[];
+  if (Array.isArray(value)) {
+    raw = value;
+  } else if (typeof value === 'string') {
+    raw = value.split(',');
+  } else if (typeof value === 'number') {
+    raw = [value];
+  } else {
+    return [];
+  }
+  const ids = raw.map((part) => Number(String(part).trim())).filter((id) => Number.isInteger(id) && id > 0);
+  return ids.length > 0 ? [...new Set(ids)] : [];
+}
+
+export class KoreaderCatalogBooksQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  size?: number = 20;
+
+  @IsOptional()
+  @IsIn(KOREADER_CATALOG_SORTS)
+  sort?: KoreaderCatalogSort = 'recently_added';
+
+  @IsOptional()
+  @IsIn(KOREADER_CATALOG_SORT_ORDERS)
+  order?: KoreaderCatalogSortOrder;
+
+  @IsOptional()
+  @IsString()
+  q?: string;
+
+  @IsOptional()
+  @IsIn(KOREADER_CATALOG_READ_STATUS_FILTERS)
+  readStatus?: KoreaderCatalogReadStatusFilter;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(16)
+  format?: string;
+
+  @IsOptional()
+  @Transform(({ value }) => parseIdList(value))
+  @IsArray()
+  @ArrayMaxSize(200)
+  @IsInt({ each: true })
+  @Min(1, { each: true })
+  ids?: number[];
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  libraryId?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  collectionId?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  smartScopeId?: number;
+
+  @IsOptional()
+  @IsString()
+  author?: string;
+
+  @IsOptional()
+  @IsString()
+  series?: string;
+}
+
+export class KoreaderCatalogSectionQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(128)
+  q?: string;
+}
+
+export class KoreaderCatalogSetReadStatusDto {
+  @IsIn(KOREADER_CATALOG_SETTABLE_READ_STATUSES)
+  status!: KoreaderCatalogSettableReadStatus;
+}
+
+export class KoreaderCatalogSetRatingDto {
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(5)
+  rating?: number | null;
+}
diff --git a/server/src/modules/koreader/dto/koreader-exchange.dto.test.ts b/server/src/modules/koreader/dto/koreader-exchange.dto.test.ts
new file mode 100644
index 000000000..3558846bd
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-exchange.dto.test.ts
@@ -0,0 +1,56 @@
+import 'reflect-metadata';
+
+import { plainToInstance } from 'class-transformer';
+import { validate, type ValidationError } from 'class-validator';
+
+import { AnnotationExchangeAckDto } from './koreader-exchange.dto';
+
+const DEVICE = { deviceId: '40A755B5', deviceModel: 'Emulator', pluginVersion: '0.4.0' };
+const HASH = '5f4dcc3b5aa765d61d8327deb882cf99';
+
+const APPLIED_ENTRY = {
+  serverId: 123,
+  version: 1,
+  status: 'applied',
+  verified: true,
+  corrected: false,
+  pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+  pos1: '/body/DocFragment[8]/body/p[12]/text().42',
+  datetimeUpdated: '2026-06-10 19:58:14',
+};
+
+function failedProperties(errors: ValidationError[]): string[] {
+  return errors.flatMap((error) => [...(error.constraints ? [error.property] : []), ...failedProperties(error.children ?? [])]);
+}
+
+describe('AnnotationExchangeAckDto', () => {
+  it('accepts an ack with applied entries and an empty deleted array', async () => {
+    const dto = plainToInstance(AnnotationExchangeAckDto, {
+      ...DEVICE,
+      books: [{ hash: HASH, applied: [APPLIED_ENTRY], deleted: [] }],
+    });
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it('accepts an ack where both lists are empty arrays', async () => {
+    const dto = plainToInstance(AnnotationExchangeAckDto, {
+      ...DEVICE,
+      books: [{ hash: HASH, applied: [], deleted: [] }],
+    });
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it('rejects empty lists encoded as JSON objects, as pre-fix plugins sent for empty Lua tables', async () => {
+    const dto = plainToInstance(AnnotationExchangeAckDto, {
+      ...DEVICE,
+      books: [{ hash: HASH, applied: [APPLIED_ENTRY], deleted: {} }],
+    });
+    const errors = await validate(dto);
+
+    expect(failedProperties(errors)).toContain('deleted');
+  });
+});
diff --git a/server/src/modules/koreader/dto/koreader-exchange.dto.ts b/server/src/modules/koreader/dto/koreader-exchange.dto.ts
new file mode 100644
index 000000000..84410d5c4
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-exchange.dto.ts
@@ -0,0 +1,138 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  ArrayMinSize,
+  IsArray,
+  IsBoolean,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  Matches,
+  MaxLength,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+
+import { KoreaderAnnotationDto, PluginDeviceDto } from './koreader-plugin.dto';
+
+const MD5_HEX = /^[0-9a-f]{32}$/i;
+const DEVICE_DATETIME = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+
+export class ExchangeKeyDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  k!: string;
+
+  @IsString()
+  @Matches(DEVICE_DATETIME)
+  dt!: string;
+}
+
+export class ExchangeBookDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsArray()
+  @ArrayMaxSize(5000)
+  @ValidateNested({ each: true })
+  @Type(() => ExchangeKeyDto)
+  keys!: ExchangeKeyDto[];
+
+  /** False when the device chunk-capped the key list; deletion detection is skipped then. */
+  @IsBoolean()
+  keysComplete!: boolean;
+
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => KoreaderAnnotationDto)
+  changes!: KoreaderAnnotationDto[];
+}
+
+export class AnnotationExchangeDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(20)
+  @ValidateNested({ each: true })
+  @Type(() => ExchangeBookDto)
+  books!: ExchangeBookDto[];
+}
+
+export class ExchangeAckAppliedDto {
+  @IsInt()
+  @Min(1)
+  serverId!: number;
+
+  @IsInt()
+  @Min(1)
+  version!: number;
+
+  @IsIn(['applied', 'failed'])
+  status!: 'applied' | 'failed';
+
+  @IsOptional()
+  @IsBoolean()
+  verified?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  corrected?: boolean;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  pos0?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  pos1?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  pageno?: number;
+
+  @IsOptional()
+  @IsString()
+  @Matches(DEVICE_DATETIME)
+  datetimeUpdated?: string;
+}
+
+export class ExchangeAckDeletedDto {
+  @IsInt()
+  @Min(1)
+  serverId!: number;
+
+  @IsIn(['applied', 'failed'])
+  status!: 'applied' | 'failed';
+}
+
+export class ExchangeAckBookDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsArray()
+  @ArrayMaxSize(200)
+  @ValidateNested({ each: true })
+  @Type(() => ExchangeAckAppliedDto)
+  applied!: ExchangeAckAppliedDto[];
+
+  @IsArray()
+  @ArrayMaxSize(200)
+  @ValidateNested({ each: true })
+  @Type(() => ExchangeAckDeletedDto)
+  deleted!: ExchangeAckDeletedDto[];
+}
+
+export class AnnotationExchangeAckDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(20)
+  @ValidateNested({ each: true })
+  @Type(() => ExchangeAckBookDto)
+  books!: ExchangeAckBookDto[];
+}
diff --git a/server/src/modules/koreader/dto/koreader-package.dto.ts b/server/src/modules/koreader/dto/koreader-package.dto.ts
new file mode 100644
index 000000000..9d499baf6
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-package.dto.ts
@@ -0,0 +1,8 @@
+import { IsString, MaxLength, MinLength } from 'class-validator';
+
+export class DownloadPluginPackageDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(2000)
+  origin!: string;
+}
diff --git a/server/src/modules/koreader/dto/koreader-plugin.dto.ts b/server/src/modules/koreader/dto/koreader-plugin.dto.ts
new file mode 100644
index 000000000..6c8c40470
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-plugin.dto.ts
@@ -0,0 +1,238 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  ArrayMinSize,
+  IsArray,
+  IsIn,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Matches,
+  Max,
+  MaxLength,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+
+const MD5_HEX = /^[0-9a-f]{32}$/i;
+const DEVICE_DATETIME = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+export class PluginDeviceDto {
+  @IsString()
+  @Matches(/^[A-Za-z0-9-]{1,100}$/)
+  deviceId!: string;
+
+  @IsString()
+  @MaxLength(100)
+  deviceModel!: string;
+
+  @IsString()
+  @MaxLength(20)
+  pluginVersion!: string;
+
+  /**
+   * Device-local wall clock at request time. KOReader datetimes carry no timezone,
+   * so the server needs this to mint datetimes in the device's clock frame.
+   */
+  @IsOptional()
+  @IsString()
+  @Matches(DEVICE_DATETIME)
+  deviceTime?: string;
+}
+
+export class MatchCheckDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(500)
+  @IsString({ each: true })
+  @Matches(MD5_HEX, { each: true })
+  hashes!: string[];
+}
+
+export class PageStatEventDto {
+  @IsInt()
+  @Min(0)
+  page!: number;
+
+  @IsInt()
+  @Min(1)
+  startTime!: number;
+
+  @IsInt()
+  @Min(0)
+  @Max(86400)
+  durationSeconds!: number;
+
+  @IsInt()
+  @Min(1)
+  totalPages!: number;
+}
+
+export class PageStatsBookDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => PageStatEventDto)
+  events!: PageStatEventDto[];
+}
+
+export class PageStatsUploadDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => PageStatsBookDto)
+  books!: PageStatsBookDto[];
+}
+
+export class KoreaderAnnotationDto {
+  @IsString()
+  @Matches(DEVICE_DATETIME)
+  datetime!: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(DEVICE_DATETIME)
+  datetimeUpdated?: string;
+
+  @IsIn(['lighten', 'underscore', 'strikeout', 'invert'])
+  drawer!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(30)
+  color?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10000)
+  text?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(5000)
+  note?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  chapter?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  pageno?: number;
+
+  @IsIn(['xpointer', 'pdf'])
+  posFormat!: string;
+
+  @IsString()
+  @MaxLength(4000)
+  pos0!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  pos1?: string;
+}
+
+export class AnnotationsBookDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => KoreaderAnnotationDto)
+  annotations!: KoreaderAnnotationDto[];
+}
+
+export class AnnotationsUploadDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(20)
+  @ValidateNested({ each: true })
+  @Type(() => AnnotationsBookDto)
+  books!: AnnotationsBookDto[];
+}
+
+export class BookStateDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsOptional()
+  @IsIn(['reading', 'complete', 'abandoned'])
+  status?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(DATE_ONLY)
+  statusModified?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(5)
+  rating?: number;
+}
+
+export class BookStatesUploadDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(200)
+  @ValidateNested({ each: true })
+  @Type(() => BookStateDto)
+  books!: BookStateDto[];
+}
+
+export class BulkProgressItemDto {
+  @IsString()
+  @Matches(MD5_HEX)
+  hash!: string;
+
+  @IsNumber()
+  @Min(0)
+  @Max(1)
+  percentage!: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(4000)
+  progress?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  timestamp?: number;
+}
+
+export class BulkProgressDto extends PluginDeviceDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(100)
+  @ValidateNested({ each: true })
+  @Type(() => BulkProgressItemDto)
+  items!: BulkProgressItemDto[];
+}
+
+export class SweepCompleteDto extends PluginDeviceDto {
+  @IsInt()
+  @Min(0)
+  booksMatched!: number;
+
+  @IsInt()
+  @Min(0)
+  pageStatsUploaded!: number;
+
+  @IsInt()
+  @Min(0)
+  annotationsUpserted!: number;
+}
diff --git a/server/src/modules/koreader/dto/koreader-progress.dto.test.ts b/server/src/modules/koreader/dto/koreader-progress.dto.test.ts
new file mode 100644
index 000000000..c9ee0b715
--- /dev/null
+++ b/server/src/modules/koreader/dto/koreader-progress.dto.test.ts
@@ -0,0 +1,42 @@
+import 'reflect-metadata';
+
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+
+import { SaveProgressDto } from './koreader-progress.dto';
+
+const BASE = { document: 'abc123', percentage: 0.42 };
+
+describe('SaveProgressDto', () => {
+  it('accepts an xpointer string progress from reflowable documents', async () => {
+    const dto = plainToInstance(SaveProgressDto, { ...BASE, progress: '/body/DocFragment[8]/body/p[12]/text().0' });
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+    expect(dto.progress).toBe('/body/DocFragment[8]/body/p[12]/text().0');
+  });
+
+  it('coerces the numeric page progress sent for paged documents into a string', async () => {
+    const dto = plainToInstance(SaveProgressDto, { ...BASE, progress: 42 });
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+    expect(dto.progress).toBe('42');
+  });
+
+  it('keeps progress undefined when omitted', async () => {
+    const dto = plainToInstance(SaveProgressDto, { ...BASE });
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+    expect(dto.progress).toBeUndefined();
+  });
+
+  it('rejects progress values that are neither string nor number', async () => {
+    const dto = plainToInstance(SaveProgressDto, { ...BASE, progress: true });
+    const errors = await validate(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]?.property).toBe('progress');
+  });
+});
diff --git a/server/src/modules/koreader/dto/koreader-progress.dto.ts b/server/src/modules/koreader/dto/koreader-progress.dto.ts
index 39cf44b84..3e8412bff 100644
--- a/server/src/modules/koreader/dto/koreader-progress.dto.ts
+++ b/server/src/modules/koreader/dto/koreader-progress.dto.ts
@@ -1,3 +1,4 @@
+import { Transform } from 'class-transformer';
 import { IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 
 export class SaveProgressDto {
@@ -9,6 +10,9 @@ export class SaveProgressDto {
   @Max(1)
   percentage!: number;
 
+  // KOReader sends an xpointer string for reflowable documents but a plain
+  // page number for paged ones (PDF/CBZ/DjVu), so numbers are normalized here.
+  @Transform(({ value }) => (typeof value === 'number' && Number.isFinite(value) ? String(value) : value))
   @IsString()
   @IsOptional()
   progress?: string;
diff --git a/server/src/modules/koreader/koreader-annotation-exchange.service.test.ts b/server/src/modules/koreader/koreader-annotation-exchange.service.test.ts
new file mode 100644
index 000000000..4e057f0bc
--- /dev/null
+++ b/server/src/modules/koreader/koreader-annotation-exchange.service.test.ts
@@ -0,0 +1,262 @@
+import { BadRequestException, Logger } from '@nestjs/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestUser } from '../../common/types/request-user';
+import type { AnnotationSyncService } from '../annotation/annotation-sync.service';
+import type { PositionConverterService } from '../position-converter/position-converter.service';
+import type { AnnotationExchangeAckDto, AnnotationExchangeDto } from './dto';
+import { KoreaderAnnotationExchangeService } from './koreader-annotation-exchange.service';
+import type { KoreaderRepository } from './koreader.repository';
+
+const DEVICE_ID = 'device-1234';
+const HASH_A = 'a'.repeat(32);
+const HASH_B = 'b'.repeat(32);
+
+function makeUser(): RequestUser {
+  return { id: 7, settings: {} } as unknown as RequestUser;
+}
+
+function makeAnnotationRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 100,
+    userId: 7,
+    bookId: 20,
+    text: 'highlighted text',
+    color: '#FACC15',
+    style: 'squiggly',
+    note: 'a note',
+    chapterTitle: 'Chapter 1',
+    origin: 'web',
+    version: 2,
+    deletedAt: null,
+    deviceCreatedAt: null,
+    deviceUpdatedAt: null,
+    createdAt: new Date('2026-06-08T10:00:00Z'),
+    updatedAt: new Date('2026-06-09T11:30:00Z'),
+    ...overrides,
+  };
+}
+
+function makeStateRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 900,
+    annotationId: 100,
+    userId: 7,
+    source: 'koreader',
+    deviceId: DEVICE_ID,
+    externalKey: 'c'.repeat(32),
+    externalCreatedAt: '2026-06-01 21:14:03',
+    lastAppliedVersion: 1,
+    deleteAckedAt: null,
+    ...overrides,
+  };
+}
+
+function makeExchangeDto(books: AnnotationExchangeDto['books']): AnnotationExchangeDto {
+  return { deviceId: DEVICE_ID, deviceModel: 'Kobo', pluginVersion: '0.4.0', books } as AnnotationExchangeDto;
+}
+
+describe('KoreaderAnnotationExchangeService', () => {
+  let koreaderRepo: { getAccessibleLibraryIds: ReturnType<typeof vi.fn>; resolveBookFilesByHashes: ReturnType<typeof vi.fn> };
+  // Loose mock typing: format-dependent mockImplementations return promises.
+  let annotationSync: Record<string, any>;
+  let positionConverter: { version: number; cfiToXpointer: ReturnType<typeof vi.fn> };
+  let service: KoreaderAnnotationExchangeService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+
+    koreaderRepo = {
+      getAccessibleLibraryIds: vi.fn().mockResolvedValue([1]),
+      resolveBookFilesByHashes: vi.fn().mockResolvedValue(new Map([[HASH_A, { bookFileId: 10, bookId: 20, libraryId: 1 }]])),
+    };
+    annotationSync = {
+      ingestDeviceAnnotations: vi.fn().mockResolvedValue({ created: 0, updated: 0, moved: 0, unchanged: 0, skippedDeleted: 0 }),
+      detectDeviceDeletions: vi.fn().mockResolvedValue(0),
+      computePushDown: vi.fn().mockResolvedValue({ adds: [], edits: [], deletes: [], more: false }),
+      ensureDeviceCreatedAt: vi.fn().mockResolvedValue('2026-06-08 10:00:00'),
+      findDevicePositionFor: vi.fn().mockResolvedValue(null),
+      upsertGeneratedPosition: vi.fn().mockResolvedValue(undefined),
+      applyExchangeAck: vi.fn().mockResolvedValue({ acked: 0 }),
+    };
+    positionConverter = {
+      version: 1,
+      cfiToXpointer: vi.fn().mockResolvedValue({
+        status: 'exact',
+        pos0: '/body/DocFragment[1]/body/p/text().0',
+        pos1: '/body/DocFragment[1]/body/p/text().5',
+        chapterIndex: 0,
+      }),
+    };
+
+    service = new KoreaderAnnotationExchangeService(
+      koreaderRepo as unknown as KoreaderRepository,
+      annotationSync as unknown as AnnotationSyncService,
+      positionConverter as unknown as PositionConverterService,
+    );
+  });
+
+  function makeBook(overrides: Partial<AnnotationExchangeDto['books'][number]> = {}): AnnotationExchangeDto['books'][number] {
+    return { hash: HASH_A, keys: [], keysComplete: true, changes: [], ...overrides } as AnnotationExchangeDto['books'][number];
+  }
+
+  it('reports unmatched hashes without processing them', async () => {
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook({ hash: HASH_B })]));
+
+    expect(response.unmatched).toEqual([HASH_B]);
+    expect(response.results).toEqual([]);
+    expect(annotationSync.ingestDeviceAnnotations).not.toHaveBeenCalled();
+  });
+
+  it('rejects requests with too many changes', async () => {
+    const changes = Array.from({ length: 51 }, (_, i) => ({
+      datetime: '2026-06-01 21:14:03',
+      drawer: 'lighten',
+      posFormat: 'xpointer',
+      pos0: `/pos-${i}`,
+    })) as AnnotationExchangeDto['books'][number]['changes'];
+
+    await expect(service.exchange(makeUser(), makeExchangeDto([makeBook({ changes })]))).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('skips deletion detection when the key set is incomplete', async () => {
+    await service.exchange(makeUser(), makeExchangeDto([makeBook({ keysComplete: false })]));
+
+    expect(annotationSync.detectDeviceDeletions).not.toHaveBeenCalled();
+    expect(annotationSync.computePushDown).toHaveBeenCalled();
+  });
+
+  it('runs deletion detection on complete key sets', async () => {
+    const keys = [{ k: 'd'.repeat(32), dt: '2026-06-01 21:14:03' }];
+    await service.exchange(makeUser(), makeExchangeDto([makeBook({ keys })]));
+
+    expect(annotationSync.detectDeviceDeletions).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: 7, deviceId: DEVICE_ID, bookId: 20, presentKeys: keys }),
+    );
+  });
+
+  it('builds add entries with projected drawer, named color and minted datetime', async () => {
+    annotationSync.computePushDown.mockResolvedValue({ adds: [makeAnnotationRow()], edits: [], deletes: [], more: false });
+    annotationSync.findDevicePositionFor.mockImplementation((_id: number, format: string) =>
+      Promise.resolve(
+        format === 'xpointer'
+          ? {
+              format: 'xpointer',
+              pos0: '/body/DocFragment[1]/body/p/text().0',
+              pos1: '/body/DocFragment[1]/body/p/text().5',
+              status: 'pending',
+              converterVersion: 1,
+              extras: { pageno: 3 },
+            }
+          : null,
+      ),
+    );
+
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook()]));
+
+    const add = response.results[0].toApply.add[0];
+    expect(add).toMatchObject({
+      serverId: 100,
+      version: 2,
+      datetime: '2026-06-08 10:00:00',
+      drawer: 'underscore',
+      color: 'yellow',
+      text: 'highlighted text',
+      note: 'a note',
+      posFormat: 'xpointer',
+      pos0: '/body/DocFragment[1]/body/p/text().0',
+      pageno: 3,
+    });
+  });
+
+  it('converts missing xpointers within the budget and defers the entry to the next exchange', async () => {
+    annotationSync.computePushDown.mockResolvedValue({ adds: [makeAnnotationRow()], edits: [], deletes: [], more: false });
+    annotationSync.findDevicePositionFor.mockImplementation((_id: number, format: string) =>
+      Promise.resolve(format === 'cfi' ? { format: 'cfi', pos0: 'epubcfi(/6/2!/4/2,/1:0,/1:5)', status: 'exact' } : null),
+    );
+
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook()]));
+
+    expect(positionConverter.cfiToXpointer).toHaveBeenCalledWith({ bookFileId: 10, cfi: 'epubcfi(/6/2!/4/2,/1:0,/1:5)', text: 'highlighted text' });
+    expect(annotationSync.upsertGeneratedPosition).toHaveBeenCalledWith(
+      expect.objectContaining({ format: 'xpointer', status: 'pending', pos0: '/body/DocFragment[1]/body/p/text().0' }),
+    );
+    expect(response.results[0].toApply.add).toEqual([]);
+    expect(response.results[0].skippedNoPosition).toBe(0);
+  });
+
+  it('marks conversion failures and counts them as skipped without retrying at current version', async () => {
+    annotationSync.computePushDown.mockResolvedValue({ adds: [makeAnnotationRow()], edits: [], deletes: [], more: false });
+    annotationSync.findDevicePositionFor.mockImplementation((_id: number, format: string) =>
+      Promise.resolve(
+        format === 'xpointer' ? { format: 'xpointer', pos0: null, pos1: null, status: 'failed', converterVersion: 1, extras: null } : null,
+      ),
+    );
+
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook()]));
+
+    expect(positionConverter.cfiToXpointer).not.toHaveBeenCalled();
+    expect(response.results[0].skippedNoPosition).toBe(1);
+  });
+
+  it('builds edit entries with a datetime_updated ahead of the last device edit', async () => {
+    annotationSync.computePushDown.mockResolvedValue({
+      adds: [],
+      edits: [
+        { state: makeStateRow(), annotation: makeAnnotationRow({ deviceCreatedAt: '2026-06-01 21:14:03', deviceUpdatedAt: '2026-06-10 09:00:00' }) },
+      ],
+      deletes: [],
+      more: false,
+    });
+
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook()]));
+
+    const edit = response.results[0].toApply.edit[0];
+    expect(edit).toMatchObject({ serverId: 100, key: 'c'.repeat(32), datetime: '2026-06-01 21:14:03' });
+    expect(edit.datetimeUpdated).toBe('2026-06-10 09:00:01');
+  });
+
+  it('builds delete entries from sync state identity', async () => {
+    annotationSync.computePushDown.mockResolvedValue({
+      adds: [],
+      edits: [],
+      deletes: [{ state: makeStateRow(), annotation: makeAnnotationRow({ deletedAt: new Date() }) }],
+      more: false,
+    });
+
+    const response = await service.exchange(makeUser(), makeExchangeDto([makeBook()]));
+
+    expect(response.results[0].toApply.delete[0]).toEqual({
+      serverId: 100,
+      key: 'c'.repeat(32),
+      datetime: '2026-06-01 21:14:03',
+    });
+  });
+
+  it('routes acks per matched book into the sync service', async () => {
+    annotationSync.applyExchangeAck.mockResolvedValue({ acked: 2 });
+    const dto = {
+      deviceId: DEVICE_ID,
+      deviceModel: 'Kobo',
+      pluginVersion: '0.4.0',
+      books: [
+        {
+          hash: HASH_A,
+          applied: [{ serverId: 100, version: 2, status: 'applied', verified: true }],
+          deleted: [{ serverId: 101, status: 'applied' }],
+        },
+        { hash: HASH_B, applied: [], deleted: [] },
+      ],
+    } as unknown as AnnotationExchangeAckDto;
+
+    const response = await service.exchangeAck(makeUser(), dto);
+
+    expect(response.results).toEqual([{ hash: HASH_A, acked: 2 }]);
+    expect(response.unmatched).toEqual([HASH_B]);
+    expect(annotationSync.applyExchangeAck).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: 7, deviceId: DEVICE_ID, bookFileId: 10, converterVersion: 1 }),
+    );
+  });
+});
diff --git a/server/src/modules/koreader/koreader-annotation-exchange.service.ts b/server/src/modules/koreader/koreader-annotation-exchange.service.ts
new file mode 100644
index 000000000..5ff197e68
--- /dev/null
+++ b/server/src/modules/koreader/koreader-annotation-exchange.service.ts
@@ -0,0 +1,405 @@
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+
+import type { RequestUser } from '../../common/types/request-user';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import type { AnnotationRow } from '../../db/schema';
+import { drawerFromStyle, koreaderColorFromHex } from '../annotation/annotation-style-map';
+import { AnnotationSyncService, formatDeviceDatetime, type IncomingDeviceAnnotation, type IngestResult } from '../annotation/annotation-sync.service';
+import { PositionConverterService } from '../position-converter/position-converter.service';
+import type { AnnotationExchangeAckDto, AnnotationExchangeDto, ExchangeBookDto } from './dto';
+import type { KoreaderAnnotationDto } from './dto';
+import { KoreaderRepository } from './koreader.repository';
+
+const EXCHANGE_EVENT = 'koreader.annotation_exchange';
+const ACK_EVENT = 'koreader.annotation_exchange_ack';
+const MAX_CHANGES_PER_REQUEST = 50;
+const PUSH_DOWN_PAGE = 100;
+const CONVERSION_BUDGET_PER_REQUEST = 20;
+
+export interface ExchangeAddEntry {
+  serverId: number;
+  version: number;
+  datetime: string;
+  datetimeUpdated: string | null;
+  drawer: string;
+  color: string;
+  text: string;
+  note: string | null;
+  chapter: string | null;
+  posFormat: 'xpointer' | 'pdf';
+  pos0: string;
+  pos1: string | null;
+  pageno: number | null;
+}
+
+export interface ExchangeEditEntry {
+  serverId: number;
+  version: number;
+  key: string;
+  datetime: string | null;
+  datetimeUpdated: string;
+  drawer: string;
+  color: string;
+  text: string;
+  note: string | null;
+  chapter: string | null;
+}
+
+export interface ExchangeDeleteEntry {
+  serverId: number;
+  key: string;
+  datetime: string | null;
+}
+
+export interface ExchangeBookResult {
+  hash: string;
+  bookId: number;
+  applied: IngestResult & { deviceDeleted: number };
+  toApply: {
+    add: ExchangeAddEntry[];
+    edit: ExchangeEditEntry[];
+    delete: ExchangeDeleteEntry[];
+  };
+  more: boolean;
+  skippedNoPosition: number;
+}
+
+export interface ExchangeResponse {
+  results: ExchangeBookResult[];
+  unmatched: string[];
+}
+
+export interface ExchangeAckResponse {
+  results: { hash: string; acked: number }[];
+  unmatched: string[];
+}
+
+@Injectable()
+export class KoreaderAnnotationExchangeService {
+  private readonly logger = new Logger(KoreaderAnnotationExchangeService.name);
+
+  constructor(
+    private readonly koreaderRepo: KoreaderRepository,
+    private readonly annotationSync: AnnotationSyncService,
+    private readonly positionConverter: PositionConverterService,
+  ) {}
+
+  async exchange(user: RequestUser, dto: AnnotationExchangeDto): Promise<ExchangeResponse> {
+    const startedAtMs = Date.now();
+    const totalChanges = dto.books.reduce((sum, book) => sum + book.changes.length, 0);
+    this.logger.log(
+      `[${EXCHANGE_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} books=${dto.books.length} changes=${totalChanges} - annotation exchange started`,
+    );
+
+    try {
+      if (totalChanges > MAX_CHANGES_PER_REQUEST) {
+        throw new BadRequestException(`Too many annotation changes in one request (max ${MAX_CHANGES_PER_REQUEST})`);
+      }
+
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const hashes = [...new Set(dto.books.map((book) => book.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+      const deviceClockOffsetMs = this.deviceClockOffsetMs(dto.deviceTime);
+
+      const results: ExchangeBookResult[] = [];
+      const unmatched: string[] = [];
+      let pushedTotal = 0;
+
+      for (const book of dto.books) {
+        const hash = book.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+        const result = await this.exchangeBook(user.id, dto.deviceId, hash, match.bookId, match.bookFileId, book, deviceClockOffsetMs);
+        pushedTotal += result.toApply.add.length + result.toApply.edit.length + result.toApply.delete.length;
+        results.push(result);
+      }
+
+      this.logger.log(
+        `[${EXCHANGE_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} books=${results.length} pushed=${pushedTotal} unmatched=${unmatched.length} - annotation exchange completed`,
+      );
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${EXCHANGE_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - annotation exchange failed`,
+      );
+      throw error;
+    }
+  }
+
+  async exchangeAck(user: RequestUser, dto: AnnotationExchangeAckDto): Promise<ExchangeAckResponse> {
+    const startedAtMs = Date.now();
+    try {
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const hashes = [...new Set(dto.books.map((book) => book.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+      const results: { hash: string; acked: number }[] = [];
+      const unmatched: string[] = [];
+      for (const book of dto.books) {
+        const hash = book.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+        const { acked } = await this.annotationSync.applyExchangeAck({
+          userId: user.id,
+          source: 'koreader',
+          deviceId: dto.deviceId,
+          bookFileId: match.bookFileId,
+          applied: book.applied.map((entry) => ({
+            serverId: entry.serverId,
+            version: entry.version,
+            status: entry.status,
+            verified: entry.verified,
+            corrected: entry.corrected,
+            pos0: entry.pos0 ?? null,
+            pos1: entry.pos1 ?? null,
+            pageno: entry.pageno ?? null,
+            datetimeUpdated: entry.datetimeUpdated,
+          })),
+          deleted: book.deleted,
+          converterVersion: this.positionConverter.version,
+        });
+        results.push({ hash, acked });
+      }
+
+      this.logger.log(
+        `[${ACK_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} books=${results.length} unmatched=${unmatched.length} - annotation exchange ack applied`,
+      );
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${ACK_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - annotation exchange ack failed`,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * KOReader datetimes are device-local wall clock with no timezone; minting them
+   * from server UTC time can land in the device's future, which freezes the
+   * device-side upload watermark. The offset shifts mints into the device frame.
+   */
+  private deviceClockOffsetMs(deviceTime: string | undefined): number {
+    if (!deviceTime) return 0;
+    const parsed = Date.parse(`${deviceTime.replace(' ', 'T')}Z`);
+    return Number.isNaN(parsed) ? 0 : parsed - Date.now();
+  }
+
+  private async exchangeBook(
+    userId: number,
+    deviceId: string,
+    hash: string,
+    bookId: number,
+    bookFileId: number,
+    book: ExchangeBookDto,
+    deviceClockOffsetMs: number,
+  ): Promise<ExchangeBookResult> {
+    const ingest = await this.annotationSync.ingestDeviceAnnotations({
+      userId,
+      source: 'koreader',
+      deviceId,
+      bookId,
+      bookFileId,
+      annotations: book.changes.map((change) => this.toIncoming(change)),
+    });
+
+    let deviceDeleted = 0;
+    if (book.keysComplete) {
+      deviceDeleted = await this.annotationSync.detectDeviceDeletions({
+        userId,
+        source: 'koreader',
+        deviceId,
+        bookId,
+        presentKeys: book.keys,
+      });
+    }
+
+    const pushDown = await this.annotationSync.computePushDown(userId, 'koreader', deviceId, bookId, PUSH_DOWN_PAGE);
+
+    const deleteEntries: ExchangeDeleteEntry[] = pushDown.deletes.map(({ state, annotation }) => ({
+      serverId: annotation.id,
+      key: state.externalKey,
+      datetime: state.externalCreatedAt ?? annotation.deviceCreatedAt,
+    }));
+
+    const editEntries: ExchangeEditEntry[] = pushDown.edits.map(({ state, annotation }) => ({
+      serverId: annotation.id,
+      version: annotation.version,
+      key: state.externalKey,
+      datetime: annotation.deviceCreatedAt,
+      datetimeUpdated: this.mintEditDatetime(annotation, deviceClockOffsetMs),
+      drawer: drawerFromStyle(annotation.style),
+      color: koreaderColorFromHex(annotation.color),
+      text: annotation.text,
+      note: annotation.note,
+      chapter: annotation.chapterTitle,
+    }));
+
+    let conversionBudget = CONVERSION_BUDGET_PER_REQUEST;
+    let skippedNoPosition = 0;
+    const addEntries: ExchangeAddEntry[] = [];
+    for (const annotation of pushDown.adds) {
+      const entry = await this.buildAddEntry(userId, bookId, bookFileId, annotation, conversionBudget > 0, deviceClockOffsetMs);
+      if (entry === 'converted') {
+        conversionBudget -= 1;
+        continue;
+      }
+      if (entry == null) {
+        skippedNoPosition += 1;
+        continue;
+      }
+      addEntries.push(entry);
+    }
+
+    return {
+      hash,
+      bookId,
+      applied: { ...ingest, deviceDeleted },
+      toApply: { add: addEntries, edit: editEntries, delete: deleteEntries },
+      more: pushDown.more,
+      skippedNoPosition,
+    };
+  }
+
+  /**
+   * Builds an add entry for the device, converting the CFI position to an xpointer
+   * when needed (bounded per request). Returns null when no usable device position
+   * exists, or the literal 'converted' when a conversion was attempted this round
+   * (the entry is picked up by the next exchange call once stored).
+   */
+  private async buildAddEntry(
+    userId: number,
+    bookId: number,
+    bookFileId: number,
+    annotation: AnnotationRow,
+    mayConvert: boolean,
+    deviceClockOffsetMs: number,
+  ): Promise<ExchangeAddEntry | null | 'converted'> {
+    const pdfPosition = await this.annotationSync.findDevicePositionFor(annotation.id, 'pdf');
+    const xpointerPosition = pdfPosition ? null : await this.annotationSync.findDevicePositionFor(annotation.id, 'xpointer');
+    const converterVersion = this.positionConverter.version;
+
+    const position = pdfPosition ?? xpointerPosition;
+    const usable =
+      position?.pos0 != null && position.status !== 'failed' && (position.converterVersion == null || position.converterVersion >= converterVersion);
+    const retryable = position == null || position.converterVersion == null || position.converterVersion < converterVersion;
+
+    if (!usable && pdfPosition == null) {
+      if (!mayConvert || !retryable) return null;
+      await this.convertCfiToXpointer(userId, bookId, bookFileId, annotation, deviceClockOffsetMs);
+      return 'converted';
+    }
+    if (!usable || !position?.pos0) return null;
+
+    const datetime = await this.annotationSync.ensureDeviceCreatedAt(userId, bookId, annotation, deviceClockOffsetMs);
+    const pageno = ((position.extras as { pageno?: number } | null)?.pageno ?? null) as number | null;
+    return {
+      serverId: annotation.id,
+      version: annotation.version,
+      datetime,
+      datetimeUpdated: annotation.deviceUpdatedAt,
+      drawer: drawerFromStyle(annotation.style),
+      color: koreaderColorFromHex(annotation.color),
+      text: annotation.text,
+      note: annotation.note,
+      chapter: annotation.chapterTitle,
+      posFormat: position.format as 'xpointer' | 'pdf',
+      pos0: position.pos0,
+      pos1: position.pos1,
+      pageno,
+    };
+  }
+
+  private async convertCfiToXpointer(
+    userId: number,
+    bookId: number,
+    bookFileId: number,
+    annotation: AnnotationRow,
+    deviceClockOffsetMs: number,
+  ): Promise<void> {
+    const cfiPosition = await this.annotationSync.findDevicePositionFor(annotation.id, 'cfi');
+    if (!cfiPosition?.pos0) {
+      await this.annotationSync.upsertGeneratedPosition({
+        annotationId: annotation.id,
+        userId,
+        bookFileId,
+        format: 'xpointer',
+        pos0: '',
+        pos1: null,
+        status: 'failed',
+        converterVersion: this.positionConverter.version,
+      });
+      return;
+    }
+
+    const outcome = await this.positionConverter.cfiToXpointer({
+      bookFileId,
+      cfi: cfiPosition.pos0,
+      text: annotation.text || null,
+    });
+    if (outcome.status === 'failed' || !outcome.pos0 || !outcome.pos1) {
+      await this.annotationSync.upsertGeneratedPosition({
+        annotationId: annotation.id,
+        userId,
+        bookFileId,
+        format: 'xpointer',
+        pos0: '',
+        pos1: null,
+        status: 'failed',
+        converterVersion: this.positionConverter.version,
+        extras: outcome.reason ? { reason: outcome.reason } : null,
+      });
+      return;
+    }
+
+    await this.annotationSync.ensureDeviceCreatedAt(userId, bookId, annotation, deviceClockOffsetMs);
+    await this.annotationSync.upsertGeneratedPosition({
+      annotationId: annotation.id,
+      userId,
+      bookFileId,
+      format: 'xpointer',
+      pos0: outcome.pos0,
+      pos1: outcome.pos1,
+      status: 'pending',
+      converterVersion: this.positionConverter.version,
+      extras: outcome.chapterIndex != null ? { chapterIndex: outcome.chapterIndex, converterStatus: outcome.status } : null,
+    });
+  }
+
+  /**
+   * datetime_updated pushed to the device must be ahead of any device edit we already
+   * ingested, or the device-side dedup would treat the pushed edit as stale.
+   */
+  private mintEditDatetime(annotation: AnnotationRow, deviceClockOffsetMs: number): string {
+    const candidate = formatDeviceDatetime(new Date(annotation.updatedAt.getTime() + deviceClockOffsetMs));
+    if (annotation.deviceUpdatedAt && annotation.deviceUpdatedAt >= candidate) {
+      const bumped = new Date(`${annotation.deviceUpdatedAt.replace(' ', 'T')}Z`);
+      bumped.setUTCSeconds(bumped.getUTCSeconds() + 1);
+      return formatDeviceDatetime(bumped);
+    }
+    return candidate;
+  }
+
+  private toIncoming(change: KoreaderAnnotationDto): IncomingDeviceAnnotation {
+    return {
+      datetime: change.datetime,
+      datetimeUpdated: change.datetimeUpdated ?? null,
+      drawer: change.drawer,
+      color: change.color ?? null,
+      text: change.text ?? null,
+      note: change.note ?? null,
+      chapter: change.chapter ?? null,
+      pageno: change.pageno ?? null,
+      posFormat: change.posFormat as IncomingDeviceAnnotation['posFormat'],
+      pos0: change.pos0,
+      pos1: change.pos1 ?? null,
+    };
+  }
+}
diff --git a/server/src/modules/koreader/koreader-catalog.controller.test.ts b/server/src/modules/koreader/koreader-catalog.controller.test.ts
new file mode 100644
index 000000000..f52c2391d
--- /dev/null
+++ b/server/src/modules/koreader/koreader-catalog.controller.test.ts
@@ -0,0 +1,53 @@
+import { GUARDS_METADATA } from '@nestjs/common/constants';
+
+import { IS_PUBLIC_KEY } from '../../common/decorators/public.decorator';
+import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderCatalogController } from './koreader-catalog.controller';
+
+function makeController() {
+  const catalogService = {
+    getRoot: vi.fn().mockReturnValue({ sections: [] }),
+    getSectionEntries: vi.fn().mockResolvedValue({ section: 'libraries', items: [] }),
+    getBooksPage: vi
+      .fn()
+      .mockResolvedValue({ items: [], total: 0, page: 1, size: 20, hasNext: false, hasPrevious: false, nextUrl: null, previousUrl: null }),
+    getBookDetail: vi.fn().mockResolvedValue({ id: 10 }),
+    setReadStatus: vi.fn().mockResolvedValue({ readStatus: 'reading' }),
+    setRating: vi.fn().mockResolvedValue({ rating: 4 }),
+    streamThumbnail: vi.fn().mockResolvedValue(undefined),
+    streamFile: vi.fn().mockResolvedValue(undefined),
+  };
+  return { controller: new KoreaderCatalogController(catalogService as never), catalogService };
+}
+
+describe('KoreaderCatalogController', () => {
+  it('is public only for the global JWT guard and uses the KOReader auth guard', () => {
+    expect(Reflect.getMetadata(IS_PUBLIC_KEY, KoreaderCatalogController)).toBe(true);
+    expect(Reflect.getMetadata(GUARDS_METADATA, KoreaderCatalogController)).toEqual([KoreaderAuthGuard]);
+  });
+
+  it('forwards catalog routes to the service', async () => {
+    const { controller, catalogService } = makeController();
+    const user = { id: 7 } as never;
+    const reply = { send: vi.fn() } as never;
+    const query = { page: 1, size: 20 } as never;
+    const sectionQuery = { page: 1 } as never;
+
+    expect(controller.root()).toEqual({ sections: [] });
+    await expect(controller.sections(user, 'libraries', sectionQuery)).resolves.toEqual({ section: 'libraries', items: [] });
+    await expect(controller.books(user, query)).resolves.toEqual(expect.objectContaining({ total: 0 }));
+    await expect(controller.bookDetail(user, 10)).resolves.toEqual({ id: 10 });
+    await expect(controller.setReadStatus(user, 10, { status: 'reading' } as never)).resolves.toEqual({ readStatus: 'reading' });
+    await expect(controller.setRating(user, 10, { rating: 4 } as never)).resolves.toEqual({ rating: 4 });
+    await controller.thumbnail(user, 10, reply, '"etag"');
+    await controller.download(user, 100, reply);
+
+    expect(catalogService.getSectionEntries).toHaveBeenCalledWith(user, 'libraries', sectionQuery);
+    expect(catalogService.getBooksPage).toHaveBeenCalledWith(user, query);
+    expect(catalogService.getBookDetail).toHaveBeenCalledWith(user, 10);
+    expect(catalogService.setReadStatus).toHaveBeenCalledWith(user, 10, 'reading');
+    expect(catalogService.setRating).toHaveBeenCalledWith(user, 10, 4);
+    expect(catalogService.streamThumbnail).toHaveBeenCalledWith(user, 10, reply, '"etag"');
+    expect(catalogService.streamFile).toHaveBeenCalledWith(user, 100, reply);
+  });
+});
diff --git a/server/src/modules/koreader/koreader-catalog.controller.ts b/server/src/modules/koreader/koreader-catalog.controller.ts
new file mode 100644
index 000000000..c2814342f
--- /dev/null
+++ b/server/src/modules/koreader/koreader-catalog.controller.ts
@@ -0,0 +1,70 @@
+import { Body, Controller, Get, Header, Headers, Param, ParseIntPipe, Put, Query, Res, UseGuards } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
+
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+import { Public } from '../../common/decorators/public.decorator';
+import type { RequestUser } from '../../common/types/request-user';
+import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderCatalogService } from './koreader-catalog.service';
+import {
+  KoreaderCatalogBooksQueryDto,
+  KoreaderCatalogSectionQueryDto,
+  KoreaderCatalogSetRatingDto,
+  KoreaderCatalogSetReadStatusDto,
+} from './dto/koreader-catalog-query.dto';
+
+@Public()
+@UseGuards(KoreaderAuthGuard)
+@Controller('koreader/plugin/catalog')
+export class KoreaderCatalogController {
+  constructor(private readonly catalogService: KoreaderCatalogService) {}
+
+  @Get('root')
+  @Header('Cache-Control', 'private, max-age=30')
+  root() {
+    return this.catalogService.getRoot();
+  }
+
+  @Get('sections/:section')
+  @Header('Cache-Control', 'private, max-age=30')
+  sections(@CurrentUser() user: RequestUser, @Param('section') section: string, @Query() query: KoreaderCatalogSectionQueryDto) {
+    return this.catalogService.getSectionEntries(user, section, query);
+  }
+
+  @Get('books')
+  @Header('Cache-Control', 'private, max-age=30')
+  books(@CurrentUser() user: RequestUser, @Query() query: KoreaderCatalogBooksQueryDto) {
+    return this.catalogService.getBooksPage(user, query);
+  }
+
+  @Get('books/:bookId')
+  @Header('Cache-Control', 'private, max-age=30')
+  bookDetail(@CurrentUser() user: RequestUser, @Param('bookId', ParseIntPipe) bookId: number) {
+    return this.catalogService.getBookDetail(user, bookId);
+  }
+
+  @Put('books/:bookId/read-status')
+  setReadStatus(@CurrentUser() user: RequestUser, @Param('bookId', ParseIntPipe) bookId: number, @Body() body: KoreaderCatalogSetReadStatusDto) {
+    return this.catalogService.setReadStatus(user, bookId, body.status);
+  }
+
+  @Put('books/:bookId/rating')
+  setRating(@CurrentUser() user: RequestUser, @Param('bookId', ParseIntPipe) bookId: number, @Body() body: KoreaderCatalogSetRatingDto) {
+    return this.catalogService.setRating(user, bookId, body.rating ?? null);
+  }
+
+  @Get('books/:bookId/thumbnail')
+  thumbnail(
+    @CurrentUser() user: RequestUser,
+    @Param('bookId', ParseIntPipe) bookId: number,
+    @Res() reply: FastifyReply,
+    @Headers('if-none-match') ifNoneMatch?: string,
+  ) {
+    return this.catalogService.streamThumbnail(user, bookId, reply, ifNoneMatch);
+  }
+
+  @Get('files/:fileId/download')
+  download(@CurrentUser() user: RequestUser, @Param('fileId', ParseIntPipe) fileId: number, @Res() reply: FastifyReply) {
+    return this.catalogService.streamFile(user, fileId, reply);
+  }
+}
diff --git a/server/src/modules/koreader/koreader-catalog.service.test.ts b/server/src/modules/koreader/koreader-catalog.service.test.ts
new file mode 100644
index 000000000..3992fe179
--- /dev/null
+++ b/server/src/modules/koreader/koreader-catalog.service.test.ts
@@ -0,0 +1,439 @@
+vi.mock('fs', () => ({
+  createReadStream: vi.fn(() => 'stream'),
+}));
+
+vi.mock('fs/promises', () => ({
+  stat: vi.fn(),
+}));
+
+import { createReadStream } from 'fs';
+import { stat } from 'fs/promises';
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import type { MockedFunction } from 'vitest';
+
+import { makeUser } from '../../common/test-utils/make-user';
+import { KoreaderCatalogBooksQueryDto } from './dto/koreader-catalog-query.dto';
+import { KoreaderCatalogService } from './koreader-catalog.service';
+
+const mockCreateReadStream = createReadStream as MockedFunction<typeof createReadStream>;
+const mockStat = stat as MockedFunction<typeof stat>;
+
+function makeReply() {
+  const reply = {
+    header: vi.fn(),
+    status: vi.fn(),
+    type: vi.fn(),
+    send: vi.fn(),
+  };
+  reply.header.mockReturnValue(reply);
+  reply.status.mockReturnValue(reply);
+  reply.type.mockReturnValue(reply);
+  return reply;
+}
+
+function makeDetail(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 10,
+    libraryId: 1,
+    libraryName: 'Main',
+    status: 'present',
+    folderPath: '/books/dune',
+    addedAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-02-01T00:00:00.000Z'),
+    title: 'Dune',
+    subtitle: null,
+    description: 'Desert planet',
+    isbn10: null,
+    isbn13: '9780441172719',
+    publisher: 'Ace',
+    publishedYear: 1965,
+    language: 'en',
+    pageCount: 412,
+    seriesId: null,
+    seriesName: 'Dune',
+    seriesIndex: 1,
+    seriesMemberships: [],
+    rating: 5,
+    coverSource: 'extracted',
+    providerIds: {},
+    authors: [{ id: 1, name: 'Frank Herbert', sortName: 'Herbert, Frank' }],
+    genres: ['Science Fiction'],
+    tags: ['classic'],
+    files: [
+      {
+        id: 100,
+        format: 'epub',
+        role: 'primary',
+        sizeBytes: 1234,
+        absolutePath: '/books/dune.epub',
+        createdAt: new Date('2026-01-01T00:00:00.000Z'),
+        filename: 'dune.epub',
+        durationSeconds: null,
+      },
+    ],
+    lastWrittenAt: null,
+    metadataScore: 90,
+    readStatus: { status: 'reading' },
+    audioMetadata: null,
+    formatPriority: [],
+    comicMetadata: null,
+    lockedFields: [],
+    collections: [{ id: 5, name: 'Favorites' }],
+    fileWriteStatus: { enabled: false, reason: 'library_disabled', writableFormats: [], writableFields: [] },
+    ...overrides,
+  };
+}
+
+function makeService() {
+  const opdsBookService = {
+    getAccessibleLibraries: vi.fn().mockResolvedValue([{ id: 1, name: 'Main', bookCount: 99 }]),
+    getUserCollections: vi.fn().mockResolvedValue([{ id: 2, name: 'Favorites', bookCount: 99 }]),
+    getUserSmartScopes: vi.fn().mockResolvedValue([{ id: 3, name: 'Unread', icon: 'book-open' }]),
+    getDistinctAuthorsPage: vi.fn().mockResolvedValue({ items: [{ name: 'Frank Herbert', bookCount: 2 }], hasNext: false }),
+    getDistinctSeriesPage: vi.fn().mockResolvedValue({ items: [{ name: 'Dune', bookCount: 6 }], hasNext: false }),
+    getBooksPage: vi.fn().mockResolvedValue({ entries: [], total: 0 }),
+  };
+  const bookService = {
+    getDetail: vi.fn().mockResolvedValue(makeDetail()),
+    verifyBookAccess: vi.fn().mockResolvedValue(undefined),
+    bulkSetRating: vi.fn().mockResolvedValue(undefined),
+    verifyFileAccess: vi.fn().mockResolvedValue({
+      id: 100,
+      role: 'content',
+      bookId: 10,
+      libraryId: 1,
+      absolutePath: '/books/dune.epub',
+      format: 'epub',
+    }),
+  };
+  const bookReadService = {
+    findProgressByBook: vi.fn().mockResolvedValue([
+      {
+        fileId: 100,
+        percentage: 47.4,
+        koreaderProgress: '/body/DocFragment[2]/body/p[1]',
+        updatedAt: new Date('2026-03-01T00:00:00.000Z'),
+      },
+    ]),
+    findProgressByBooks: vi.fn().mockResolvedValue([
+      {
+        bookId: 10,
+        fileId: 100,
+        percentage: 47.4,
+        koreaderProgress: '/body/DocFragment[2]/body/p[1]',
+        updatedAt: new Date('2026-03-01T00:00:00.000Z'),
+      },
+    ]),
+  };
+  const userBookStatusService = {
+    findOne: vi.fn().mockResolvedValue({ status: 'reading' }),
+    findByBookIds: vi.fn().mockResolvedValue(new Map([[10, { status: 'reading' }]])),
+    setManual: vi.fn().mockResolvedValue(undefined),
+  };
+
+  const service = new KoreaderCatalogService(
+    opdsBookService as never,
+    bookService as never,
+    bookReadService as never,
+    userBookStatusService as never,
+    { appDataPath: '/data', bookDockPath: '/data/book-dock' },
+  );
+
+  return { service, opdsBookService, bookService, bookReadService, userBookStatusService };
+}
+
+describe('KoreaderCatalogService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStat.mockResolvedValue({ size: 1234, mtimeMs: 5000 } as never);
+  });
+
+  it('returns root catalog sections', () => {
+    const { service } = makeService();
+
+    expect(service.getRoot().sections.map((section) => section.id)).toEqual([
+      'continue-reading',
+      'recent',
+      'libraries',
+      'collections',
+      'smart-scopes',
+      'authors',
+      'series',
+      'all-books',
+    ]);
+  });
+
+  it('exposes the continue-reading shortcut as a recently_read reading scope', () => {
+    const { service } = makeService();
+
+    const entry = service.getRoot().sections.find((section) => section.id === 'continue-reading');
+
+    expect(entry).toEqual(
+      expect.objectContaining({
+        section: 'continue-reading',
+        booksHref: '/api/v1/koreader/plugin/catalog/books?sort=recently_read&readStatus=reading',
+      }),
+    );
+  });
+
+  it('forwards read-status, format, and id filters to the books query', async () => {
+    const { service, opdsBookService } = makeService();
+    const user = makeUser({ id: 4 });
+
+    const query = Object.assign(new KoreaderCatalogBooksQueryDto(), {
+      page: 1,
+      size: 20,
+      sort: 'recently_read',
+      readStatus: 'reading',
+      format: 'EPUB',
+      ids: [3, 1, 2],
+    });
+    await service.getBooksPage(user, query);
+
+    expect(opdsBookService.getBooksPage).toHaveBeenCalledWith(
+      4,
+      'recently_read',
+      1,
+      20,
+      { readStatus: 'reading', format: 'epub', ids: [3, 1, 2] },
+      false,
+      user.contentFilters,
+    );
+  });
+
+  it('maps explicit sort order to ascending/descending variants', async () => {
+    const { service, opdsBookService } = makeService();
+    const user = makeUser({ id: 11 });
+
+    await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'title', order: 'desc' }));
+    expect(opdsBookService.getBooksPage).toHaveBeenLastCalledWith(11, 'title_desc', 1, 20, {}, false, user.contentFilters);
+
+    await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'recently_added', order: 'asc' }));
+    expect(opdsBookService.getBooksPage).toHaveBeenLastCalledWith(11, 'recent_asc', 1, 20, {}, false, user.contentFilters);
+
+    await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'recently_read', order: 'asc' }));
+    expect(opdsBookService.getBooksPage).toHaveBeenLastCalledWith(11, 'recently_read_asc', 1, 20, {}, false, user.contentFilters);
+  });
+
+  it('falls back to the natural direction when no order is given', async () => {
+    const { service, opdsBookService } = makeService();
+    const user = makeUser({ id: 12 });
+
+    await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'title' }));
+    expect(opdsBookService.getBooksPage).toHaveBeenLastCalledWith(12, 'title_asc', 1, 20, {}, false, user.contentFilters);
+
+    await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'recently_updated' }));
+    expect(opdsBookService.getBooksPage).toHaveBeenLastCalledWith(12, 'updated', 1, 20, {}, false, user.contentFilters);
+  });
+
+  it('maps section entries to scoped book links and content-filtered counts', async () => {
+    const { service, opdsBookService } = makeService();
+    opdsBookService.getBooksPage.mockResolvedValue({ entries: [], total: 3 });
+    const user = makeUser({ id: 7 });
+
+    const libraries = await service.getSectionEntries(user, 'libraries');
+    const authors = await service.getSectionEntries(user, 'authors');
+    const series = await service.getSectionEntries(user, 'series');
+
+    expect(libraries.items[0]).toEqual(
+      expect.objectContaining({
+        id: '1',
+        title: 'Main',
+        section: 'libraries',
+        count: 3,
+        booksHref: '/api/v1/koreader/plugin/catalog/books?sort=title&libraryId=1',
+      }),
+    );
+    expect(opdsBookService.getBooksPage).toHaveBeenCalledWith(7, 'title_asc', 1, 1, { libraryId: 1 }, false, user.contentFilters);
+    expect(authors.items[0]!.booksHref).toContain('author=Frank+Herbert');
+    expect(series.items.map((item) => item.title)).toEqual(['Dune']);
+  });
+
+  it('rejects unknown section names', async () => {
+    const { service } = makeService();
+    await expect(service.getSectionEntries(makeUser(), 'bogus')).rejects.toThrow(BadRequestException);
+  });
+
+  it('returns paged book lists with sort mapping, scoped filters, progress, and status', async () => {
+    const { service, opdsBookService } = makeService();
+    const user = makeUser({ id: 9, isSuperuser: true });
+    opdsBookService.getBooksPage.mockResolvedValueOnce({
+      total: 50,
+      entries: [
+        {
+          id: 10,
+          title: 'Dune',
+          folderPath: '/books/dune',
+          addedAt: new Date('2026-01-01T00:00:00.000Z'),
+          updatedAt: new Date('2026-02-01T00:00:00.000Z'),
+          description: null,
+          seriesName: 'Dune',
+          seriesIndex: 1,
+          language: 'en',
+          publisher: 'Ace',
+          isbn13: null,
+          hasCover: true,
+          authors: ['Frank Herbert'],
+          files: [
+            { id: 100, format: 'epub' },
+            { id: 101, format: 'pdf' },
+          ],
+        },
+      ],
+    });
+
+    const query = Object.assign(new KoreaderCatalogBooksQueryDto(), {
+      page: 2,
+      size: 20,
+      sort: 'recently_updated',
+      q: ' dune ',
+      libraryId: 1,
+    });
+    const result = await service.getBooksPage(user, query);
+
+    expect(opdsBookService.getBooksPage).toHaveBeenCalledWith(9, 'updated', 2, 20, { libraryId: 1, q: 'dune' }, true, user.contentFilters);
+    expect(result.items[0]).toEqual(
+      expect.objectContaining({
+        id: 10,
+        title: 'Dune',
+        progressPercentage: 47.4,
+        readStatus: 'reading',
+        formats: ['epub', 'pdf'],
+        thumbnailUrl: '/api/v1/koreader/plugin/catalog/books/10/thumbnail',
+      }),
+    );
+    expect(result.previousUrl).toContain('page=1');
+    expect(result.nextUrl).toContain('page=3');
+  });
+
+  it('maps book detail without exposing absolute paths', async () => {
+    const { service } = makeService();
+
+    const detail = await service.getBookDetail(makeUser({ id: 7 }), 10);
+
+    expect(detail).toEqual(
+      expect.objectContaining({
+        id: 10,
+        title: 'Dune',
+        authors: ['Frank Herbert'],
+        libraryName: 'Main',
+        progress: expect.objectContaining({ fileId: 100, percentage: 47.4 }),
+        files: [
+          {
+            id: 100,
+            format: 'epub',
+            role: 'primary',
+            sizeBytes: 1234,
+            durationSeconds: null,
+            downloadUrl: '/api/v1/koreader/plugin/catalog/files/100/download',
+          },
+        ],
+      }),
+    );
+    expect(JSON.stringify(detail)).not.toContain('/books/dune.epub');
+  });
+
+  it('streams thumbnails with access checks and etags', async () => {
+    const { service, bookService } = makeService();
+    const reply = makeReply();
+
+    await service.streamThumbnail(makeUser(), 10, reply as never);
+
+    expect(bookService.verifyBookAccess).toHaveBeenCalledWith(10, expect.objectContaining({ id: 1 }));
+    expect(reply.header).toHaveBeenCalledWith('ETag', '"5000"');
+    expect(reply.type).toHaveBeenCalledWith('image/jpeg');
+    expect(mockCreateReadStream).toHaveBeenCalledWith('/data/covers/10/thumbnail.jpg');
+
+    const cachedReply = makeReply();
+    await service.streamThumbnail(makeUser(), 10, cachedReply as never, '"5000"');
+    expect(cachedReply.status).toHaveBeenCalledWith(304);
+  });
+
+  it('streams content files without LibraryDownload permission', async () => {
+    const { service, bookService } = makeService();
+    const reply = makeReply();
+
+    await service.streamFile(makeUser({ permissions: [] }), 100, reply as never);
+
+    expect(bookService.verifyFileAccess).toHaveBeenCalledWith(100, expect.objectContaining({ permissions: [] }));
+    expect(reply.header).toHaveBeenCalledWith('Content-Disposition', 'attachment; filename="Dune - Frank Herbert.epub"');
+    expect(reply.header).toHaveBeenCalledWith('Content-Length', 1234);
+    expect(reply.type).toHaveBeenCalledWith('application/epub+zip');
+    expect(mockCreateReadStream).toHaveBeenCalledWith('/books/dune.epub');
+  });
+
+  it('rejects non-content file downloads and missing thumbnails', async () => {
+    const { service, bookService } = makeService();
+    bookService.verifyFileAccess.mockResolvedValueOnce({
+      id: 200,
+      role: 'cover',
+      bookId: 10,
+      libraryId: 1,
+      absolutePath: '/cover.jpg',
+      format: 'jpg',
+    });
+
+    await expect(service.streamFile(makeUser(), 200, makeReply() as never)).rejects.toThrow(NotFoundException);
+
+    mockStat.mockRejectedValueOnce(new Error('missing'));
+    await expect(service.streamThumbnail(makeUser(), 10, makeReply() as never)).rejects.toThrow(NotFoundException);
+  });
+
+  it('paginates author sections with a filter and navigation links', async () => {
+    const { service, opdsBookService } = makeService();
+    opdsBookService.getDistinctAuthorsPage.mockResolvedValueOnce({ items: [{ name: 'Frank Herbert', bookCount: 2 }], hasNext: true });
+    const user = makeUser({ id: 7 });
+
+    const res = await service.getSectionEntries(user, 'authors', { page: 2, q: 'her' });
+
+    expect(opdsBookService.getDistinctAuthorsPage).toHaveBeenCalledWith(7, { q: 'her', limit: 60, offset: 60 }, false, user.contentFilters);
+    expect(res.page).toBe(2);
+    expect(res.hasNext).toBe(true);
+    expect(res.nextUrl).toContain('sections/authors?page=3&q=her');
+    expect(res.previousUrl).toContain('sections/authors?q=her');
+    expect(res.query).toBe('her');
+  });
+
+  it('includes a series read-through summary on series-scoped pages', async () => {
+    const { service, opdsBookService } = makeService();
+    opdsBookService.getBooksPage
+      .mockResolvedValueOnce({ entries: [], total: 6 })
+      .mockResolvedValueOnce({ entries: [], total: 6 })
+      .mockResolvedValueOnce({ entries: [], total: 2 });
+    const user = makeUser({ id: 7 });
+
+    const result = await service.getBooksPage(user, Object.assign(new KoreaderCatalogBooksQueryDto(), { series: 'Dune', sort: 'series' }));
+
+    expect(result.seriesSummary).toEqual({ total: 6, finished: 2 });
+  });
+
+  it('omits the series summary for non-series listings', async () => {
+    const { service } = makeService();
+    const result = await service.getBooksPage(makeUser({ id: 7 }), Object.assign(new KoreaderCatalogBooksQueryDto(), { sort: 'title' }));
+    expect(result.seriesSummary).toBeNull();
+  });
+
+  it('sets read status through ownership-checked services', async () => {
+    const { service, bookService, userBookStatusService } = makeService();
+    const user = makeUser({ id: 7 });
+
+    const res = await service.setReadStatus(user, 10, 'reading');
+
+    expect(bookService.verifyBookAccess).toHaveBeenCalledWith(10, user);
+    expect(userBookStatusService.setManual).toHaveBeenCalledWith(7, 10, 'reading');
+    expect(res).toEqual({ readStatus: 'reading' });
+  });
+
+  it('sets and clears rating through the book service', async () => {
+    const { service, bookService } = makeService();
+    const user = makeUser({ id: 7 });
+
+    const res = await service.setRating(user, 10, 4);
+    expect(bookService.bulkSetRating).toHaveBeenCalledWith([10], 4, user);
+    expect(res).toEqual({ rating: 4 });
+
+    const cleared = await service.setRating(user, 10, null);
+    expect(bookService.bulkSetRating).toHaveBeenLastCalledWith([10], null, user);
+    expect(cleared).toEqual({ rating: null });
+  });
+});
diff --git a/server/src/modules/koreader/koreader-catalog.service.ts b/server/src/modules/koreader/koreader-catalog.service.ts
new file mode 100644
index 000000000..d52192473
--- /dev/null
+++ b/server/src/modules/koreader/koreader-catalog.service.ts
@@ -0,0 +1,578 @@
+import { createReadStream } from 'fs';
+import { stat } from 'fs/promises';
+import { basename, extname } from 'path';
+
+import { BadRequestException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import type { ConfigType } from '@nestjs/config';
+import type { FastifyReply } from 'fastify';
+
+import type {
+  KoreaderCatalogBookDetail,
+  KoreaderCatalogBookListItem,
+  KoreaderCatalogEntry,
+  KoreaderCatalogFile,
+  KoreaderCatalogPage,
+  KoreaderCatalogProgress,
+  KoreaderCatalogRatingResult,
+  KoreaderCatalogReadStatusResult,
+  KoreaderCatalogSection,
+  KoreaderCatalogSectionResponse,
+  KoreaderCatalogSeriesSummary,
+  KoreaderCatalogSettableReadStatus,
+  KoreaderCatalogSort,
+  KoreaderCatalogSortOrder,
+} from '@bookorbit/types';
+import { bookThumbnailPath } from '../../common/book-cover-storage';
+import { MAX_OFFSET_ROWS, isOffsetWithinLimit } from '../../common/constants/pagination.constants';
+import { imageContentTypeFromPath } from '../../common/image-content-type';
+import type { RequestUser } from '../../common/types/request-user';
+import { storageConfig } from '../../config/config';
+import { BookReadService } from '../book/book-read.service';
+import { BookService } from '../book/book.service';
+import type { BookDetailDto } from '../book/dto/book-detail.dto';
+import { fileMimeType } from '../opds/opds-xml.helpers';
+import { OpdsBookEntry, OpdsBookService } from '../opds/opds-book.service';
+import { UserBookStatusService } from '../user-book-status/user-book-status.service';
+import { KoreaderCatalogBooksQueryDto } from './dto/koreader-catalog-query.dto';
+
+type OpdsSortOrder = Parameters<OpdsBookService['getBooksPage']>[1];
+type BookProgressRow = Awaited<ReturnType<BookReadService['findProgressByBook']>>[number];
+type ProgressCandidate = BookProgressRow & { percentage: number; updatedAt: Date };
+type BatchProgressRow = Awaited<ReturnType<BookReadService['findProgressByBooks']>>[number];
+type BatchProgressCandidate = BatchProgressRow & { percentage: number; updatedAt: Date };
+
+const CATALOG_BASE = '/api/v1/koreader/plugin/catalog';
+const AUTHOR_SERIES_PAGE_SIZE = 60;
+
+const NATURAL_SORT_ORDER: Record<KoreaderCatalogSort, KoreaderCatalogSortOrder> = {
+  title: 'asc',
+  author: 'asc',
+  series: 'asc',
+  recently_added: 'desc',
+  recently_updated: 'desc',
+  recently_read: 'desc',
+};
+
+const ROOT_SECTIONS: KoreaderCatalogEntry[] = [
+  {
+    id: 'continue-reading',
+    title: 'Continue reading',
+    section: 'continue-reading',
+    booksHref: `${CATALOG_BASE}/books?sort=recently_read&readStatus=reading`,
+  },
+  {
+    id: 'recent',
+    title: 'Recently added',
+    section: 'recent',
+    booksHref: `${CATALOG_BASE}/books?sort=recently_added`,
+  },
+  {
+    id: 'libraries',
+    title: 'Libraries',
+    section: 'libraries',
+    href: `${CATALOG_BASE}/sections/libraries`,
+  },
+  {
+    id: 'collections',
+    title: 'Collections',
+    section: 'collections',
+    href: `${CATALOG_BASE}/sections/collections`,
+  },
+  {
+    id: 'smart-scopes',
+    title: 'SmartScopes',
+    section: 'smart-scopes',
+    href: `${CATALOG_BASE}/sections/smart-scopes`,
+  },
+  {
+    id: 'authors',
+    title: 'Authors',
+    section: 'authors',
+    href: `${CATALOG_BASE}/sections/authors`,
+  },
+  {
+    id: 'series',
+    title: 'Series',
+    section: 'series',
+    href: `${CATALOG_BASE}/sections/series`,
+  },
+  {
+    id: 'all-books',
+    title: 'All Books',
+    section: 'all-books',
+    booksHref: `${CATALOG_BASE}/books?sort=title`,
+  },
+];
+
+@Injectable()
+export class KoreaderCatalogService {
+  constructor(
+    private readonly opdsBookService: OpdsBookService,
+    private readonly bookService: BookService,
+    private readonly bookReadService: BookReadService,
+    private readonly userBookStatusService: UserBookStatusService,
+    @Inject(storageConfig.KEY) private readonly storage: ConfigType<typeof storageConfig>,
+  ) {}
+
+  getRoot(): { sections: KoreaderCatalogEntry[] } {
+    return { sections: ROOT_SECTIONS.map((section) => ({ ...section })) };
+  }
+
+  async getSectionEntries(user: RequestUser, section: string, query: { page?: number; q?: string } = {}): Promise<KoreaderCatalogSectionResponse> {
+    switch (section) {
+      case 'libraries':
+        return { section, items: await this.getLibraryEntries(user) };
+      case 'collections':
+        return { section, items: await this.getCollectionEntries(user) };
+      case 'smart-scopes':
+        return { section, items: await this.getSmartScopeEntries(user) };
+      case 'authors':
+        return this.getAuthorsSection(user, query);
+      case 'series':
+        return this.getSeriesSection(user, query);
+      default:
+        throw new BadRequestException('Unknown catalog section');
+    }
+  }
+
+  async getBooksPage(user: RequestUser, query: KoreaderCatalogBooksQueryDto): Promise<KoreaderCatalogPage<KoreaderCatalogBookListItem>> {
+    const page = query.page ?? 1;
+    const size = query.size ?? 20;
+    this.assertPaginationWindow(page, size);
+
+    const filters = this.buildBookFilters(query);
+    const sort = this.mapSort(query.sort ?? 'recently_added', query.order);
+    const { entries, total } = await this.opdsBookService.getBooksPage(user.id, sort, page, size, filters, user.isSuperuser, user.contentFilters);
+
+    const bookIds = entries.map((entry) => entry.id);
+    const [progressMap, statusMap, seriesSummary] = await Promise.all([
+      this.findBestProgressMap(user.id, bookIds),
+      this.userBookStatusService.findByBookIds(user.id, bookIds),
+      query.series ? this.computeSeriesSummary(user, query.series) : Promise.resolve(null),
+    ]);
+
+    const items = entries.map((entry) => this.mapBookListItem(entry, progressMap.get(entry.id) ?? null, statusMap.get(entry.id)?.status ?? null));
+    return this.paginate(items, total, page, size, query, seriesSummary);
+  }
+
+  async setReadStatus(user: RequestUser, bookId: number, status: KoreaderCatalogSettableReadStatus): Promise<KoreaderCatalogReadStatusResult> {
+    await this.bookService.verifyBookAccess(bookId, user);
+    await this.userBookStatusService.setManual(user.id, bookId, status);
+    return { readStatus: status };
+  }
+
+  async setRating(user: RequestUser, bookId: number, rating: number | null): Promise<KoreaderCatalogRatingResult> {
+    const normalized = rating ?? null;
+    await this.bookService.bulkSetRating([bookId], normalized, user);
+    return { rating: normalized };
+  }
+
+  async getBookDetail(user: RequestUser, bookId: number): Promise<KoreaderCatalogBookDetail> {
+    const detail = await this.bookService.getDetail(bookId, user);
+    const progress = await this.findBestProgress(user.id, detail.id);
+    return this.mapBookDetail(detail, progress);
+  }
+
+  async streamThumbnail(user: RequestUser, bookId: number, reply: FastifyReply, ifNoneMatch?: string): Promise<void> {
+    await this.bookService.verifyBookAccess(bookId, user);
+    const thumbnailPath = bookThumbnailPath(this.storage.appDataPath, bookId);
+    try {
+      const { mtimeMs } = await stat(thumbnailPath);
+      const etag = `"${Math.floor(mtimeMs)}"`;
+      if (ifNoneMatch === etag) {
+        reply.status(304).send();
+        return;
+      }
+      reply.header('Cache-Control', 'no-cache');
+      reply.header('Cross-Origin-Resource-Policy', 'cross-origin');
+      reply.header('ETag', etag);
+      reply.type(imageContentTypeFromPath(thumbnailPath));
+      reply.send(createReadStream(thumbnailPath));
+    } catch {
+      throw new NotFoundException('No thumbnail');
+    }
+  }
+
+  async streamFile(user: RequestUser, fileId: number, reply: FastifyReply): Promise<void> {
+    const file = await this.bookService.verifyFileAccess(fileId, user);
+    if (file.role !== 'content') {
+      throw new NotFoundException('File not found');
+    }
+
+    const detail = await this.bookService.getDetail(file.bookId, user);
+    const format = this.normalizeFormat(file.format);
+    const filename = this.downloadFilename(detail, fileId, format);
+
+    try {
+      const { size } = await stat(file.absolutePath);
+      reply.header('Content-Disposition', `attachment; filename="${filename}"`);
+      reply.header('Content-Length', size);
+      reply.type(fileMimeType(format));
+      reply.send(createReadStream(file.absolutePath));
+    } catch {
+      throw new NotFoundException('File not found on disk');
+    }
+  }
+
+  private async getLibraryEntries(user: RequestUser): Promise<KoreaderCatalogEntry[]> {
+    const rows = await this.opdsBookService.getAccessibleLibraries(user.id, user.isSuperuser);
+    return Promise.all(
+      rows.map(async (row) => {
+        const count = await this.countBooks(user, { libraryId: row.id });
+        return {
+          id: String(row.id),
+          title: row.name,
+          section: 'libraries',
+          count,
+          booksHref: this.booksHref({ libraryId: row.id, sort: 'title' }),
+        };
+      }),
+    );
+  }
+
+  private async getCollectionEntries(user: RequestUser): Promise<KoreaderCatalogEntry[]> {
+    const rows = await this.opdsBookService.getUserCollections(user.id);
+    return Promise.all(
+      rows.map(async (row) => {
+        const count = await this.countBooks(user, { collectionId: row.id });
+        return {
+          id: String(row.id),
+          title: row.name,
+          section: 'collections',
+          count,
+          booksHref: this.booksHref({ collectionId: row.id, sort: 'title' }),
+        };
+      }),
+    );
+  }
+
+  private async getSmartScopeEntries(user: RequestUser): Promise<KoreaderCatalogEntry[]> {
+    const rows = await this.opdsBookService.getUserSmartScopes(user.id);
+    return rows.map((row) => ({
+      id: String(row.id),
+      title: row.name,
+      section: 'smart-scopes',
+      icon: row.icon ?? null,
+      booksHref: this.booksHref({ smartScopeId: row.id, sort: 'title' }),
+    }));
+  }
+
+  private async getAuthorsSection(user: RequestUser, query: { page?: number; q?: string }): Promise<KoreaderCatalogSectionResponse> {
+    const page = query.page ?? 1;
+    const offset = (page - 1) * AUTHOR_SERIES_PAGE_SIZE;
+    const { items, hasNext } = await this.opdsBookService.getDistinctAuthorsPage(
+      user.id,
+      { q: query.q, limit: AUTHOR_SERIES_PAGE_SIZE, offset },
+      user.isSuperuser,
+      user.contentFilters,
+    );
+    const entries: KoreaderCatalogEntry[] = items.map((row) => ({
+      id: row.name,
+      title: row.name,
+      section: 'authors',
+      count: row.bookCount,
+      booksHref: this.booksHref({ author: row.name, sort: 'title' }),
+    }));
+    return this.buildSectionPage('authors', entries, page, hasNext, query.q);
+  }
+
+  private async getSeriesSection(user: RequestUser, query: { page?: number; q?: string }): Promise<KoreaderCatalogSectionResponse> {
+    const page = query.page ?? 1;
+    const offset = (page - 1) * AUTHOR_SERIES_PAGE_SIZE;
+    const { items, hasNext } = await this.opdsBookService.getDistinctSeriesPage(
+      user.id,
+      { q: query.q, limit: AUTHOR_SERIES_PAGE_SIZE, offset },
+      user.isSuperuser,
+      user.contentFilters,
+    );
+    const entries: KoreaderCatalogEntry[] = items.map((row) => ({
+      id: row.name,
+      title: row.name,
+      section: 'series',
+      count: row.bookCount,
+      booksHref: this.booksHref({ series: row.name, sort: 'series' }),
+    }));
+    return this.buildSectionPage('series', entries, page, hasNext, query.q);
+  }
+
+  private buildSectionPage(
+    section: KoreaderCatalogSection,
+    items: KoreaderCatalogEntry[],
+    page: number,
+    hasNext: boolean,
+    q?: string,
+  ): KoreaderCatalogSectionResponse {
+    const hasPrevious = page > 1;
+    return {
+      section,
+      items,
+      page,
+      hasNext,
+      hasPrevious,
+      nextUrl: hasNext ? this.sectionHref(section, page + 1, q) : null,
+      previousUrl: hasPrevious ? this.sectionHref(section, page - 1, q) : null,
+      query: q?.trim() ? q.trim() : null,
+    };
+  }
+
+  private sectionHref(section: KoreaderCatalogSection, page: number, q?: string): string {
+    const search = new URLSearchParams();
+    if (page > 1) search.set('page', String(page));
+    if (q?.trim()) search.set('q', q.trim());
+    const suffix = search.toString();
+    return suffix ? `${CATALOG_BASE}/sections/${section}?${suffix}` : `${CATALOG_BASE}/sections/${section}`;
+  }
+
+  private async countBooks(
+    user: RequestUser,
+    filters: { libraryId?: number; collectionId?: number; series?: string; readStatus?: 'unread' | 'reading' | 'finished' },
+  ): Promise<number> {
+    const result = await this.opdsBookService.getBooksPage(user.id, 'title_asc', 1, 1, filters, user.isSuperuser, user.contentFilters);
+    return result.total;
+  }
+
+  private async computeSeriesSummary(user: RequestUser, series: string): Promise<KoreaderCatalogSeriesSummary> {
+    const [total, finished] = await Promise.all([this.countBooks(user, { series }), this.countBooks(user, { series, readStatus: 'finished' })]);
+    return { total, finished };
+  }
+
+  private mapBookListItem(entry: OpdsBookEntry, progress: KoreaderCatalogProgress | null, readStatus: string | null): KoreaderCatalogBookListItem {
+    const formats = this.uniqueFormats(entry.files.map((file) => file.format));
+    return {
+      id: entry.id,
+      title: entry.title,
+      authors: entry.authors,
+      seriesName: entry.seriesName,
+      seriesIndex: entry.seriesIndex,
+      progressPercentage: progress?.percentage ?? null,
+      readStatus,
+      formats,
+      hasCover: entry.hasCover,
+      thumbnailUrl: entry.hasCover ? `${CATALOG_BASE}/books/${entry.id}/thumbnail` : null,
+      detailUrl: `${CATALOG_BASE}/books/${entry.id}`,
+      addedAt: entry.addedAt.toISOString(),
+      updatedAt: entry.updatedAt.toISOString(),
+    };
+  }
+
+  private mapBookDetail(detail: BookDetailDto, progress: KoreaderCatalogProgress | null): KoreaderCatalogBookDetail {
+    const title = detail.title ?? (basename(detail.folderPath) || `Book ${detail.id}`);
+    const files = detail.files
+      .filter((file) => file.role === 'primary' || file.role === 'content')
+      .map<KoreaderCatalogFile>((file) => ({
+        id: file.id,
+        format: this.normalizeFormat(file.format),
+        role: file.role,
+        sizeBytes: file.sizeBytes,
+        durationSeconds: file.durationSeconds,
+        downloadUrl: `${CATALOG_BASE}/files/${file.id}/download`,
+      }));
+
+    return {
+      id: detail.id,
+      title,
+      authors: detail.authors.map((author) => author.name),
+      seriesName: detail.seriesName,
+      seriesIndex: detail.seriesIndex,
+      progressPercentage: progress?.percentage ?? null,
+      readStatus: detail.readStatus?.status ?? null,
+      formats: this.uniqueFormats(files.map((file) => file.format)),
+      hasCover: detail.coverSource !== null,
+      thumbnailUrl: detail.coverSource !== null ? `${CATALOG_BASE}/books/${detail.id}/thumbnail` : null,
+      detailUrl: `${CATALOG_BASE}/books/${detail.id}`,
+      addedAt: detail.addedAt.toISOString(),
+      updatedAt: (detail.updatedAt ?? detail.addedAt).toISOString(),
+      subtitle: detail.subtitle,
+      description: detail.description,
+      publisher: detail.publisher,
+      publishedYear: detail.publishedYear,
+      language: detail.language,
+      isbn10: detail.isbn10,
+      isbn13: detail.isbn13,
+      libraryId: detail.libraryId,
+      libraryName: detail.libraryName,
+      rating: detail.rating,
+      pageCount: detail.pageCount,
+      collections: detail.collections,
+      genres: detail.genres,
+      tags: detail.tags,
+      progress,
+      files,
+    };
+  }
+
+  private async findBestProgress(userId: number, bookId: number): Promise<KoreaderCatalogProgress | null> {
+    const rows = await this.bookReadService.findProgressByBook(userId, bookId);
+    let best: ProgressCandidate | null = null;
+    for (const row of rows) {
+      if (row.percentage == null || row.updatedAt == null) continue;
+      const candidate = row as ProgressCandidate;
+      if (!best || candidate.updatedAt > best.updatedAt) {
+        best = candidate;
+      }
+    }
+
+    return best ? this.mapProgress(best) : null;
+  }
+
+  private async findBestProgressMap(userId: number, bookIds: number[]): Promise<Map<number, KoreaderCatalogProgress>> {
+    const map = new Map<number, KoreaderCatalogProgress>();
+    if (bookIds.length === 0) return map;
+
+    const rows = await this.bookReadService.findProgressByBooks(userId, bookIds);
+    const best = new Map<number, BatchProgressCandidate>();
+    for (const row of rows) {
+      if (row.percentage == null || row.updatedAt == null) continue;
+      const candidate = row as BatchProgressCandidate;
+      const current = best.get(row.bookId);
+      if (!current || candidate.updatedAt > current.updatedAt) {
+        best.set(row.bookId, candidate);
+      }
+    }
+
+    for (const [bookId, candidate] of best) {
+      map.set(bookId, {
+        fileId: candidate.fileId,
+        percentage: candidate.percentage,
+        koreaderProgress: candidate.koreaderProgress ?? null,
+        updatedAt: candidate.updatedAt.toISOString(),
+      });
+    }
+    return map;
+  }
+
+  private mapProgress(row: ProgressCandidate): KoreaderCatalogProgress {
+    return {
+      fileId: row.fileId,
+      percentage: row.percentage ?? 0,
+      koreaderProgress: row.koreaderProgress ?? null,
+      updatedAt: row.updatedAt.toISOString(),
+    };
+  }
+
+  private buildBookFilters(query: KoreaderCatalogBooksQueryDto): {
+    libraryId?: number;
+    collectionId?: number;
+    smartScopeId?: number;
+    author?: string;
+    series?: string;
+    q?: string;
+    readStatus?: 'unread' | 'reading' | 'finished';
+    format?: string;
+    ids?: number[];
+  } {
+    return {
+      ...(query.libraryId !== undefined ? { libraryId: query.libraryId } : {}),
+      ...(query.collectionId !== undefined ? { collectionId: query.collectionId } : {}),
+      ...(query.smartScopeId !== undefined ? { smartScopeId: query.smartScopeId } : {}),
+      ...(query.author ? { author: query.author } : {}),
+      ...(query.series ? { series: query.series } : {}),
+      ...(query.q?.trim() ? { q: query.q.trim() } : {}),
+      ...(query.readStatus ? { readStatus: query.readStatus } : {}),
+      ...(query.format?.trim() ? { format: query.format.trim().toLowerCase() } : {}),
+      ...(query.ids ? { ids: query.ids } : {}),
+    };
+  }
+
+  private mapSort(sort: KoreaderCatalogSort, order?: KoreaderCatalogSortOrder): OpdsSortOrder {
+    const direction = order ?? NATURAL_SORT_ORDER[sort];
+    const descending = direction === 'desc';
+    switch (sort) {
+      case 'title':
+        return descending ? 'title_desc' : 'title_asc';
+      case 'author':
+        return descending ? 'author_desc' : 'author_asc';
+      case 'recently_updated':
+        return descending ? 'updated' : 'updated_asc';
+      case 'recently_read':
+        return descending ? 'recently_read' : 'recently_read_asc';
+      case 'series':
+        return descending ? 'series_desc' : 'series_asc';
+      case 'recently_added':
+      default:
+        return descending ? 'recent' : 'recent_asc';
+    }
+  }
+
+  private paginate<T>(
+    items: T[],
+    total: number,
+    page: number,
+    size: number,
+    query: KoreaderCatalogBooksQueryDto,
+    seriesSummary: KoreaderCatalogSeriesSummary | null = null,
+  ): KoreaderCatalogPage<T> {
+    const hasNext = page * size < total;
+    const hasPrevious = page > 1;
+    return {
+      items,
+      total,
+      page,
+      size,
+      hasNext,
+      hasPrevious,
+      nextUrl: hasNext ? this.pageHref(query, page + 1, size) : null,
+      previousUrl: hasPrevious ? this.pageHref(query, page - 1, size) : null,
+      seriesSummary,
+    };
+  }
+
+  private pageHref(query: KoreaderCatalogBooksQueryDto, page: number, size: number): string {
+    return this.booksHref({ ...query, page, size });
+  }
+
+  private booksHref(params: Partial<KoreaderCatalogBooksQueryDto>): string {
+    const search = new URLSearchParams();
+    const orderedKeys = [
+      'page',
+      'size',
+      'sort',
+      'order',
+      'q',
+      'readStatus',
+      'format',
+      'ids',
+      'libraryId',
+      'collectionId',
+      'smartScopeId',
+      'author',
+      'series',
+    ] as const;
+    for (const key of orderedKeys) {
+      const value = params[key];
+      if (value !== undefined && value !== null && value !== '') {
+        search.set(key, Array.isArray(value) ? value.join(',') : String(value));
+      }
+    }
+    const suffix = search.toString();
+    return suffix ? `${CATALOG_BASE}/books?${suffix}` : `${CATALOG_BASE}/books`;
+  }
+
+  private assertPaginationWindow(page: number, size: number): void {
+    if (!isOffsetWithinLimit((page - 1) * size)) {
+      throw new BadRequestException(`pagination window is too deep; (page - 1) * size must be <= ${MAX_OFFSET_ROWS}`);
+    }
+  }
+
+  private normalizeFormat(format: string | null | undefined): string {
+    return (format ?? 'bin').toLowerCase();
+  }
+
+  private uniqueFormats(formats: string[]): string[] {
+    return [...new Set(formats.map((format) => this.normalizeFormat(format)).filter(Boolean))];
+  }
+
+  private downloadFilename(detail: BookDetailDto, fileId: number, format: string): string {
+    const title = detail.title ?? (basename(detail.folderPath) || `book-${detail.id}`);
+    const author = detail.authors[0]?.name;
+    const base = [title, author].filter(Boolean).join(' - ');
+    const safeBase =
+      base
+        .replace(/["\\/:*?<>|]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim() || `book-${detail.id}-file-${fileId}`;
+    const ext = extname(safeBase).replace(/^\./, '').toLowerCase();
+    if (ext === format) return safeBase;
+    return `${safeBase}.${format}`;
+  }
+}
diff --git a/server/src/modules/koreader/koreader-package.service.test.ts b/server/src/modules/koreader/koreader-package.service.test.ts
new file mode 100644
index 000000000..4261497c7
--- /dev/null
+++ b/server/src/modules/koreader/koreader-package.service.test.ts
@@ -0,0 +1,190 @@
+import { BadRequestException, Logger, NotFoundException, ServiceUnavailableException } from '@nestjs/common';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import * as unzipper from 'unzipper';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { KoreaderPackageService } from './koreader-package.service';
+
+function makeCredentialsRow(overrides?: Record<string, unknown>) {
+  return {
+    userId: 7,
+    username: 'reader',
+    passwordHash: 'stored-bcrypt-hash',
+    passwordMd5: '0123456789abcdef0123456789abcdef',
+    syncEnabled: true,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    ...overrides,
+  };
+}
+
+describe('KoreaderPackageService', () => {
+  let service: KoreaderPackageService;
+  let mockRepo: { findKoreaderUser: ReturnType<typeof vi.fn> };
+  let pluginDir: string;
+
+  function makeService(sourcePath?: string, version = 'test-server-version') {
+    return new KoreaderPackageService(mockRepo as never, { koreaderPluginSourcePath: sourcePath ?? pluginDir, version } as never);
+  }
+
+  async function readZipEntries(zip: Buffer): Promise<Map<string, string>> {
+    const directory = await unzipper.Open.buffer(zip);
+    const entries = new Map<string, string>();
+    for (const file of directory.files) {
+      if (file.type === 'File') {
+        entries.set(file.path, (await file.buffer()).toString('utf8'));
+      }
+    }
+    return entries;
+  }
+
+  beforeAll(() => {
+    pluginDir = mkdtempSync(join(tmpdir(), 'bookorbit-koplugin-test-'));
+    writeFileSync(join(pluginDir, 'main.lua'), 'local PLUGIN_VERSION = "1.2.3"\nreturn {}\n');
+    writeFileSync(join(pluginDir, '_meta.lua'), 'return { name = "bookorbit" }\n');
+    writeFileSync(join(pluginDir, '.DS_Store'), 'junk');
+    mkdirSync(join(pluginDir, 'assets'));
+    writeFileSync(join(pluginDir, 'assets', 'note.txt'), 'nested\n');
+  });
+
+  afterAll(() => {
+    rmSync(pluginDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => {});
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => {});
+
+    mockRepo = { findKoreaderUser: vi.fn() };
+    service = makeService();
+  });
+
+  it('throws NotFoundException when no credentials exist', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(undefined);
+
+    await expect(service.buildPluginPackage(7, 'https://books.example.com')).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('throws BadRequestException when stored credentials have no md5', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow({ passwordMd5: null }));
+
+    await expect(service.buildPluginPackage(7, 'https://books.example.com')).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it.each(['not a url', 'ftp://books.example.com', ''])('rejects invalid origin %j', async (origin) => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow());
+
+    await expect(service.buildPluginPackage(7, origin)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('throws ServiceUnavailableException when the plugin source folder is missing', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow());
+    service = makeService(join(pluginDir, 'does-not-exist'));
+
+    await expect(service.buildPluginPackage(7, 'https://books.example.com')).rejects.toBeInstanceOf(ServiceUnavailableException);
+  });
+
+  it('builds a zip with the plugin files and a provision file', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow());
+
+    const zip = await service.buildPluginPackage(7, 'https://books.example.com');
+    const entries = await readZipEntries(zip);
+
+    expect(entries.has('bookorbit.koplugin/main.lua')).toBe(true);
+    expect(entries.has('bookorbit.koplugin/_meta.lua')).toBe(true);
+    expect(entries.has('bookorbit.koplugin/assets/note.txt')).toBe(true);
+    expect(entries.has('bookorbit.koplugin/.DS_Store')).toBe(false);
+
+    const provision = entries.get('bookorbit.koplugin/bookorbit_provision.lua');
+    expect(provision).toBeDefined();
+    expect(provision).toContain('server_url = "https://books.example.com"');
+    expect(provision).toContain('username = "reader"');
+    expect(provision).toContain('userkey = "0123456789abcdef0123456789abcdef"');
+    expect(provision).toContain('generated_at = "');
+  });
+
+  it('normalizes the origin to scheme and host only', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow());
+
+    const zip = await service.buildPluginPackage(7, 'https://books.example.com:8443/library/books?tab=1');
+    const entries = await readZipEntries(zip);
+
+    expect(entries.get('bookorbit.koplugin/bookorbit_provision.lua')).toContain('server_url = "https://books.example.com:8443"');
+  });
+
+  it('escapes lua string characters in the username', async () => {
+    mockRepo.findKoreaderUser.mockResolvedValue(makeCredentialsRow({ username: 'rea"der\\one' }));
+
+    const zip = await service.buildPluginPackage(7, 'https://books.example.com');
+    const entries = await readZipEntries(zip);
+
+    expect(entries.get('bookorbit.koplugin/bookorbit_provision.lua')).toContain('username = "rea\\"der\\\\one"');
+  });
+
+  describe('buildRawPluginPackage', () => {
+    it('throws ServiceUnavailableException when the plugin source folder is missing', async () => {
+      service = makeService(join(pluginDir, 'does-not-exist'));
+
+      await expect(service.buildRawPluginPackage(7)).rejects.toBeInstanceOf(ServiceUnavailableException);
+    });
+
+    it('builds a zip with the plugin files and no provision file', async () => {
+      const zip = await service.buildRawPluginPackage(7);
+      const entries = await readZipEntries(zip);
+
+      expect(entries.has('bookorbit.koplugin/main.lua')).toBe(true);
+      expect(entries.has('bookorbit.koplugin/_meta.lua')).toBe(true);
+      expect(entries.has('bookorbit.koplugin/assets/note.txt')).toBe(true);
+      expect(entries.has('bookorbit.koplugin/.DS_Store')).toBe(false);
+      expect(entries.has('bookorbit.koplugin/bookorbit_provision.lua')).toBe(false);
+    });
+
+    it('does not require user credentials', async () => {
+      mockRepo.findKoreaderUser.mockResolvedValue(undefined);
+
+      const zip = await service.buildRawPluginPackage(7);
+
+      expect(zip).toBeInstanceOf(Buffer);
+      expect(mockRepo.findKoreaderUser).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getVersionInfo', () => {
+    it('returns pluginVersion from main.lua and serverVersion from config', async () => {
+      const result = await service.getVersionInfo();
+
+      expect(result.pluginVersion).toBe('1.2.3');
+      expect(result.serverVersion).toBe('test-server-version');
+    });
+
+    it('returns pluginVersion=unknown when the plugin source dir does not exist', async () => {
+      service = makeService(join(pluginDir, 'does-not-exist'));
+
+      const result = await service.getVersionInfo();
+
+      expect(result.pluginVersion).toBe('unknown');
+      expect(result.serverVersion).toBe('test-server-version');
+    });
+
+    it('returns pluginVersion=unknown when main.lua has no PLUGIN_VERSION declaration', async () => {
+      const altDir = mkdtempSync(join(tmpdir(), 'bookorbit-alt-test-'));
+      writeFileSync(join(altDir, 'main.lua'), '-- no version line\nreturn {}\n');
+      try {
+        const result = await makeService(altDir).getVersionInfo();
+        expect(result.pluginVersion).toBe('unknown');
+      } finally {
+        rmSync(altDir, { recursive: true, force: true });
+      }
+    });
+
+    it('returns the configured serverVersion regardless of plugin dir availability', async () => {
+      service = makeService(join(pluginDir, 'missing'), '2.0.0-rc1');
+
+      const result = await service.getVersionInfo();
+
+      expect(result.serverVersion).toBe('2.0.0-rc1');
+    });
+  });
+});
diff --git a/server/src/modules/koreader/koreader-package.service.ts b/server/src/modules/koreader/koreader-package.service.ts
new file mode 100644
index 000000000..8b488dd50
--- /dev/null
+++ b/server/src/modules/koreader/koreader-package.service.ts
@@ -0,0 +1,153 @@
+import { BadRequestException, Inject, Injectable, Logger, NotFoundException, ServiceUnavailableException } from '@nestjs/common';
+import type { ConfigType } from '@nestjs/config';
+import { ZipArchive } from 'archiver';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+
+import { appConfig } from '../../config/config';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { KoreaderRepository } from './koreader.repository';
+
+const PACKAGE_EVENT = 'koreader.plugin_package';
+const PLUGIN_FOLDER = 'bookorbit.koplugin';
+const PROVISION_FILE = 'bookorbit_provision.lua';
+
+@Injectable()
+export class KoreaderPackageService {
+  private readonly logger = new Logger(KoreaderPackageService.name);
+
+  constructor(
+    private readonly repo: KoreaderRepository,
+    @Inject(appConfig.KEY) private readonly config: ConfigType<typeof appConfig>,
+  ) {}
+
+  async buildPluginPackage(userId: number, origin: string): Promise<Buffer> {
+    const startedAt = Date.now();
+    this.logger.log(`[${PACKAGE_EVENT}] [start] userId=${userId} - building preconfigured plugin package`);
+
+    try {
+      const serverUrl = this.normalizeOrigin(origin);
+      const credentials = await this.repo.findKoreaderUser(userId);
+      if (!credentials) throw new NotFoundException('Create KOReader sync credentials first');
+      if (!credentials.passwordMd5) {
+        throw new BadRequestException('Update your KOReader password once to enable the preconfigured download');
+      }
+
+      const pluginDir = this.resolvePluginSourceDir();
+      const provision = this.renderProvisionFile(serverUrl, credentials.username, credentials.passwordMd5);
+      const zip = await this.zipPlugin(pluginDir, provision);
+
+      this.logger.log(`[${PACKAGE_EVENT}] [end] userId=${userId} durationMs=${Date.now() - startedAt} bytes=${zip.length} - plugin package built`);
+      return zip;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.logger.warn(
+        `[${PACKAGE_EVENT}] [fail] userId=${userId} durationMs=${Date.now() - startedAt} errorClass=${error.constructor.name} error="${sanitizeLogValue(error.message)}" - plugin package failed`,
+      );
+      throw err;
+    }
+  }
+
+  async buildRawPluginPackage(userId: number): Promise<Buffer> {
+    const startedAt = Date.now();
+    this.logger.log(`[${PACKAGE_EVENT}] [start] userId=${userId} - building raw plugin update package`);
+
+    try {
+      const pluginDir = this.resolvePluginSourceDir();
+      const zip = await this.zipPlugin(pluginDir);
+
+      this.logger.log(
+        `[${PACKAGE_EVENT}] [end] userId=${userId} durationMs=${Date.now() - startedAt} bytes=${zip.length} - raw plugin update package built`,
+      );
+      return zip;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.logger.warn(
+        `[${PACKAGE_EVENT}] [fail] userId=${userId} durationMs=${Date.now() - startedAt} errorClass=${error.constructor.name} error="${sanitizeLogValue(error.message)}" - raw plugin update package failed`,
+      );
+      throw err;
+    }
+  }
+
+  async getVersionInfo(): Promise<{ pluginVersion: string; serverVersion: string }> {
+    return {
+      pluginVersion: await this.readPluginVersion(),
+      serverVersion: this.config.version,
+    };
+  }
+
+  private async readPluginVersion(): Promise<string> {
+    try {
+      const pluginDir = this.resolvePluginSourceDir();
+      const content = await readFile(join(pluginDir, 'main.lua'), 'utf8');
+      const match = content.match(/^local PLUGIN_VERSION = "(.+)"$/m);
+      return match?.[1] ?? 'unknown';
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  private normalizeOrigin(rawOrigin: string): string {
+    let parsed: URL;
+    try {
+      parsed = new URL(rawOrigin);
+    } catch {
+      throw new BadRequestException('origin must be a valid http(s) URL');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new BadRequestException('origin must be a valid http(s) URL');
+    }
+    return parsed.origin;
+  }
+
+  private resolvePluginSourceDir(): string {
+    const configured = this.config.koreaderPluginSourcePath;
+    const candidates = configured
+      ? [resolve(configured)]
+      : [resolve(process.cwd(), '..', 'koreader-plugin', PLUGIN_FOLDER), resolve(process.cwd(), 'koreader-plugin', PLUGIN_FOLDER)];
+    const found = candidates.find((dir) => existsSync(join(dir, 'main.lua')));
+    if (!found) {
+      throw new ServiceUnavailableException('KOReader plugin source is not available on this server');
+    }
+    return found;
+  }
+
+  private renderProvisionFile(serverUrl: string, username: string, userkey: string): string {
+    return [
+      '-- Generated by BookOrbit. Applied automatically when KOReader starts, then removed.',
+      'return {',
+      `    server_url = ${luaQuote(serverUrl)},`,
+      `    username = ${luaQuote(username)},`,
+      `    userkey = ${luaQuote(userkey)},`,
+      `    generated_at = ${luaQuote(new Date().toISOString())},`,
+      '}',
+      '',
+    ].join('\n');
+  }
+
+  private zipPlugin(pluginDir: string, provisionContent?: string): Promise<Buffer> {
+    return new Promise((resolveZip, reject) => {
+      const archive = new ZipArchive({ zlib: { level: 9 } });
+      const chunks: Buffer[] = [];
+      archive.on('data', (chunk: Buffer) => chunks.push(chunk));
+      archive.on('warning', reject);
+      archive.on('error', reject);
+      archive.on('end', () => resolveZip(Buffer.concat(chunks)));
+      archive.directory(pluginDir, PLUGIN_FOLDER, (entry) => (isHiddenPath(entry.name) ? false : entry));
+      if (provisionContent !== undefined) {
+        archive.append(provisionContent, { name: `${PLUGIN_FOLDER}/${PROVISION_FILE}` });
+      }
+      void archive.finalize();
+    });
+  }
+}
+
+function isHiddenPath(entryName: string): boolean {
+  return entryName.split('/').some((part) => part.startsWith('.'));
+}
+
+function luaQuote(value: string): string {
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r/g, '\\r').replace(/\n/g, '\\n');
+  return `"${escaped}"`;
+}
diff --git a/server/src/modules/koreader/koreader-plugin-annotation.service.test.ts b/server/src/modules/koreader/koreader-plugin-annotation.service.test.ts
new file mode 100644
index 000000000..0e752dc9a
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin-annotation.service.test.ts
@@ -0,0 +1,112 @@
+import { BadRequestException, Logger } from '@nestjs/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestUser } from '../../common/types/request-user';
+import type { AnnotationSyncService, IncomingDeviceAnnotation } from '../annotation/annotation-sync.service';
+import type { AnnotationsUploadDto } from './dto';
+import { KoreaderPluginAnnotationService } from './koreader-plugin-annotation.service';
+import type { KoreaderRepository } from './koreader.repository';
+
+const DEVICE_ID = 'abcdef12-3456-7890-abcd-ef1234567890';
+const HASH_A = 'a'.repeat(32);
+const HASH_B = 'b'.repeat(32);
+
+function makeUser(): RequestUser {
+  return { id: 7, settings: {} } as unknown as RequestUser;
+}
+
+function makeDto(books: AnnotationsUploadDto['books']): AnnotationsUploadDto {
+  return { deviceId: DEVICE_ID, deviceModel: 'Kobo Libra 2', pluginVersion: '0.1.0', books } as AnnotationsUploadDto;
+}
+
+function makeAnnotation(overrides: Record<string, unknown> = {}) {
+  return {
+    datetime: '2026-06-01 21:14:03',
+    drawer: 'lighten',
+    posFormat: 'xpointer',
+    pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+    pos1: '/body/DocFragment[8]/body/p[12]/text().57',
+    text: 'highlighted text',
+    ...overrides,
+  } as AnnotationsUploadDto['books'][number]['annotations'][number];
+}
+
+describe('KoreaderPluginAnnotationService', () => {
+  let koreaderRepo: { getAccessibleLibraryIds: ReturnType<typeof vi.fn>; resolveBookFilesByHashes: ReturnType<typeof vi.fn> };
+  let annotationSync: {
+    ingestDeviceAnnotations: ReturnType<typeof vi.fn>;
+  };
+  let service: KoreaderPluginAnnotationService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+
+    koreaderRepo = {
+      getAccessibleLibraryIds: vi.fn().mockResolvedValue([1]),
+      resolveBookFilesByHashes: vi.fn().mockResolvedValue(new Map([[HASH_A, { bookFileId: 10, bookId: 20, libraryId: 1 }]])),
+    };
+    annotationSync = {
+      ingestDeviceAnnotations: vi
+        .fn()
+        .mockImplementation((params: { annotations: unknown[] }) =>
+          Promise.resolve({ created: params.annotations.length, updated: 0, moved: 0, unchanged: 0, skippedDeleted: 0 }),
+        ),
+    };
+
+    service = new KoreaderPluginAnnotationService(koreaderRepo as unknown as KoreaderRepository, annotationSync as unknown as AnnotationSyncService);
+  });
+
+  it('routes matched books through the sync ingest with mapped fields', async () => {
+    const dto = makeDto([
+      { hash: HASH_A, annotations: [makeAnnotation({ datetimeUpdated: '2026-06-03 09:30:00', note: 'edited note', color: 'red' })] },
+    ]);
+
+    const result = await service.uploadAnnotations(makeUser(), dto);
+
+    expect(annotationSync.ingestDeviceAnnotations).toHaveBeenCalledTimes(1);
+    const params = annotationSync.ingestDeviceAnnotations.mock.calls[0]![0] as {
+      userId: number;
+      source: string;
+      deviceId: string;
+      bookId: number;
+      bookFileId: number;
+      annotations: IncomingDeviceAnnotation[];
+    };
+    expect(params).toMatchObject({ userId: 7, source: 'koreader', deviceId: DEVICE_ID, bookId: 20, bookFileId: 10 });
+    expect(params.annotations[0]).toMatchObject({
+      datetime: '2026-06-01 21:14:03',
+      datetimeUpdated: '2026-06-03 09:30:00',
+      drawer: 'lighten',
+      color: 'red',
+      note: 'edited note',
+      posFormat: 'xpointer',
+      pos0: '/body/DocFragment[8]/body/p[12]/text().0',
+    });
+    expect(result.results[0]).toEqual({ hash: HASH_A, upserted: 1 });
+  });
+
+  it('counts created, updated and moved annotations as upserted', async () => {
+    annotationSync.ingestDeviceAnnotations.mockResolvedValue({ created: 1, updated: 2, moved: 1, unchanged: 3, skippedDeleted: 1 });
+
+    const result = await service.uploadAnnotations(makeUser(), makeDto([{ hash: HASH_A, annotations: [makeAnnotation()] }]));
+
+    expect(result.results[0]).toEqual({ hash: HASH_A, upserted: 4 });
+  });
+
+  it('reports unmatched hashes without ingesting', async () => {
+    const result = await service.uploadAnnotations(makeUser(), makeDto([{ hash: HASH_B, annotations: [makeAnnotation()] }]));
+
+    expect(result.unmatched).toEqual([HASH_B]);
+    expect(annotationSync.ingestDeviceAnnotations).not.toHaveBeenCalled();
+  });
+
+  it('rejects requests with more than 50 annotations in total', async () => {
+    const annotations = Array.from({ length: 51 }, (_, i) =>
+      makeAnnotation({ datetime: `2026-06-01 21:14:${String(i % 60).padStart(2, '0')}`, pos0: `pos-${i}` }),
+    );
+
+    await expect(service.uploadAnnotations(makeUser(), makeDto([{ hash: HASH_A, annotations }]))).rejects.toBeInstanceOf(BadRequestException);
+  });
+});
diff --git a/server/src/modules/koreader/koreader-plugin-annotation.service.ts b/server/src/modules/koreader/koreader-plugin-annotation.service.ts
new file mode 100644
index 000000000..a96eaf806
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin-annotation.service.ts
@@ -0,0 +1,97 @@
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+
+import type { RequestUser } from '../../common/types/request-user';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { AnnotationSyncService, type IncomingDeviceAnnotation } from '../annotation/annotation-sync.service';
+import type { AnnotationsUploadDto, KoreaderAnnotationDto } from './dto';
+import { KoreaderRepository } from './koreader.repository';
+
+const ANNOTATIONS_EVENT = 'koreader.plugin.annotations';
+const MAX_ANNOTATIONS_PER_REQUEST = 50;
+
+export interface AnnotationsUploadResult {
+  results: { hash: string; upserted: number }[];
+  unmatched: string[];
+}
+
+@Injectable()
+export class KoreaderPluginAnnotationService {
+  private readonly logger = new Logger(KoreaderPluginAnnotationService.name);
+
+  constructor(
+    private readonly koreaderRepo: KoreaderRepository,
+    private readonly annotationSync: AnnotationSyncService,
+  ) {}
+
+  /** Legacy one-way upload used by plugin 0.3.x; the 0.4+ exchange endpoint supersedes it. */
+  async uploadAnnotations(user: RequestUser, dto: AnnotationsUploadDto): Promise<AnnotationsUploadResult> {
+    const startedAtMs = Date.now();
+    const totalAnnotations = dto.books.reduce((sum, book) => sum + book.annotations.length, 0);
+    this.logger.log(
+      `[${ANNOTATIONS_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} books=${dto.books.length} annotations=${totalAnnotations} - annotations upload started`,
+    );
+
+    try {
+      if (totalAnnotations > MAX_ANNOTATIONS_PER_REQUEST) {
+        throw new BadRequestException(`Too many annotations in one request (max ${MAX_ANNOTATIONS_PER_REQUEST})`);
+      }
+
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const hashes = [...new Set(dto.books.map((book) => book.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+      const results: { hash: string; upserted: number }[] = [];
+      const unmatched: string[] = [];
+      let upsertedTotal = 0;
+
+      for (const book of dto.books) {
+        const hash = book.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+
+        const ingest = await this.annotationSync.ingestDeviceAnnotations({
+          userId: user.id,
+          source: 'koreader',
+          deviceId: dto.deviceId,
+          bookId: match.bookId,
+          bookFileId: match.bookFileId,
+          annotations: book.annotations.map((annotation) => this.toIncoming(annotation)),
+        });
+        const upserted = ingest.created + ingest.updated + ingest.moved;
+        upsertedTotal += upserted;
+        results.push({ hash, upserted });
+      }
+
+      this.logger.log(
+        `[${ANNOTATIONS_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} upserted=${upsertedTotal} unmatched=${unmatched.length} - annotations upload completed`,
+      );
+
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${ANNOTATIONS_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - annotations upload failed`,
+      );
+      throw error;
+    }
+  }
+
+  private toIncoming(annotation: KoreaderAnnotationDto): IncomingDeviceAnnotation {
+    return {
+      datetime: annotation.datetime,
+      datetimeUpdated: annotation.datetimeUpdated ?? null,
+      drawer: annotation.drawer,
+      color: annotation.color ?? null,
+      text: annotation.text ?? null,
+      note: annotation.note ?? null,
+      chapter: annotation.chapter ?? null,
+      pageno: annotation.pageno ?? null,
+      posFormat: annotation.posFormat as IncomingDeviceAnnotation['posFormat'],
+      pos0: annotation.pos0,
+      pos1: annotation.pos1 ?? null,
+    };
+  }
+}
diff --git a/server/src/modules/koreader/koreader-plugin-source.test.ts b/server/src/modules/koreader/koreader-plugin-source.test.ts
new file mode 100644
index 000000000..003f70eca
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin-source.test.ts
@@ -0,0 +1,56 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { describe, expect, it } from 'vitest';
+
+const pluginRoot = join(process.cwd(), '..', 'koreader-plugin', 'bookorbit.koplugin');
+
+async function readPluginFile(name: string): Promise<string> {
+  return readFile(join(pluginRoot, name), 'utf8');
+}
+
+describe('KOReader plugin update source wiring', () => {
+  it('places update checking after full sync and keeps sync behavior unboxed', async () => {
+    const main = await readPluginFile('main.lua');
+    const updateRowIndex = main.indexOf('return self:updateCheckMenuText()');
+    const browseBlock = main.slice(main.indexOf('text = _("Browse library")'), main.indexOf('text = _("Auto sync this book")'));
+    const fullSyncBlock = main.slice(main.indexOf('text = _("Sync all books now")'), updateRowIndex);
+    const syncBehaviorBlock = main.slice(
+      main.indexOf('return T(_("Periodically sync every # pages (%1)")'),
+      main.indexOf('text = _("Sync this book now")'),
+    );
+
+    expect(main).toContain('function BookOrbit:updateCheckMenuText()');
+    expect(browseBlock).toContain('separator = true');
+    expect(fullSyncBlock).toContain('separator = true');
+    expect(syncBehaviorBlock).not.toContain('separator = true');
+    expect(updateRowIndex).toBeGreaterThan(main.indexOf('text = _("Sync all books now")'));
+    expect(updateRowIndex).toBeLessThan(main.indexOf('return T(_("Last sync: %1")'));
+    expect(main.indexOf('keep_menu_open = true,\n                callback = function()\n                    self:checkForUpdate()')).toBeGreaterThan(
+      0,
+    );
+    expect(main).toContain('return T(_("Plugin update available: v%1 -> v%2"), PLUGIN_VERSION, self.settings.update_latest_version)');
+    expect(main).toContain('return T(_("Installed plugin: v%1 (Check for update)"), PLUGIN_VERSION)');
+    expect(main).toContain('return T(_("Installed plugin: v%1 (Login required)"), PLUGIN_VERSION)');
+    expect(main).not.toContain('return T(_("Installed plugin: v%1"), PLUGIN_VERSION)');
+  });
+
+  it('throttles automatic update prompts and does not interrupt the catalog browser', async () => {
+    const main = await readPluginFile('main.lua');
+
+    expect(main).toContain('local UPDATE_CHECK_INTERVAL = 24 * 60 * 60');
+    expect(main).toContain('update_check_last_at = 0');
+    expect(main).toContain('function BookOrbit:maybeCheckForUpdate(interactive)');
+    expect(main).toContain('self:handleUpdateVersionResponse(body, interactive, interactive or self.catalog_browser == nil)');
+    expect(main).toContain('if not prompt_allowed then');
+    expect(main).toContain('self.settings.update_dismissed_version = plugin_latest');
+  });
+
+  it('runs a throttled update check after successful full-library sweeps', async () => {
+    const main = await readPluginFile('main.lua');
+    const sweep = await readPluginFile('bookorbit_sweep.lua');
+
+    expect(main).toContain('if not err then self:maybeCheckForUpdate(false) end');
+    expect(sweep).toContain('on_finish = opts.on_finish');
+    expect(sweep).toContain('pcall(ctx.on_finish, err)');
+  });
+});
diff --git a/server/src/modules/koreader/koreader-plugin.controller.test.ts b/server/src/modules/koreader/koreader-plugin.controller.test.ts
new file mode 100644
index 000000000..fbb811516
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin.controller.test.ts
@@ -0,0 +1,156 @@
+import { GUARDS_METADATA } from '@nestjs/common/constants';
+import { describe, expect, it, vi } from 'vitest';
+
+import { IS_PUBLIC_KEY } from '../../common/decorators/public.decorator';
+import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderPluginController } from './koreader-plugin.controller';
+
+function makeController() {
+  const pluginService = {
+    matchCheck: vi.fn().mockResolvedValue({ matches: [], libraryVersion: 'v1' }),
+    uploadBookStates: vi.fn().mockResolvedValue({ results: [], unmatched: [] }),
+    bulkProgress: vi.fn().mockResolvedValue({ results: [], unmatched: [] }),
+    sweepComplete: vi.fn().mockResolvedValue({ ok: true, lastSweepAt: '2026-01-01', libraryVersion: 'v1' }),
+  };
+  const statsService = {
+    uploadPageStats: vi.fn().mockResolvedValue({ uploaded: 1 }),
+  };
+  const annotationService = {
+    uploadAnnotations: vi.fn().mockResolvedValue({ uploaded: 1 }),
+  };
+  const annotationExchangeService = {
+    exchange: vi.fn().mockResolvedValue({ books: [] }),
+    exchangeAck: vi.fn().mockResolvedValue({ ok: true }),
+  };
+  const packageService = {
+    getVersionInfo: vi.fn().mockResolvedValue({ pluginVersion: '0.4.0', serverVersion: '1.0.0' }),
+    buildPluginPackage: vi.fn().mockResolvedValue(Buffer.from('fake-zip-content')),
+    buildRawPluginPackage: vi.fn().mockResolvedValue(Buffer.from('fake-zip-content')),
+  };
+
+  return {
+    controller: new KoreaderPluginController(
+      pluginService as never,
+      statsService as never,
+      annotationService as never,
+      annotationExchangeService as never,
+      packageService as never,
+    ),
+    pluginService,
+    statsService,
+    annotationService,
+    annotationExchangeService,
+    packageService,
+  };
+}
+
+describe('KoreaderPluginController', () => {
+  it('is public for the global JWT guard and uses the KOReader auth guard', () => {
+    expect(Reflect.getMetadata(IS_PUBLIC_KEY, KoreaderPluginController)).toBe(true);
+    expect(Reflect.getMetadata(GUARDS_METADATA, KoreaderPluginController)).toEqual([KoreaderAuthGuard]);
+  });
+
+  it('matchCheck delegates to plugin service', async () => {
+    const { controller, pluginService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = { deviceId: 'abc123', deviceModel: 'Kobo', pluginVersion: '0.4.0', hashes: ['aabbccdd'] } as never;
+
+    await controller.matchCheck(user, dto);
+
+    expect(pluginService.matchCheck).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('uploadPageStats delegates to stats service', async () => {
+    const { controller, statsService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.uploadPageStats(user, dto);
+
+    expect(statsService.uploadPageStats).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('uploadAnnotations delegates to annotation service', async () => {
+    const { controller, annotationService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.uploadAnnotations(user, dto);
+
+    expect(annotationService.uploadAnnotations).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('exchangeAnnotations delegates to annotation exchange service', async () => {
+    const { controller, annotationExchangeService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.exchangeAnnotations(user, dto);
+
+    expect(annotationExchangeService.exchange).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('exchangeAnnotationsAck delegates to annotation exchange service', async () => {
+    const { controller, annotationExchangeService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.exchangeAnnotationsAck(user, dto);
+
+    expect(annotationExchangeService.exchangeAck).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('uploadBookStates delegates to plugin service', async () => {
+    const { controller, pluginService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.uploadBookStates(user, dto);
+
+    expect(pluginService.uploadBookStates).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('bulkProgress delegates to plugin service', async () => {
+    const { controller, pluginService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.bulkProgress(user, dto);
+
+    expect(pluginService.bulkProgress).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('sweepComplete delegates to plugin service', async () => {
+    const { controller, pluginService } = makeController();
+    const user = { id: 7 } as never;
+    const dto = {} as never;
+
+    await controller.sweepComplete(user, dto);
+
+    expect(pluginService.sweepComplete).toHaveBeenCalledWith(user, dto);
+  });
+
+  it('getVersion returns plugin and server versions from package service', async () => {
+    const { controller, packageService } = makeController();
+
+    const result = await controller.getVersion();
+
+    expect(packageService.getVersionInfo).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ pluginVersion: '0.4.0', serverVersion: '1.0.0' });
+  });
+
+  it('downloadUpdatePackage builds a raw package and streams it with correct headers', async () => {
+    const { controller, packageService } = makeController();
+    const user = { id: 7 } as never;
+    const reply = { header: vi.fn().mockReturnThis(), send: vi.fn() } as never;
+
+    await controller.downloadUpdatePackage(user, reply);
+
+    expect(packageService.buildRawPluginPackage).toHaveBeenCalledWith(7);
+    expect(packageService.buildPluginPackage).not.toHaveBeenCalled();
+    expect(reply.header).toHaveBeenCalledWith('Content-Type', 'application/zip');
+    expect(reply.header).toHaveBeenCalledWith('Content-Disposition', 'attachment; filename="bookorbit.koplugin.zip"');
+    expect(reply.header).toHaveBeenCalledWith('Cache-Control', 'no-store');
+    expect(reply.send).toHaveBeenCalledWith(Buffer.from('fake-zip-content'));
+  });
+});
diff --git a/server/src/modules/koreader/koreader-plugin.controller.ts b/server/src/modules/koreader/koreader-plugin.controller.ts
new file mode 100644
index 000000000..a16e2390e
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin.controller.ts
@@ -0,0 +1,91 @@
+import { Body, Controller, Get, Post, Res, UseGuards } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
+
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+import { Public } from '../../common/decorators/public.decorator';
+import type { RequestUser } from '../../common/types/request-user';
+import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderAnnotationExchangeService } from './koreader-annotation-exchange.service';
+import { KoreaderPackageService } from './koreader-package.service';
+import { KoreaderPluginAnnotationService } from './koreader-plugin-annotation.service';
+import { KoreaderPluginService } from './koreader-plugin.service';
+import { KoreaderStatsService } from './koreader-stats.service';
+import {
+  AnnotationExchangeAckDto,
+  AnnotationExchangeDto,
+  AnnotationsUploadDto,
+  BookStatesUploadDto,
+  BulkProgressDto,
+  MatchCheckDto,
+  PageStatsUploadDto,
+  SweepCompleteDto,
+} from './dto';
+
+@Public()
+@UseGuards(KoreaderAuthGuard)
+@Controller('koreader/plugin')
+export class KoreaderPluginController {
+  constructor(
+    private readonly pluginService: KoreaderPluginService,
+    private readonly statsService: KoreaderStatsService,
+    private readonly annotationService: KoreaderPluginAnnotationService,
+    private readonly annotationExchangeService: KoreaderAnnotationExchangeService,
+    private readonly packageService: KoreaderPackageService,
+  ) {}
+
+  @Post('match-check')
+  matchCheck(@CurrentUser() user: RequestUser, @Body() dto: MatchCheckDto) {
+    return this.pluginService.matchCheck(user, dto);
+  }
+
+  @Post('page-stats')
+  uploadPageStats(@CurrentUser() user: RequestUser, @Body() dto: PageStatsUploadDto) {
+    return this.statsService.uploadPageStats(user, dto);
+  }
+
+  /** Deprecated one-way upload kept for plugin 0.3.x; 0.4+ uses the exchange below. */
+  @Post('annotations')
+  uploadAnnotations(@CurrentUser() user: RequestUser, @Body() dto: AnnotationsUploadDto) {
+    return this.annotationService.uploadAnnotations(user, dto);
+  }
+
+  @Post('annotations/exchange')
+  exchangeAnnotations(@CurrentUser() user: RequestUser, @Body() dto: AnnotationExchangeDto) {
+    return this.annotationExchangeService.exchange(user, dto);
+  }
+
+  @Post('annotations/exchange-ack')
+  exchangeAnnotationsAck(@CurrentUser() user: RequestUser, @Body() dto: AnnotationExchangeAckDto) {
+    return this.annotationExchangeService.exchangeAck(user, dto);
+  }
+
+  @Post('book-states')
+  uploadBookStates(@CurrentUser() user: RequestUser, @Body() dto: BookStatesUploadDto) {
+    return this.pluginService.uploadBookStates(user, dto);
+  }
+
+  @Post('progress')
+  bulkProgress(@CurrentUser() user: RequestUser, @Body() dto: BulkProgressDto) {
+    return this.pluginService.bulkProgress(user, dto);
+  }
+
+  @Post('sweeps')
+  sweepComplete(@CurrentUser() user: RequestUser, @Body() dto: SweepCompleteDto) {
+    return this.pluginService.sweepComplete(user, dto);
+  }
+
+  @Get('version')
+  getVersion() {
+    return this.packageService.getVersionInfo();
+  }
+
+  @Get('package')
+  async downloadUpdatePackage(@CurrentUser() user: RequestUser, @Res() reply: FastifyReply) {
+    const zip = await this.packageService.buildRawPluginPackage(user.id);
+    reply
+      .header('Content-Type', 'application/zip')
+      .header('Content-Disposition', 'attachment; filename="bookorbit.koplugin.zip"')
+      .header('Cache-Control', 'no-store')
+      .send(zip);
+  }
+}
diff --git a/server/src/modules/koreader/koreader-plugin.repository.ts b/server/src/modules/koreader/koreader-plugin.repository.ts
new file mode 100644
index 000000000..d9b76a718
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin.repository.ts
@@ -0,0 +1,401 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, desc, eq, gt, inArray, like, lt, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../db';
+import * as schema from '../../db/schema';
+import {
+  aggregateReadingSessionDailyStats,
+  getDayRangeForDateKeys,
+  getReadingSessionDayKeys,
+  type ReadingDailyStatsSegment,
+} from '../../common/utils/reading-daily-stats.utils';
+import { buildSessionIdPrefix, deriveKoreaderSessions, type DerivedKoreaderSession, type KoreaderPageEvent } from './koreader-stats.util';
+
+type Db = NodePgDatabase<typeof schema>;
+type Tx = Parameters<Parameters<Db['transaction']>[0]>[0];
+
+export interface IngestPageStatsResult {
+  accepted: number;
+  duplicates: number;
+  insertedSessions: DerivedKoreaderSession[];
+  updatedSessions: number;
+  deletedSessions: number;
+}
+
+@Injectable()
+export class KoreaderPluginRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async ingestAndDeriveForBook(params: {
+    userId: number;
+    bookFileId: number;
+    bookId: number;
+    libraryId: number;
+    deviceId: string;
+    events: KoreaderPageEvent[];
+    timeZone: string;
+  }): Promise<IngestPageStatsResult> {
+    const { userId, bookFileId, bookId, libraryId, deviceId, events, timeZone } = params;
+
+    return this.db.transaction(async (tx) => {
+      const inserted = await tx
+        .insert(schema.koreaderPageStats)
+        .values(
+          events.map((event) => ({
+            userId,
+            bookFileId,
+            deviceId,
+            page: event.page,
+            startTime: event.startTime,
+            durationSeconds: event.durationSeconds,
+            totalPages: event.totalPages,
+          })),
+        )
+        .onConflictDoNothing({
+          target: [
+            schema.koreaderPageStats.userId,
+            schema.koreaderPageStats.bookFileId,
+            schema.koreaderPageStats.deviceId,
+            schema.koreaderPageStats.page,
+            schema.koreaderPageStats.startTime,
+          ],
+        })
+        .returning({ id: schema.koreaderPageStats.id });
+
+      const accepted = inserted.length;
+      const duplicates = events.length - accepted;
+      if (accepted === 0) {
+        return { accepted, duplicates, insertedSessions: [], updatedSessions: 0, deletedSessions: 0 };
+      }
+
+      const allEvents = await tx
+        .select({
+          page: schema.koreaderPageStats.page,
+          startTime: schema.koreaderPageStats.startTime,
+          durationSeconds: schema.koreaderPageStats.durationSeconds,
+          totalPages: schema.koreaderPageStats.totalPages,
+        })
+        .from(schema.koreaderPageStats)
+        .where(
+          and(
+            eq(schema.koreaderPageStats.userId, userId),
+            eq(schema.koreaderPageStats.bookFileId, bookFileId),
+            eq(schema.koreaderPageStats.deviceId, deviceId),
+          ),
+        )
+        .orderBy(schema.koreaderPageStats.startTime, schema.koreaderPageStats.page);
+
+      const desired = deriveKoreaderSessions(allEvents, deviceId, bookFileId);
+      const prefix = buildSessionIdPrefix(deviceId, bookFileId);
+
+      const existing = await tx
+        .select({
+          id: schema.readingSessions.id,
+          sessionId: schema.readingSessions.sessionId,
+          startedAt: schema.readingSessions.startedAt,
+          endedAt: schema.readingSessions.endedAt,
+          durationSeconds: schema.readingSessions.durationSeconds,
+          progressDelta: schema.readingSessions.progressDelta,
+          endProgress: schema.readingSessions.endProgress,
+        })
+        .from(schema.readingSessions)
+        .where(
+          and(
+            eq(schema.readingSessions.userId, userId),
+            eq(schema.readingSessions.bookFileId, bookFileId),
+            like(schema.readingSessions.sessionId, `${prefix}%`),
+          ),
+        );
+
+      const desiredById = new Map(desired.map((session) => [session.sessionId, session]));
+      const existingById = new Map(existing.map((session) => [session.sessionId, session]));
+
+      const toDelete = existing.filter((session) => !desiredById.has(session.sessionId));
+      const toInsert = desired.filter((session) => !existingById.has(session.sessionId));
+      const toUpdate = desired.filter((session) => {
+        const current = existingById.get(session.sessionId);
+        if (!current) return false;
+        return (
+          current.endedAt.getTime() !== session.endedAt.getTime() ||
+          current.durationSeconds !== session.durationSeconds ||
+          (current.progressDelta ?? null) !== (session.progressDelta ?? null) ||
+          (current.endProgress ?? null) !== (session.endProgress ?? null)
+        );
+      });
+
+      if (toDelete.length > 0) {
+        await tx.delete(schema.readingSessions).where(
+          inArray(
+            schema.readingSessions.id,
+            toDelete.map((session) => session.id),
+          ),
+        );
+      }
+
+      const upserts = [...toInsert, ...toUpdate];
+      if (upserts.length > 0) {
+        await tx
+          .insert(schema.readingSessions)
+          .values(
+            upserts.map((session) => ({
+              userId,
+              bookFileId,
+              bookId,
+              sessionId: session.sessionId,
+              source: 'koreader' as const,
+              startedAt: session.startedAt,
+              endedAt: session.endedAt,
+              durationSeconds: session.durationSeconds,
+              progressDelta: session.progressDelta,
+              endProgress: session.endProgress,
+            })),
+          )
+          .onConflictDoUpdate({
+            target: [schema.readingSessions.userId, schema.readingSessions.sessionId],
+            set: {
+              endedAt: sql`excluded.ended_at`,
+              durationSeconds: sql`excluded.duration_seconds`,
+              progressDelta: sql`excluded.progress_delta`,
+              endProgress: sql`excluded.end_progress`,
+            },
+          });
+      }
+
+      const affectedDays = new Set<string>();
+      for (const session of toDelete) {
+        for (const day of getReadingSessionDayKeys(
+          {
+            startedAt: session.startedAt,
+            endedAt: session.endedAt,
+            durationSeconds: session.durationSeconds,
+            progressDelta: session.progressDelta ?? null,
+          },
+          timeZone,
+        )) {
+          affectedDays.add(day);
+        }
+      }
+      for (const session of upserts) {
+        for (const day of getReadingSessionDayKeys(session, timeZone)) {
+          affectedDays.add(day);
+        }
+      }
+
+      if (affectedDays.size > 0) {
+        await this.recomputeDailyStats(tx, userId, libraryId, [...affectedDays], timeZone);
+      }
+
+      return {
+        accepted,
+        duplicates,
+        insertedSessions: toInsert,
+        updatedSessions: toUpdate.length,
+        deletedSessions: toDelete.length,
+      };
+    });
+  }
+
+  private async recomputeDailyStats(tx: Tx, userId: number, libraryId: number, days: string[], timeZone: string) {
+    const affectedDays = [...new Set(days)].sort();
+    if (affectedDays.length === 0) return;
+
+    await this.lockDailyStats(tx, userId, libraryId);
+
+    await tx
+      .delete(schema.userReadingDailyStats)
+      .where(
+        and(
+          eq(schema.userReadingDailyStats.userId, userId),
+          eq(schema.userReadingDailyStats.libraryId, libraryId),
+          inArray(schema.userReadingDailyStats.day, affectedDays),
+        ),
+      );
+
+    const range = getDayRangeForDateKeys(affectedDays, timeZone);
+    if (!range) return;
+
+    const rows = await tx
+      .select({
+        startedAt: schema.readingSessions.startedAt,
+        endedAt: schema.readingSessions.endedAt,
+        durationSeconds: schema.readingSessions.durationSeconds,
+        progressDelta: schema.readingSessions.progressDelta,
+      })
+      .from(schema.readingSessions)
+      .innerJoin(schema.books, eq(schema.books.id, schema.readingSessions.bookId))
+      .where(
+        and(
+          eq(schema.readingSessions.userId, userId),
+          eq(schema.books.libraryId, libraryId),
+          lt(schema.readingSessions.startedAt, range.end),
+          gt(schema.readingSessions.endedAt, range.start),
+        ),
+      );
+
+    const segments = aggregateReadingSessionDailyStats(
+      rows.map((row) => ({
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        durationSeconds: row.durationSeconds,
+        progressDelta: row.progressDelta ?? null,
+      })),
+      timeZone,
+      new Set(affectedDays),
+    );
+    await this.insertDailyStatsSegments(tx, userId, libraryId, segments);
+  }
+
+  private async lockDailyStats(tx: Tx, userId: number, libraryId: number): Promise<void> {
+    await tx.execute(sql`select pg_advisory_xact_lock(${userId}::int, ${libraryId}::int)`);
+  }
+
+  private async insertDailyStatsSegments(tx: Tx, userId: number, libraryId: number, segments: ReadingDailyStatsSegment[]): Promise<void> {
+    if (segments.length === 0) return;
+
+    const now = new Date();
+    await tx
+      .insert(schema.userReadingDailyStats)
+      .values(
+        segments.map((segment) => ({
+          userId,
+          libraryId,
+          day: segment.day,
+          readingSeconds: segment.readingSeconds,
+          progressDelta: segment.progressDelta,
+          sessionsCount: segment.sessionsCount,
+          updatedAt: now,
+        })),
+      )
+      .onConflictDoUpdate({
+        target: [schema.userReadingDailyStats.userId, schema.userReadingDailyStats.libraryId, schema.userReadingDailyStats.day],
+        set: {
+          readingSeconds: sql`excluded.reading_seconds`,
+          progressDelta: sql`excluded.progress_delta`,
+          sessionsCount: sql`excluded.sessions_count`,
+          updatedAt: now,
+        },
+      });
+  }
+
+  async getRating(userId: number, bookId: number): Promise<{ rating: number; updatedAt: Date } | null> {
+    const [row] = await this.db
+      .select({ rating: schema.userBookRatings.rating, updatedAt: schema.userBookRatings.updatedAt })
+      .from(schema.userBookRatings)
+      .where(and(eq(schema.userBookRatings.userId, userId), eq(schema.userBookRatings.bookId, bookId)))
+      .limit(1);
+    return row ?? null;
+  }
+
+  async upsertRating(userId: number, bookId: number, rating: number) {
+    await this.db
+      .insert(schema.userBookRatings)
+      .values({ userId, bookId, rating })
+      .onConflictDoUpdate({
+        target: [schema.userBookRatings.userId, schema.userBookRatings.bookId],
+        set: { rating, updatedAt: new Date() },
+      });
+  }
+
+  async upsertSweep(data: {
+    userId: number;
+    deviceId: string;
+    deviceModel: string;
+    pluginVersion: string;
+    booksMatched: number;
+    pageStatsUploaded: number;
+    annotationsUpserted: number;
+  }): Promise<Date> {
+    const lastSweepAt = new Date();
+    await this.db
+      .insert(schema.koreaderDeviceSweeps)
+      .values({
+        userId: data.userId,
+        deviceId: data.deviceId,
+        deviceModel: data.deviceModel,
+        pluginVersion: data.pluginVersion,
+        lastSweepAt,
+        lastSweepBooksMatched: data.booksMatched,
+        lastSweepPageStats: data.pageStatsUploaded,
+        lastSweepAnnotations: data.annotationsUpserted,
+      })
+      .onConflictDoUpdate({
+        target: [schema.koreaderDeviceSweeps.userId, schema.koreaderDeviceSweeps.deviceId],
+        set: {
+          deviceModel: data.deviceModel,
+          pluginVersion: data.pluginVersion,
+          lastSweepAt,
+          lastSweepBooksMatched: data.booksMatched,
+          lastSweepPageStats: data.pageStatsUploaded,
+          lastSweepAnnotations: data.annotationsUpserted,
+        },
+      });
+    return lastSweepAt;
+  }
+
+  async listSweeps(userId: number) {
+    return this.db
+      .select()
+      .from(schema.koreaderDeviceSweeps)
+      .where(eq(schema.koreaderDeviceSweeps.userId, userId))
+      .orderBy(desc(schema.koreaderDeviceSweeps.lastSweepAt));
+  }
+
+  async getPluginTotals(userId: number): Promise<{
+    matchedBooks: number;
+    pageStatEvents: number;
+    annotations: number;
+    trashedAnnotations: number;
+    pendingDeletes: number;
+    failedPositions: number;
+  }> {
+    const result = await this.db.execute<{
+      matched_books: string | number;
+      page_stat_events: string | number;
+      annotations: string | number;
+      trashed_annotations: string | number;
+      pending_deletes: string | number;
+      failed_positions: string | number;
+    }>(sql`
+      select
+        (select count(distinct t.book_file_id) from (
+          select book_file_id from koreader_page_stats where user_id = ${userId}
+          union
+          select ap.book_file_id from annotation_positions ap
+            join annotations a on a.id = ap.annotation_id
+            where a.user_id = ${userId} and a.origin = 'koreader' and ap.book_file_id is not null and ap.format in ('xpointer', 'pdf')
+        ) t) as matched_books,
+        (select count(*) from koreader_page_stats where user_id = ${userId}) as page_stat_events,
+        (select count(*) from annotations where user_id = ${userId} and origin = 'koreader' and deleted_at is null) as annotations,
+        (select count(*) from annotations where user_id = ${userId} and deleted_at is not null) as trashed_annotations,
+        (select count(*) from annotation_sync_state s
+          join annotations a on a.id = s.annotation_id
+          where s.user_id = ${userId} and a.deleted_at is not null and s.delete_acked_at is null) as pending_deletes,
+        (select count(*) from annotation_positions ap
+          join annotations a on a.id = ap.annotation_id
+          where ap.user_id = ${userId} and a.deleted_at is null and ap.status = 'failed') as failed_positions
+    `);
+    const row = result.rows[0];
+    return {
+      matchedBooks: Number(row?.matched_books ?? 0),
+      pageStatEvents: Number(row?.page_stat_events ?? 0),
+      annotations: Number(row?.annotations ?? 0),
+      trashedAnnotations: Number(row?.trashed_annotations ?? 0),
+      pendingDeletes: Number(row?.pending_deletes ?? 0),
+      failedPositions: Number(row?.failed_positions ?? 0),
+    };
+  }
+
+  async getLibraryMaxFileTimestamp(accessibleLibraryIds: number[] | null): Promise<Date | null> {
+    if (accessibleLibraryIds !== null && accessibleLibraryIds.length === 0) return null;
+    const libraryFilter = accessibleLibraryIds ? inArray(schema.books.libraryId, accessibleLibraryIds) : undefined;
+
+    const [row] = await this.db
+      .select({ maxTs: sql<Date | string | null>`max(greatest(${schema.bookFiles.createdAt}, ${schema.bookFiles.updatedAt}))` })
+      .from(schema.bookFiles)
+      .innerJoin(schema.books, eq(schema.books.id, schema.bookFiles.bookId))
+      .where(libraryFilter);
+
+    return row?.maxTs ? new Date(row.maxTs) : null;
+  }
+}
diff --git a/server/src/modules/koreader/koreader-plugin.service.test.ts b/server/src/modules/koreader/koreader-plugin.service.test.ts
new file mode 100644
index 000000000..8654b88b1
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin.service.test.ts
@@ -0,0 +1,244 @@
+import { Logger } from '@nestjs/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestUser } from '../../common/types/request-user';
+import { ACHIEVEMENT_EVENT_BOOK_RATING_CHANGED, type AchievementEventsService } from '../achievement/achievement-events.service';
+import type { UserBookStatusService } from '../user-book-status/user-book-status.service';
+import type { BookStatesUploadDto, BulkProgressDto, MatchCheckDto, SweepCompleteDto } from './dto';
+import type { KoreaderPluginRepository } from './koreader-plugin.repository';
+import { KoreaderPluginService } from './koreader-plugin.service';
+import type { KoreaderRepository } from './koreader.repository';
+import type { KoreaderService } from './koreader.service';
+
+const DEVICE_ID = 'abcdef12-3456-7890-abcd-ef1234567890';
+const HASH_A = 'a'.repeat(32);
+const HASH_B = 'b'.repeat(32);
+
+function makeUser(): RequestUser {
+  return { id: 7, settings: {} } as unknown as RequestUser;
+}
+
+function deviceFields() {
+  return { deviceId: DEVICE_ID, deviceModel: 'Kobo Libra 2', pluginVersion: '0.1.0' };
+}
+
+describe('KoreaderPluginService', () => {
+  let koreaderRepo: {
+    getAccessibleLibraryIds: ReturnType<typeof vi.fn>;
+    resolveBookFilesByHashes: ReturnType<typeof vi.fn>;
+    getAllDeviceProgress: ReturnType<typeof vi.fn>;
+    getReadingProgress: ReturnType<typeof vi.fn>;
+  };
+  let pluginRepo: {
+    getRating: ReturnType<typeof vi.fn>;
+    upsertRating: ReturnType<typeof vi.fn>;
+    upsertSweep: ReturnType<typeof vi.fn>;
+    listSweeps: ReturnType<typeof vi.fn>;
+    getPluginTotals: ReturnType<typeof vi.fn>;
+    getLibraryMaxFileTimestamp: ReturnType<typeof vi.fn>;
+  };
+  let koreaderService: { applyProgressForResolvedFile: ReturnType<typeof vi.fn> };
+  let userBookStatusService: { findOne: ReturnType<typeof vi.fn>; setManual: ReturnType<typeof vi.fn> };
+  let achievementEvents: { emit: ReturnType<typeof vi.fn> };
+  let service: KoreaderPluginService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+
+    koreaderRepo = {
+      getAccessibleLibraryIds: vi.fn().mockResolvedValue([1]),
+      resolveBookFilesByHashes: vi.fn().mockResolvedValue(new Map([[HASH_A, { bookFileId: 10, bookId: 20, libraryId: 1 }]])),
+      getAllDeviceProgress: vi.fn().mockResolvedValue([]),
+      getReadingProgress: vi.fn().mockResolvedValue(null),
+    };
+    pluginRepo = {
+      getRating: vi.fn().mockResolvedValue(null),
+      upsertRating: vi.fn().mockResolvedValue(undefined),
+      upsertSweep: vi.fn().mockResolvedValue(new Date('2026-06-09T10:00:00.000Z')),
+      listSweeps: vi.fn().mockResolvedValue([]),
+      getPluginTotals: vi.fn().mockResolvedValue({ matchedBooks: 0, pageStatEvents: 0, annotations: 0 }),
+      getLibraryMaxFileTimestamp: vi.fn().mockResolvedValue(new Date('2026-06-01T00:00:00.000Z')),
+    };
+    koreaderService = { applyProgressForResolvedFile: vi.fn().mockResolvedValue(undefined) };
+    userBookStatusService = { findOne: vi.fn().mockResolvedValue(null), setManual: vi.fn().mockResolvedValue(undefined) };
+    achievementEvents = { emit: vi.fn() };
+
+    service = new KoreaderPluginService(
+      koreaderRepo as unknown as KoreaderRepository,
+      pluginRepo as unknown as KoreaderPluginRepository,
+      koreaderService as unknown as KoreaderService,
+      userBookStatusService as unknown as UserBookStatusService,
+      achievementEvents as unknown as AchievementEventsService,
+    );
+  });
+
+  describe('matchCheck', () => {
+    it('returns matches and a stable 16-char library version token', async () => {
+      const dto = { ...deviceFields(), hashes: [HASH_A.toUpperCase(), HASH_A, HASH_B] } as MatchCheckDto;
+
+      const result = await service.matchCheck(makeUser(), dto);
+
+      expect(koreaderRepo.resolveBookFilesByHashes).toHaveBeenCalledWith([HASH_A, HASH_B], [1]);
+      expect(result.matches).toEqual([{ hash: HASH_A, bookId: 20, bookFileId: 10 }]);
+      expect(result.libraryVersion).toMatch(/^[0-9a-f]{16}$/);
+    });
+
+    it('changes the library version token when the accessible library set changes', async () => {
+      const dto = { ...deviceFields(), hashes: [HASH_A] } as MatchCheckDto;
+
+      const first = await service.matchCheck(makeUser(), dto);
+      koreaderRepo.getAccessibleLibraryIds.mockResolvedValue([1, 2]);
+      const second = await service.matchCheck(makeUser(), dto);
+
+      expect(second.libraryVersion).not.toBe(first.libraryVersion);
+    });
+  });
+
+  describe('uploadBookStates', () => {
+    function statesDto(books: BookStatesUploadDto['books']): BookStatesUploadDto {
+      return { ...deviceFields(), books } as BookStatesUploadDto;
+    }
+
+    it('reports unmatched hashes', async () => {
+      const result = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_B, status: 'reading' }]));
+      expect(result.unmatched).toEqual([HASH_B]);
+      expect(result.results).toHaveLength(0);
+    });
+
+    it('applies a status when no server status exists', async () => {
+      const result = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'complete', statusModified: '2026-06-01' }]));
+
+      expect(userBookStatusService.setManual).toHaveBeenCalledWith(7, 20, 'read');
+      expect(result.results[0]).toEqual({ hash: HASH_A, statusApplied: true, ratingApplied: false });
+    });
+
+    it('treats an identical status as applied without writing', async () => {
+      userBookStatusService.findOne.mockResolvedValue({ status: 'read', source: 'manual', updatedAt: '2026-06-05T08:00:00.000Z' });
+
+      const result = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'complete', statusModified: '2026-01-01' }]));
+
+      expect(userBookStatusService.setManual).not.toHaveBeenCalled();
+      expect(result.results[0]!.statusApplied).toBe(true);
+    });
+
+    it('applies the device status when its date is strictly newer than the server update', async () => {
+      userBookStatusService.findOne.mockResolvedValue({ status: 'reading', source: 'manual', updatedAt: '2026-06-05T08:00:00.000Z' });
+
+      await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'abandoned', statusModified: '2026-06-06' }]));
+
+      expect(userBookStatusService.setManual).toHaveBeenCalledWith(7, 20, 'abandoned');
+    });
+
+    it('keeps the server status on a same-day tie or older device date', async () => {
+      userBookStatusService.findOne.mockResolvedValue({ status: 'reading', source: 'manual', updatedAt: '2026-06-05T08:00:00.000Z' });
+
+      const tie = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'complete', statusModified: '2026-06-05' }]));
+      const older = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'complete', statusModified: '2026-06-04' }]));
+
+      expect(userBookStatusService.setManual).not.toHaveBeenCalled();
+      expect(tie.results[0]!.statusApplied).toBe(false);
+      expect(older.results[0]!.statusApplied).toBe(false);
+    });
+
+    it('applies a rating when none exists and emits the rating event', async () => {
+      const result = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, rating: 4 }]));
+
+      expect(pluginRepo.upsertRating).toHaveBeenCalledWith(7, 20, 4);
+      expect(achievementEvents.emit).toHaveBeenCalledWith(ACHIEVEMENT_EVENT_BOOK_RATING_CHANGED, { userId: 7, bookIds: [20], rating: 4 });
+      expect(result.results[0]!.ratingApplied).toBe(true);
+    });
+
+    it('keeps the server rating on a same-day tie and never clears without a device rating', async () => {
+      pluginRepo.getRating.mockResolvedValue({ rating: 5, updatedAt: new Date('2026-06-05T08:00:00.000Z') });
+
+      const tie = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, rating: 3, statusModified: '2026-06-05' }]));
+      const noRating = await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, status: 'reading' }]));
+
+      expect(pluginRepo.upsertRating).not.toHaveBeenCalled();
+      expect(tie.results[0]!.ratingApplied).toBe(false);
+      expect(noRating.results[0]!.ratingApplied).toBe(false);
+    });
+
+    it('overwrites the server rating when the device change is newer', async () => {
+      pluginRepo.getRating.mockResolvedValue({ rating: 2, updatedAt: new Date('2026-06-01T08:00:00.000Z') });
+
+      await service.uploadBookStates(makeUser(), statesDto([{ hash: HASH_A, rating: 5, statusModified: '2026-06-02' }]));
+
+      expect(pluginRepo.upsertRating).toHaveBeenCalledWith(7, 20, 5);
+    });
+  });
+
+  describe('bulkProgress', () => {
+    function progressDto(items: BulkProgressDto['items']): BulkProgressDto {
+      return { ...deviceFields(), items } as BulkProgressDto;
+    }
+
+    it('applies progress with the shared device identity', async () => {
+      const result = await service.bulkProgress(
+        makeUser(),
+        progressDto([{ hash: HASH_A, percentage: 0.5, progress: '/body/DocFragment[3]/body', timestamp: 1700000000 }]),
+      );
+
+      expect(koreaderService.applyProgressForResolvedFile).toHaveBeenCalledWith(
+        7,
+        { id: 10, bookId: 20 },
+        {
+          percentage: 0.5,
+          progress: '/body/DocFragment[3]/body',
+          device: 'Kobo Libra 2',
+          deviceId: DEVICE_ID,
+          timestamp: 1700000000,
+        },
+        { skipSharedProgress: false },
+      );
+      expect(result.results[0]).toEqual({ hash: HASH_A, accepted: true });
+    });
+
+    it('skips shared progress updates when something newer is already known server-side', async () => {
+      koreaderRepo.getAllDeviceProgress.mockResolvedValue([{ deviceId: 'other', syncTimestamp: 1800000000, updatedAt: new Date() }]);
+
+      await service.bulkProgress(makeUser(), progressDto([{ hash: HASH_A, percentage: 0.2, timestamp: 1700000000 }]));
+
+      expect(koreaderService.applyProgressForResolvedFile).toHaveBeenCalledWith(7, { id: 10, bookId: 20 }, expect.any(Object), {
+        skipSharedProgress: true,
+      });
+    });
+
+    it('never treats progress as stale without a device timestamp', async () => {
+      koreaderRepo.getAllDeviceProgress.mockResolvedValue([{ deviceId: 'other', syncTimestamp: 1800000000, updatedAt: new Date() }]);
+
+      await service.bulkProgress(makeUser(), progressDto([{ hash: HASH_A, percentage: 0.2 }]));
+
+      expect(koreaderService.applyProgressForResolvedFile).toHaveBeenCalledWith(7, { id: 10, bookId: 20 }, expect.any(Object), {
+        skipSharedProgress: false,
+      });
+    });
+
+    it('reports unmatched hashes', async () => {
+      const result = await service.bulkProgress(makeUser(), progressDto([{ hash: HASH_B, percentage: 0.3 }]));
+      expect(result.unmatched).toEqual([HASH_B]);
+      expect(koreaderService.applyProgressForResolvedFile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('sweepComplete', () => {
+    it('records the sweep and returns the library version', async () => {
+      const dto = { ...deviceFields(), booksMatched: 3, pageStatsUploaded: 120, annotationsUpserted: 4 } as SweepCompleteDto;
+
+      const result = await service.sweepComplete(makeUser(), dto);
+
+      expect(pluginRepo.upsertSweep).toHaveBeenCalledWith({
+        userId: 7,
+        deviceId: DEVICE_ID,
+        deviceModel: 'Kobo Libra 2',
+        pluginVersion: '0.1.0',
+        booksMatched: 3,
+        pageStatsUploaded: 120,
+        annotationsUpserted: 4,
+      });
+      expect(result).toEqual({ ok: true, lastSweepAt: '2026-06-09T10:00:00.000Z', libraryVersion: expect.stringMatching(/^[0-9a-f]{16}$/) });
+    });
+  });
+});
diff --git a/server/src/modules/koreader/koreader-plugin.service.ts b/server/src/modules/koreader/koreader-plugin.service.ts
new file mode 100644
index 000000000..95bc03730
--- /dev/null
+++ b/server/src/modules/koreader/koreader-plugin.service.ts
@@ -0,0 +1,263 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { createHash } from 'crypto';
+
+import type { ReadStatus } from '@bookorbit/types';
+import type { RequestUser } from '../../common/types/request-user';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { ACHIEVEMENT_EVENT_BOOK_RATING_CHANGED, AchievementEventsService } from '../achievement/achievement-events.service';
+import { UserBookStatusService } from '../user-book-status/user-book-status.service';
+import type { BookStatesUploadDto, BulkProgressDto, MatchCheckDto, SweepCompleteDto } from './dto';
+import { KoreaderPluginRepository } from './koreader-plugin.repository';
+import { KoreaderRepository } from './koreader.repository';
+import { KoreaderService } from './koreader.service';
+
+const MATCH_EVENT = 'koreader.plugin.match_check';
+const BOOK_STATES_EVENT = 'koreader.plugin.book_states';
+const BULK_PROGRESS_EVENT = 'koreader.plugin.bulk_progress';
+const SWEEP_EVENT = 'koreader.plugin.sweep';
+
+const DEVICE_STATUS_TO_READ_STATUS: Record<string, ReadStatus> = {
+  reading: 'reading',
+  complete: 'read',
+  abandoned: 'abandoned',
+};
+
+export interface MatchCheckResult {
+  matches: { hash: string; bookId: number; bookFileId: number }[];
+  libraryVersion: string;
+}
+
+export interface BookStatesUploadResult {
+  results: { hash: string; statusApplied: boolean; ratingApplied: boolean }[];
+  unmatched: string[];
+}
+
+export interface BulkProgressResult {
+  results: { hash: string; accepted: boolean }[];
+  unmatched: string[];
+}
+
+export interface SweepCompleteResult {
+  ok: true;
+  lastSweepAt: string;
+  libraryVersion: string;
+}
+
+@Injectable()
+export class KoreaderPluginService {
+  private readonly logger = new Logger(KoreaderPluginService.name);
+
+  constructor(
+    private readonly koreaderRepo: KoreaderRepository,
+    private readonly pluginRepo: KoreaderPluginRepository,
+    private readonly koreaderService: KoreaderService,
+    private readonly userBookStatusService: UserBookStatusService,
+    private readonly achievementEvents: AchievementEventsService,
+  ) {}
+
+  async matchCheck(user: RequestUser, dto: MatchCheckDto): Promise<MatchCheckResult> {
+    const startedAtMs = Date.now();
+    this.logger.log(
+      `[${MATCH_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} hashes=${dto.hashes.length} - match check started`,
+    );
+
+    const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+    const hashes = [...new Set(dto.hashes.map((hash) => hash.toLowerCase()))];
+    const resolved = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+    const matches = [...resolved.entries()].map(([hash, match]) => ({
+      hash,
+      bookId: match.bookId,
+      bookFileId: match.bookFileId,
+    }));
+    const libraryVersion = await this.computeLibraryVersion(accessibleLibraryIds);
+
+    this.logger.log(
+      `[${MATCH_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} matched=${matches.length} total=${hashes.length} - match check completed`,
+    );
+
+    return { matches, libraryVersion };
+  }
+
+  async uploadBookStates(user: RequestUser, dto: BookStatesUploadDto): Promise<BookStatesUploadResult> {
+    const startedAtMs = Date.now();
+    this.logger.log(
+      `[${BOOK_STATES_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} books=${dto.books.length} - book states upload started`,
+    );
+
+    try {
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const hashes = [...new Set(dto.books.map((book) => book.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+      const results: BookStatesUploadResult['results'] = [];
+      const unmatched: string[] = [];
+
+      for (const book of dto.books) {
+        const hash = book.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+
+        let statusApplied = false;
+        let ratingApplied = false;
+        if (book.status) {
+          statusApplied = await this.applyStatus(user.id, match.bookId, book.status, book.statusModified);
+        }
+        if (book.rating) {
+          ratingApplied = await this.applyRating(user.id, match.bookId, book.rating, book.statusModified);
+        }
+        results.push({ hash, statusApplied, ratingApplied });
+      }
+
+      this.logger.log(
+        `[${BOOK_STATES_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} applied=${results.filter((r) => r.statusApplied || r.ratingApplied).length} unmatched=${unmatched.length} - book states upload completed`,
+      );
+
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${BOOK_STATES_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - book states upload failed`,
+      );
+      throw error;
+    }
+  }
+
+  async bulkProgress(user: RequestUser, dto: BulkProgressDto): Promise<BulkProgressResult> {
+    const startedAtMs = Date.now();
+    this.logger.log(
+      `[${BULK_PROGRESS_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} items=${dto.items.length} - bulk progress started`,
+    );
+
+    try {
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const hashes = [...new Set(dto.items.map((item) => item.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+      const results: BulkProgressResult['results'] = [];
+      const unmatched: string[] = [];
+
+      for (const item of dto.items) {
+        const hash = item.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+
+        // A sweep can carry a stale sidecar position from a secondary device (book last opened
+        // there long ago). Record the per-device row regardless, but skip the shared
+        // reading_progress/status updates when something newer is already known server-side.
+        const stale = await this.isStaleProgress(user.id, match.bookFileId, item.timestamp);
+        await this.koreaderService.applyProgressForResolvedFile(
+          user.id,
+          { id: match.bookFileId, bookId: match.bookId },
+          {
+            percentage: item.percentage,
+            progress: item.progress,
+            device: dto.deviceModel,
+            deviceId: dto.deviceId,
+            timestamp: item.timestamp,
+          },
+          { skipSharedProgress: stale },
+        );
+        results.push({ hash, accepted: true });
+      }
+
+      this.logger.log(
+        `[${BULK_PROGRESS_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} accepted=${results.length} unmatched=${unmatched.length} - bulk progress completed`,
+      );
+
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${BULK_PROGRESS_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - bulk progress failed`,
+      );
+      throw error;
+    }
+  }
+
+  async sweepComplete(user: RequestUser, dto: SweepCompleteDto): Promise<SweepCompleteResult> {
+    const startedAtMs = Date.now();
+    const lastSweepAt = await this.pluginRepo.upsertSweep({
+      userId: user.id,
+      deviceId: dto.deviceId,
+      deviceModel: dto.deviceModel,
+      pluginVersion: dto.pluginVersion,
+      booksMatched: dto.booksMatched,
+      pageStatsUploaded: dto.pageStatsUploaded,
+      annotationsUpserted: dto.annotationsUpserted,
+    });
+
+    const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+    const libraryVersion = await this.computeLibraryVersion(accessibleLibraryIds);
+
+    this.logger.log(
+      `[${SWEEP_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} booksMatched=${dto.booksMatched} pageStats=${dto.pageStatsUploaded} annotations=${dto.annotationsUpserted} - sweep recorded`,
+    );
+
+    return { ok: true, lastSweepAt: lastSweepAt.toISOString(), libraryVersion };
+  }
+
+  private async computeLibraryVersion(accessibleLibraryIds: number[] | null): Promise<string> {
+    const maxTs = await this.pluginRepo.getLibraryMaxFileTimestamp(accessibleLibraryIds);
+    const libraryKey = accessibleLibraryIds === null ? 'all' : [...accessibleLibraryIds].sort((a, b) => a - b).join(',');
+    return createHash('md5') // codeql[js/weak-cryptographic-algorithm] - non-security cache token
+      .update(`${libraryKey}|${maxTs ? maxTs.toISOString() : 'none'}`)
+      .digest('hex')
+      .slice(0, 16);
+  }
+
+  private async applyStatus(userId: number, bookId: number, deviceStatus: string, statusModified?: string): Promise<boolean> {
+    const mapped = DEVICE_STATUS_TO_READ_STATUS[deviceStatus];
+    if (!mapped) return false;
+
+    const existing = await this.userBookStatusService.findOne(userId, bookId);
+    if (existing) {
+      if (existing.status === mapped) return true;
+      // Newest change wins at date granularity; a same-day tie keeps the server value.
+      const serverDate = existing.updatedAt.slice(0, 10);
+      if (!statusModified || statusModified <= serverDate) return false;
+    }
+
+    await this.userBookStatusService.setManual(userId, bookId, mapped);
+    return true;
+  }
+
+  private async applyRating(userId: number, bookId: number, rating: number, statusModified?: string): Promise<boolean> {
+    const current = await this.pluginRepo.getRating(userId, bookId);
+    if (current) {
+      if (current.rating === rating) return true;
+      const serverDate = current.updatedAt.toISOString().slice(0, 10);
+      if (!statusModified || statusModified <= serverDate) return false;
+    }
+
+    await this.pluginRepo.upsertRating(userId, bookId, rating);
+    this.achievementEvents.emit(ACHIEVEMENT_EVENT_BOOK_RATING_CHANGED, { userId, bookIds: [bookId], rating });
+    return true;
+  }
+
+  private async isStaleProgress(userId: number, bookFileId: number, timestamp?: number): Promise<boolean> {
+    if (!timestamp) return false;
+
+    const [deviceRows, readingProg] = await Promise.all([
+      this.koreaderRepo.getAllDeviceProgress(bookFileId, userId),
+      this.koreaderRepo.getReadingProgress(bookFileId, userId),
+    ]);
+
+    let newestKnown = 0;
+    for (const row of deviceRows) {
+      const rowTs = row.syncTimestamp ?? Math.floor((row.updatedAt?.getTime() ?? 0) / 1000);
+      newestKnown = Math.max(newestKnown, rowTs);
+    }
+    if (readingProg?.updatedAt) {
+      newestKnown = Math.max(newestKnown, Math.floor(readingProg.updatedAt.getTime() / 1000));
+    }
+
+    return timestamp < newestKnown;
+  }
+}
diff --git a/server/src/modules/koreader/koreader-stats.service.test.ts b/server/src/modules/koreader/koreader-stats.service.test.ts
new file mode 100644
index 000000000..afe7ae7a2
--- /dev/null
+++ b/server/src/modules/koreader/koreader-stats.service.test.ts
@@ -0,0 +1,160 @@
+import { BadRequestException, Logger } from '@nestjs/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestUser } from '../../common/types/request-user';
+import {
+  ACHIEVEMENT_EVENT_BACKFILL,
+  ACHIEVEMENT_EVENT_READING_SESSION_SAVED,
+  type AchievementEventsService,
+} from '../achievement/achievement-events.service';
+import type { PageStatsUploadDto } from './dto';
+import type { KoreaderPluginRepository } from './koreader-plugin.repository';
+import type { KoreaderRepository } from './koreader.repository';
+import { KoreaderStatsService } from './koreader-stats.service';
+import type { DerivedKoreaderSession } from './koreader-stats.util';
+
+const DEVICE_ID = 'abcdef12-3456-7890-abcd-ef1234567890';
+const HASH_A = 'a'.repeat(32);
+const HASH_B = 'b'.repeat(32);
+
+function makeUser(): RequestUser {
+  return { id: 7, settings: { timezone: 'Asia/Kolkata' } } as unknown as RequestUser;
+}
+
+function makeDto(books: PageStatsUploadDto['books']): PageStatsUploadDto {
+  return { deviceId: DEVICE_ID, deviceModel: 'Kobo Libra 2', pluginVersion: '0.1.0', books } as PageStatsUploadDto;
+}
+
+function makeSession(startEpoch: number): DerivedKoreaderSession {
+  return {
+    sessionId: `kor:abcdef12:10:${startEpoch}`,
+    startedAt: new Date(startEpoch * 1000),
+    endedAt: new Date((startEpoch + 60) * 1000),
+    durationSeconds: 60,
+    progressDelta: 1,
+    endProgress: 10,
+  };
+}
+
+describe('KoreaderStatsService', () => {
+  let koreaderRepo: { getAccessibleLibraryIds: ReturnType<typeof vi.fn>; resolveBookFilesByHashes: ReturnType<typeof vi.fn> };
+  let pluginRepo: { ingestAndDeriveForBook: ReturnType<typeof vi.fn> };
+  let achievementEvents: { emit: ReturnType<typeof vi.fn> };
+  let service: KoreaderStatsService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+
+    koreaderRepo = {
+      getAccessibleLibraryIds: vi.fn().mockResolvedValue([1]),
+      resolveBookFilesByHashes: vi.fn().mockResolvedValue(new Map([[HASH_A, { bookFileId: 10, bookId: 20, libraryId: 1 }]])),
+    };
+    pluginRepo = {
+      ingestAndDeriveForBook: vi.fn().mockResolvedValue({ accepted: 2, duplicates: 0, insertedSessions: [], updatedSessions: 0, deletedSessions: 0 }),
+    };
+    achievementEvents = { emit: vi.fn() };
+
+    service = new KoreaderStatsService(
+      koreaderRepo as unknown as KoreaderRepository,
+      pluginRepo as unknown as KoreaderPluginRepository,
+      achievementEvents as unknown as AchievementEventsService,
+    );
+  });
+
+  it('rejects requests with more than 500 events in total', async () => {
+    const events = Array.from({ length: 501 }, (_, i) => ({ page: 1, startTime: 1000 + i, durationSeconds: 10, totalPages: 100 }));
+    await expect(service.uploadPageStats(makeUser(), makeDto([{ hash: HASH_A, events }]))).rejects.toBeInstanceOf(BadRequestException);
+    expect(pluginRepo.ingestAndDeriveForBook).not.toHaveBeenCalled();
+  });
+
+  it('reports unmatched hashes without ingesting them', async () => {
+    const dto = makeDto([
+      { hash: HASH_A, events: [{ page: 1, startTime: 1000, durationSeconds: 30, totalPages: 100 }] },
+      { hash: HASH_B, events: [{ page: 2, startTime: 2000, durationSeconds: 30, totalPages: 100 }] },
+    ]);
+
+    const result = await service.uploadPageStats(makeUser(), dto);
+
+    expect(result.unmatched).toEqual([HASH_B]);
+    expect(result.results).toHaveLength(1);
+    expect(pluginRepo.ingestAndDeriveForBook).toHaveBeenCalledTimes(1);
+    expect(pluginRepo.ingestAndDeriveForBook).toHaveBeenCalledWith({
+      userId: 7,
+      bookFileId: 10,
+      bookId: 20,
+      libraryId: 1,
+      deviceId: DEVICE_ID,
+      events: dto.books[0]!.events,
+      timeZone: 'Asia/Kolkata',
+    });
+  });
+
+  it('returns the max submitted startTime as watermark even when everything is a duplicate', async () => {
+    pluginRepo.ingestAndDeriveForBook.mockResolvedValue({
+      accepted: 0,
+      duplicates: 2,
+      insertedSessions: [],
+      updatedSessions: 0,
+      deletedSessions: 0,
+    });
+    const dto = makeDto([
+      {
+        hash: HASH_A,
+        events: [
+          { page: 1, startTime: 5000, durationSeconds: 30, totalPages: 100 },
+          { page: 2, startTime: 9000, durationSeconds: 30, totalPages: 100 },
+        ],
+      },
+    ]);
+
+    const result = await service.uploadPageStats(makeUser(), dto);
+
+    expect(result.results[0]).toEqual({ hash: HASH_A, accepted: 0, duplicates: 2, watermark: 9000 });
+  });
+
+  it('emits one reading-session event per inserted session below the backfill threshold', async () => {
+    pluginRepo.ingestAndDeriveForBook.mockResolvedValue({
+      accepted: 2,
+      duplicates: 0,
+      insertedSessions: [makeSession(1000), makeSession(5000)],
+      updatedSessions: 0,
+      deletedSessions: 0,
+    });
+    const dto = makeDto([{ hash: HASH_A, events: [{ page: 1, startTime: 1000, durationSeconds: 30, totalPages: 100 }] }]);
+
+    await service.uploadPageStats(makeUser(), dto);
+
+    expect(achievementEvents.emit).toHaveBeenCalledTimes(2);
+    expect(achievementEvents.emit).toHaveBeenCalledWith(
+      ACHIEVEMENT_EVENT_READING_SESSION_SAVED,
+      expect.objectContaining({ userId: 7, bookFileId: 10, durationSeconds: 60, timezone: 'Asia/Kolkata' }),
+    );
+  });
+
+  it('emits a single backfill event when more sessions than the threshold are inserted', async () => {
+    pluginRepo.ingestAndDeriveForBook.mockResolvedValue({
+      accepted: 30,
+      duplicates: 0,
+      insertedSessions: Array.from({ length: 21 }, (_, i) => makeSession(1000 + i * 4000)),
+      updatedSessions: 0,
+      deletedSessions: 0,
+    });
+    const dto = makeDto([{ hash: HASH_A, events: [{ page: 1, startTime: 1000, durationSeconds: 30, totalPages: 100 }] }]);
+
+    await service.uploadPageStats(makeUser(), dto);
+
+    expect(achievementEvents.emit).toHaveBeenCalledTimes(1);
+    expect(achievementEvents.emit).toHaveBeenCalledWith(ACHIEVEMENT_EVENT_BACKFILL, { userId: 7 });
+  });
+
+  it('normalizes hashes to lowercase before resolution', async () => {
+    const dto = makeDto([{ hash: HASH_A.toUpperCase(), events: [{ page: 1, startTime: 1000, durationSeconds: 30, totalPages: 100 }] }]);
+
+    const result = await service.uploadPageStats(makeUser(), dto);
+
+    expect(koreaderRepo.resolveBookFilesByHashes).toHaveBeenCalledWith([HASH_A], [1]);
+    expect(result.results[0]!.hash).toBe(HASH_A);
+  });
+});
diff --git a/server/src/modules/koreader/koreader-stats.service.ts b/server/src/modules/koreader/koreader-stats.service.ts
new file mode 100644
index 000000000..1861e4737
--- /dev/null
+++ b/server/src/modules/koreader/koreader-stats.service.ts
@@ -0,0 +1,131 @@
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
+
+import type { UserSettings } from '@bookorbit/types';
+import type { RequestUser } from '../../common/types/request-user';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { resolveTimeZone } from '../../common/utils/timezone.utils';
+import {
+  ACHIEVEMENT_EVENT_BACKFILL,
+  ACHIEVEMENT_EVENT_READING_SESSION_SAVED,
+  AchievementEventsService,
+} from '../achievement/achievement-events.service';
+import type { PageStatsUploadDto } from './dto';
+import { KoreaderPluginRepository } from './koreader-plugin.repository';
+import { KoreaderRepository } from './koreader.repository';
+import { KOREADER_BACKFILL_EVENT_THRESHOLD, type DerivedKoreaderSession } from './koreader-stats.util';
+
+const PAGE_STATS_EVENT = 'koreader.plugin.page_stats';
+const MAX_EVENTS_PER_REQUEST = 500;
+
+export interface PageStatsBookResult {
+  hash: string;
+  accepted: number;
+  duplicates: number;
+  watermark: number;
+}
+
+export interface PageStatsUploadResult {
+  results: PageStatsBookResult[];
+  unmatched: string[];
+}
+
+@Injectable()
+export class KoreaderStatsService {
+  private readonly logger = new Logger(KoreaderStatsService.name);
+
+  constructor(
+    private readonly koreaderRepo: KoreaderRepository,
+    private readonly pluginRepo: KoreaderPluginRepository,
+    private readonly achievementEvents: AchievementEventsService,
+  ) {}
+
+  async uploadPageStats(user: RequestUser, dto: PageStatsUploadDto): Promise<PageStatsUploadResult> {
+    const startedAtMs = Date.now();
+    const totalEvents = dto.books.reduce((sum, book) => sum + book.events.length, 0);
+    this.logger.log(
+      `[${PAGE_STATS_EVENT}] [start] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} books=${dto.books.length} events=${totalEvents} - page stats upload started`,
+    );
+
+    try {
+      if (totalEvents > MAX_EVENTS_PER_REQUEST) {
+        throw new BadRequestException(`Too many page stat events in one request (max ${MAX_EVENTS_PER_REQUEST})`);
+      }
+
+      const accessibleLibraryIds = await this.koreaderRepo.getAccessibleLibraryIds(user.id);
+      const timeZone = resolveTimeZone((user.settings as unknown as UserSettings | undefined)?.timezone, 'UTC');
+      const hashes = [...new Set(dto.books.map((book) => book.hash.toLowerCase()))];
+      const matches = await this.koreaderRepo.resolveBookFilesByHashes(hashes, accessibleLibraryIds);
+
+      const results: PageStatsBookResult[] = [];
+      const unmatched: string[] = [];
+      const insertedSessions: { session: DerivedKoreaderSession; bookFileId: number }[] = [];
+      let acceptedTotal = 0;
+
+      for (const book of dto.books) {
+        const hash = book.hash.toLowerCase();
+        const match = matches.get(hash);
+        if (!match) {
+          unmatched.push(hash);
+          continue;
+        }
+
+        const result = await this.pluginRepo.ingestAndDeriveForBook({
+          userId: user.id,
+          bookFileId: match.bookFileId,
+          bookId: match.bookId,
+          libraryId: match.libraryId,
+          deviceId: dto.deviceId,
+          events: book.events,
+          timeZone,
+        });
+
+        acceptedTotal += result.accepted;
+        for (const session of result.insertedSessions) {
+          insertedSessions.push({ session, bookFileId: match.bookFileId });
+        }
+
+        // Watermark covers every event processed in this batch, duplicates included, so a plugin
+        // that lost its local state still advances past history the server already has.
+        const watermark = book.events.reduce((max, event) => Math.max(max, event.startTime), 0);
+        results.push({ hash, accepted: result.accepted, duplicates: result.duplicates, watermark });
+      }
+
+      this.emitSessionAchievements(user, insertedSessions);
+
+      this.logger.log(
+        `[${PAGE_STATS_EVENT}] [end] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} accepted=${acceptedTotal} sessionsInserted=${insertedSessions.length} unmatched=${unmatched.length} - page stats upload completed`,
+      );
+
+      return { results, unmatched };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${PAGE_STATS_EVENT}] [fail] userId=${user.id} deviceId=${dto.deviceId.slice(0, 8)} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - page stats upload failed`,
+      );
+      throw error;
+    }
+  }
+
+  private emitSessionAchievements(user: RequestUser, inserted: { session: DerivedKoreaderSession; bookFileId: number }[]) {
+    if (inserted.length === 0) return;
+
+    if (inserted.length > KOREADER_BACKFILL_EVENT_THRESHOLD) {
+      this.achievementEvents.emit(ACHIEVEMENT_EVENT_BACKFILL, { userId: user.id });
+      return;
+    }
+
+    const timezone = resolveTimeZone((user.settings as unknown as UserSettings | undefined)?.timezone, 'UTC');
+    for (const { session, bookFileId } of inserted) {
+      this.achievementEvents.emit(ACHIEVEMENT_EVENT_READING_SESSION_SAVED, {
+        userId: user.id,
+        bookFileId,
+        durationSeconds: session.durationSeconds,
+        startedAt: session.startedAt,
+        endedAt: session.endedAt,
+        progressDelta: session.progressDelta,
+        endProgress: session.endProgress,
+        timezone,
+      });
+    }
+  }
+}
diff --git a/server/src/modules/koreader/koreader-stats.util.test.ts b/server/src/modules/koreader/koreader-stats.util.test.ts
new file mode 100644
index 000000000..35e70f22c
--- /dev/null
+++ b/server/src/modules/koreader/koreader-stats.util.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildSessionId,
+  buildSessionIdPrefix,
+  clusterPageStats,
+  computeClusterMetrics,
+  deriveKoreaderSessions,
+  type KoreaderPageEvent,
+} from './koreader-stats.util';
+
+const DEVICE_ID = 'abcdef12-3456-7890-abcd-ef1234567890';
+const FILE_ID = 42;
+
+function event(startTime: number, durationSeconds = 60, page = 1, totalPages = 100): KoreaderPageEvent {
+  return { page, startTime, durationSeconds, totalPages };
+}
+
+describe('clusterPageStats', () => {
+  it('returns a single cluster for one event', () => {
+    expect(clusterPageStats([event(1000)])).toHaveLength(1);
+  });
+
+  it('returns no clusters for no events', () => {
+    expect(clusterPageStats([])).toHaveLength(0);
+  });
+
+  it('keeps a gap of exactly the threshold in the same cluster', () => {
+    const clusters = clusterPageStats([event(1000, 60), event(1000 + 60 + 1800, 60)]);
+    expect(clusters).toHaveLength(1);
+  });
+
+  it('splits when the gap exceeds the threshold by one second', () => {
+    const clusters = clusterPageStats([event(1000, 60), event(1000 + 60 + 1801, 60)]);
+    expect(clusters).toHaveLength(2);
+  });
+
+  it('sorts unordered input before clustering', () => {
+    const clusters = clusterPageStats([event(5000), event(1000), event(5100)]);
+    expect(clusters).toHaveLength(2);
+    expect(clusters[0]![0]!.startTime).toBe(1000);
+  });
+
+  it('measures gaps from the furthest cluster end with overlapping events', () => {
+    // First event spans 1000-2000; the short second event does not shrink the cluster end,
+    // so an event at 3700 (gap 1700 from 2000) still joins the cluster.
+    const clusters = clusterPageStats([event(1000, 1000), event(1500, 100), event(3700, 60)]);
+    expect(clusters).toHaveLength(1);
+  });
+});
+
+describe('computeClusterMetrics', () => {
+  it('uses the event duration for a single-event cluster', () => {
+    const session = computeClusterMetrics([event(1000, 45, 10, 200)], DEVICE_ID, FILE_ID);
+    expect(session.durationSeconds).toBe(45);
+    expect(session.startedAt).toEqual(new Date(1000 * 1000));
+    expect(session.endedAt).toEqual(new Date(1045 * 1000));
+  });
+
+  it('caps duration at the wall clock span for overlapping events', () => {
+    const session = computeClusterMetrics([event(1000, 600), event(1000, 600)], DEVICE_ID, FILE_ID);
+    expect(session.durationSeconds).toBe(600);
+  });
+
+  it('sums durations and excludes idle time inside the cluster', () => {
+    const session = computeClusterMetrics([event(1000, 60), event(2000, 60)], DEVICE_ID, FILE_ID);
+    expect(session.durationSeconds).toBe(120);
+    expect(session.endedAt).toEqual(new Date(2060 * 1000));
+  });
+
+  it('computes endProgress from the last event and progressDelta from first to last', () => {
+    const session = computeClusterMetrics([event(1000, 60, 10, 200), event(1100, 60, 30, 200)], DEVICE_ID, FILE_ID);
+    expect(session.endProgress).toBe(15);
+    expect(session.progressDelta).toBe(10);
+  });
+
+  it('allows negative progressDelta when reading backwards', () => {
+    const session = computeClusterMetrics([event(1000, 60, 50, 100), event(1100, 60, 20, 100)], DEVICE_ID, FILE_ID);
+    expect(session.progressDelta).toBe(-30);
+    expect(session.endProgress).toBe(20);
+  });
+
+  it('builds deterministic session ids that fit varchar(64)', () => {
+    const session = computeClusterMetrics([event(1000)], DEVICE_ID, FILE_ID);
+    expect(session.sessionId).toBe('kor:abcdef12:42:1000');
+
+    const longest = buildSessionId(DEVICE_ID, 2147483647, 2147483647);
+    expect(longest).toBe('kor:abcdef12:2147483647:2147483647');
+    expect(longest.length).toBeLessThanOrEqual(64);
+  });
+});
+
+describe('deriveKoreaderSessions', () => {
+  it('drops sessions shorter than the minimum duration', () => {
+    const sessions = deriveKoreaderSessions([event(1000, 5)], DEVICE_ID, FILE_ID);
+    expect(sessions).toHaveLength(0);
+  });
+
+  it('merges two sessions when a late gap-filling event arrives, keeping the earlier session id', () => {
+    const early = [event(1000, 60, 10), event(2000, 60, 12)];
+    const late = [event(5000, 60, 20)];
+
+    const before = deriveKoreaderSessions([...early, ...late], DEVICE_ID, FILE_ID);
+    expect(before).toHaveLength(2);
+    expect(before.map((s) => s.sessionId)).toEqual([buildSessionId(DEVICE_ID, FILE_ID, 1000), buildSessionId(DEVICE_ID, FILE_ID, 5000)]);
+
+    const filler = event(3500, 60, 15);
+    const after = deriveKoreaderSessions([...early, ...late, filler], DEVICE_ID, FILE_ID);
+    expect(after).toHaveLength(1);
+    expect(after[0]!.sessionId).toBe(buildSessionId(DEVICE_ID, FILE_ID, 1000));
+    expect(after[0]!.durationSeconds).toBe(240);
+  });
+
+  it('builds a prefix that scopes ids per device and file', () => {
+    expect(buildSessionIdPrefix(DEVICE_ID, FILE_ID)).toBe('kor:abcdef12:42:');
+  });
+});
diff --git a/server/src/modules/koreader/koreader-stats.util.ts b/server/src/modules/koreader/koreader-stats.util.ts
new file mode 100644
index 000000000..2e0409520
--- /dev/null
+++ b/server/src/modules/koreader/koreader-stats.util.ts
@@ -0,0 +1,95 @@
+export const KOREADER_SESSION_GAP_SECONDS = 1800;
+export const KOREADER_MIN_SESSION_SECONDS = 10;
+export const KOREADER_BACKFILL_EVENT_THRESHOLD = 20;
+
+export interface KoreaderPageEvent {
+  page: number;
+  startTime: number;
+  durationSeconds: number;
+  totalPages: number;
+}
+
+export interface DerivedKoreaderSession {
+  sessionId: string;
+  startedAt: Date;
+  endedAt: Date;
+  durationSeconds: number;
+  progressDelta: number | null;
+  endProgress: number | null;
+}
+
+export function buildSessionIdPrefix(deviceId: string, bookFileId: number): string {
+  return `kor:${deviceId.slice(0, 8)}:${bookFileId}:`;
+}
+
+export function buildSessionId(deviceId: string, bookFileId: number, clusterStartEpoch: number): string {
+  return `${buildSessionIdPrefix(deviceId, bookFileId)}${clusterStartEpoch}`;
+}
+
+export function clusterPageStats(events: KoreaderPageEvent[], gapSeconds: number = KOREADER_SESSION_GAP_SECONDS): KoreaderPageEvent[][] {
+  const sorted = [...events].sort((a, b) => a.startTime - b.startTime || a.page - b.page);
+  const clusters: KoreaderPageEvent[][] = [];
+  let current: KoreaderPageEvent[] = [];
+  let clusterEnd = 0;
+
+  for (const event of sorted) {
+    // A gap of exactly gapSeconds stays in the same cluster; only a strictly larger gap splits.
+    if (current.length > 0 && event.startTime - clusterEnd > gapSeconds) {
+      clusters.push(current);
+      current = [];
+    }
+    current.push(event);
+    clusterEnd = Math.max(clusterEnd, event.startTime + event.durationSeconds);
+  }
+  if (current.length > 0) clusters.push(current);
+
+  return clusters;
+}
+
+export function computeClusterMetrics(cluster: KoreaderPageEvent[], deviceId: string, bookFileId: number): DerivedKoreaderSession {
+  const first = cluster[0]!;
+  let endEpoch = first.startTime;
+  let durationSum = 0;
+  let last = first;
+
+  for (const event of cluster) {
+    durationSum += event.durationSeconds;
+    endEpoch = Math.max(endEpoch, event.startTime + event.durationSeconds);
+    if (event.startTime >= last.startTime) last = event;
+  }
+
+  // Sum of page durations excludes idle gaps inside the cluster; the wall-clock cap keeps the
+  // existing reading_sessions invariant that duration never exceeds endedAt - startedAt.
+  const wallClockSeconds = endEpoch - first.startTime;
+  const durationSeconds = Math.min(durationSum, wallClockSeconds);
+  const endProgress = last.totalPages > 0 ? clamp(round2((last.page / last.totalPages) * 100), 0, 100) : null;
+  const progressDelta = last.totalPages > 0 ? clamp(round2(((last.page - first.page) / last.totalPages) * 100), -100, 100) : null;
+
+  return {
+    sessionId: buildSessionId(deviceId, bookFileId, first.startTime),
+    startedAt: new Date(first.startTime * 1000),
+    endedAt: new Date(endEpoch * 1000),
+    durationSeconds,
+    progressDelta,
+    endProgress,
+  };
+}
+
+export function deriveKoreaderSessions(
+  events: KoreaderPageEvent[],
+  deviceId: string,
+  bookFileId: number,
+  gapSeconds: number = KOREADER_SESSION_GAP_SECONDS,
+): DerivedKoreaderSession[] {
+  return clusterPageStats(events, gapSeconds)
+    .map((cluster) => computeClusterMetrics(cluster, deviceId, bookFileId))
+    .filter((session) => session.durationSeconds >= KOREADER_MIN_SESSION_SECONDS);
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
diff --git a/server/src/modules/koreader/koreader.controller.ts b/server/src/modules/koreader/koreader.controller.ts
index 94fc09e83..1227b8b29 100644
--- a/server/src/modules/koreader/koreader.controller.ts
+++ b/server/src/modules/koreader/koreader.controller.ts
@@ -1,4 +1,20 @@
-import { Body, Controller, Delete, ForbiddenException, Get, Headers, Param, ParseIntPipe, Patch, Post, Put, UseGuards } from '@nestjs/common';
+import {
+  Body,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Get,
+  Headers,
+  Param,
+  ParseIntPipe,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Res,
+  UseGuards,
+} from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
 
 import { Permission } from '@bookorbit/types';
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
@@ -6,12 +22,16 @@ import { Public } from '../../common/decorators/public.decorator';
 import { RequirePermission } from '../../common/decorators/require-permission.decorator';
 import type { RequestUser } from '../../common/types/request-user';
 import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderPackageService } from './koreader-package.service';
 import { KoreaderService } from './koreader.service';
-import { CreateKoreaderUserDto, SaveProgressDto, TestConnectionDto, UpdateKoreaderUserDto } from './dto';
+import { CreateKoreaderUserDto, DownloadPluginPackageDto, SaveProgressDto, TestConnectionDto, UpdateKoreaderUserDto } from './dto';
 
 @Controller('koreader')
 export class KoreaderController {
-  constructor(private readonly koreaderService: KoreaderService) {}
+  constructor(
+    private readonly koreaderService: KoreaderService,
+    private readonly packageService: KoreaderPackageService,
+  ) {}
 
   // --- KOReader kosync protocol endpoints (header-based auth) ---
 
@@ -90,10 +110,21 @@ export class KoreaderController {
     return this.koreaderService.getBookProgress(user.id, bookId);
   }
 
+  @RequirePermission(Permission.KoreaderSync)
+  @Get('plugin-package')
+  async downloadPluginPackage(@CurrentUser() user: RequestUser, @Query() query: DownloadPluginPackageDto, @Res() reply: FastifyReply) {
+    const zip = await this.packageService.buildPluginPackage(user.id, query.origin);
+    reply
+      .header('Content-Type', 'application/zip')
+      .header('Content-Disposition', 'attachment; filename="bookorbit.koplugin.zip"')
+      .header('Cache-Control', 'no-store')
+      .send(zip);
+  }
+
   @RequirePermission(Permission.KoreaderSync)
   @Post('test-connection')
   async testConnection(@CurrentUser() user: RequestUser, @Body() dto: TestConnectionDto) {
     const success = await this.koreaderService.testConnection(user.id, dto.username, dto.password);
-    return { success, username: dto.username, serverUrl: '/api/koreader' };
+    return { success, username: dto.username, serverUrl: '/api/v1/koreader' };
   }
 }
diff --git a/server/src/modules/koreader/koreader.module.ts b/server/src/modules/koreader/koreader.module.ts
index 854af79b9..0e095e069 100644
--- a/server/src/modules/koreader/koreader.module.ts
+++ b/server/src/modules/koreader/koreader.module.ts
@@ -2,19 +2,45 @@ import { Module } from '@nestjs/common';
 
 import { CommonModule } from '../../common/common.module';
 import { AchievementModule } from '../achievement/achievement.module';
+import { AnnotationModule } from '../annotation/annotation.module';
+import { BookModule } from '../book/book.module';
+import { OpdsModule } from '../opds/opds.module';
+import { PositionConverterModule } from '../position-converter/position-converter.module';
 import { UserModule } from '../user/user.module';
 import { UserBookStatusModule } from '../user-book-status/user-book-status.module';
+import { KoreaderAnnotationExchangeService } from './koreader-annotation-exchange.service';
 import { KoreaderAuthGuard } from './koreader-auth.guard';
+import { KoreaderCatalogController } from './koreader-catalog.controller';
+import { KoreaderCatalogService } from './koreader-catalog.service';
+import { KoreaderPackageService } from './koreader-package.service';
 import { KoreaderChapterExtractorService } from './koreader-chapter-extractor.service';
 import { KoreaderChapterService } from './koreader-chapter.service';
 import { KoreaderController } from './koreader.controller';
+import { KoreaderPluginAnnotationService } from './koreader-plugin-annotation.service';
+import { KoreaderPluginController } from './koreader-plugin.controller';
+import { KoreaderPluginRepository } from './koreader-plugin.repository';
+import { KoreaderPluginService } from './koreader-plugin.service';
 import { KoreaderRepository } from './koreader.repository';
 import { KoreaderService } from './koreader.service';
+import { KoreaderStatsService } from './koreader-stats.service';
 
 @Module({
-  imports: [CommonModule, UserModule, UserBookStatusModule, AchievementModule],
-  controllers: [KoreaderController],
-  providers: [KoreaderService, KoreaderRepository, KoreaderAuthGuard, KoreaderChapterService, KoreaderChapterExtractorService],
+  imports: [CommonModule, UserModule, UserBookStatusModule, AchievementModule, AnnotationModule, BookModule, OpdsModule, PositionConverterModule],
+  controllers: [KoreaderController, KoreaderPluginController, KoreaderCatalogController],
+  providers: [
+    KoreaderService,
+    KoreaderRepository,
+    KoreaderAuthGuard,
+    KoreaderCatalogService,
+    KoreaderPackageService,
+    KoreaderChapterService,
+    KoreaderChapterExtractorService,
+    KoreaderPluginService,
+    KoreaderPluginRepository,
+    KoreaderPluginAnnotationService,
+    KoreaderAnnotationExchangeService,
+    KoreaderStatsService,
+  ],
   exports: [KoreaderService, KoreaderRepository],
 })
 export class KoreaderModule {}
diff --git a/server/src/modules/koreader/koreader.repository.ts b/server/src/modules/koreader/koreader.repository.ts
index 3e781f8ca..79998ed09 100644
--- a/server/src/modules/koreader/koreader.repository.ts
+++ b/server/src/modules/koreader/koreader.repository.ts
@@ -63,6 +63,57 @@ export class KoreaderRepository {
     return null;
   }
 
+  async resolveBookFilesByHashes(
+    hashes: string[],
+    accessibleLibraryIds: number[] | null,
+  ): Promise<Map<string, { bookFileId: number; bookId: number; libraryId: number }>> {
+    const result = new Map<string, { bookFileId: number; bookId: number; libraryId: number }>();
+    if (hashes.length === 0) return result;
+    if (accessibleLibraryIds !== null && accessibleLibraryIds.length === 0) return result;
+
+    const libraryFilter = accessibleLibraryIds ? inArray(schema.books.libraryId, accessibleLibraryIds) : undefined;
+
+    const direct = await this.db
+      .select({
+        hash: schema.bookFiles.fileHash,
+        bookFileId: schema.bookFiles.id,
+        bookId: schema.bookFiles.bookId,
+        libraryId: schema.books.libraryId,
+      })
+      .from(schema.bookFiles)
+      .innerJoin(schema.books, eq(schema.books.id, schema.bookFiles.bookId))
+      .where(and(inArray(schema.bookFiles.fileHash, hashes), libraryFilter));
+
+    for (const row of direct) {
+      if (row.hash && !result.has(row.hash)) {
+        result.set(row.hash, { bookFileId: row.bookFileId, bookId: row.bookId, libraryId: row.libraryId });
+      }
+    }
+
+    const missing = hashes.filter((hash) => !result.has(hash));
+    if (missing.length === 0) return result;
+
+    const history = await this.db
+      .select({
+        hash: schema.bookFileHashHistory.fileHash,
+        bookFileId: schema.bookFiles.id,
+        bookId: schema.bookFiles.bookId,
+        libraryId: schema.books.libraryId,
+      })
+      .from(schema.bookFileHashHistory)
+      .innerJoin(schema.bookFiles, eq(schema.bookFiles.id, schema.bookFileHashHistory.bookFileId))
+      .innerJoin(schema.books, eq(schema.books.id, schema.bookFiles.bookId))
+      .where(and(inArray(schema.bookFileHashHistory.fileHash, missing), libraryFilter));
+
+    for (const row of history) {
+      if (!result.has(row.hash)) {
+        result.set(row.hash, { bookFileId: row.bookFileId, bookId: row.bookId, libraryId: row.libraryId });
+      }
+    }
+
+    return result;
+  }
+
   async getAccessibleLibraryIds(userId: number): Promise<number[] | null> {
     const user = await this.db.query.users.findFirst({
       where: eq(schema.users.id, userId),
@@ -144,19 +195,31 @@ export class KoreaderRepository {
     return row ?? null;
   }
 
-  async upsertReadingProgress(bookFileId: number, userId: number, percentage: number) {
+  async upsertReadingProgress(bookFileId: number, userId: number, percentage: number, cfi: string | null = null, xpointer: string | null = null) {
     await this.db
       .insert(schema.readingProgress)
-      .values({ bookFileId, userId, percentage })
+      .values({ bookFileId, userId, percentage, cfi, koreaderProgress: xpointer })
       .onConflictDoUpdate({
         target: [schema.readingProgress.bookFileId, schema.readingProgress.userId],
         // Deliberately do NOT update updatedAt here. reading_progress.updatedAt must only
         // change when the web reader writes it, so getProgress can use it as an accurate
         // "last web-reader sync time" for comparison against koreader_device_progress.updatedAt.
-        // KOReader sends percentage + XPointer, while the web reader stores CFI and its own
-        // KOReader-compatible XPointer. If we keep stale web locator fields, clients may resume
-        // at an older location even when KOReader synced newer percentage.
-        set: { percentage, cfi: null, pageNumber: null, koreaderProgress: null, updatedAt: sql`"reading_progress"."updated_at"` },
+        // The cfi stored here is the server-side conversion of KOReader's XPointer (null when
+        // conversion fails) so the web reader resumes at the same paragraph; stale web locator
+        // fields are never kept, or clients may resume at an older location. Kobo location
+        // fields clear because the position no longer matches the device's bookmark; the Kobo
+        // pull path recomputes a precise Location from the cfi.
+        set: {
+          percentage,
+          cfi,
+          pageNumber: null,
+          koreaderProgress: xpointer,
+          koboLocationSource: null,
+          koboLocationType: null,
+          koboLocationValue: null,
+          koboContentSourceProgressPercent: null,
+          updatedAt: sql`"reading_progress"."updated_at"`,
+        },
       });
   }
 
diff --git a/server/src/modules/koreader/koreader.service.test.ts b/server/src/modules/koreader/koreader.service.test.ts
index 4271794fb..4b3b6199e 100644
--- a/server/src/modules/koreader/koreader.service.test.ts
+++ b/server/src/modules/koreader/koreader.service.test.ts
@@ -20,6 +20,8 @@ import { AchievementEventsService, ACHIEVEMENT_EVENT_BOOK_PROGRESS_CHANGED } fro
 import { UserBookStatusService } from '../user-book-status/user-book-status.service';
 import { KoreaderChapterExtractorService } from './koreader-chapter-extractor.service';
 import { KoreaderChapterService } from './koreader-chapter.service';
+import type { KoreaderPackageService } from './koreader-package.service';
+import { KoreaderPluginRepository } from './koreader-plugin.repository';
 import { KoreaderRepository } from './koreader.repository';
 import { KoreaderService } from './koreader.service';
 
@@ -77,6 +79,19 @@ describe('KoreaderService', () => {
   let mockAchievementEvents: {
     emit: ReturnType<typeof vi.fn>;
   };
+  let mockPluginRepo: {
+    listSweeps: ReturnType<typeof vi.fn>;
+    getPluginTotals: ReturnType<typeof vi.fn>;
+  };
+  let mockPositionConverter: {
+    xpointerPointToCfi: ReturnType<typeof vi.fn>;
+  };
+  let mockBookService: {
+    syncKoboReadingStateForExternalProgress: ReturnType<typeof vi.fn>;
+  };
+  let mockPackageService: {
+    getVersionInfo: ReturnType<typeof vi.fn>;
+  };
 
   beforeEach(() => {
     vi.restoreAllMocks();
@@ -133,6 +148,29 @@ describe('KoreaderService', () => {
       emit: vi.fn(),
     };
 
+    mockPositionConverter = {
+      xpointerPointToCfi: vi.fn().mockResolvedValue({ status: 'failed', reason: 'chapter_unavailable' }),
+    };
+
+    mockBookService = {
+      syncKoboReadingStateForExternalProgress: vi.fn().mockResolvedValue(undefined),
+    };
+    mockPackageService = {
+      getVersionInfo: vi.fn().mockResolvedValue({ pluginVersion: 'unknown', serverVersion: '1.0.0' }),
+    };
+
+    mockPluginRepo = {
+      listSweeps: vi.fn().mockResolvedValue([]),
+      getPluginTotals: vi.fn().mockResolvedValue({
+        matchedBooks: 0,
+        trashedAnnotations: 0,
+        pendingDeletes: 0,
+        failedPositions: 0,
+        pageStatEvents: 0,
+        annotations: 0,
+      }),
+    };
+
     mockRepo.deleteKoreaderUser.mockResolvedValue(undefined);
     mockRepo.updateKoreaderUser.mockResolvedValue(undefined);
     mockRepo.upsertDeviceProgress.mockResolvedValue(undefined);
@@ -148,10 +186,14 @@ describe('KoreaderService', () => {
 
     service = new KoreaderService(
       mockRepo as unknown as KoreaderRepository,
+      mockPluginRepo as unknown as KoreaderPluginRepository,
       mockChapterService as unknown as KoreaderChapterService,
       mockChapterExtractor as unknown as KoreaderChapterExtractorService,
       mockUserBookStatusService as unknown as UserBookStatusService,
       mockAchievementEvents as unknown as AchievementEventsService,
+      mockPositionConverter as never,
+      mockBookService as never,
+      mockPackageService as unknown as KoreaderPackageService,
     );
   });
 
@@ -327,7 +369,8 @@ describe('KoreaderService', () => {
         chapterIndex: 6,
         syncTimestamp: 1700000000,
       });
-      expect(mockRepo.upsertReadingProgress).toHaveBeenCalledWith(44, 12, 50);
+      expect(mockRepo.upsertReadingProgress).toHaveBeenCalledWith(44, 12, 50, null, '/body/DocFragment[7]');
+      expect(mockBookService.syncKoboReadingStateForExternalProgress).toHaveBeenCalledWith(12, 44, 50);
       expect(mockUserBookStatusService.autoUpdate).toHaveBeenCalledWith(12, 55, 50);
       expect(mockAchievementEvents.emit).toHaveBeenCalledWith(ACHIEVEMENT_EVENT_BOOK_PROGRESS_CHANGED, {
         userId: 12,
@@ -549,11 +592,105 @@ describe('KoreaderService', () => {
         devices,
         totalSyncedBooks: 14,
         lastSyncAt: '2026-02-01T10:00:00.000Z',
+        latestPluginVersion: null,
+        pluginUpdateAvailable: false,
+        sweeps: [],
+        pluginTotals: { matchedBooks: 0, trashedAnnotations: 0, pendingDeletes: 0, failedPositions: 0, pageStatEvents: 0, annotations: 0 },
       });
 
       expect(getCredentialsSpy).toHaveBeenCalledWith(7);
       expect(getDevicesSpy).toHaveBeenCalledWith(7);
       expect(mockRepo.getTotalSyncedBooks).toHaveBeenCalledWith(7);
+      expect(mockPluginRepo.listSweeps).toHaveBeenCalledWith(7);
+      expect(mockPluginRepo.getPluginTotals).toHaveBeenCalledWith(7);
+      expect(mockPackageService.getVersionInfo).toHaveBeenCalledTimes(1);
+    });
+
+    it('marks only devices with older comparable plugin versions as updateable', async () => {
+      vi.spyOn(service, 'getCredentials').mockResolvedValue(null);
+      vi.spyOn(service, 'getDevices').mockResolvedValue([]);
+      mockRepo.getTotalSyncedBooks.mockResolvedValue(0);
+      mockPackageService.getVersionInfo.mockResolvedValue({ pluginVersion: '0.5.0', serverVersion: '1.0.0' });
+      mockPluginRepo.listSweeps.mockResolvedValue([
+        {
+          deviceId: 'old-device',
+          deviceModel: 'Kobo Libra 2',
+          pluginVersion: '0.4.0',
+          lastSweepAt: new Date('2026-02-01T10:00:00.000Z'),
+          lastSweepBooksMatched: 12,
+          lastSweepPageStats: 30,
+          lastSweepAnnotations: 8,
+        },
+        {
+          deviceId: 'current-device',
+          deviceModel: 'Kobo Clara',
+          pluginVersion: '0.5.0',
+          lastSweepAt: new Date('2026-02-01T11:00:00.000Z'),
+          lastSweepBooksMatched: 3,
+          lastSweepPageStats: 4,
+          lastSweepAnnotations: 5,
+        },
+        {
+          deviceId: 'unknown-device',
+          deviceModel: 'Kobo Sage',
+          pluginVersion: null,
+          lastSweepAt: new Date('2026-02-01T12:00:00.000Z'),
+          lastSweepBooksMatched: 0,
+          lastSweepPageStats: 0,
+          lastSweepAnnotations: 0,
+        },
+      ]);
+
+      const result = await service.getSyncStatus(7);
+
+      expect(result.latestPluginVersion).toBe('0.5.0');
+      expect(result.pluginUpdateAvailable).toBe(true);
+      expect(result.sweeps).toEqual([
+        expect.objectContaining({
+          deviceId: 'old-device',
+          latestPluginVersion: '0.5.0',
+          updateAvailable: true,
+        }),
+        expect.objectContaining({
+          deviceId: 'current-device',
+          latestPluginVersion: '0.5.0',
+          updateAvailable: false,
+        }),
+        expect.objectContaining({
+          deviceId: 'unknown-device',
+          latestPluginVersion: '0.5.0',
+          updateAvailable: null,
+        }),
+      ]);
+    });
+
+    it('keeps plugin update state unknown when the server cannot report a plugin version', async () => {
+      vi.spyOn(service, 'getCredentials').mockResolvedValue(null);
+      vi.spyOn(service, 'getDevices').mockResolvedValue([]);
+      mockRepo.getTotalSyncedBooks.mockResolvedValue(0);
+      mockPackageService.getVersionInfo.mockResolvedValue({ pluginVersion: 'unknown', serverVersion: '1.0.0' });
+      mockPluginRepo.listSweeps.mockResolvedValue([
+        {
+          deviceId: 'device-1',
+          deviceModel: 'Kobo Libra 2',
+          pluginVersion: '0.4.0',
+          lastSweepAt: new Date('2026-02-01T10:00:00.000Z'),
+          lastSweepBooksMatched: 12,
+          lastSweepPageStats: 30,
+          lastSweepAnnotations: 8,
+        },
+      ]);
+
+      const result = await service.getSyncStatus(7);
+
+      expect(result.latestPluginVersion).toBeNull();
+      expect(result.pluginUpdateAvailable).toBe(false);
+      expect(result.sweeps[0]).toEqual(
+        expect.objectContaining({
+          latestPluginVersion: null,
+          updateAvailable: null,
+        }),
+      );
     });
   });
 
diff --git a/server/src/modules/koreader/koreader.service.ts b/server/src/modules/koreader/koreader.service.ts
index d45c3eccf..6f2e17fb0 100644
--- a/server/src/modules/koreader/koreader.service.ts
+++ b/server/src/modules/koreader/koreader.service.ts
@@ -3,9 +3,14 @@ import { hash as bcryptHash } from 'bcryptjs';
 import { createHash } from 'crypto';
 
 import type { KoreaderBookSyncInfo, KoreaderDeviceInfo, KoreaderSyncStatus } from '@bookorbit/types';
+import { isSemverNewer } from '../../common/utils/semver.utils';
 import { KoreaderRepository } from './koreader.repository';
 import { KoreaderChapterService } from './koreader-chapter.service';
 import { KoreaderChapterExtractorService } from './koreader-chapter-extractor.service';
+import { KoreaderPackageService } from './koreader-package.service';
+import { KoreaderPluginRepository } from './koreader-plugin.repository';
+import { BookService } from '../book/book.service';
+import { PositionConverterService } from '../position-converter/position-converter.service';
 import { UserBookStatusService } from '../user-book-status/user-book-status.service';
 import { AchievementEventsService, ACHIEVEMENT_EVENT_BOOK_PROGRESS_CHANGED } from '../achievement/achievement-events.service';
 
@@ -20,10 +25,14 @@ export class KoreaderService {
 
   constructor(
     private readonly repo: KoreaderRepository,
+    private readonly pluginRepo: KoreaderPluginRepository,
     private readonly chapterService: KoreaderChapterService,
     private readonly chapterExtractor: KoreaderChapterExtractorService,
     private readonly userBookStatusService: UserBookStatusService,
     private readonly achievementEvents: AchievementEventsService,
+    private readonly positionConverter: PositionConverterService,
+    private readonly bookService: BookService,
+    private readonly packageService: KoreaderPackageService,
   ) {}
 
   async createCredentials(userId: number, username: string, password: string) {
@@ -118,6 +127,27 @@ export class KoreaderService {
       throw new NotFoundException('Book not found for the given document hash');
     }
 
+    await this.applyProgressForResolvedFile(userId, bookFile, {
+      percentage: data.percentage,
+      progress: data.progress,
+      device,
+      deviceId,
+      timestamp: data.timestamp,
+    });
+
+    this.logger.log(
+      `[${SYNC_EVENT}] [end] userId=${userId} bookFileId=${bookFile.id} device=${device} durationMs=${Date.now() - startedAt} percentage=${data.percentage} - save progress completed`,
+    );
+
+    return { document: data.document, timestamp: data.timestamp ?? Math.floor(Date.now() / 1000) };
+  }
+
+  async applyProgressForResolvedFile(
+    userId: number,
+    bookFile: { id: number; bookId: number },
+    data: { percentage: number; progress?: string; device: string; deviceId: string; timestamp?: number },
+    options?: { skipSharedProgress?: boolean },
+  ) {
     const chapterIndex = this.chapterService.parseChapterIndexFromProgress(data.progress ?? null);
 
     this.chapterExtractor.extractAndStoreChapters(bookFile.id).catch(() => {});
@@ -125,16 +155,20 @@ export class KoreaderService {
     await this.repo.upsertDeviceProgress({
       bookFileId: bookFile.id,
       userId,
-      device,
-      deviceId,
+      device: data.device,
+      deviceId: data.deviceId,
       percentage: data.percentage,
       progress: data.progress ?? null,
       chapterIndex,
       syncTimestamp: data.timestamp ?? null,
     });
 
+    if (options?.skipSharedProgress) return;
+
     const bookorbitPercentage = toBookorbitPercentage(data.percentage);
-    await this.repo.upsertReadingProgress(bookFile.id, userId, bookorbitPercentage);
+    const cfi = data.progress ? await this.convertProgressToCfi(bookFile.id, data.progress) : null;
+    await this.repo.upsertReadingProgress(bookFile.id, userId, bookorbitPercentage, cfi, data.progress ?? null);
+    await this.bookService.syncKoboReadingStateForExternalProgress(userId, bookFile.id, bookorbitPercentage).catch(() => undefined);
     await this.userBookStatusService.autoUpdate(userId, bookFile.bookId, bookorbitPercentage);
     this.achievementEvents.emit(ACHIEVEMENT_EVENT_BOOK_PROGRESS_CHANGED, {
       userId,
@@ -143,12 +177,15 @@ export class KoreaderService {
       progress: bookorbitPercentage,
       source: 'koreader',
     });
+  }
 
-    this.logger.debug(
-      `[${SYNC_EVENT}] [end] userId=${userId} bookFileId=${bookFile.id} device=${device} durationMs=${Date.now() - startedAt} percentage=${data.percentage} - save progress completed`,
-    );
-
-    return { document: data.document, timestamp: data.timestamp ?? Math.floor(Date.now() / 1000) };
+  private async convertProgressToCfi(bookFileId: number, xpointer: string): Promise<string | null> {
+    try {
+      const outcome = await this.positionConverter.xpointerPointToCfi({ bookFileId, pos: xpointer });
+      return outcome.status === 'failed' ? null : (outcome.cfi ?? null);
+    } catch {
+      return null;
+    }
   }
 
   async getProgress(userId: number, documentHash: string) {
@@ -202,12 +239,30 @@ export class KoreaderService {
   }
 
   async getSyncStatus(userId: number): Promise<KoreaderSyncStatus> {
-    const credentials = await this.getCredentials(userId);
-    const devices = await this.getDevices(userId);
-    const totalSyncedBooks = await this.repo.getTotalSyncedBooks(userId);
+    const [credentials, devices, totalSyncedBooks, sweepRows, pluginTotals, versionInfo] = await Promise.all([
+      this.getCredentials(userId),
+      this.getDevices(userId),
+      this.repo.getTotalSyncedBooks(userId),
+      this.pluginRepo.listSweeps(userId),
+      this.pluginRepo.getPluginTotals(userId),
+      this.packageService.getVersionInfo(),
+    ]);
     const lastSyncAt = devices.length > 0 ? devices[0]!.lastSyncAt : null;
+    const latestPluginVersion = versionInfo.pluginVersion === 'unknown' ? null : versionInfo.pluginVersion;
+    const sweeps = sweepRows.map((row) => ({
+      deviceId: row.deviceId,
+      deviceModel: row.deviceModel,
+      pluginVersion: row.pluginVersion,
+      latestPluginVersion,
+      updateAvailable: isSemverNewer(latestPluginVersion, row.pluginVersion),
+      lastSweepAt: row.lastSweepAt.toISOString(),
+      lastSweepBooksMatched: row.lastSweepBooksMatched,
+      lastSweepPageStats: row.lastSweepPageStats,
+      lastSweepAnnotations: row.lastSweepAnnotations,
+    }));
+    const pluginUpdateAvailable = sweeps.some((sweep) => sweep.updateAvailable === true);
 
-    return { credentials, devices, totalSyncedBooks, lastSyncAt };
+    return { credentials, devices, totalSyncedBooks, lastSyncAt, latestPluginVersion, pluginUpdateAvailable, sweeps, pluginTotals };
   }
 
   async getDevices(userId: number): Promise<KoreaderDeviceInfo[]> {
diff --git a/server/src/modules/metadata/lib/opf-parser.test.ts b/server/src/modules/metadata/lib/opf-parser.test.ts
index 2e5815b70..912146fec 100644
--- a/server/src/modules/metadata/lib/opf-parser.test.ts
+++ b/server/src/modules/metadata/lib/opf-parser.test.ts
@@ -418,8 +418,56 @@ describe('parseOpf', () => {
       expect(r.ranobedbId).toBe('ranobe-legacy');
     });
 
+    it('normalizes urn-prefixed provider IDs when opf:scheme is present', () => {
+      const xml = epub2Opf(`
+        <dc:identifier opf:scheme="GOOGLE">urn:google:RPyFDwAAQBAJ</dc:identifier>
+        <dc:identifier opf:scheme="AMAZON">urn:amazon:0345415000</dc:identifier>
+        <dc:identifier opf:scheme="GOODREADS">urn:goodreads:42129393</dc:identifier>
+        <dc:identifier opf:scheme="HARDCOVER">urn:hardcover:new-orleans-rush</dc:identifier>
+        <dc:identifier opf:scheme="OPENLIBRARY">urn:openlibrary:OL20652610W</dc:identifier>
+        <dc:identifier opf:scheme="RANOBEDB">urn:ranobedb:ranobe-legacy</dc:identifier>
+        <dc:identifier opf:scheme="KOBO">urn:kobo:kobo-123</dc:identifier>
+        <dc:identifier opf:scheme="LUBIMYCZYTAC">urn:lubimyczytac:lub-99999</dc:identifier>
+        <dc:identifier opf:scheme="ALADIN">urn:aladin:9791190090018</dc:identifier>
+        <dc:identifier opf:scheme="ITUNES">urn:itunes:123456789</dc:identifier>
+      `);
+      const r = parseOpf(xml);
+      expect(r.googleBooksId).toBe('RPyFDwAAQBAJ');
+      expect(r.amazonId).toBe('0345415000');
+      expect(r.goodreadsId).toBe('42129393');
+      expect(r.hardcoverId).toBe('new-orleans-rush');
+      expect(r.openLibraryId).toBe('OL20652610W');
+      expect(r.ranobedbId).toBe('ranobe-legacy');
+      expect(r.koboId).toBe('kobo-123');
+      expect(r.lubimyczytacId).toBe('lub-99999');
+      expect(r.aladinId).toBe('9791190090018');
+      expect(r.itunesId).toBe('123456789');
+    });
+
+    it('normalizes the real-world Amazon URN value that exceeds the amazon_id column when untrimmed', () => {
+      const r = parseOpf(epub2Opf(`<dc:identifier opf:scheme="AMAZON">urn:amazon:0345415000</dc:identifier>`));
+      expect(r.amazonId).toBe('0345415000');
+      expect(r.amazonId).toHaveLength(10);
+    });
+
+    it('normalizes provider URN prefixes case-insensitively', () => {
+      const xml = epub2Opf(`
+        <dc:identifier>URN:GOOGLE:CaseSensitiveGoogleId</dc:identifier>
+        <dc:identifier>URN:AMAZON:B0G3YRNY6Y</dc:identifier>
+      `);
+      const r = parseOpf(xml);
+      expect(r.googleBooksId).toBe('CaseSensitiveGoogleId');
+      expect(r.amazonId).toBe('B0G3YRNY6Y');
+    });
+
+    it('normalizes Amazon alias prefixes when opf:scheme is present', () => {
+      expect(parseOpf(epub2Opf(`<dc:identifier opf:scheme="AMAZON">amazon:B0G3YRNY6Y</dc:identifier>`)).amazonId).toBe('B0G3YRNY6Y');
+      expect(parseOpf(epub2Opf(`<dc:identifier opf:scheme="AMAZON">asin:B0G3YRNY6Y</dc:identifier>`)).amazonId).toBe('B0G3YRNY6Y');
+      expect(parseOpf(epub2Opf(`<dc:identifier opf:scheme="AMAZON">mobi-asin:B0ABCDEFGH</dc:identifier>`)).amazonId).toBe('B0ABCDEFGH');
+    });
+
     it('opf:scheme format wins over urn: when both are present for the same provider', () => {
-      // urn: appears first in document order — scheme should still win
+      // urn: appears first in document order; scheme should still win.
       const xml = epub2Opf(`
         <dc:identifier>urn:google:OLD_URN_VALUE</dc:identifier>
         <dc:identifier opf:scheme="GOOGLE">SCHEME_VALUE</dc:identifier>
diff --git a/server/src/modules/metadata/lib/opf-parser.ts b/server/src/modules/metadata/lib/opf-parser.ts
index cf3119259..39b3bd235 100644
--- a/server/src/modules/metadata/lib/opf-parser.ts
+++ b/server/src/modules/metadata/lib/opf-parser.ts
@@ -38,7 +38,7 @@ const parser = new XMLParser({
   isArray: (name) => ['creator', 'identifier', 'subject', 'title', 'meta', 'item', 'reference'].includes(name),
   textNodeName: '#text',
   allowBooleanAttributes: true,
-  parseTagValue: false, // keep all values as strings — prevents leading-zero loss on ISBNs and numeric year conversion
+  parseTagValue: false, // keep all values as strings to preserve ISBNs with leading zeroes
 });
 
 function toArray<T>(val: T | T[] | undefined): T[] {
@@ -122,6 +122,34 @@ const PREFIX_TO_PROVIDER: Record<string, ProviderKey> = {
   aladin: 'aladin',
 };
 
+const PROVIDER_PREFIXES: Record<ProviderKey, readonly string[]> = {
+  amazon: ['urn:amazon:', 'amazon:', 'asin:', 'mobi-asin:'],
+  google: ['urn:google:', 'google:'],
+  goodreads: ['urn:goodreads:', 'goodreads:'],
+  hardcover: ['urn:hardcover:', 'hardcover:'],
+  hardcoverEdition: ['urn:hardcover_edition:', 'hardcover_edition:', 'hardcover-edition:', 'hardcoveredition:'],
+  openlibrary: ['urn:openlibrary:', 'openlibrary:'],
+  ranobedb: ['urn:ranobedb:', 'ranobedb:'],
+  kobo: ['urn:kobo:', 'kobo:'],
+  lubimyczytac: ['urn:lubimyczytac:', 'lubimyczytac:'],
+  aladin: ['urn:aladin:', 'aladin:'],
+  itunes: ['urn:itunes:', 'itunes:'],
+};
+
+function normalizeProviderId(provider: ProviderKey, raw: string): string | null {
+  const value = raw.trim();
+  if (!value) return null;
+
+  const lower = value.toLowerCase();
+  for (const prefix of PROVIDER_PREFIXES[provider]) {
+    if (lower.startsWith(prefix)) {
+      return value.slice(prefix.length).trim() || null;
+    }
+  }
+
+  return value;
+}
+
 // Calibre stores custom-column values in a `calibre:user_metadata` JSON blob keyed by column name,
 // each value carrying the actual value under `#value#`. Used only to fill page count / subtitle when null.
 function parseCalibreUserMetadata(raw: string | null): { pageCount: number | null; subtitle: string | null } {
@@ -296,7 +324,7 @@ export function parseOpf(xml: string): ParsedOpf {
   let urnAladinId: string | null = null;
   let urnItunesId: string | null = null;
 
-  // Calibre prefix:value identifiers — lowest priority, resolved after scheme and urn.
+  // Calibre prefix:value identifiers have the lowest priority, after scheme and urn.
   const prefixIds: Partial<Record<ProviderKey, string>> = {};
 
   for (const ident of toArray(metadata['identifier'])) {
@@ -304,57 +332,58 @@ export function parseOpf(xml: string): ParsedOpf {
     const scheme = ((mo['@_opf:scheme'] ?? mo['@_scheme'] ?? '') as string).toLowerCase().trim();
     const value = getText(ident);
     if (!value) continue;
+    const lowerValue = value.toLowerCase();
 
     const looksLikeBareIsbn = scheme === '' && /^[\d\s-]{9,17}$/.test(value) && /^\d{9}[\dX]$|^\d{13}$/.test(value.replace(/[\s-]/g, ''));
-    if (scheme === 'isbn' || value.toLowerCase().includes('isbn') || looksLikeBareIsbn) {
+    if (scheme === 'isbn' || lowerValue.includes('isbn') || looksLikeBareIsbn) {
       const parsed = parseIsbn(value);
       isbn10 ??= parsed.isbn10;
       isbn13 ??= parsed.isbn13;
     }
 
     // opf:scheme-based provider identifiers (preferred format)
-    if (scheme === 'google') schemeGoogleBooksId ??= value || null;
-    if (scheme === 'amazon') schemeAmazonId ??= value || null;
-    if (scheme === 'goodreads') schemeGoodreadsId ??= value || null;
-    if (scheme === 'hardcover') schemeHardcoverId ??= value || null;
+    if (scheme === 'google') schemeGoogleBooksId ??= normalizeProviderId('google', value);
+    if (scheme === 'amazon') schemeAmazonId ??= normalizeProviderId('amazon', value);
+    if (scheme === 'goodreads') schemeGoodreadsId ??= normalizeProviderId('goodreads', value);
+    if (scheme === 'hardcover') schemeHardcoverId ??= normalizeProviderId('hardcover', value);
     if (scheme === 'hardcover_edition' || scheme === 'hardcover-edition' || scheme === 'hardcoveredition') {
-      schemeHardcoverEditionId ??= value || null;
+      schemeHardcoverEditionId ??= normalizeProviderId('hardcoverEdition', value);
     }
-    if (scheme === 'openlibrary') schemeOpenLibraryId ??= value || null;
-    if (scheme === 'ranobedb') schemeRanobedbId ??= value || null;
-    if (scheme === 'kobo') schemeKoboId ??= value || null;
-    if (scheme === 'lubimyczytac') schemeLubimyczytacId ??= value || null;
-    if (scheme === 'aladin') schemeAladinId ??= value || null;
-    if (scheme === 'itunes') schemeItunesId ??= value || null;
+    if (scheme === 'openlibrary') schemeOpenLibraryId ??= normalizeProviderId('openlibrary', value);
+    if (scheme === 'ranobedb') schemeRanobedbId ??= normalizeProviderId('ranobedb', value);
+    if (scheme === 'kobo') schemeKoboId ??= normalizeProviderId('kobo', value);
+    if (scheme === 'lubimyczytac') schemeLubimyczytacId ??= normalizeProviderId('lubimyczytac', value);
+    if (scheme === 'aladin') schemeAladinId ??= normalizeProviderId('aladin', value);
+    if (scheme === 'itunes') schemeItunesId ??= normalizeProviderId('itunes', value);
 
     // urn:-prefixed provider identifiers (legacy / backward-compat)
-    if (value.startsWith('urn:goodreads:')) urnGoodreadsId ??= value.slice('urn:goodreads:'.length) || null;
-    if (value.startsWith('urn:amazon:')) urnAmazonId ??= value.slice('urn:amazon:'.length) || null;
-    if (value.startsWith('urn:hardcover:')) urnHardcoverId ??= value.slice('urn:hardcover:'.length) || null;
-    if (value.startsWith('urn:hardcover_edition:')) urnHardcoverEditionId ??= value.slice('urn:hardcover_edition:'.length) || null;
-    if (value.startsWith('urn:hardcover-edition:')) urnHardcoverEditionId ??= value.slice('urn:hardcover-edition:'.length) || null;
-    if (value.startsWith('urn:google:')) urnGoogleBooksId ??= value.slice('urn:google:'.length) || null;
-    if (value.startsWith('urn:openlibrary:')) urnOpenLibraryId ??= value.slice('urn:openlibrary:'.length) || null;
-    if (value.startsWith('urn:ranobedb:')) urnRanobedbId ??= value.slice('urn:ranobedb:'.length) || null;
-    if (value.startsWith('urn:kobo:')) urnKoboId ??= value.slice('urn:kobo:'.length) || null;
-    if (value.startsWith('urn:lubimyczytac:')) urnLubimyczytacId ??= value.slice('urn:lubimyczytac:'.length) || null;
-    if (value.startsWith('urn:aladin:')) urnAladinId ??= value.slice('urn:aladin:'.length) || null;
-    if (value.startsWith('urn:itunes:')) urnItunesId ??= value.slice('urn:itunes:'.length) || null;
+    if (lowerValue.startsWith('urn:goodreads:')) urnGoodreadsId ??= normalizeProviderId('goodreads', value);
+    if (lowerValue.startsWith('urn:amazon:')) urnAmazonId ??= normalizeProviderId('amazon', value);
+    if (lowerValue.startsWith('urn:hardcover:')) urnHardcoverId ??= normalizeProviderId('hardcover', value);
+    if (lowerValue.startsWith('urn:hardcover_edition:')) urnHardcoverEditionId ??= normalizeProviderId('hardcoverEdition', value);
+    if (lowerValue.startsWith('urn:hardcover-edition:')) urnHardcoverEditionId ??= normalizeProviderId('hardcoverEdition', value);
+    if (lowerValue.startsWith('urn:google:')) urnGoogleBooksId ??= normalizeProviderId('google', value);
+    if (lowerValue.startsWith('urn:openlibrary:')) urnOpenLibraryId ??= normalizeProviderId('openlibrary', value);
+    if (lowerValue.startsWith('urn:ranobedb:')) urnRanobedbId ??= normalizeProviderId('ranobedb', value);
+    if (lowerValue.startsWith('urn:kobo:')) urnKoboId ??= normalizeProviderId('kobo', value);
+    if (lowerValue.startsWith('urn:lubimyczytac:')) urnLubimyczytacId ??= normalizeProviderId('lubimyczytac', value);
+    if (lowerValue.startsWith('urn:aladin:')) urnAladinId ??= normalizeProviderId('aladin', value);
+    if (lowerValue.startsWith('urn:itunes:')) urnItunesId ??= normalizeProviderId('itunes', value);
 
-    // Calibre prefix:value — only when there is no opf:scheme attribute and the value is not a urn:
-    if (scheme === '' && !value.startsWith('urn:')) {
+    // Calibre prefix:value only applies when there is no opf:scheme attribute and the value is not a urn.
+    if (scheme === '' && !lowerValue.startsWith('urn:')) {
       const colon = value.indexOf(':');
       if (colon > 0) {
         const provider = PREFIX_TO_PROVIDER[value.slice(0, colon).toLowerCase()];
         if (provider) {
-          const id = value.slice(colon + 1).trim();
+          const id = normalizeProviderId(provider, value);
           if (id) prefixIds[provider] ??= id;
         }
       }
     }
   }
 
-  // Priority: opf:scheme → urn: → Calibre prefix:value
+  // Priority: opf:scheme, then urn:, then Calibre prefix:value.
   const googleBooksId = schemeGoogleBooksId ?? urnGoogleBooksId ?? prefixIds.google ?? null;
   const goodreadsId = schemeGoodreadsId ?? urnGoodreadsId ?? prefixIds.goodreads ?? null;
   const amazonId = schemeAmazonId ?? urnAmazonId ?? prefixIds.amazon ?? null;
diff --git a/server/src/modules/migration/executor/migration-import.repository.test.ts b/server/src/modules/migration/executor/migration-import.repository.test.ts
index f31f8a3da..cd853a18d 100644
--- a/server/src/modules/migration/executor/migration-import.repository.test.ts
+++ b/server/src/modules/migration/executor/migration-import.repository.test.ts
@@ -330,6 +330,7 @@ describe('MigrationImportRepository', () => {
       .mockResolvedValueOnce([{ id: 102 }])
       .mockResolvedValueOnce([{ id: 103 }])
       .mockResolvedValueOnce([{ id: 104 }])
+      .mockResolvedValueOnce([{ id: 105, userId: 1 }])
       .mockResolvedValueOnce([{ id: 500 }]);
     const onConflictDoUpdate = vi.fn().mockReturnValue({ returning });
     const onConflictDoNothing = vi.fn().mockReturnValue({ returning });
@@ -360,6 +361,7 @@ describe('MigrationImportRepository', () => {
     expect(insert).toHaveBeenCalledWith(schema.genres);
     expect(insert).toHaveBeenCalledWith(schema.tags);
     expect(insert).toHaveBeenCalledWith(schema.annotations);
+    expect(insert).toHaveBeenCalledWith(schema.annotationPositions);
     expect(insert).toHaveBeenCalledWith(schema.collections);
     expect(select).toHaveBeenCalled();
   });
@@ -430,7 +432,8 @@ describe('MigrationImportRepository', () => {
   it('runs batch user-state write methods for non-empty and empty batches', async () => {
     const onConflictDoUpdate = vi.fn().mockResolvedValue(undefined);
     const onConflictDoNothing = vi.fn().mockResolvedValue(undefined);
-    const values = vi.fn().mockReturnValue({ onConflictDoUpdate, onConflictDoNothing });
+    const returning = vi.fn().mockResolvedValue([{ id: 1, userId: 1 }]);
+    const values = vi.fn().mockReturnValue({ onConflictDoUpdate, onConflictDoNothing, returning });
     const insert = vi.fn().mockReturnValue({ values });
     const repo = new MigrationImportRepository({ insert } as never);
 
@@ -456,6 +459,7 @@ describe('MigrationImportRepository', () => {
     expect(insert).toHaveBeenCalledWith(schema.audiobookProgress);
     expect(insert).toHaveBeenCalledWith(schema.bookmarks);
     expect(insert).toHaveBeenCalledWith(schema.annotations);
+    expect(insert).toHaveBeenCalledWith(schema.annotationPositions);
     expect(insert).toHaveBeenCalledWith(schema.collectionBooks);
   });
 });
diff --git a/server/src/modules/migration/executor/migration-import.repository.ts b/server/src/modules/migration/executor/migration-import.repository.ts
index 148a9bdae..c1ebc73a5 100644
--- a/server/src/modules/migration/executor/migration-import.repository.ts
+++ b/server/src/modules/migration/executor/migration-import.repository.ts
@@ -272,13 +272,25 @@ export class MigrationImportRepository {
     const targetUserIds = uniqueNumbers(userIds);
     const targetBookIds = uniqueNumbers(bookIds);
     if (targetUserIds.length === 0 || targetBookIds.length === 0) return;
+    // Only web-origin rows are replaced by an import; device-synced annotations stay.
     await this.db
       .delete(schema.annotations)
-      .where(and(inArray(schema.annotations.userId, targetUserIds), inArray(schema.annotations.bookId, targetBookIds)));
+      .where(
+        and(
+          inArray(schema.annotations.userId, targetUserIds),
+          inArray(schema.annotations.bookId, targetBookIds),
+          eq(schema.annotations.origin, 'web'),
+        ),
+      );
   }
 
-  async insertAnnotation(values: typeof schema.annotations.$inferInsert): Promise<void> {
-    await this.db.insert(schema.annotations).values(values);
+  async insertAnnotation(values: typeof schema.annotations.$inferInsert & { cfi: string }): Promise<void> {
+    const { cfi, ...annotation } = values;
+    const [row] = await this.db
+      .insert(schema.annotations)
+      .values(annotation)
+      .returning({ id: schema.annotations.id, userId: schema.annotations.userId });
+    await this.db.insert(schema.annotationPositions).values({ annotationId: row.id, userId: row.userId, format: 'cfi', pos0: cfi, status: 'exact' });
   }
 
   // --- Collections ---
@@ -513,10 +525,28 @@ export class MigrationImportRepository {
     }
   }
 
-  async batchInsertAnnotations(items: Array<typeof schema.annotations.$inferInsert>): Promise<void> {
+  async batchInsertAnnotations(items: Array<typeof schema.annotations.$inferInsert & { cfi: string }>): Promise<void> {
     if (items.length === 0) return;
     for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
-      await this.db.insert(schema.annotations).values(batch);
+      const rows = await this.db
+        .insert(schema.annotations)
+        .values(
+          batch.map((item) => {
+            const annotation: typeof schema.annotations.$inferInsert & { cfi?: string } = { ...item };
+            delete annotation.cfi;
+            return annotation;
+          }),
+        )
+        .returning({ id: schema.annotations.id, userId: schema.annotations.userId });
+      await this.db.insert(schema.annotationPositions).values(
+        rows.map((row, index) => ({
+          annotationId: row.id,
+          userId: row.userId,
+          format: 'cfi' as const,
+          pos0: batch[index].cfi,
+          status: 'exact' as const,
+        })),
+      );
     }
   }
 
diff --git a/server/src/modules/opds/__tests__/opds-book.service.test.ts b/server/src/modules/opds/__tests__/opds-book.service.test.ts
index 14fea280d..a726d75fa 100644
--- a/server/src/modules/opds/__tests__/opds-book.service.test.ts
+++ b/server/src/modules/opds/__tests__/opds-book.service.test.ts
@@ -79,7 +79,12 @@ describe('OpdsBookService', () => {
     accessSpy.mockResolvedValueOnce([1, 2]);
     smartScopeSpy.mockResolvedValueOnce({ entries: [{ id: 5 }], total: 1 });
     await expect(service.getBooksPage(7, 'recent', 3, 25, { smartScopeId: 4 })).resolves.toEqual({ entries: [{ id: 5 }], total: 1 });
-    expect(smartScopeSpy).toHaveBeenCalledWith(7, 4, [1, 2], 'recent', 3, 25, undefined);
+    expect(smartScopeSpy).toHaveBeenCalledWith(7, 4, [1, 2], 'recent', 3, 25, undefined, undefined);
+
+    accessSpy.mockResolvedValueOnce([1, 2]);
+    smartScopeSpy.mockResolvedValueOnce({ entries: [{ id: 6 }], total: 1 });
+    await expect(service.getBooksPage(7, 'recent', 1, 20, { smartScopeId: 4, q: 'dune' })).resolves.toEqual({ entries: [{ id: 6 }], total: 1 });
+    expect(smartScopeSpy).toHaveBeenCalledWith(7, 4, [1, 2], 'recent', 1, 20, undefined, 'dune');
 
     accessSpy.mockResolvedValueOnce([1, 2]);
     paginatedSpy.mockResolvedValueOnce({ entries: [{ id: 9 }], total: 1 });
@@ -195,6 +200,30 @@ describe('OpdsBookService', () => {
     });
   });
 
+  it('applies text search inside smartScope when q is provided', async () => {
+    const { service } = makeService([[{ id: 3, userId: 7, isPublic: false, filter: null }]]);
+    const paginatedSpy = vi.spyOn(service as never, 'paginatedBookQuery').mockResolvedValue({ entries: [], total: 0 });
+    const searchSpy = vi.spyOn(service as never, 'buildCatalogSearchClause');
+
+    await (service as never).getBooksBySmartScope(7, 3, [1], 'title_asc', 1, 20, undefined, 'dune');
+
+    expect(searchSpy).toHaveBeenCalledWith('dune');
+    expect(paginatedSpy).toHaveBeenCalledTimes(1);
+    const [where] = paginatedSpy.mock.calls[0] as unknown[];
+    expect(collectValues(where)).toContain('%dune%');
+  });
+
+  it('omits text search clause inside smartScope when q is absent', async () => {
+    const { service } = makeService([[{ id: 3, userId: 7, isPublic: false, filter: null }]]);
+    const paginatedSpy = vi.spyOn(service as never, 'paginatedBookQuery').mockResolvedValue({ entries: [], total: 0 });
+    const searchSpy = vi.spyOn(service as never, 'buildCatalogSearchClause');
+
+    await (service as never).getBooksBySmartScope(7, 3, [1], 'title_asc', 1, 20);
+
+    expect(searchSpy).not.toHaveBeenCalled();
+    expect(paginatedSpy).toHaveBeenCalledTimes(1);
+  });
+
   it('returns no smartScope books when smartScope is missing or private to another user', async () => {
     const { service } = makeService([[], [{ id: 5, userId: 99, isPublic: false, filter: null }]]);
 
@@ -227,12 +256,66 @@ describe('OpdsBookService', () => {
     expect(fetchSpy).toHaveBeenCalledWith([3, 1]);
   });
 
+  it('builds read-status, format, and id filters and forwards the user id to pagination', async () => {
+    const { service } = makeService();
+    const accessSpy = vi.spyOn(service, 'getAccessibleLibraryIds');
+    const paginatedSpy = vi.spyOn(service as never, 'paginatedBookQuery').mockResolvedValue({ entries: [{ id: 1 }], total: 1 });
+
+    accessSpy.mockResolvedValueOnce([1, 2]);
+    await expect(service.getBooksPage(7, 'recently_read', 1, 20, { readStatus: 'reading', format: 'EPUB', ids: [3, 1] })).resolves.toEqual({
+      entries: [{ id: 1 }],
+      total: 1,
+    });
+
+    expect(paginatedSpy).toHaveBeenCalledTimes(1);
+    const [where, sortOrder, page, size, userId] = paginatedSpy.mock.calls[0] as unknown[];
+    expect(sortOrder).toBe('recently_read');
+    expect(page).toBe(1);
+    expect(size).toBe(20);
+    expect(userId).toBe(7);
+
+    const values = collectValues(where);
+    expect(values).toContain('reading');
+    expect(values).toContain('epub');
+    expect(values).toContain(3);
+    expect(values).toContain(1);
+  });
+
+  it('short-circuits when an empty id filter is supplied', async () => {
+    const { service } = makeService();
+    vi.spyOn(service, 'getAccessibleLibraryIds').mockResolvedValueOnce([1]);
+    await expect(service.getBooksPage(7, 'recent', 1, 20, { ids: [] })).resolves.toEqual({ entries: [], total: 0 });
+  });
+
+  it('builds unread read-status as a negated active-status subquery', () => {
+    const { service } = makeService();
+
+    const readingClause = (service as never).buildReadStatusClause(7, 'reading');
+    const unreadClause = (service as never).buildReadStatusClause(7, 'unread');
+
+    expect(collectValues(readingClause)).toEqual(expect.arrayContaining([7, 'reading', 'rereading', 'on_hold']));
+    expect(collectValues(unreadClause)).toEqual(expect.arrayContaining([7, 'read', 'skimmed', 'abandoned']));
+  });
+
   it('every sort order includes a books.id tiebreaker as its final ORDER BY clause', async () => {
-    const sortOrders = ['recent', 'title_asc', 'title_desc', 'author_asc', 'author_desc', 'series_asc', 'series_desc'] as const;
+    const sortOrders = [
+      'recent',
+      'recent_asc',
+      'updated',
+      'updated_asc',
+      'recently_read',
+      'recently_read_asc',
+      'title_asc',
+      'title_desc',
+      'author_asc',
+      'author_desc',
+      'series_asc',
+      'series_desc',
+    ] as const;
 
     for (const sortOrder of sortOrders) {
       const { service, db } = makeService([[], [{ total: 0 }]]);
-      await (service as never).paginatedBookQuery({ kind: 'where' }, sortOrder, 1, 25);
+      await (service as never).paginatedBookQuery({ kind: 'where' }, sortOrder, 1, 25, 7);
 
       const chains = (db.select as ReturnType<typeof vi.fn>).mock.results.map((r: { value: Record<string, unknown> }) => r.value);
       const orderByArgs = chains.flatMap((chain: Record<string, unknown>) => {
diff --git a/server/src/modules/opds/opds-book.service.ts b/server/src/modules/opds/opds-book.service.ts
index 569afe02f..3b8cbc60c 100644
--- a/server/src/modules/opds/opds-book.service.ts
+++ b/server/src/modules/opds/opds-book.service.ts
@@ -14,6 +14,7 @@ import {
   collectionBooks,
   smartScopes,
   libraries,
+  userBookStatus,
   userLibraryAccess,
 } from '../../db/schema';
 import { BookQueryBuilder } from '../book/book-query-builder.service';
@@ -22,10 +23,27 @@ import { buildContentFilterClauses } from '../../common/utils/content-filter-sql
 
 type Db = NodePgDatabase<typeof schema>;
 
-type OpdsSortOrder = 'recent' | 'title_asc' | 'title_desc' | 'author_asc' | 'author_desc' | 'series_asc' | 'series_desc';
+type OpdsSortOrder =
+  | 'recent'
+  | 'recent_asc'
+  | 'updated'
+  | 'updated_asc'
+  | 'recently_read'
+  | 'recently_read_asc'
+  | 'title_asc'
+  | 'title_desc'
+  | 'author_asc'
+  | 'author_desc'
+  | 'series_asc'
+  | 'series_desc';
 
 const OPDS_SORT_MAP: Record<OpdsSortOrder, SQL[]> = {
   recent: [sql`${books.addedAt} DESC`, sql`${books.id} ASC`],
+  recent_asc: [sql`${books.addedAt} ASC`, sql`${books.id} ASC`],
+  updated: [sql`${books.updatedAt} DESC`, sql`${books.id} ASC`],
+  updated_asc: [sql`${books.updatedAt} ASC`, sql`${books.id} ASC`],
+  recently_read: [sql`${userBookStatus.updatedAt} DESC NULLS LAST`, sql`${books.id} ASC`],
+  recently_read_asc: [sql`${userBookStatus.updatedAt} ASC NULLS LAST`, sql`${books.id} ASC`],
   title_asc: [sql`${bookMetadata.title} ASC NULLS LAST`, sql`${books.id} ASC`],
   title_desc: [sql`${bookMetadata.title} DESC NULLS LAST`, sql`${books.id} ASC`],
   author_asc: [sql`min(${authors.sortName}) ASC NULLS LAST`, sql`${bookMetadata.title} ASC NULLS LAST`, sql`${books.id} ASC`],
@@ -34,6 +52,13 @@ const OPDS_SORT_MAP: Record<OpdsSortOrder, SQL[]> = {
   series_desc: [sql`${bookMetadata.seriesName} DESC NULLS LAST`, sql`${bookMetadata.seriesIndex} DESC NULLS LAST`, sql`${books.id} ASC`],
 };
 
+const READ_STATUS_BUCKETS = {
+  reading: ['reading', 'rereading', 'on_hold'],
+  finished: ['read', 'skimmed', 'abandoned'],
+} as const;
+
+const ACTIVE_READ_STATUSES = [...READ_STATUS_BUCKETS.reading, ...READ_STATUS_BUCKETS.finished];
+
 const LIKE_SPECIAL_CHARS = /[%_\\]/g;
 
 export interface OpdsBookEntry {
@@ -100,13 +125,25 @@ export class OpdsBookService {
     sortOrder: OpdsSortOrder,
     page: number,
     size: number,
-    filters?: { libraryId?: number; collectionId?: number; smartScopeId?: number; author?: string; series?: string; q?: string },
+    filters?: {
+      libraryId?: number;
+      collectionId?: number;
+      smartScopeId?: number;
+      author?: string;
+      series?: string;
+      q?: string;
+      readStatus?: 'unread' | 'reading' | 'finished';
+      format?: string;
+      ids?: number[];
+    },
     isSuperuser = false,
     contentFilters?: ContentFilterRules,
   ): Promise<{ entries: OpdsBookEntry[]; total: number }> {
     const accessibleIds = await this.getAccessibleLibraryIds(userId, isSuperuser);
     if (accessibleIds.length === 0) return { entries: [], total: 0 };
 
+    if (filters?.ids && filters.ids.length === 0) return { entries: [], total: 0 };
+
     if (filters?.libraryId && !accessibleIds.includes(filters.libraryId)) {
       throw new ForbiddenException('No access to this library');
     }
@@ -123,13 +160,15 @@ export class OpdsBookService {
     }
 
     if (filters?.smartScopeId) {
-      return this.getBooksBySmartScope(userId, filters.smartScopeId, accessibleIds, sortOrder, page, size, contentFilters);
+      return this.getBooksBySmartScope(userId, filters.smartScopeId, accessibleIds, sortOrder, page, size, contentFilters, filters.q);
     }
 
     const clauses: SQL[] = [inArray(books.libraryId, accessibleIds), eq(books.status, 'present')];
 
     if (filters?.libraryId) clauses.push(eq(books.libraryId, filters.libraryId));
 
+    if (filters?.ids) clauses.push(inArray(books.id, filters.ids));
+
     if (filters?.collectionId) {
       clauses.push(
         sql`${books.id} IN (SELECT ${collectionBooks.bookId} FROM ${collectionBooks} WHERE ${collectionBooks.collectionId} = ${filters.collectionId})`,
@@ -146,6 +185,19 @@ export class OpdsBookService {
       clauses.push(eq(bookMetadata.seriesName, filters.series));
     }
 
+    if (filters?.format) {
+      const format = filters.format.trim().toLowerCase();
+      if (format) {
+        clauses.push(
+          sql`${books.id} IN (SELECT ${bookFiles.bookId} FROM ${bookFiles} WHERE ${bookFiles.role} = 'content' AND lower(${bookFiles.format}) = ${format})`,
+        );
+      }
+    }
+
+    if (filters?.readStatus) {
+      clauses.push(this.buildReadStatusClause(userId, filters.readStatus));
+    }
+
     if (filters?.q) {
       const searchClause = this.buildCatalogSearchClause(filters.q);
       if (searchClause) clauses.push(searchClause);
@@ -155,7 +207,15 @@ export class OpdsBookService {
       clauses.push(...buildContentFilterClauses(contentFilters, this.db));
     }
 
-    return this.paginatedBookQuery(and(...clauses)!, sortOrder, page, size);
+    return this.paginatedBookQuery(and(...clauses)!, sortOrder, page, size, userId);
+  }
+
+  private buildReadStatusClause(userId: number, readStatus: 'unread' | 'reading' | 'finished'): SQL {
+    if (readStatus === 'unread') {
+      return sql`${books.id} NOT IN (SELECT ${userBookStatus.bookId} FROM ${userBookStatus} WHERE ${userBookStatus.userId} = ${userId} AND ${userBookStatus.status} IN ${ACTIVE_READ_STATUSES})`;
+    }
+    const statuses = READ_STATUS_BUCKETS[readStatus];
+    return sql`${books.id} IN (SELECT ${userBookStatus.bookId} FROM ${userBookStatus} WHERE ${userBookStatus.userId} = ${userId} AND ${userBookStatus.status} IN ${statuses})`;
   }
 
   private buildCatalogSearchClause(q: string): SQL | undefined {
@@ -285,6 +345,73 @@ export class OpdsBookService {
       .orderBy(sql`${bookMetadata.seriesName} ASC`);
   }
 
+  async getDistinctAuthorsPage(
+    userId: number,
+    opts: { q?: string; limit: number; offset: number },
+    isSuperuser = false,
+    contentFilters?: ContentFilterRules,
+  ): Promise<{ items: { name: string; bookCount: number }[]; hasNext: boolean }> {
+    const accessibleIds = await this.getAccessibleLibraryIds(userId, isSuperuser);
+    if (accessibleIds.length === 0) return { items: [], hasNext: false };
+
+    const filterClauses = !isSuperuser && contentFilters ? buildContentFilterClauses(contentFilters, this.db) : [];
+    const where: SQL[] = [inArray(books.libraryId, accessibleIds)];
+    const term = opts.q?.trim();
+    if (term) {
+      where.push(ilike(authors.name, `%${term.replace(LIKE_SPECIAL_CHARS, '\\$&')}%`));
+    }
+
+    const rows = await this.db
+      .select({
+        name: authors.name,
+        bookCount: sql<number>`count(DISTINCT ${bookAuthors.bookId})::int`,
+      })
+      .from(authors)
+      .innerJoin(bookAuthors, eq(bookAuthors.authorId, authors.id))
+      .innerJoin(books, and(eq(books.id, bookAuthors.bookId), eq(books.status, 'present'), ...filterClauses))
+      .where(and(...where))
+      .groupBy(authors.name, authors.sortName)
+      .orderBy(sql`${authors.sortName} ASC NULLS LAST`)
+      .limit(opts.limit + 1)
+      .offset(opts.offset);
+
+    const hasNext = rows.length > opts.limit;
+    return { items: hasNext ? rows.slice(0, opts.limit) : rows, hasNext };
+  }
+
+  async getDistinctSeriesPage(
+    userId: number,
+    opts: { q?: string; limit: number; offset: number },
+    isSuperuser = false,
+    contentFilters?: ContentFilterRules,
+  ): Promise<{ items: { name: string; bookCount: number }[]; hasNext: boolean }> {
+    const accessibleIds = await this.getAccessibleLibraryIds(userId, isSuperuser);
+    if (accessibleIds.length === 0) return { items: [], hasNext: false };
+
+    const filterClauses = !isSuperuser && contentFilters ? buildContentFilterClauses(contentFilters, this.db) : [];
+    const where: SQL[] = [inArray(books.libraryId, accessibleIds), sql`${bookMetadata.seriesName} IS NOT NULL`];
+    const term = opts.q?.trim();
+    if (term) {
+      where.push(ilike(bookMetadata.seriesName, `%${term.replace(LIKE_SPECIAL_CHARS, '\\$&')}%`));
+    }
+
+    const rows = await this.db
+      .select({
+        name: sql<string>`${bookMetadata.seriesName}`,
+        bookCount: sql<number>`count(DISTINCT ${books.id})::int`,
+      })
+      .from(bookMetadata)
+      .innerJoin(books, and(eq(books.id, bookMetadata.bookId), eq(books.status, 'present'), ...filterClauses))
+      .where(and(...where))
+      .groupBy(bookMetadata.seriesName)
+      .orderBy(sql`${bookMetadata.seriesName} ASC`)
+      .limit(opts.limit + 1)
+      .offset(opts.offset);
+
+    const hasNext = rows.length > opts.limit;
+    return { items: hasNext ? rows.slice(0, opts.limit) : rows, hasNext };
+  }
+
   async getUserCollections(userId: number) {
     return this.db
       .select({
@@ -370,6 +497,7 @@ export class OpdsBookService {
     page: number,
     size: number,
     contentFilters?: ContentFilterRules,
+    q?: string,
   ): Promise<{ entries: OpdsBookEntry[]; total: number }> {
     const [smartScope] = await this.db.select().from(smartScopes).where(eq(smartScopes.id, smartScopeId)).limit(1);
     if (!smartScope) return { entries: [], total: 0 };
@@ -381,8 +509,9 @@ export class OpdsBookService {
       contentFilters,
     });
     const statusClause = eq(books.status, 'present');
-    const combinedWhere = where ? and(where, statusClause) : statusClause;
-    return this.paginatedBookQuery(combinedWhere!, sortOrder, page, size);
+    const searchClause = q?.trim() ? this.buildCatalogSearchClause(q) : undefined;
+    const combinedWhere = and(...([where, statusClause, searchClause].filter(Boolean) as SQL[]));
+    return this.paginatedBookQuery(combinedWhere!, sortOrder, page, size, userId);
   }
 
   private async paginatedBookQuery(
@@ -390,32 +519,50 @@ export class OpdsBookService {
     sortOrder: OpdsSortOrder,
     page: number,
     size: number,
+    userId?: number,
   ): Promise<{ entries: OpdsBookEntry[]; total: number }> {
     const offset = (page - 1) * size;
     const needsAuthorJoin = sortOrder === 'author_asc' || sortOrder === 'author_desc';
+    const needsStatusJoin = (sortOrder === 'recently_read' || sortOrder === 'recently_read_asc') && userId !== undefined;
     const orderClauses = OPDS_SORT_MAP[sortOrder];
 
+    const buildIdQuery = () => {
+      if (needsAuthorJoin) {
+        return this.db
+          .select({ id: books.id })
+          .from(books)
+          .leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
+          .leftJoin(bookAuthors, eq(bookAuthors.bookId, books.id))
+          .leftJoin(authors, eq(authors.id, bookAuthors.authorId))
+          .where(where)
+          .groupBy(books.id, bookMetadata.title, bookMetadata.seriesName, bookMetadata.seriesIndex)
+          .orderBy(...orderClauses)
+          .limit(size)
+          .offset(offset);
+      }
+      if (needsStatusJoin) {
+        return this.db
+          .select({ id: books.id })
+          .from(books)
+          .leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
+          .leftJoin(userBookStatus, and(eq(userBookStatus.bookId, books.id), eq(userBookStatus.userId, userId!)))
+          .where(where)
+          .orderBy(...orderClauses)
+          .limit(size)
+          .offset(offset);
+      }
+      return this.db
+        .select({ id: books.id })
+        .from(books)
+        .leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
+        .where(where)
+        .orderBy(...orderClauses)
+        .limit(size)
+        .offset(offset);
+    };
+
     const [idRows, [{ total }]] = await Promise.all([
-      needsAuthorJoin
-        ? this.db
-            .select({ id: books.id })
-            .from(books)
-            .leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
-            .leftJoin(bookAuthors, eq(bookAuthors.bookId, books.id))
-            .leftJoin(authors, eq(authors.id, bookAuthors.authorId))
-            .where(where)
-            .groupBy(books.id, bookMetadata.title, bookMetadata.seriesName, bookMetadata.seriesIndex)
-            .orderBy(...orderClauses)
-            .limit(size)
-            .offset(offset)
-        : this.db
-            .select({ id: books.id })
-            .from(books)
-            .leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id))
-            .where(where)
-            .orderBy(...orderClauses)
-            .limit(size)
-            .offset(offset),
+      buildIdQuery(),
       this.db.select({ total: count() }).from(books).leftJoin(bookMetadata, eq(bookMetadata.bookId, books.id)).where(where),
     ]);
 
diff --git a/server/src/modules/opds/opds.module.ts b/server/src/modules/opds/opds.module.ts
index 93c7f006a..95b00ff68 100644
--- a/server/src/modules/opds/opds.module.ts
+++ b/server/src/modules/opds/opds.module.ts
@@ -16,5 +16,6 @@ import { OpdsUserService } from './opds-user.service';
   imports: [AppSettingsModule, BookModule, UserModule, CommonModule],
   controllers: [OpdsController, OpdsUserController],
   providers: [OpdsService, OpdsBookService, OpdsUserService, OpdsAuthGuard, OpdsEnabledGuard],
+  exports: [OpdsBookService],
 })
 export class OpdsModule {}
diff --git a/server/src/modules/position-converter/cfi.utils.ts b/server/src/modules/position-converter/cfi.utils.ts
new file mode 100644
index 000000000..ce8ba1569
--- /dev/null
+++ b/server/src/modules/position-converter/cfi.utils.ts
@@ -0,0 +1,389 @@
+/**
+ * EPUB CFI utilities over htmlparser2/cheerio DOM nodes, mirroring the vendored
+ * foliate epubcfi.js (client/public/assets/foliate/epubcfi.js) exactly: same child
+ * indexing model (virtual before/first/last/after, text chunks between elements),
+ * same tokenizer/parser, same range building. Offsets are UTF-16 code units, as in
+ * browser DOM ranges.
+ */
+
+export interface CfiPart {
+  index: number;
+  id?: string;
+  offset?: number | null;
+}
+
+export interface CfiNode {
+  type?: string;
+  name?: string;
+  attribs?: Record<string, string | undefined>;
+  data?: string;
+  parent?: CfiNode | null;
+  children?: CfiNode[];
+}
+
+export interface RangePoint {
+  node: CfiNode;
+  offset: number;
+}
+
+export interface ResolvedCfiPoint {
+  node: CfiNode | null;
+  offset: number | null;
+  before?: boolean;
+  after?: boolean;
+}
+
+export interface ParsedCfiRange {
+  spineStep: number | null;
+  start: CfiPart[];
+  end: CfiPart[];
+}
+
+const CFI_RE = /^epubcfi\((.*)\)$/;
+const NUMBER_RE = /\d/;
+
+export function isTextNode(node: CfiNode | null | undefined): boolean {
+  return node?.type === 'text' || node?.type === 'cdata';
+}
+
+export function isElementNode(node: CfiNode | null | undefined): boolean {
+  return node?.type === 'tag' || node?.type === 'script' || node?.type === 'style';
+}
+
+function escapeCfi(value: string): string {
+  return value.replace(/[\^[\](),;=]/g, '^$&');
+}
+
+function wrapCfi(value: string): string {
+  return CFI_RE.test(value) ? value : `epubcfi(${value})`;
+}
+
+function unwrapCfi(value: string): string {
+  return value.match(CFI_RE)?.[1] ?? value;
+}
+
+function partToString(part: CfiPart): string {
+  return `/${part.index}` + (part.id ? `[${escapeCfi(part.id)}]` : '') + (part.offset != null && part.index % 2 ? `:${part.offset}` : '');
+}
+
+function partsToString(parts: CfiPart[]): string {
+  return parts.map(partToString).join('');
+}
+
+export function getDocumentElement(root: CfiNode): CfiNode | null {
+  if (root.type === 'root') {
+    return (root.children ?? []).find((child) => isElementNode(child)) ?? null;
+  }
+  let current = root;
+  while (current.parent && current.parent.type !== 'root') {
+    current = current.parent;
+  }
+  return current;
+}
+
+function getChildNodes(node: CfiNode): CfiNode[] {
+  return (node.children ?? []).filter((child) => isTextNode(child) || isElementNode(child));
+}
+
+export type IndexedChild = CfiNode | CfiNode[] | null | 'before' | 'after' | 'first' | 'last';
+
+function isIndexedElement(value: IndexedChild | undefined): value is CfiNode {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && isElementNode(value as CfiNode);
+}
+
+export function indexChildNodes(node: CfiNode): IndexedChild[] {
+  const nodes = getChildNodes(node).reduce<IndexedChild[]>((arr, child) => {
+    const last = arr[arr.length - 1];
+    if (!last) {
+      arr.push(child);
+    } else if (isTextNode(child)) {
+      if (Array.isArray(last)) last.push(child);
+      else if (typeof last === 'object' && isTextNode(last)) arr[arr.length - 1] = [last, child];
+      else arr.push(child);
+    } else if (isIndexedElement(last)) {
+      arr.push(null, child);
+    } else {
+      arr.push(child);
+    }
+    return arr;
+  }, []);
+
+  if (isIndexedElement(nodes[0])) nodes.unshift('first');
+  if (isIndexedElement(nodes[nodes.length - 1])) nodes.push('last');
+  nodes.unshift('before');
+  nodes.push('after');
+  return nodes;
+}
+
+function childMatches(indexed: IndexedChild, node: CfiNode): boolean {
+  if (Array.isArray(indexed)) return indexed.includes(node);
+  return indexed === node;
+}
+
+function nodeTextLength(node: CfiNode): number {
+  return node.data?.length ?? 0;
+}
+
+export function nodeToParts(node: CfiNode, offset: number | null = null): CfiPart[] {
+  const parent = node.parent;
+  if (!parent) throw new Error('Cannot build CFI for node without parent');
+
+  const indexed = indexChildNodes(parent);
+  const index = indexed.findIndex((child) => childMatches(child, node));
+  if (index < 0) throw new Error('Cannot locate node in parent CFI index');
+
+  let adjustedOffset = offset;
+  const chunk = indexed[index];
+  if (Array.isArray(chunk) && offset != null) {
+    let sum = 0;
+    for (const child of chunk) {
+      if (child === node) {
+        sum += offset;
+        break;
+      }
+      sum += nodeTextLength(child);
+    }
+    adjustedOffset = sum;
+  }
+
+  const part: CfiPart = { index };
+  const id = node.attribs?.id;
+  if (id) part.id = id;
+  if (adjustedOffset != null) part.offset = adjustedOffset;
+
+  const documentElement = getDocumentElement(node);
+  return parent !== documentElement && parent.type !== 'root' ? nodeToParts(parent).concat(part) : [part];
+}
+
+function buildRange(from: CfiPart[], to: CfiPart[]): string {
+  const parent: CfiPart[] = [];
+  const start: CfiPart[] = [];
+  const end: CfiPart[] = [];
+  let pushToParent = true;
+  const len = Math.max(from.length, to.length);
+
+  for (let index = 0; index < len; index += 1) {
+    const a = from[index];
+    const b = to[index];
+    pushToParent &&= a?.index === b?.index && !a?.offset && !b?.offset;
+    if (pushToParent) {
+      if (a) parent.push(a);
+    } else {
+      if (a) start.push(a);
+      if (b) end.push(b);
+    }
+  }
+
+  return wrapCfi(`${partsToString(parent)},${partsToString(start)},${partsToString(end)}`);
+}
+
+export function joinCfiIndirection(...parts: string[]): string {
+  return wrapCfi(parts.map(unwrapCfi).join('!'));
+}
+
+export function spineCfiForChapterIndex(chapterIndex: number): string {
+  return wrapCfi(`/6/${(chapterIndex + 1) * 2}`);
+}
+
+export function cfiFromRangePoints(start: RangePoint, end: RangePoint): string {
+  const startParts = nodeToParts(start.node, start.offset);
+  const endParts = nodeToParts(end.node, end.offset);
+  return buildRange(startParts, endParts);
+}
+
+export function cfiFromPoint(point: RangePoint): string {
+  return wrapCfi(partsToString(nodeToParts(point.node, point.offset)));
+}
+
+export function findElementById(root: CfiNode, id: string): CfiNode | null {
+  if (isElementNode(root) && root.attribs?.id === id) return root;
+  for (const child of root.children ?? []) {
+    const found = findElementById(child, id);
+    if (found) return found;
+  }
+  return null;
+}
+
+type Token = [string, string | number | null];
+
+function tokenize(str: string): Token[] {
+  const tokens: Token[] = [];
+  let state: string | null = null;
+  let escape = false;
+  let value = '';
+  const push = (token: Token) => {
+    tokens.push(token);
+    state = null;
+    value = '';
+  };
+  const cat = (char: string) => {
+    value += char;
+    escape = false;
+  };
+  for (const char of Array.from(str.trim()).concat('')) {
+    if (char === '^' && !escape) {
+      escape = true;
+      continue;
+    }
+    if (state === '!') push(['!', null]);
+    else if (state === ',') push([',', null]);
+    else if (state === '/' || state === ':') {
+      if (NUMBER_RE.test(char)) {
+        cat(char);
+        continue;
+      } else push([state, parseInt(value, 10)]);
+    } else if (state === '~') {
+      if (NUMBER_RE.test(char) || char === '.') {
+        cat(char);
+        continue;
+      } else push(['~', parseFloat(value)]);
+    } else if (state === '@') {
+      if (char === ':') {
+        push(['@', parseFloat(value)]);
+        state = '@';
+        continue;
+      }
+      if (NUMBER_RE.test(char) || char === '.') {
+        cat(char);
+        continue;
+      } else push(['@', parseFloat(value)]);
+    } else if (state === '[') {
+      if ((char === ';' || char === ',' || char === ']') && !escape) {
+        push(['[', value]);
+        if (char === ';') state = ';';
+        if (char === ',') state = '[';
+      } else {
+        cat(char);
+      }
+      continue;
+    } else if (state?.startsWith(';')) {
+      if (char === ']' && !escape) push([state, value]);
+      else cat(char);
+      continue;
+    }
+    if (char === '/' || char === ':' || char === '~' || char === '@' || char === '[' || char === '!' || char === ',') state = char;
+  }
+  return tokens;
+}
+
+function parseParts(tokens: Token[]): CfiPart[] {
+  const parts: CfiPart[] = [];
+  let state: string | null = null;
+  for (const [type, val] of tokens) {
+    if (type === '/') {
+      parts.push({ index: val as number });
+    } else {
+      const last = parts[parts.length - 1];
+      if (!last) continue;
+      if (type === ':') last.offset = val as number;
+      else if (type === '[' && state === '/' && val) last.id = val as string;
+    }
+    state = type;
+  }
+  return parts;
+}
+
+function splitTokens(tokens: Token[], type: string): Token[][] {
+  const groups: Token[][] = [];
+  let current: Token[] = [];
+  for (const token of tokens) {
+    if (token[0] === type) {
+      groups.push(current);
+      current = [];
+    } else {
+      current.push(token);
+    }
+  }
+  groups.push(current);
+  return groups;
+}
+
+/**
+ * Parses a CFI string (plain or range) into spine step + doc-local start/end parts.
+ * Range CFIs collapse like foliate: start = parent + start segment, end = parent + end.
+ * The spine step is the index of the second part of the first indirection segment
+ * (epubcfi(/6/12!...) -> 12); chapterIndex = step / 2 - 1.
+ */
+export function parseCfi(cfi: string): ParsedCfiRange | null {
+  const tokens = tokenize(unwrapCfi(cfi));
+  if (tokens.length === 0) return null;
+
+  const commaGroups = splitTokens(tokens, ',');
+  const parseIndirection = (group: Token[]): CfiPart[][] => splitTokens(group, '!').map(parseParts);
+
+  let startSegments: CfiPart[][];
+  let endSegments: CfiPart[][];
+  if (commaGroups.length === 3) {
+    const [parent, start, end] = commaGroups.map(parseIndirection);
+    const concat = (tail: CfiPart[][]): CfiPart[][] => {
+      const merged = parent.map((segment) => [...segment]);
+      merged[merged.length - 1] = merged[merged.length - 1].concat(tail[0] ?? []);
+      return merged.concat(tail.slice(1));
+    };
+    startSegments = concat(start);
+    endSegments = concat(end);
+  } else if (commaGroups.length === 1) {
+    startSegments = parseIndirection(commaGroups[0]);
+    endSegments = startSegments;
+  } else {
+    return null;
+  }
+
+  const spineStep = startSegments.length > 1 ? (startSegments[0][1]?.index ?? null) : null;
+  return {
+    spineStep,
+    start: startSegments[startSegments.length - 1],
+    end: endSegments[endSegments.length - 1],
+  };
+}
+
+export function chapterIndexFromSpineStep(spineStep: number | null): number | null {
+  if (spineStep == null || spineStep % 2 !== 0 || spineStep < 2) return null;
+  return spineStep / 2 - 1;
+}
+
+/**
+ * Resolves doc-local CFI parts against a chapter document, foliate partsToNode style.
+ * Returns the concrete text node and UTF-16 offset within it for text positions, or
+ * the element for element positions.
+ */
+export function resolveCfiParts(root: CfiNode, parts: CfiPart[]): ResolvedCfiPoint | null {
+  if (parts.length === 0) return null;
+  const documentElement = getDocumentElement(root);
+  if (!documentElement) return null;
+
+  const lastId = parts[parts.length - 1].id;
+  if (lastId) {
+    const byId = findElementById(documentElement, lastId);
+    if (byId) return { node: byId, offset: 0 };
+  }
+
+  let node: IndexedChild | undefined = documentElement;
+  for (const { index } of parts) {
+    const next: IndexedChild | undefined = node && typeof node === 'object' && !Array.isArray(node) ? indexChildNodes(node)[index] : undefined;
+    if (next === 'first') return { node: (node as CfiNode).children?.[0] ?? (node as CfiNode), offset: null };
+    if (next === 'last') {
+      const children = (node as CfiNode).children ?? [];
+      return { node: children[children.length - 1] ?? (node as CfiNode), offset: null };
+    }
+    if (next === 'before') return { node: node as CfiNode, offset: null, before: true };
+    if (next === 'after') return { node: node as CfiNode, offset: null, after: true };
+    node = next;
+  }
+
+  const offset = parts[parts.length - 1].offset ?? null;
+  if (node == null) return null;
+  if (!Array.isArray(node)) {
+    return { node, offset };
+  }
+
+  let sum = 0;
+  const target = offset ?? 0;
+  for (const part of node) {
+    const length = nodeTextLength(part);
+    if (sum + length >= target) return { node: part, offset: target - sum };
+    sum += length;
+  }
+  const lastNode = node[node.length - 1];
+  return lastNode ? { node: lastNode, offset: nodeTextLength(lastNode) } : null;
+}
diff --git a/server/src/modules/position-converter/chapter-text-index.ts b/server/src/modules/position-converter/chapter-text-index.ts
new file mode 100644
index 000000000..9f307f724
--- /dev/null
+++ b/server/src/modules/position-converter/chapter-text-index.ts
@@ -0,0 +1,377 @@
+/**
+ * Collapsed-text index over a chapter DOM, approximating how crengine builds its
+ * text nodes (whitespace runs collapse to single spaces, leading whitespace after
+ * block boundaries drops). Every collapsed CODE POINT maps back to its raw text
+ * node + UTF-16 offset, so positions can be translated between:
+ * - crengine xpointer offsets (code points in the collapsed view of a text run)
+ * - browser/CFI offsets (UTF-16 code units in the raw text nodes)
+ * Synthetic separators are inserted between blocks for search quality; they map to
+ * no raw position and are skipped when resolving range endpoints.
+ */
+
+import { CfiNode, getDocumentElement, isElementNode, isTextNode } from './cfi.utils';
+
+const BLOCK_ELEMENTS = new Set([
+  'address',
+  'article',
+  'aside',
+  'blockquote',
+  'body',
+  'caption',
+  'dd',
+  'div',
+  'dl',
+  'dt',
+  'fieldset',
+  'figcaption',
+  'figure',
+  'footer',
+  'form',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'header',
+  'hr',
+  'li',
+  'main',
+  'nav',
+  'ol',
+  'p',
+  'pre',
+  'section',
+  'table',
+  'tbody',
+  'td',
+  'tfoot',
+  'th',
+  'thead',
+  'tr',
+  'ul',
+]);
+
+const WHITESPACE_RE = /\s/;
+
+export interface TextRun {
+  parts: { node: CfiNode; rawLength: number }[];
+  parent: CfiNode;
+  runIndex: number;
+  runCount: number;
+  collapsedStart: number;
+  collapsedLength: number;
+}
+
+export interface RawPoint {
+  node: CfiNode;
+  offset: number;
+}
+
+export interface SearchMatch {
+  startCp: number;
+  endCp: number;
+  distance: number | null;
+}
+
+interface BuildState {
+  collapsedPoints: string[];
+  runByPoint: number[];
+  rawOffsetByPoint: number[];
+  atBoundary: boolean;
+  lastWasSpace: boolean;
+  separatorPending: boolean;
+}
+
+export function normalizeForSearch(text: string): string {
+  return text.normalize('NFC').replace(/\s+/g, ' ').trim();
+}
+
+export class ChapterTextIndex {
+  readonly collapsed: string;
+  readonly collapsedCpLength: number;
+  readonly runs: TextRun[];
+
+  private readonly runByPoint: Int32Array;
+  private readonly rawOffsetByPoint: Int32Array;
+  private readonly cpByUtf16: Int32Array;
+  private readonly runsByParent = new Map<CfiNode, TextRun[]>();
+  private readonly runInfoByNode = new Map<CfiNode, { run: TextRun; rawStart: number }>();
+
+  constructor(root: CfiNode) {
+    const state: BuildState = {
+      collapsedPoints: [],
+      runByPoint: [],
+      rawOffsetByPoint: [],
+      atBoundary: true,
+      lastWasSpace: false,
+      separatorPending: false,
+    };
+    const runs: TextRun[] = [];
+
+    const documentElement = getDocumentElement(root);
+    const body =
+      (documentElement?.children ?? []).find((child): child is CfiNode => isElementNode(child) && (child.name ?? '').toLowerCase() === 'body') ??
+      documentElement;
+    if (body) this.walkElement(body, state, runs);
+
+    this.runs = runs;
+    this.collapsed = state.collapsedPoints.join('');
+    this.collapsedCpLength = state.collapsedPoints.length;
+    this.runByPoint = Int32Array.from(state.runByPoint);
+    this.rawOffsetByPoint = Int32Array.from(state.rawOffsetByPoint);
+
+    this.cpByUtf16 = new Int32Array(this.collapsed.length + 1);
+    let utf16 = 0;
+    for (let cp = 0; cp < state.collapsedPoints.length; cp += 1) {
+      const len = state.collapsedPoints[cp].length;
+      for (let k = 0; k < len; k += 1) this.cpByUtf16[utf16 + k] = cp;
+      utf16 += len;
+    }
+    this.cpByUtf16[this.collapsed.length] = state.collapsedPoints.length;
+
+    for (const run of runs) {
+      const list = this.runsByParent.get(run.parent) ?? [];
+      list.push(run);
+      this.runsByParent.set(run.parent, list);
+    }
+    for (const [, list] of this.runsByParent) {
+      for (let i = 0; i < list.length; i += 1) {
+        list[i].runIndex = i + 1;
+        list[i].runCount = list.length;
+      }
+    }
+  }
+
+  private walkElement(element: CfiNode, state: BuildState, runs: TextRun[]): void {
+    const children = element.children ?? [];
+    let i = 0;
+    while (i < children.length) {
+      const child = children[i];
+      if (isTextNode(child)) {
+        const parts: CfiNode[] = [];
+        while (i < children.length && isTextNode(children[i])) {
+          parts.push(children[i]);
+          i += 1;
+        }
+        this.emitRun(parts, element, state, runs);
+        continue;
+      }
+      if (isElementNode(child)) {
+        const isBlock = BLOCK_ELEMENTS.has((child.name ?? '').toLowerCase());
+        if (isBlock) {
+          state.atBoundary = true;
+          state.separatorPending = state.collapsedPoints.length > 0;
+        }
+        this.walkElement(child, state, runs);
+        if (isBlock) {
+          state.atBoundary = true;
+          state.separatorPending = state.collapsedPoints.length > 0;
+        }
+      }
+      i += 1;
+    }
+  }
+
+  private emitRun(partNodes: CfiNode[], parent: CfiNode, state: BuildState, runs: TextRun[]): void {
+    const run: TextRun = {
+      parts: partNodes.map((node) => ({ node, rawLength: node.data?.length ?? 0 })),
+      parent,
+      runIndex: 0,
+      runCount: 0,
+      collapsedStart: state.collapsedPoints.length,
+      collapsedLength: 0,
+    };
+    const runIdx = runs.length;
+    let emittedAny = false;
+    let rawConcatOffset = 0;
+
+    for (const part of run.parts) {
+      this.runInfoByNode.set(part.node, { run, rawStart: rawConcatOffset });
+      const raw = part.node.data ?? '';
+      for (const cp of raw) {
+        if (WHITESPACE_RE.test(cp)) {
+          if (!state.atBoundary && !state.lastWasSpace) {
+            state.collapsedPoints.push(' ');
+            state.runByPoint.push(runIdx);
+            state.rawOffsetByPoint.push(rawConcatOffset);
+            state.lastWasSpace = true;
+            if (!emittedAny) {
+              run.collapsedStart = state.collapsedPoints.length - 1;
+              emittedAny = true;
+            }
+          }
+        } else {
+          if (state.separatorPending) {
+            state.collapsedPoints.push(' ');
+            state.runByPoint.push(-1);
+            state.rawOffsetByPoint.push(-1);
+            state.separatorPending = false;
+          }
+          if (!emittedAny) {
+            run.collapsedStart = state.collapsedPoints.length;
+            emittedAny = true;
+          }
+          state.collapsedPoints.push(cp);
+          state.runByPoint.push(runIdx);
+          state.rawOffsetByPoint.push(rawConcatOffset);
+          state.atBoundary = false;
+          state.lastWasSpace = false;
+        }
+        rawConcatOffset += cp.length;
+      }
+    }
+
+    run.collapsedLength = emittedAny ? state.collapsedPoints.length - run.collapsedStart : 0;
+    runs.push(run);
+  }
+
+  runsOfParent(element: CfiNode): TextRun[] {
+    return this.runsByParent.get(element) ?? [];
+  }
+
+  /** First text run inside the element (any depth), for chapter/element-level hints. */
+  firstRunWithin(element: CfiNode): TextRun | null {
+    if (isTextNode(element)) {
+      return this.runInfoByNode.get(element)?.run ?? null;
+    }
+    for (const child of element.children ?? []) {
+      const found = this.firstRunWithin(child);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  runOfTextNode(node: CfiNode): TextRun | null {
+    return this.runInfoByNode.get(node)?.run ?? null;
+  }
+
+  collapsedForRunOffset(run: TextRun, cpOffset: number): number {
+    return run.collapsedStart + Math.max(0, Math.min(cpOffset, run.collapsedLength));
+  }
+
+  /** Inclusive start point: resolves the collapsed cp index to (raw text node, UTF-16 offset). */
+  startPointFromCollapsed(cpIndex: number): RawPoint | null {
+    let i = Math.max(0, Math.min(cpIndex, this.collapsedCpLength - 1));
+    while (i < this.collapsedCpLength && this.runByPoint[i] < 0) i += 1;
+    if (i >= this.collapsedCpLength) return null;
+    return this.rawPointAt(i);
+  }
+
+  /** Exclusive end point: maps to just after the last collapsed cp of the range. */
+  endPointFromCollapsed(cpIndexExclusive: number): RawPoint | null {
+    let i = Math.min(cpIndexExclusive, this.collapsedCpLength) - 1;
+    while (i >= 0 && this.runByPoint[i] < 0) i -= 1;
+    if (i < 0) return null;
+    const point = this.rawPointAt(i);
+    if (!point) return null;
+    const cpLength = String.fromCodePoint(this.collapsed.codePointAt(this.utf16IndexOfCp(i)) ?? 32).length;
+    return { node: point.node, offset: point.offset + cpLength };
+  }
+
+  private utf16IndexOfCp(cpIndex: number): number {
+    // cpByUtf16 is monotonic; binary search the first utf16 index mapping to cpIndex.
+    let lo = 0;
+    let hi = this.collapsed.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (this.cpByUtf16[mid] < cpIndex) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+
+  private rawPointAt(cpIndex: number): RawPoint | null {
+    const runIdx = this.runByPoint[cpIndex];
+    if (runIdx < 0) return null;
+    const run = this.runs[runIdx];
+    let rawOffset = this.rawOffsetByPoint[cpIndex];
+    for (const part of run.parts) {
+      if (rawOffset <= part.rawLength) {
+        if (rawOffset === part.rawLength && part !== run.parts[run.parts.length - 1]) {
+          rawOffset = 0;
+          continue;
+        }
+        return { node: part.node, offset: rawOffset };
+      }
+      rawOffset -= part.rawLength;
+    }
+    return null;
+  }
+
+  /** Maps a raw (text node, UTF-16 offset) to the collapsed cp index at or after it. */
+  collapsedFromNodePoint(node: CfiNode, utf16Offset: number): number | null {
+    const info = this.runInfoByNode.get(node);
+    if (!info) return null;
+    const { run, rawStart } = info;
+    const target = rawStart + utf16Offset;
+    const startIdx = run.collapsedStart;
+    const endIdx = run.collapsedStart + run.collapsedLength;
+    let lo = startIdx;
+    let hi = endIdx;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (this.rawOffsetByPoint[mid] < target) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+
+  /** Run-relative crengine offset (code points) for a collapsed cp index. */
+  runOffsetOfCollapsed(cpIndex: number, run: TextRun): number {
+    return Math.max(0, Math.min(cpIndex, run.collapsedStart + run.collapsedLength) - run.collapsedStart);
+  }
+
+  runAtCollapsed(cpIndex: number, direction: 'forward' | 'backward' = 'forward'): TextRun | null {
+    let i = Math.max(0, Math.min(cpIndex, this.collapsedCpLength - 1));
+    if (direction === 'forward') {
+      while (i < this.collapsedCpLength && this.runByPoint[i] < 0) i += 1;
+      if (i >= this.collapsedCpLength) return null;
+    } else {
+      while (i >= 0 && this.runByPoint[i] < 0) i -= 1;
+      if (i < 0) return null;
+    }
+    return this.runs[this.runByPoint[i]];
+  }
+
+  extractCollapsed(startCp: number, endCpExclusive: number): string {
+    const startUtf16 = this.utf16IndexOfCp(Math.max(0, startCp));
+    const endUtf16 = this.utf16IndexOfCp(Math.min(endCpExclusive, this.collapsedCpLength));
+    return this.collapsed.slice(startUtf16, endUtf16);
+  }
+
+  /**
+   * Whitespace-tolerant search of the normalized needle in the collapsed text.
+   * Returns the match nearest to the hint (collapsed cp index), if any.
+   */
+  searchNormalized(needle: string, hintCp: number | null): SearchMatch | null {
+    const normalized = normalizeForSearch(needle);
+    if (!normalized) return null;
+    const tokens = normalized.split(' ').map(escapeRegExp);
+    let regex: RegExp;
+    try {
+      regex = new RegExp(tokens.join('\\s+'), 'g');
+    } catch {
+      return null;
+    }
+
+    let best: SearchMatch | null = null;
+    for (const match of this.collapsed.matchAll(regex)) {
+      const startCp = this.cpByUtf16[match.index];
+      const endCp = this.cpByUtf16[match.index + match[0].length - 1] + 1;
+      const distance = hintCp == null ? null : Math.abs(startCp - hintCp);
+      const candidate: SearchMatch = { startCp, endCp, distance };
+      if (!best) {
+        best = candidate;
+        if (hintCp == null) break;
+      } else if (distance != null && best.distance != null && distance < best.distance) {
+        best = candidate;
+      }
+    }
+    return best;
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/server/src/modules/position-converter/epub-dom.service.test.ts b/server/src/modules/position-converter/epub-dom.service.test.ts
new file mode 100644
index 000000000..1e0d23d75
--- /dev/null
+++ b/server/src/modules/position-converter/epub-dom.service.test.ts
@@ -0,0 +1,103 @@
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import * as unzipper from 'unzipper';
+import { ZipArchive } from 'archiver';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { EpubDomService, loadChapterFromZip, readEpubSpine } from './epub-dom.service';
+
+const CONTAINER_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles>
+</container>`;
+
+const CONTENT_OPF = `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Test</dc:title><dc:identifier id="uid">x</dc:identifier></metadata>
+  <manifest>
+    <item id="ch1" href="text/ch1.xhtml" media-type="application/xhtml+xml"/>
+    <item id="ch2" href="text/ch2.xhtml" media-type="application/xhtml+xml"/>
+  </manifest>
+  <spine><itemref idref="ch1"/><itemref idref="ch2"/></spine>
+</package>`;
+
+const CH1 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>1</title></head>
+<body><p>First chapter text.</p></body></html>`;
+
+const CH2 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>2</title></head>
+<body><p>Second chapter text.</p></body></html>`;
+
+async function buildEpub(path: string): Promise<void> {
+  const archive = new ZipArchive({ zlib: { level: 0 } });
+  const chunks: Buffer[] = [];
+  archive.on('data', (chunk: Buffer) => chunks.push(chunk));
+  const done = new Promise<void>((resolve, reject) => {
+    archive.on('end', resolve);
+    archive.on('error', reject);
+  });
+  archive.append('application/epub+zip', { name: 'mimetype', store: true });
+  archive.append(CONTAINER_XML, { name: 'META-INF/container.xml' });
+  archive.append(CONTENT_OPF, { name: 'OEBPS/content.opf' });
+  archive.append(CH1, { name: 'OEBPS/text/ch1.xhtml' });
+  archive.append(CH2, { name: 'OEBPS/text/ch2.xhtml' });
+  await archive.finalize();
+  await done;
+  await writeFile(path, Buffer.concat(chunks));
+}
+
+describe('EpubDomService', () => {
+  let dir: string;
+  let epubPath: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'bookorbit-epub-'));
+    epubPath = join(dir, 'test.epub');
+    await buildEpub(epubPath);
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  function makeDb(absolutePath: string, format = 'epub') {
+    const limit = vi.fn().mockResolvedValue([{ absolutePath, format }]);
+    const where = vi.fn().mockReturnValue({ limit });
+    const from = vi.fn().mockReturnValue({ where });
+    const select = vi.fn().mockReturnValue({ from });
+    return { select };
+  }
+
+  it('reads the spine in order from a real zip', async () => {
+    const zip = await unzipper.Open.file(epubPath);
+    const spine = await readEpubSpine(zip);
+    expect(spine.hrefs).toEqual(['OEBPS/text/ch1.xhtml', 'OEBPS/text/ch2.xhtml']);
+  });
+
+  it('loads chapter documents with a usable text index', async () => {
+    const zip = await unzipper.Open.file(epubPath);
+    const doc = await loadChapterFromZip(zip, 'OEBPS/text/ch2.xhtml');
+    expect(doc).not.toBeNull();
+    expect(doc!.index.collapsed).toBe('Second chapter text.');
+  });
+
+  it('resolves chapters by spine index through the service and caches them', async () => {
+    const db = makeDb(epubPath);
+    const service = new EpubDomService(db as never);
+
+    expect(await service.getChapterCount(1)).toBe(2);
+    const first = await service.getChapter(1, 0);
+    expect(first!.index.collapsed).toBe('First chapter text.');
+    const again = await service.getChapter(1, 0);
+    expect(again).toBe(first);
+    expect(await service.getChapter(1, 9)).toBeNull();
+  });
+
+  it('returns null for non-epub files', async () => {
+    const db = makeDb(epubPath, 'pdf');
+    const service = new EpubDomService(db as never);
+    expect(await service.getChapter(1, 0)).toBeNull();
+  });
+});
diff --git a/server/src/modules/position-converter/epub-dom.service.ts b/server/src/modules/position-converter/epub-dom.service.ts
new file mode 100644
index 000000000..111526b8e
--- /dev/null
+++ b/server/src/modules/position-converter/epub-dom.service.ts
@@ -0,0 +1,206 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { stat } from 'fs/promises';
+import { eq } from 'drizzle-orm';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import * as unzipper from 'unzipper';
+import { XMLParser } from 'fast-xml-parser';
+
+import { DB } from '../../db';
+import * as schema from '../../db/schema';
+import { bookFiles } from '../../db/schema';
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { ChapterDocument, parseChapterDocument } from './position-converter.core';
+
+type Db = NodePgDatabase<typeof schema>;
+
+const EVENT = 'position_converter.epub_dom';
+const CHAPTER_CACHE_MAX = 12;
+const SPINE_CACHE_MAX = 24;
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  textNodeName: '#text',
+});
+
+function toArray<T>(v: T | T[] | undefined | null): T[] {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+function normalizeZipPath(path: string): string {
+  const clean = (path ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = clean.split('/');
+  const resolved: string[] = [];
+  for (const part of parts) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (resolved.length > 0) resolved.pop();
+      continue;
+    }
+    resolved.push(part);
+  }
+  return resolved.join('/');
+}
+
+function resolveHref(href: string, basePath: string): string {
+  if (!href || /^[a-z][a-z\d+.-]*:/i.test(href)) return href;
+  const path = href.split('#')[0].split('?')[0];
+  return path.startsWith('/') ? normalizeZipPath(path) : normalizeZipPath(basePath + path);
+}
+
+function findInZip(files: unzipper.File[], path: string): unzipper.File | undefined {
+  const clean = normalizeZipPath(path);
+  const cleanLower = clean.toLowerCase();
+  let ciMatch: unzipper.File | undefined;
+  for (const file of files) {
+    const fp = normalizeZipPath(file.path);
+    if (fp === clean) return file;
+    if (!ciMatch && fp.toLowerCase() === cleanLower) ciMatch = file;
+  }
+  return ciMatch;
+}
+
+export interface EpubSpine {
+  hrefs: string[];
+}
+
+/** Parses container.xml + OPF from an opened zip and returns spine hrefs in order. */
+export async function readEpubSpine(zip: unzipper.CentralDirectory): Promise<EpubSpine> {
+  const containerEntry = findInZip(zip.files, 'META-INF/container.xml');
+  if (!containerEntry) throw new Error('Missing META-INF/container.xml');
+  const containerDoc = xmlParser.parse(await containerEntry.buffer()) as Record<string, unknown>;
+  const container = containerDoc['container'] as Record<string, unknown>;
+  const rootfiles = (container?.rootfiles as Record<string, unknown>)?.rootfile;
+  const rootfile: unknown = Array.isArray(rootfiles) ? rootfiles[0] : rootfiles;
+  const opfPath = (rootfile as Record<string, string>)?.['@_full-path'];
+  if (!opfPath) throw new Error('Cannot find OPF path');
+
+  const rootPath = opfPath.includes('/') ? opfPath.slice(0, opfPath.lastIndexOf('/') + 1) : '';
+  const opfEntry = findInZip(zip.files, opfPath);
+  if (!opfEntry) throw new Error(`OPF not found: ${opfPath}`);
+  const opfDoc = xmlParser.parse(await opfEntry.buffer()) as Record<string, unknown>;
+  const pkg = (opfDoc['package'] ?? opfDoc) as Record<string, unknown>;
+  const manifestEl = pkg['manifest'] as Record<string, unknown> | undefined;
+  const spineEl = pkg['spine'] as Record<string, unknown> | undefined;
+
+  const manifestById = new Map<string, string>();
+  for (const item of toArray(manifestEl?.item as Record<string, string>[])) {
+    const id = item['@_id'];
+    const relHref = item['@_href'];
+    if (id && relHref) manifestById.set(id, normalizeZipPath(resolveHref(relHref, rootPath)));
+  }
+
+  const hrefs: string[] = [];
+  for (const itemref of toArray(spineEl?.itemref as Record<string, string>[])) {
+    const href = manifestById.get(itemref['@_idref']);
+    if (href != null) hrefs.push(href);
+  }
+  return { hrefs };
+}
+
+export async function loadChapterFromZip(zip: unzipper.CentralDirectory, href: string): Promise<ChapterDocument | null> {
+  const entry = findInZip(zip.files, href);
+  if (!entry) return null;
+  const xhtml = (await entry.buffer()).toString('utf-8');
+  return parseChapterDocument(xhtml);
+}
+
+interface SpineCacheEntry {
+  absolutePath: string;
+  mtimeMs: number;
+  spine: EpubSpine;
+}
+
+@Injectable()
+export class EpubDomService {
+  private readonly logger = new Logger(EpubDomService.name);
+  private readonly spineCache = new Map<number, SpineCacheEntry>();
+  private readonly chapterCache = new Map<string, ChapterDocument>();
+
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async getChapterCount(bookFileId: number): Promise<number | null> {
+    const entry = await this.getSpineEntry(bookFileId);
+    return entry ? entry.spine.hrefs.length : null;
+  }
+
+  async getSpineHrefs(bookFileId: number): Promise<string[] | null> {
+    const entry = await this.getSpineEntry(bookFileId);
+    return entry ? entry.spine.hrefs : null;
+  }
+
+  async getChapter(bookFileId: number, chapterIndex: number): Promise<ChapterDocument | null> {
+    const entry = await this.getSpineEntry(bookFileId);
+    if (!entry) return null;
+    const href = entry.spine.hrefs[chapterIndex];
+    if (href == null) return null;
+
+    const cacheKey = `${bookFileId}:${entry.mtimeMs}:${chapterIndex}`;
+    const cached = this.chapterCache.get(cacheKey);
+    if (cached) {
+      this.chapterCache.delete(cacheKey);
+      this.chapterCache.set(cacheKey, cached);
+      return cached;
+    }
+
+    try {
+      const zip = await unzipper.Open.file(entry.absolutePath);
+      const doc = await loadChapterFromZip(zip, href);
+      if (!doc) return null;
+      this.chapterCache.set(cacheKey, doc);
+      while (this.chapterCache.size > CHAPTER_CACHE_MAX) {
+        const oldest = this.chapterCache.keys().next().value as string;
+        this.chapterCache.delete(oldest);
+      }
+      return doc;
+    } catch (error) {
+      this.logFail(bookFileId, error);
+      return null;
+    }
+  }
+
+  private async getSpineEntry(bookFileId: number): Promise<SpineCacheEntry | null> {
+    const [file] = await this.db
+      .select({ absolutePath: bookFiles.absolutePath, format: bookFiles.format })
+      .from(bookFiles)
+      .where(eq(bookFiles.id, bookFileId))
+      .limit(1);
+    if (!file || file.format !== 'epub') return null;
+
+    let mtimeMs: number;
+    try {
+      mtimeMs = (await stat(file.absolutePath)).mtimeMs;
+    } catch (error) {
+      this.logFail(bookFileId, error);
+      return null;
+    }
+
+    const cached = this.spineCache.get(bookFileId);
+    if (cached && cached.absolutePath === file.absolutePath && cached.mtimeMs === mtimeMs) return cached;
+
+    try {
+      const zip = await unzipper.Open.file(file.absolutePath);
+      const spine = await readEpubSpine(zip);
+      const entry: SpineCacheEntry = { absolutePath: file.absolutePath, mtimeMs, spine };
+      this.spineCache.set(bookFileId, entry);
+      while (this.spineCache.size > SPINE_CACHE_MAX) {
+        const oldest = this.spineCache.keys().next().value as number;
+        this.spineCache.delete(oldest);
+      }
+      return entry;
+    } catch (error) {
+      this.logFail(bookFileId, error);
+      return null;
+    }
+  }
+
+  private logFail(bookFileId: number, error: unknown): void {
+    const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+    this.logger.warn(
+      `[${EVENT}] [fail] bookFileId=${bookFileId} errorClass=${errorClass} error="${sanitizeLogValue(
+        error instanceof Error ? error.message : 'unknown error',
+      )}" - epub chapter load failed`,
+    );
+  }
+}
diff --git a/server/src/modules/position-converter/kepub-dom.service.test.ts b/server/src/modules/position-converter/kepub-dom.service.test.ts
new file mode 100644
index 000000000..e74f0e917
--- /dev/null
+++ b/server/src/modules/position-converter/kepub-dom.service.test.ts
@@ -0,0 +1,91 @@
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { ZipArchive } from 'archiver';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { KepubDomService } from './kepub-dom.service';
+
+const CONTAINER_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles>
+</container>`;
+
+const CONTENT_OPF = `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Test</dc:title><dc:identifier id="uid">x</dc:identifier></metadata>
+  <manifest>
+    <item id="ch1" href="text/ch1.xhtml" media-type="application/xhtml+xml"/>
+    <item id="ch2" href="text/ch2.xhtml" media-type="application/xhtml+xml"/>
+  </manifest>
+  <spine><itemref idref="ch1"/><itemref idref="ch2"/></spine>
+</package>`;
+
+const CH1 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>1</title></head>
+<body><div id="book-columns"><div id="book-inner"><p><span class="koboSpan" id="kobo.1.1">First chapter text.</span></p></div></div></body></html>`;
+
+const CH2 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>2</title></head>
+<body><div id="book-columns"><div id="book-inner"><p><span class="koboSpan" id="kobo.1.1">Second chapter text.</span></p></div></div></body></html>`;
+
+async function buildKepub(path: string): Promise<void> {
+  const archive = new ZipArchive({ zlib: { level: 0 } });
+  const chunks: Buffer[] = [];
+  archive.on('data', (chunk: Buffer) => chunks.push(chunk));
+  const done = new Promise<void>((resolve, reject) => {
+    archive.on('end', resolve);
+    archive.on('error', reject);
+  });
+  archive.append('application/epub+zip', { name: 'mimetype', store: true });
+  archive.append(CONTAINER_XML, { name: 'META-INF/container.xml' });
+  archive.append(CONTENT_OPF, { name: 'OEBPS/content.opf' });
+  archive.append(CH1, { name: 'OEBPS/text/ch1.xhtml' });
+  archive.append(CH2, { name: 'OEBPS/text/ch2.xhtml' });
+  await archive.finalize();
+  await done;
+  await writeFile(path, Buffer.concat(chunks));
+}
+
+describe('KepubDomService', () => {
+  let dir: string;
+  let kepubPath: string;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'bookorbit-kepub-'));
+    kepubPath = join(dir, 'test.kepub.epub');
+    await buildKepub(kepubPath);
+  });
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('reads the kepub spine by path', async () => {
+    const service = new KepubDomService();
+    const spine = await service.getSpine(kepubPath);
+    expect(spine?.hrefs).toEqual(['OEBPS/text/ch1.xhtml', 'OEBPS/text/ch2.xhtml']);
+  });
+
+  it('loads chapters by index and caches the parsed document', async () => {
+    const service = new KepubDomService();
+    const doc = await service.getChapterByIndex(kepubPath, 1);
+    expect(doc?.index.collapsed).toBe('Second chapter text.');
+    expect(await service.getChapterByIndex(kepubPath, 1)).toBe(doc);
+    expect(await service.getChapterByIndex(kepubPath, 5)).toBeNull();
+  });
+
+  it('resolves chapter filenames through the matching ladder', async () => {
+    const service = new KepubDomService();
+    expect(await service.findChapterIndexByFilename(kepubPath, 'OEBPS/text/ch2.xhtml')).toBe(1);
+    expect(await service.findChapterIndexByFilename(kepubPath, 'oebps/TEXT/CH2.xhtml')).toBe(1);
+    expect(await service.findChapterIndexByFilename(kepubPath, 'ch2.xhtml')).toBe(1);
+    expect(await service.findChapterIndexByFilename(kepubPath, 'text/ch1.xhtml#fragment')).toBe(0);
+    expect(await service.findChapterIndexByFilename(kepubPath, 'missing.xhtml')).toBeNull();
+  });
+
+  it('returns null for missing files', async () => {
+    const service = new KepubDomService();
+    expect(await service.getSpine(join(dir, 'nope.kepub.epub'))).toBeNull();
+  });
+});
diff --git a/server/src/modules/position-converter/kepub-dom.service.ts b/server/src/modules/position-converter/kepub-dom.service.ts
new file mode 100644
index 000000000..7097b8f64
--- /dev/null
+++ b/server/src/modules/position-converter/kepub-dom.service.ts
@@ -0,0 +1,131 @@
+import { stat } from 'fs/promises';
+
+import { Injectable, Logger } from '@nestjs/common';
+import * as unzipper from 'unzipper';
+
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { EpubSpine, loadChapterFromZip, readEpubSpine } from './epub-dom.service';
+import { ChapterDocument } from './position-converter.core';
+
+const EVENT = 'position_converter.kepub_dom';
+const CHAPTER_CACHE_MAX = 12;
+const SPINE_CACHE_MAX = 24;
+
+interface SpineCacheEntry {
+  mtimeMs: number;
+  spine: EpubSpine;
+}
+
+function normalizeChapterPath(path: string): string {
+  let clean = (path ?? '').replace(/\\/g, '/');
+  try {
+    clean = decodeURI(clean);
+  } catch {
+    // Keep the raw path when it is not valid URI-encoded.
+  }
+  return clean.split('#')[0].split('?')[0].replace(/^\/+/, '');
+}
+
+/**
+ * Path-keyed twin of EpubDomService for kepub artifacts produced by the kepub
+ * conversion cache. Callers resolve the kepub path themselves, so this service
+ * stays free of DB and Kobo dependencies.
+ */
+@Injectable()
+export class KepubDomService {
+  private readonly logger = new Logger(KepubDomService.name);
+  private readonly spineCache = new Map<string, SpineCacheEntry>();
+  private readonly chapterCache = new Map<string, ChapterDocument>();
+
+  async getSpine(kepubPath: string): Promise<EpubSpine | null> {
+    return (await this.getSpineEntry(kepubPath))?.spine ?? null;
+  }
+
+  async getChapterByIndex(kepubPath: string, chapterIndex: number): Promise<ChapterDocument | null> {
+    const entry = await this.getSpineEntry(kepubPath);
+    if (!entry) return null;
+    const href = entry.spine.hrefs[chapterIndex];
+    if (href == null) return null;
+    return this.loadChapter(kepubPath, entry, chapterIndex, href);
+  }
+
+  /**
+   * Resolves a Kobo chapter filename against the kepub spine: exact normalized
+   * match, then case-insensitive, then path-suffix match.
+   */
+  async findChapterIndexByFilename(kepubPath: string, chapterFilename: string): Promise<number | null> {
+    const entry = await this.getSpineEntry(kepubPath);
+    if (!entry) return null;
+    const normalized = normalizeChapterPath(chapterFilename);
+    if (!normalized) return null;
+    const lower = normalized.toLowerCase();
+    const hrefs = entry.spine.hrefs;
+
+    let index = hrefs.findIndex((href) => href === normalized);
+    if (index < 0) index = hrefs.findIndex((href) => href.toLowerCase() === lower);
+    if (index < 0) index = hrefs.findIndex((href) => href.toLowerCase().endsWith(`/${lower}`));
+    return index >= 0 ? index : null;
+  }
+
+  private async loadChapter(kepubPath: string, entry: SpineCacheEntry, chapterIndex: number, href: string): Promise<ChapterDocument | null> {
+    const cacheKey = `${kepubPath}:${entry.mtimeMs}:${chapterIndex}`;
+    const cached = this.chapterCache.get(cacheKey);
+    if (cached) {
+      this.chapterCache.delete(cacheKey);
+      this.chapterCache.set(cacheKey, cached);
+      return cached;
+    }
+
+    try {
+      const zip = await unzipper.Open.file(kepubPath);
+      const doc = await loadChapterFromZip(zip, href);
+      if (!doc) return null;
+      this.chapterCache.set(cacheKey, doc);
+      while (this.chapterCache.size > CHAPTER_CACHE_MAX) {
+        const oldest = this.chapterCache.keys().next().value as string;
+        this.chapterCache.delete(oldest);
+      }
+      return doc;
+    } catch (error) {
+      this.logFail(kepubPath, error);
+      return null;
+    }
+  }
+
+  private async getSpineEntry(kepubPath: string): Promise<SpineCacheEntry | null> {
+    let mtimeMs: number;
+    try {
+      mtimeMs = (await stat(kepubPath)).mtimeMs;
+    } catch (error) {
+      this.logFail(kepubPath, error);
+      return null;
+    }
+
+    const cached = this.spineCache.get(kepubPath);
+    if (cached && cached.mtimeMs === mtimeMs) return cached;
+
+    try {
+      const zip = await unzipper.Open.file(kepubPath);
+      const spine = await readEpubSpine(zip);
+      const entry: SpineCacheEntry = { mtimeMs, spine };
+      this.spineCache.set(kepubPath, entry);
+      while (this.spineCache.size > SPINE_CACHE_MAX) {
+        const oldest = this.spineCache.keys().next().value as string;
+        this.spineCache.delete(oldest);
+      }
+      return entry;
+    } catch (error) {
+      this.logFail(kepubPath, error);
+      return null;
+    }
+  }
+
+  private logFail(kepubPath: string, error: unknown): void {
+    const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+    this.logger.warn(
+      `[${EVENT}] [fail] path="${sanitizeLogValue(kepubPath)}" errorClass=${errorClass} error="${sanitizeLogValue(
+        error instanceof Error ? error.message : 'unknown error',
+      )}" - kepub chapter load failed`,
+    );
+  }
+}
diff --git a/server/src/modules/position-converter/kobo-span-converter.service.test.ts b/server/src/modules/position-converter/kobo-span-converter.service.test.ts
new file mode 100644
index 000000000..622a38379
--- /dev/null
+++ b/server/src/modules/position-converter/kobo-span-converter.service.test.ts
@@ -0,0 +1,267 @@
+import { execFile } from 'child_process';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { promisify } from 'util';
+import { ZipArchive } from 'archiver';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { KepubifyBinaryService } from '../kobo/services/kepubify-binary.service';
+import { EpubDomService } from './epub-dom.service';
+import { KepubDomService } from './kepub-dom.service';
+import { KepubContext, KoboSpanConverterService, parseKoboSpanPos, serializeKoboSpanPos } from './kobo-span-converter.service';
+import { buildKoboSpanIndex, spanSelectorFromId } from './kobo-span.core';
+
+const execFileAsync = promisify(execFile);
+
+const CONTAINER_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles>
+</container>`;
+
+const CONTENT_OPF = `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>Spans</dc:title><dc:identifier id="uid">spike</dc:identifier><dc:language>en</dc:language></metadata>
+  <manifest>
+    <item id="ch1" href="text/ch1.xhtml" media-type="application/xhtml+xml"/>
+    <item id="ch2" href="text/ch2.xhtml" media-type="application/xhtml+xml"/>
+    <item id="pic" href="img/pic.png" media-type="image/png"/>
+  </manifest>
+  <spine><itemref idref="ch1"/><itemref idref="ch2"/></spine>
+</package>`;
+
+// Exercises the structures kepubify treats specially: nested inline formatting that
+// crosses sentence boundaries, lists, blockquotes, images, entities, curly quotes,
+// non-breaking spaces and astral characters.
+const CH1 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>One</title></head>
+<body>
+  <h1>The First Chapter</h1>
+  <p>It was a bright cold day in April. The clocks were striking thirteen!</p>
+  <p>Winston Smith, his chin nuzzled into his breast, slipped <em>quickly through. The glass</em> doors of Victory Mansions.</p>
+  <p>He said “stay awhile” and then left&#160;again. Asked: why?</p>
+  <blockquote><p>Quoted wisdom lives here. It spans two sentences.</p></blockquote>
+  <ul><li>First item sentence.</li><li>Second item with <strong>bold capture</strong> inside.</li></ul>
+</body>
+</html>`;
+
+const CH2 = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>Two</title></head>
+<body>
+  <p>Emoji ahead \u{1F600} and after. Trailing sentence to anchor!</p>
+  <img src="../img/pic.png" alt="pic"/>
+  <p>Past the image now. Another line of text follows here.</p>
+</body>
+</html>`;
+
+const PNG_1X1 = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==', 'base64');
+
+async function buildEpub(path: string): Promise<void> {
+  const archive = new ZipArchive({ zlib: { level: 0 } });
+  const chunks: Buffer[] = [];
+  archive.on('data', (chunk: Buffer) => chunks.push(chunk));
+  const done = new Promise<void>((resolve, reject) => {
+    archive.on('end', resolve);
+    archive.on('error', reject);
+  });
+  archive.append('application/epub+zip', { name: 'mimetype', store: true });
+  archive.append(CONTAINER_XML, { name: 'META-INF/container.xml' });
+  archive.append(CONTENT_OPF, { name: 'OEBPS/content.opf' });
+  archive.append(CH1, { name: 'OEBPS/text/ch1.xhtml' });
+  archive.append(CH2, { name: 'OEBPS/text/ch2.xhtml' });
+  archive.append(PNG_1X1, { name: 'OEBPS/img/pic.png' });
+  await archive.finalize();
+  await done;
+  await writeFile(path, Buffer.concat(chunks));
+}
+
+function makeDb(absolutePath: string) {
+  const limit = vi.fn().mockResolvedValue([{ absolutePath, format: 'epub' }]);
+  const where = vi.fn().mockReturnValue({ limit });
+  const from = vi.fn().mockReturnValue({ where });
+  const select = vi.fn().mockReturnValue({ from });
+  return { select };
+}
+
+// Runs the actual bundled kepubify binary: this is the gate for the codec's core
+// assumption that kepub chapter text is collapse-identical to the epub chapter's.
+describe('KoboSpanConverterService (real kepubify output)', () => {
+  let dir: string;
+  let epubPath: string;
+  let kepubPath: string;
+  let epubDom: EpubDomService;
+  let kepubDom: KepubDomService;
+  let service: KoboSpanConverterService;
+  let ctx: KepubContext;
+
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'bookorbit-kobo-span-'));
+    epubPath = join(dir, 'fixture.epub');
+    kepubPath = join(dir, 'fixture.kepub.epub');
+    await buildEpub(epubPath);
+
+    const binary = new KepubifyBinaryService();
+    await execFileAsync(await binary.getBinaryPath(), ['--output', kepubPath, epubPath], { timeout: 60_000 });
+
+    epubDom = new EpubDomService(makeDb(epubPath) as never);
+    kepubDom = new KepubDomService();
+    service = new KoboSpanConverterService(epubDom, kepubDom);
+    ctx = { kepubPath, fileHash: 'testhash', hyphenate: false, kepubifyVersion: await binary.getVersion() };
+  }, 60_000);
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('produces collapse-identical chapter text for every chapter (R1 gate)', async () => {
+    for (let chapterIndex = 0; chapterIndex < 2; chapterIndex += 1) {
+      const epubDoc = await epubDom.getChapter(1, chapterIndex);
+      const kepubDoc = await kepubDom.getChapterByIndex(kepubPath, chapterIndex);
+      expect(epubDoc).not.toBeNull();
+      expect(kepubDoc).not.toBeNull();
+      expect(kepubDoc!.index.collapsed).toBe(epubDoc!.index.collapsed);
+    }
+  });
+
+  it('keeps spine hrefs unchanged', async () => {
+    const spine = await kepubDom.getSpine(kepubPath);
+    expect(spine?.hrefs).toEqual(['OEBPS/text/ch1.xhtml', 'OEBPS/text/ch2.xhtml']);
+  });
+
+  it('converts a device-style span location to exact canonical positions', async () => {
+    const kepubDoc = (await kepubDom.getChapterByIndex(kepubPath, 0))!;
+    const spanIndex = buildKoboSpanIndex(kepubDoc);
+    expect(spanIndex.ordered.length).toBeGreaterThan(5);
+
+    // Pick the real span holding the second sentence of paragraph one.
+    const target = spanIndex.ordered.find((span) => kepubDoc.index.extractCollapsed(span.collapsedStart, span.collapsedEnd).includes('clocks'));
+    expect(target).toBeDefined();
+    const text = 'The clocks were striking thirteen!';
+    const spanText = kepubDoc.index.extractCollapsed(target!.collapsedStart, target!.collapsedEnd);
+    const startChar = spanText.indexOf('The clocks');
+
+    const result = await service.koboSpanToCanonical({
+      bookFileId: 1,
+      ctx,
+      location: {
+        span: {
+          startPath: spanSelectorFromId(target!.id),
+          startChar,
+          endPath: spanSelectorFromId(target!.id),
+          endChar: startChar + text.length,
+          chapterFilename: 'OEBPS/text/ch1.xhtml',
+          chapterProgress: 0,
+        },
+      },
+      text,
+    });
+
+    expect(result.status).toBe('exact');
+    expect(result.chapterIndex).toBe(0);
+    expect(result.cfi).toContain('epubcfi(/6/2!');
+    expect(result.xpointerPos0).toContain('/body/DocFragment[1]/');
+    expect(result.renditionHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('round-trips a canonical cfi to a device location and back', async () => {
+    const text = 'quickly through. The glass';
+    const kepubDoc = (await kepubDom.getChapterByIndex(kepubPath, 0))!;
+    const spanIndex = buildKoboSpanIndex(kepubDoc);
+    const emTarget = spanIndex.ordered.find((span) => kepubDoc.index.extractCollapsed(span.collapsedStart, span.collapsedEnd).includes('quickly'));
+    expect(emTarget).toBeDefined();
+
+    const forward = await service.koboSpanToCanonical({
+      bookFileId: 1,
+      ctx,
+      location: {
+        span: {
+          startPath: spanSelectorFromId(emTarget!.id),
+          startChar: 0,
+          endPath: spanSelectorFromId(spanIndex.ordered[spanIndex.ordered.indexOf(emTarget!) + 1].id),
+          endChar: spanIndex.ordered[spanIndex.ordered.indexOf(emTarget!) + 1].utf16Length,
+          chapterFilename: 'text/ch1.xhtml',
+          chapterProgress: 0,
+        },
+      },
+      text: null,
+    });
+    expect(forward.status).not.toBe('failed');
+
+    const back = await service.canonicalToKoboSpan({ bookFileId: 1, ctx, cfi: forward.cfi!, text, chapterTitle: 'One' });
+    expect(back.status).not.toBe('failed');
+    expect(back.location?.span.chapterFilename).toBe('OEBPS/text/ch1.xhtml');
+    expect(back.location?.span.startPath).toBe(spanSelectorFromId(emTarget!.id));
+    expect(back.pos0).toBe(serializeKoboSpanPos(emTarget!.id, 0));
+
+    const again = await service.koboSpanToCanonical({ bookFileId: 1, ctx, location: back.location, text });
+    expect(again.status).toBe('exact');
+    expect(again.cfi).toBe(forward.cfi);
+  });
+
+  it('handles astral characters in device offsets (UTF-16 units)', async () => {
+    const kepubDoc = (await kepubDom.getChapterByIndex(kepubPath, 1))!;
+    const spanIndex = buildKoboSpanIndex(kepubDoc);
+    const emojiSpan = spanIndex.ordered.find((span) => kepubDoc.index.extractCollapsed(span.collapsedStart, span.collapsedEnd).includes('\u{1F600}'));
+    expect(emojiSpan).toBeDefined();
+
+    const raw = emojiSpan!.textNodes.map((n) => n.data ?? '').join('');
+    const needle = 'and after.';
+    const startCharUtf16 = raw.indexOf(needle);
+    expect(startCharUtf16).toBeGreaterThan(0);
+
+    const result = await service.koboSpanToCanonical({
+      bookFileId: 1,
+      ctx,
+      location: {
+        span: {
+          startPath: spanSelectorFromId(emojiSpan!.id),
+          startChar: startCharUtf16,
+          endPath: spanSelectorFromId(emojiSpan!.id),
+          endChar: startCharUtf16 + needle.length,
+          chapterFilename: 'OEBPS/text/ch2.xhtml',
+          chapterProgress: 0.5,
+        },
+      },
+      text: needle,
+    });
+    expect(result.status).toBe('exact');
+    expect(result.chapterIndex).toBe(1);
+  });
+
+  it('round-trips reading-position bookmarks through span ids', async () => {
+    const kepubDoc = (await kepubDom.getChapterByIndex(kepubPath, 1))!;
+    const spanIndex = buildKoboSpanIndex(kepubDoc);
+    const target = spanIndex.ordered.find((span) =>
+      kepubDoc.index.extractCollapsed(span.collapsedStart, span.collapsedEnd).includes('Past the image'),
+    );
+    expect(target).toBeDefined();
+
+    const positions = await service.koboBookmarkToPositions({ bookFileId: 1, ctx, chapterFilename: 'text/ch2.xhtml', spanId: target!.id });
+    expect(positions.status).toBe('exact');
+    expect(positions.cfi).toContain('epubcfi(/6/4!');
+    expect(positions.xpointer).toContain('/body/DocFragment[2]/');
+
+    const bookmark = await service.cfiPointToKoboBookmark({ bookFileId: 1, ctx, cfi: positions.cfi! });
+    expect(bookmark.status).toBe('exact');
+    expect(bookmark.spanId).toBe(target!.id);
+    expect(bookmark.chapterFilename).toBe('OEBPS/text/ch2.xhtml');
+    expect(bookmark.contentSourceProgressPercent).toBeGreaterThan(0);
+  });
+
+  it('computes a stable rendition hash and reacts to version changes', async () => {
+    const first = await service.computeRenditionHash(ctx);
+    const second = await service.computeRenditionHash(ctx);
+    expect(first).toBe(second);
+    const bumped = await service.computeRenditionHash({ ...ctx, kepubifyVersion: 'other' });
+    expect(bumped).not.toBe(first);
+    expect(await service.computeRenditionHash({ ...ctx, kepubPath: join(dir, 'missing.kepub.epub') })).toBeNull();
+  });
+
+  it('parses serialized kobo_span pos values', () => {
+    expect(parseKoboSpanPos('kobo.3.2:15')).toEqual({ spanId: 'kobo.3.2', char: 15 });
+    expect(parseKoboSpanPos('kobo.3.2')).toBeNull();
+    expect(parseKoboSpanPos('weird:5')).toBeNull();
+  });
+});
diff --git a/server/src/modules/position-converter/kobo-span-converter.service.ts b/server/src/modules/position-converter/kobo-span-converter.service.ts
new file mode 100644
index 000000000..a18fbabda
--- /dev/null
+++ b/server/src/modules/position-converter/kobo-span-converter.service.ts
@@ -0,0 +1,347 @@
+import { createHash } from 'crypto';
+import { stat } from 'fs/promises';
+
+import { Injectable, Logger } from '@nestjs/common';
+
+import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { chapterIndexFromSpineStep, parseCfi } from './cfi.utils';
+import { EpubDomService } from './epub-dom.service';
+import { KepubDomService } from './kepub-dom.service';
+import {
+  KOBO_SPAN_RESOLVER_VERSION,
+  KoboSpanIndex,
+  KoboSpanRange,
+  buildKoboSpanIndex,
+  canonicalCfiToKoboSpan,
+  cfiPointToKoboSpanPoint,
+  koboSpanPointToCanonical,
+  koboSpanRangeToCanonical,
+  parseSpanSelector,
+  spanSelectorFromId,
+} from './kobo-span.core';
+import { ChapterDocument } from './position-converter.core';
+
+const EVENT = 'position_converter.kobo_span';
+
+export interface KepubContext {
+  kepubPath: string;
+  fileHash: string | null;
+  hyphenate: boolean;
+  kepubifyVersion: string;
+}
+
+export interface KoboSpanLocation {
+  startPath: string;
+  startChar: number;
+  endPath: string;
+  endChar: number;
+  chapterFilename: string;
+  chapterProgress?: number;
+  chapterTitle?: string | null;
+}
+
+export interface KoboSpanToCanonicalOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  reason?: string;
+  chapterIndex?: number;
+  cfi?: string;
+  xpointerPos0?: string;
+  xpointerPos1?: string;
+  renditionHash: string | null;
+}
+
+export interface CanonicalToKoboSpanOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  reason?: string;
+  chapterIndex?: number;
+  pos0?: string;
+  pos1?: string;
+  location?: {
+    span: Required<Pick<KoboSpanLocation, 'startPath' | 'startChar' | 'endPath' | 'endChar' | 'chapterFilename' | 'chapterProgress'>> & {
+      chapterTitle: string | null;
+    };
+  };
+  renditionHash: string | null;
+}
+
+export interface KoboBookmarkToPositionsOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  reason?: string;
+  chapterIndex?: number;
+  cfi?: string;
+  xpointer?: string;
+  chapterFraction?: number;
+}
+
+export interface CfiPointToKoboBookmarkOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  reason?: string;
+  chapterIndex?: number;
+  spanId?: string;
+  chapterFilename?: string;
+  contentSourceProgressPercent?: number;
+}
+
+/** Parses an annotation_positions kobo_span pos value ("kobo.N.M:char"). */
+export function parseKoboSpanPos(pos: string): { spanId: string; char: number } | null {
+  const splitAt = pos.lastIndexOf(':');
+  if (splitAt <= 0) return null;
+  const spanId = pos.slice(0, splitAt);
+  const char = Number(pos.slice(splitAt + 1));
+  if (!/^kobo\.\d+\.\d+$/.test(spanId) || !Number.isInteger(char) || char < 0) return null;
+  return { spanId, char };
+}
+
+export function serializeKoboSpanPos(spanId: string, char: number): string {
+  return `${spanId}:${char}`;
+}
+
+@Injectable()
+export class KoboSpanConverterService {
+  readonly version = KOBO_SPAN_RESOLVER_VERSION;
+
+  private readonly logger = new Logger(KoboSpanConverterService.name);
+  private readonly spanIndexCache = new WeakMap<ChapterDocument, KoboSpanIndex>();
+  private renditionHashCache: { key: string; hash: string } | null = null;
+
+  constructor(
+    private readonly epubDom: EpubDomService,
+    private readonly kepubDom: KepubDomService,
+  ) {}
+
+  async koboSpanToCanonical(params: {
+    bookFileId: number;
+    ctx: KepubContext;
+    location: unknown;
+    text: string | null;
+  }): Promise<KoboSpanToCanonicalOutcome> {
+    const renditionHash = await this.computeRenditionHash(params.ctx);
+    const location = this.parseLocation(params.location);
+    if (!location) return { status: 'failed', reason: 'invalid_location', renditionHash };
+
+    const startId = parseSpanSelector(location.startPath);
+    const endId = parseSpanSelector(location.endPath);
+    if (!startId || !endId) return { status: 'failed', reason: 'invalid_span_path', renditionHash };
+
+    const docs = await this.loadChapterPairByFilename(params.bookFileId, params.ctx, location.chapterFilename);
+    if ('reason' in docs) return { status: 'failed', reason: docs.reason, renditionHash };
+
+    const range: KoboSpanRange = { startId, startChar: location.startChar, endId, endChar: location.endChar };
+    const result = koboSpanRangeToCanonical(docs.epubDoc, docs.kepubDoc, this.getSpanIndex(docs.kepubDoc), docs.epubChapterIndex, range, params.text);
+    if (result.status === 'failed') {
+      this.logFail('kobo_to_canonical', params.bookFileId, result.reason);
+      return { status: 'failed', reason: result.reason, chapterIndex: docs.epubChapterIndex, renditionHash };
+    }
+    return {
+      status: result.status,
+      chapterIndex: docs.epubChapterIndex,
+      cfi: result.cfi,
+      xpointerPos0: result.xpointerPos0,
+      xpointerPos1: result.xpointerPos1,
+      renditionHash,
+    };
+  }
+
+  async canonicalToKoboSpan(params: {
+    bookFileId: number;
+    ctx: KepubContext;
+    cfi: string;
+    text: string | null;
+    chapterTitle?: string | null;
+  }): Promise<CanonicalToKoboSpanOutcome> {
+    const renditionHash = await this.computeRenditionHash(params.ctx);
+    const chapterIndex = chapterIndexFromSpineStep(parseCfi(params.cfi)?.spineStep ?? null);
+    if (chapterIndex == null) return { status: 'failed', reason: 'missing_spine_step', renditionHash };
+
+    const docs = await this.loadChapterPairByIndex(params.bookFileId, params.ctx, chapterIndex);
+    if ('reason' in docs) return { status: 'failed', reason: docs.reason, chapterIndex, renditionHash };
+
+    const result = canonicalCfiToKoboSpan(docs.epubDoc, docs.kepubDoc, this.getSpanIndex(docs.kepubDoc), params.cfi, params.text);
+    if (result.status === 'failed') {
+      this.logFail('canonical_to_kobo', params.bookFileId, result.reason);
+      return { status: 'failed', reason: result.reason, chapterIndex, renditionHash };
+    }
+
+    const chapterProgress = docs.kepubSpineLength > 0 ? docs.kepubChapterIndex / docs.kepubSpineLength : 0;
+    return {
+      status: result.status,
+      chapterIndex,
+      pos0: serializeKoboSpanPos(result.startId, result.startChar),
+      pos1: serializeKoboSpanPos(result.endId, result.endChar),
+      location: {
+        span: {
+          startPath: spanSelectorFromId(result.startId),
+          startChar: result.startChar,
+          endPath: spanSelectorFromId(result.endId),
+          endChar: result.endChar,
+          chapterFilename: docs.kepubHref,
+          chapterProgress,
+          chapterTitle: params.chapterTitle ?? null,
+        },
+      },
+      renditionHash,
+    };
+  }
+
+  async koboBookmarkToPositions(params: {
+    bookFileId: number;
+    ctx: KepubContext;
+    chapterFilename: string;
+    spanId: string;
+  }): Promise<KoboBookmarkToPositionsOutcome> {
+    const docs = await this.loadChapterPairByFilename(params.bookFileId, params.ctx, params.chapterFilename);
+    if ('reason' in docs) return { status: 'failed', reason: docs.reason };
+
+    const result = koboSpanPointToCanonical(docs.epubDoc, docs.kepubDoc, this.getSpanIndex(docs.kepubDoc), docs.epubChapterIndex, params.spanId);
+    if (result.status === 'failed') {
+      this.logFail('bookmark_to_canonical', params.bookFileId, result.reason);
+      return { status: 'failed', reason: result.reason, chapterIndex: docs.epubChapterIndex };
+    }
+    return {
+      status: result.status,
+      chapterIndex: docs.epubChapterIndex,
+      cfi: result.cfi,
+      xpointer: result.xpointer,
+      chapterFraction: result.chapterFraction,
+    };
+  }
+
+  async cfiPointToKoboBookmark(params: { bookFileId: number; ctx: KepubContext; cfi: string }): Promise<CfiPointToKoboBookmarkOutcome> {
+    const chapterIndex = chapterIndexFromSpineStep(parseCfi(params.cfi)?.spineStep ?? null);
+    if (chapterIndex == null) return { status: 'failed', reason: 'missing_spine_step' };
+
+    const docs = await this.loadChapterPairByIndex(params.bookFileId, params.ctx, chapterIndex);
+    if ('reason' in docs) return { status: 'failed', reason: docs.reason, chapterIndex };
+
+    const result = cfiPointToKoboSpanPoint(docs.epubDoc, docs.kepubDoc, this.getSpanIndex(docs.kepubDoc), params.cfi);
+    if (result.status === 'failed') {
+      this.logFail('cfi_to_bookmark', params.bookFileId, result.reason);
+      return { status: 'failed', reason: result.reason, chapterIndex };
+    }
+    return {
+      status: result.status,
+      chapterIndex,
+      spanId: result.spanId,
+      chapterFilename: docs.kepubHref,
+      contentSourceProgressPercent: Math.round(result.chapterFraction * 10000) / 100,
+    };
+  }
+
+  async computeRenditionHash(ctx: KepubContext): Promise<string | null> {
+    try {
+      const kepubStat = await stat(ctx.kepubPath);
+      const material = [
+        ctx.fileHash ?? 'nohash',
+        `hyph=${ctx.hyphenate}`,
+        `size=${kepubStat.size}`,
+        `mtime=${kepubStat.mtimeMs}`,
+        `kepubify=${ctx.kepubifyVersion}`,
+        `resolver=${KOBO_SPAN_RESOLVER_VERSION}`,
+      ].join('|');
+      const key = `${ctx.kepubPath}|${material}`;
+      if (this.renditionHashCache?.key === key) return this.renditionHashCache.hash;
+      const hash = createHash('sha256').update(material).digest('hex');
+      this.renditionHashCache = { key, hash };
+      return hash;
+    } catch {
+      return null;
+    }
+  }
+
+  private getSpanIndex(kepubDoc: ChapterDocument): KoboSpanIndex {
+    const cached = this.spanIndexCache.get(kepubDoc);
+    if (cached) return cached;
+    const index = buildKoboSpanIndex(kepubDoc);
+    this.spanIndexCache.set(kepubDoc, index);
+    return index;
+  }
+
+  private parseLocation(location: unknown): KoboSpanLocation | null {
+    if (!location || typeof location !== 'object') return null;
+    const span = (location as Record<string, unknown>).span;
+    if (!span || typeof span !== 'object') return null;
+    const raw = span as Record<string, unknown>;
+    const { startPath, endPath, chapterFilename, startChar, endChar } = raw;
+    if (typeof startPath !== 'string' || typeof endPath !== 'string' || typeof chapterFilename !== 'string') return null;
+    if (typeof startChar !== 'number' || typeof endChar !== 'number') return null;
+    if (!Number.isInteger(startChar) || !Number.isInteger(endChar) || startChar < 0 || endChar < 0) return null;
+    return {
+      startPath,
+      startChar,
+      endPath,
+      endChar,
+      chapterFilename,
+      chapterTitle: typeof raw.chapterTitle === 'string' ? raw.chapterTitle : null,
+    };
+  }
+
+  private async loadChapterPairByFilename(bookFileId: number, ctx: KepubContext, chapterFilename: string): Promise<ChapterPair | { reason: string }> {
+    const kepubChapterIndex = await this.kepubDom.findChapterIndexByFilename(ctx.kepubPath, chapterFilename);
+    if (kepubChapterIndex == null) return { reason: 'chapter_not_found' };
+    return this.loadChapterPair(bookFileId, ctx, kepubChapterIndex, 'kepub');
+  }
+
+  private async loadChapterPairByIndex(bookFileId: number, ctx: KepubContext, epubChapterIndex: number): Promise<ChapterPair | { reason: string }> {
+    return this.loadChapterPair(bookFileId, ctx, epubChapterIndex, 'epub');
+  }
+
+  /**
+   * Loads the epub/kepub chapter docs for one chapter. kepubify preserves spine
+   * order and hrefs, so indexes normally align; when they do not (renamed or
+   * filtered spine), the matching href on the other side wins.
+   */
+  private async loadChapterPair(
+    bookFileId: number,
+    ctx: KepubContext,
+    chapterIndex: number,
+    side: 'epub' | 'kepub',
+  ): Promise<ChapterPair | { reason: string }> {
+    const kepubSpine = await this.kepubDom.getSpine(ctx.kepubPath);
+    if (!kepubSpine) return { reason: 'kepub_unavailable' };
+    const epubHrefs = await this.epubDom.getSpineHrefs(bookFileId);
+    if (!epubHrefs) return { reason: 'chapter_unavailable' };
+
+    let epubChapterIndex = chapterIndex;
+    let kepubChapterIndex = chapterIndex;
+    if (side === 'kepub') {
+      const href = kepubSpine.hrefs[chapterIndex];
+      if (href == null) return { reason: 'chapter_not_found' };
+      if (epubHrefs[chapterIndex] !== href) {
+        const alt = epubHrefs.indexOf(href);
+        if (alt >= 0) epubChapterIndex = alt;
+      }
+    } else {
+      const href = epubHrefs[chapterIndex];
+      if (href == null) return { reason: 'chapter_not_found' };
+      if (kepubSpine.hrefs[chapterIndex] !== href) {
+        const alt = kepubSpine.hrefs.indexOf(href);
+        if (alt >= 0) kepubChapterIndex = alt;
+      }
+    }
+
+    const kepubHref = kepubSpine.hrefs[kepubChapterIndex];
+    if (kepubHref == null) return { reason: 'chapter_not_found' };
+
+    const [epubDoc, kepubDoc] = await Promise.all([
+      this.epubDom.getChapter(bookFileId, epubChapterIndex),
+      this.kepubDom.getChapterByIndex(ctx.kepubPath, kepubChapterIndex),
+    ]);
+    if (!epubDoc) return { reason: 'chapter_unavailable' };
+    if (!kepubDoc) return { reason: 'kepub_unavailable' };
+
+    return { epubDoc, kepubDoc, epubChapterIndex, kepubChapterIndex, kepubHref, kepubSpineLength: kepubSpine.hrefs.length };
+  }
+
+  private logFail(operation: string, bookFileId: number, reason: string): void {
+    this.logger.debug(`[${EVENT}] [fail] op=${operation} bookFileId=${bookFileId} reason=${sanitizeLogValue(reason)} - kobo span conversion failed`);
+  }
+}
+
+interface ChapterPair {
+  epubDoc: ChapterDocument;
+  kepubDoc: ChapterDocument;
+  epubChapterIndex: number;
+  kepubChapterIndex: number;
+  kepubHref: string;
+  kepubSpineLength: number;
+}
diff --git a/server/src/modules/position-converter/kobo-span.core.test.ts b/server/src/modules/position-converter/kobo-span.core.test.ts
new file mode 100644
index 000000000..f797a9d40
--- /dev/null
+++ b/server/src/modules/position-converter/kobo-span.core.test.ts
@@ -0,0 +1,363 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildKoboSpanIndex,
+  canonicalCfiToKoboSpan,
+  cfiPointToKoboSpanPoint,
+  koboSpanPointToCanonical,
+  koboSpanRangeToCanonical,
+  parseSpanSelector,
+  spanSelectorFromId,
+  utf16OffsetForCodePointCount,
+} from './kobo-span.core';
+import { cfiRangeToCollapsed, parseChapterDocument, xpointerRangeToCfi } from './position-converter.core';
+
+const EPUB_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body>
+  <p>First sentence here. Second sentence follows!</p>
+  <p>Another <em>styled</em> paragraph.</p>
+</body>
+</html>`;
+
+const KEPUB_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><div id="book-columns"><div id="book-inner">
+  <p><span class="koboSpan" id="kobo.1.1">First sentence here. </span><span class="koboSpan" id="kobo.1.2">Second sentence follows!</span></p>
+  <p><span class="koboSpan" id="kobo.2.1">Another </span><em><span class="koboSpan" id="kobo.2.2">styled</span></em><span class="koboSpan" id="kobo.2.3"> paragraph.</span></p>
+</div></div></body>
+</html>`;
+
+const ASTRAL_EPUB = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><p>ab\u{1F600}cd efgh.</p></body>
+</html>`;
+
+const ASTRAL_KEPUB = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><div id="book-columns"><div id="book-inner"><p><span class="koboSpan" id="kobo.1.1">ab\u{1F600}cd efgh.</span></p></div></div></body>
+</html>`;
+
+const IMG_KEPUB = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><div id="book-columns"><div id="book-inner">
+  <p><span class="koboSpan" id="kobo.1.1">Before image.</span></p>
+  <span class="koboSpan" id="kobo.2.1"><img src="pic.png" alt=""/></span>
+  <p><span class="koboSpan" id="kobo.3.1">After image.</span></p>
+</div></div></body>
+</html>`;
+
+const IMG_EPUB = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body>
+  <p>Before image.</p>
+  <img src="pic.png" alt=""/>
+  <p>After image.</p>
+</body>
+</html>`;
+
+function docs(epubXhtml: string, kepubXhtml: string) {
+  const epubDoc = parseChapterDocument(epubXhtml);
+  const kepubDoc = parseChapterDocument(kepubXhtml);
+  return { epubDoc, kepubDoc, spanIndex: buildKoboSpanIndex(kepubDoc) };
+}
+
+describe('parseSpanSelector', () => {
+  it('extracts ids from escaped selectors', () => {
+    expect(parseSpanSelector('span#kobo\\.1\\.2')).toBe('kobo.1.2');
+    expect(parseSpanSelector('#kobo.4.2')).toBe('kobo.4.2');
+    expect(parseSpanSelector('OEBPS/ch1.xhtml#span#kobo\\.3\\.1')).toBe('kobo.3.1');
+    expect(parseSpanSelector('span.koboSpan')).toBeNull();
+  });
+
+  it('round-trips through spanSelectorFromId', () => {
+    expect(parseSpanSelector(spanSelectorFromId('kobo.12.34'))).toBe('kobo.12.34');
+  });
+});
+
+describe('buildKoboSpanIndex', () => {
+  it('indexes spans with collapsed ranges matching the epub text', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    expect(kepubDoc.index.collapsed).toBe(epubDoc.index.collapsed);
+    expect(spanIndex.ordered.map((s) => s.id)).toEqual(['kobo.1.1', 'kobo.1.2', 'kobo.2.1', 'kobo.2.2', 'kobo.2.3']);
+
+    const first = spanIndex.byId.get('kobo.1.1')!;
+    expect(kepubDoc.index.extractCollapsed(first.collapsedStart, first.collapsedEnd)).toBe('First sentence here. ');
+    const second = spanIndex.byId.get('kobo.1.2')!;
+    expect(kepubDoc.index.extractCollapsed(second.collapsedStart, second.collapsedEnd)).toBe('Second sentence follows!');
+  });
+
+  it('anchors textless image spans to the nearest text span', () => {
+    const { kepubDoc, spanIndex } = docs(IMG_EPUB, IMG_KEPUB);
+    const imgSpan = spanIndex.byId.get('kobo.2.1')!;
+    expect(imgSpan.synthetic).toBe(true);
+    const after = spanIndex.byId.get('kobo.3.1')!;
+    expect(imgSpan.collapsedStart).toBe(after.collapsedStart);
+    expect(spanIndex.ordered.map((s) => s.id)).toEqual(['kobo.1.1', 'kobo.3.1']);
+    expect(kepubDoc.index.collapsed).toBe('Before image. After image.');
+  });
+});
+
+describe('koboSpanRangeToCanonical', () => {
+  it('converts an exact single-span range to cfi and xpointers', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.2', startChar: 0, endId: 'kobo.1.2', endChar: 6 },
+      'Second',
+    );
+    expect(result.status).toBe('exact');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('Second');
+
+    const roundTrip = cfiRangeToCollapsed(epubDoc, result.cfi);
+    expect(roundTrip).toEqual({ startCp: result.startCp, endCp: result.endCp });
+
+    const viaXPointer = xpointerRangeToCfi(epubDoc, 0, result.xpointerPos0, result.xpointerPos1, 'Second');
+    expect(viaXPointer.status).toBe('exact');
+    if (viaXPointer.status !== 'failed') expect(viaXPointer.pos0).toBe(result.cfi);
+  });
+
+  it('converts a range spanning two spans', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.1', startChar: 6, endId: 'kobo.1.2', endChar: 15 },
+      'sentence here. Second sentence',
+    );
+    expect(result.status).toBe('exact');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('sentence here. Second sentence');
+  });
+
+  it('resolves structurally without text', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.2.2', startChar: 0, endId: 'kobo.2.2', endChar: 6 },
+      null,
+    );
+    expect(result.status).toBe('exact');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('styled');
+  });
+
+  it('retries char offsets as code points when UTF-16 interpretation mismatches', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(ASTRAL_EPUB, ASTRAL_KEPUB);
+    // "cd" in code points: start 3, end 5 (UTF-16 would be 4 and 6).
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.1', startChar: 3, endChar: 5, endId: 'kobo.1.1' },
+      'cd',
+    );
+    expect(result.status).toBe('exact');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('cd');
+  });
+
+  it('repairs via text search when the span is missing', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.9.9', startChar: 0, endId: 'kobo.9.9', endChar: 6 },
+      'styled',
+    );
+    expect(result.status).toBe('repaired');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('styled');
+  });
+
+  it('repairs via epub text search when kepub text is misaligned', () => {
+    const misalignedKepub = KEPUB_CHAPTER.replace('First sentence here.', 'First sentence HERE!');
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, misalignedKepub);
+    expect(kepubDoc.index.collapsed).not.toBe(epubDoc.index.collapsed);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.2', startChar: 0, endId: 'kobo.1.2', endChar: 6 },
+      'Second',
+    );
+    expect(result.status).toBe('repaired');
+    if (result.status === 'failed') return;
+    expect(epubDoc.index.extractCollapsed(result.startCp, result.endCp)).toBe('Second');
+  });
+
+  it('fails with span_not_found when structure is missing and no text is given', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.9.9', startChar: 0, endId: 'kobo.9.9', endChar: 3 },
+      null,
+    );
+    expect(result).toEqual({ status: 'failed', reason: 'span_not_found' });
+  });
+
+  it('fails with span_not_found when both the spans and the text are missing', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.9.9', startChar: 0, endId: 'kobo.9.9', endChar: 3 },
+      'absent words entirely',
+    );
+    expect(result).toEqual({ status: 'failed', reason: 'span_not_found' });
+  });
+
+  it('fails with text_not_found when spans resolve but the text is absent', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const result = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.1', startChar: 0, endId: 'kobo.1.1', endChar: 21 },
+      'absent words entirely',
+    );
+    expect(result).toEqual({ status: 'failed', reason: 'text_mismatch' });
+  });
+});
+
+describe('canonicalCfiToKoboSpan', () => {
+  it('round-trips a single-span range', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const forward = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.2', startChar: 0, endId: 'kobo.1.2', endChar: 6 },
+      'Second',
+    );
+    expect(forward.status).toBe('exact');
+    if (forward.status === 'failed') return;
+
+    const back = canonicalCfiToKoboSpan(epubDoc, kepubDoc, spanIndex, forward.cfi, 'Second');
+    expect(back.status).toBe('exact');
+    if (back.status === 'failed') return;
+    expect(back).toMatchObject({ startId: 'kobo.1.2', startChar: 0, endId: 'kobo.1.2', endChar: 6 });
+  });
+
+  it('round-trips a multi-span range', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const forward = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.1', startChar: 6, endId: 'kobo.1.2', endChar: 15 },
+      'sentence here. Second sentence',
+    );
+    expect(forward.status).toBe('exact');
+    if (forward.status === 'failed') return;
+
+    const back = canonicalCfiToKoboSpan(epubDoc, kepubDoc, spanIndex, forward.cfi, 'sentence here. Second sentence');
+    expect(back.status).toBe('exact');
+    if (back.status === 'failed') return;
+    expect(back).toMatchObject({ startId: 'kobo.1.1', startChar: 6, endId: 'kobo.1.2', endChar: 15 });
+  });
+
+  it('keeps an exclusive end at the span boundary inside the start span', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const forward = koboSpanRangeToCanonical(
+      epubDoc,
+      kepubDoc,
+      spanIndex,
+      0,
+      { startId: 'kobo.1.1', startChar: 0, endId: 'kobo.1.1', endChar: 20 },
+      'First sentence here.',
+    );
+    expect(forward.status).toBe('exact');
+    if (forward.status === 'failed') return;
+
+    const back = canonicalCfiToKoboSpan(epubDoc, kepubDoc, spanIndex, forward.cfi, 'First sentence here.');
+    expect(back.status).toBe('exact');
+    if (back.status === 'failed') return;
+    expect(back.startId).toBe('kobo.1.1');
+    expect(back.endId).toBe('kobo.1.1');
+    expect(back.endChar).toBe(20);
+  });
+
+  it('repairs from text when the cfi does not resolve', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const back = canonicalCfiToKoboSpan(epubDoc, kepubDoc, spanIndex, 'epubcfi(/6/2!/4/99/1:0,/1:6)', 'styled');
+    expect(back.status).toBe('repaired');
+    if (back.status === 'failed') return;
+    expect(back.startId).toBe('kobo.2.2');
+    expect(back.startChar).toBe(0);
+    expect(back.endId).toBe('kobo.2.2');
+    expect(back.endChar).toBe(6);
+  });
+
+  it('fails when the highlight text is not in the kepub chapter', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const back = canonicalCfiToKoboSpan(epubDoc, kepubDoc, spanIndex, 'epubcfi(/6/2!/4/99/1:0,/1:6)', 'absent words entirely');
+    expect(back).toEqual({ status: 'failed', reason: 'text_not_found' });
+  });
+});
+
+describe('point conversions for reading position', () => {
+  it('converts a span id to a point cfi and xpointer and back', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    const point = koboSpanPointToCanonical(epubDoc, kepubDoc, spanIndex, 0, 'kobo.2.1');
+    expect(point.status).toBe('exact');
+    if (point.status === 'failed') return;
+    expect(point.cfi).toContain('epubcfi(');
+    expect(point.xpointer).toContain('/body/DocFragment[1]/');
+    expect(point.chapterFraction).toBeGreaterThan(0);
+
+    const back = cfiPointToKoboSpanPoint(epubDoc, kepubDoc, spanIndex, point.cfi);
+    expect(back.status).toBe('exact');
+    if (back.status === 'failed') return;
+    expect(back.spanId).toBe('kobo.2.1');
+  });
+
+  it('snaps a textless image span to its neighbor for point conversion', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(IMG_EPUB, IMG_KEPUB);
+    const point = koboSpanPointToCanonical(epubDoc, kepubDoc, spanIndex, 0, 'kobo.2.1');
+    expect(point.status).toBe('repaired');
+    if (point.status === 'failed') return;
+    const after = spanIndex.byId.get('kobo.3.1')!;
+    expect(point.cp).toBe(after.collapsedStart);
+  });
+
+  it('fails for unknown span ids', () => {
+    const { epubDoc, kepubDoc, spanIndex } = docs(EPUB_CHAPTER, KEPUB_CHAPTER);
+    expect(koboSpanPointToCanonical(epubDoc, kepubDoc, spanIndex, 0, 'kobo.99.99')).toEqual({ status: 'failed', reason: 'span_not_found' });
+  });
+});
+
+describe('utf16OffsetForCodePointCount', () => {
+  it('accounts for astral characters', () => {
+    expect(utf16OffsetForCodePointCount('ab\u{1F600}cd', 3)).toBe(4);
+    expect(utf16OffsetForCodePointCount('abc', 2)).toBe(2);
+    expect(utf16OffsetForCodePointCount('abc', 10)).toBe(3);
+  });
+});
diff --git a/server/src/modules/position-converter/kobo-span.core.ts b/server/src/modules/position-converter/kobo-span.core.ts
new file mode 100644
index 000000000..605d7ed04
--- /dev/null
+++ b/server/src/modules/position-converter/kobo-span.core.ts
@@ -0,0 +1,423 @@
+/**
+ * Kobo kepub span codec core. Kobo positions reference the koboSpan wrappers
+ * (<span class="koboSpan" id="kobo.N.M">) that kepubify inserts around sentences;
+ * char offsets count UTF-16 code units into the span's concatenated descendant text
+ * (Kobo firmware walks raw text nodes). BookOrbit converts epub -> kepub without
+ * text-altering options, so the collapsed text of a kepub chapter equals the original
+ * epub chapter's; ranges bridge between the two DOMs through collapsed cp indexes.
+ * Structure resolves positions, but the stored highlight text is the truth: results
+ * are verified by extraction and re-anchored by search, like the xpointer codec.
+ */
+
+import { ChapterTextIndex, normalizeForSearch } from './chapter-text-index';
+import { CfiNode, isElementNode, isTextNode } from './cfi.utils';
+import {
+  ChapterDocument,
+  CollapsedRange,
+  ConversionFailure,
+  cfiPointToCollapsedCp,
+  cfiRangeToCollapsed,
+  collapsedPointToCfi,
+  collapsedPointToXPointer,
+  collapsedRangeToCfi,
+  collapsedRangeToXPointerPair,
+} from './position-converter.core';
+
+export const KOBO_SPAN_RESOLVER_VERSION = 1;
+
+const KOBO_SPAN_ID_RE = /^kobo\.\d+\.\d+$/;
+
+export interface KoboSpanRange {
+  startId: string;
+  startChar: number;
+  endId: string;
+  endChar: number;
+}
+
+export interface KoboSpanEntry {
+  id: string;
+  element: CfiNode;
+  textNodes: CfiNode[];
+  utf16Length: number;
+  collapsedStart: number;
+  collapsedEnd: number;
+  /** True when the anchor was borrowed from a neighbor (textless span, e.g. an image). */
+  synthetic: boolean;
+}
+
+export interface KoboSpanIndex {
+  /** Spans that own collapsed text, ordered by collapsedStart. */
+  ordered: KoboSpanEntry[];
+  byId: Map<string, KoboSpanEntry>;
+}
+
+/** Extracts the span id from a Kobo selector path like "span#kobo\.3\.2". */
+export function parseSpanSelector(path: string): string | null {
+  const hashIndex = path.lastIndexOf('#');
+  if (hashIndex < 0) return null;
+  const raw = path
+    .slice(hashIndex + 1)
+    .trim()
+    .split(/[\s>[/:]/)[0]
+    ?.replace(/\\/g, '');
+  return raw || null;
+}
+
+export function spanSelectorFromId(id: string): string {
+  return `span#${id.replace(/\./g, '\\.')}`;
+}
+
+function isKoboSpanElement(node: CfiNode): boolean {
+  if (!isElementNode(node) || (node.name ?? '').toLowerCase() !== 'span') return false;
+  const className = node.attribs?.class ?? '';
+  if (!/\bkoboSpan\b/.test(className)) return false;
+  return KOBO_SPAN_ID_RE.test(node.attribs?.id ?? '');
+}
+
+function collectTextNodes(node: CfiNode, out: CfiNode[]): void {
+  for (const child of node.children ?? []) {
+    if (isTextNode(child)) out.push(child);
+    else if (isElementNode(child)) collectTextNodes(child, out);
+  }
+}
+
+export function buildKoboSpanIndex(doc: ChapterDocument): KoboSpanIndex {
+  const entries: KoboSpanEntry[] = [];
+
+  const walk = (node: CfiNode): void => {
+    for (const child of node.children ?? []) {
+      if (!isElementNode(child)) continue;
+      if (isKoboSpanElement(child)) {
+        const textNodes: CfiNode[] = [];
+        collectTextNodes(child, textNodes);
+        const first = textNodes[0];
+        const last = textNodes[textNodes.length - 1];
+        const start = first ? doc.index.collapsedFromNodePoint(first, 0) : null;
+        const end = last ? doc.index.collapsedFromNodePoint(last, last.data?.length ?? 0) : null;
+        const hasText = start != null && end != null && end > start;
+        entries.push({
+          id: child.attribs!.id!,
+          element: child,
+          textNodes,
+          utf16Length: textNodes.reduce((sum, n) => sum + (n.data?.length ?? 0), 0),
+          collapsedStart: hasText ? start : -1,
+          collapsedEnd: hasText ? end : -1,
+          synthetic: !hasText,
+        });
+      }
+      walk(child);
+    }
+  };
+  walk(doc.root);
+
+  const ordered = entries.filter((entry) => !entry.synthetic).sort((a, b) => a.collapsedStart - b.collapsedStart);
+
+  // Textless spans (image wrappers, collapsed whitespace) borrow the nearest
+  // text-owning neighbor's anchor so point lookups still land somewhere sane.
+  // entries and ordered share document order, so a single advancing cursor works.
+  let lastSeen: KoboSpanEntry | null = null;
+  let nextIdx = 0;
+  for (const entry of entries) {
+    if (!entry.synthetic) {
+      lastSeen = entry;
+      nextIdx += 1;
+      continue;
+    }
+    const next = ordered[nextIdx] ?? null;
+    const anchor = next ?? lastSeen;
+    if (anchor) {
+      entry.collapsedStart = next ? anchor.collapsedStart : anchor.collapsedEnd;
+      entry.collapsedEnd = entry.collapsedStart;
+    }
+  }
+
+  return { ordered, byId: new Map(entries.map((entry) => [entry.id, entry])) };
+}
+
+function spanText(span: KoboSpanEntry): string {
+  return span.textNodes.map((node) => node.data ?? '').join('');
+}
+
+export function utf16OffsetForCodePointCount(text: string, count: number): number {
+  let codePoints = 0;
+  let utf16 = 0;
+  for (const ch of text) {
+    if (codePoints >= count) break;
+    codePoints += 1;
+    utf16 += ch.length;
+  }
+  return utf16;
+}
+
+interface SpanCollapsedPoint {
+  cp: number;
+  withinBounds: boolean;
+}
+
+/** Maps a Kobo char offset (UTF-16 units into the span's concatenated text) to a collapsed cp. */
+export function spanCharToCollapsed(index: ChapterTextIndex, span: KoboSpanEntry, charUtf16: number): SpanCollapsedPoint | null {
+  let remaining = Math.max(0, charUtf16);
+  for (const node of span.textNodes) {
+    const length = node.data?.length ?? 0;
+    if (remaining <= length) {
+      const cp = index.collapsedFromNodePoint(node, remaining);
+      return cp == null ? null : { cp, withinBounds: charUtf16 >= 0 };
+    }
+    remaining -= length;
+  }
+  const last = span.textNodes[span.textNodes.length - 1];
+  if (!last) return null;
+  const cp = index.collapsedFromNodePoint(last, last.data?.length ?? 0);
+  return cp == null ? null : { cp, withinBounds: false };
+}
+
+interface SpanCharPoint {
+  spanId: string;
+  char: number;
+}
+
+/** Maps a collapsed cp (kepub space) to the owning span and Kobo char offset, snapping into the nearest span. */
+export function collapsedToSpanChar(index: ChapterTextIndex, spanIndex: KoboSpanIndex, cp: number, exclusiveEnd: boolean): SpanCharPoint | null {
+  const spans = spanIndex.ordered;
+  if (spans.length === 0) return null;
+
+  let span: KoboSpanEntry;
+  if (exclusiveEnd) {
+    span = findLast(spans, (s) => s.collapsedStart < cp) ?? spans[0];
+  } else {
+    span = spans.find((s) => s.collapsedEnd > cp) ?? spans[spans.length - 1];
+  }
+
+  const clamped = Math.max(span.collapsedStart, Math.min(cp, span.collapsedEnd));
+  const point = exclusiveEnd ? index.endPointFromCollapsed(clamped) : index.startPointFromCollapsed(clamped);
+  if (!point) return null;
+
+  let sum = 0;
+  for (const node of span.textNodes) {
+    if (node === point.node) return { spanId: span.id, char: Math.min(sum + point.offset, span.utf16Length) };
+    sum += node.data?.length ?? 0;
+  }
+  return { spanId: span.id, char: exclusiveEnd ? span.utf16Length : 0 };
+}
+
+function findLast<T>(items: T[], predicate: (item: T) => boolean): T | null {
+  for (let i = items.length - 1; i >= 0; i -= 1) {
+    if (predicate(items[i])) return items[i];
+  }
+  return null;
+}
+
+export interface KoboToCanonicalSuccess {
+  status: 'exact' | 'repaired';
+  cfi: string;
+  xpointerPos0: string;
+  xpointerPos1: string;
+  startCp: number;
+  endCp: number;
+  aligned: boolean;
+}
+
+export type KoboToCanonicalResult = KoboToCanonicalSuccess | ConversionFailure;
+
+export function koboSpanRangeToCanonical(
+  epubDoc: ChapterDocument,
+  kepubDoc: ChapterDocument,
+  spanIndex: KoboSpanIndex,
+  chapterIndex: number,
+  range: KoboSpanRange,
+  text: string | null,
+): KoboToCanonicalResult {
+  const aligned = kepubDoc.index.collapsed === epubDoc.index.collapsed;
+  const normalizedText = text ? normalizeForSearch(text) : '';
+
+  const emit = (startCp: number, endCp: number, status: 'exact' | 'repaired'): KoboToCanonicalResult => {
+    const cfi = collapsedRangeToCfi(epubDoc, chapterIndex, startCp, endCp);
+    const pair = collapsedRangeToXPointerPair(epubDoc, chapterIndex, startCp, endCp);
+    if (!cfi || !pair) return { status: 'failed', reason: 'position_generation_failed' };
+    return { status, cfi, xpointerPos0: pair.pos0, xpointerPos1: pair.pos1, startCp, endCp, aligned };
+  };
+
+  const startSpan = spanIndex.byId.get(range.startId) ?? null;
+  const endSpan = spanIndex.byId.get(range.endId) ?? null;
+  let structural: { startCp: number; endCp: number; withinBounds: boolean } | null = null;
+
+  if (aligned && startSpan && endSpan && !startSpan.synthetic && !endSpan.synthetic) {
+    const start = spanCharToCollapsed(kepubDoc.index, startSpan, range.startChar);
+    const end = spanCharToCollapsed(kepubDoc.index, endSpan, range.endChar);
+    if (start && end && end.cp > start.cp) {
+      structural = { startCp: start.cp, endCp: end.cp, withinBounds: start.withinBounds && end.withinBounds };
+    }
+  }
+
+  if (!normalizedText) {
+    if (structural) return emit(structural.startCp, structural.endCp, structural.withinBounds ? 'exact' : 'repaired');
+    return { status: 'failed', reason: aligned ? 'span_not_found' : 'kepub_text_mismatch' };
+  }
+
+  if (structural) {
+    const extracted = epubDoc.index.extractCollapsed(structural.startCp, structural.endCp);
+    if (normalizeForSearch(extracted) === normalizedText) return emit(structural.startCp, structural.endCp, 'exact');
+
+    // Offset-unit ambiguity: retry interpreting char offsets as code points.
+    const startRetry = spanCharToCollapsed(kepubDoc.index, startSpan!, utf16OffsetForCodePointCount(spanText(startSpan!), range.startChar));
+    const endRetry = spanCharToCollapsed(kepubDoc.index, endSpan!, utf16OffsetForCodePointCount(spanText(endSpan!), range.endChar));
+    if (startRetry && endRetry && endRetry.cp > startRetry.cp) {
+      const retried = epubDoc.index.extractCollapsed(startRetry.cp, endRetry.cp);
+      if (normalizeForSearch(retried) === normalizedText) return emit(startRetry.cp, endRetry.cp, 'exact');
+    }
+  }
+
+  const hint = structural?.startCp ?? scaledHint(startSpan, kepubDoc.index, epubDoc.index);
+  const match = epubDoc.index.searchNormalized(normalizedText, hint);
+  if (match) return emit(match.startCp, match.endCp, 'repaired');
+
+  if (!aligned) return { status: 'failed', reason: 'kepub_text_mismatch' };
+  return { status: 'failed', reason: structural ? 'text_mismatch' : startSpan && endSpan ? 'text_not_found' : 'span_not_found' };
+}
+
+function scaledHint(span: KoboSpanEntry | null, from: ChapterTextIndex, to: ChapterTextIndex): number | null {
+  if (!span || span.collapsedStart < 0 || from.collapsedCpLength === 0) return null;
+  return Math.round((span.collapsedStart * to.collapsedCpLength) / from.collapsedCpLength);
+}
+
+export interface CanonicalToKoboSuccess {
+  status: 'exact' | 'repaired';
+  startId: string;
+  startChar: number;
+  endId: string;
+  endChar: number;
+  startCp: number;
+  endCp: number;
+  aligned: boolean;
+}
+
+export type CanonicalToKoboResult = CanonicalToKoboSuccess | ConversionFailure;
+
+export function canonicalCfiToKoboSpan(
+  epubDoc: ChapterDocument,
+  kepubDoc: ChapterDocument,
+  spanIndex: KoboSpanIndex,
+  cfi: string,
+  text: string | null,
+): CanonicalToKoboResult {
+  const aligned = kepubDoc.index.collapsed === epubDoc.index.collapsed;
+  const normalizedText = text ? normalizeForSearch(text) : '';
+
+  // Structural resolution against the epub DOM; legacy CFIs minted while the web
+  // reader rendered kepubs resolve against the kepub DOM instead.
+  let candidate: CollapsedRange | null = null;
+  const fromEpub = cfiRangeToCollapsed(epubDoc, cfi);
+  if (fromEpub && aligned) candidate = fromEpub;
+  if (!candidate) candidate = cfiRangeToCollapsed(kepubDoc, cfi);
+
+  let status: 'exact' | 'repaired' = 'exact';
+  if (normalizedText) {
+    const verified = candidate && normalizeForSearch(kepubDoc.index.extractCollapsed(candidate.startCp, candidate.endCp)) === normalizedText;
+    if (!verified) {
+      const match = kepubDoc.index.searchNormalized(normalizedText, candidate?.startCp ?? null);
+      if (!match) return { status: 'failed', reason: candidate ? 'text_mismatch' : 'text_not_found' };
+      candidate = { startCp: match.startCp, endCp: match.endCp };
+      status = 'repaired';
+    }
+  } else if (!candidate) {
+    return { status: 'failed', reason: 'unresolvable_structure' };
+  }
+
+  const start = collapsedToSpanChar(kepubDoc.index, spanIndex, candidate!.startCp, false);
+  const end = collapsedToSpanChar(kepubDoc.index, spanIndex, candidate!.endCp, true);
+  if (!start || !end) return { status: 'failed', reason: 'span_not_found' };
+
+  return {
+    status,
+    startId: start.spanId,
+    startChar: start.char,
+    endId: end.spanId,
+    endChar: end.char,
+    startCp: candidate!.startCp,
+    endCp: candidate!.endCp,
+    aligned,
+  };
+}
+
+export interface SpanPointToCanonicalSuccess {
+  status: 'exact' | 'repaired';
+  cfi: string;
+  xpointer: string;
+  cp: number;
+  /** Position within the chapter's collapsed text, 0..1 (epub space). */
+  chapterFraction: number;
+}
+
+export type SpanPointToCanonicalResult = SpanPointToCanonicalSuccess | ConversionFailure;
+
+/** Converts a Kobo progress bookmark span id (no char offset) to canonical point positions. */
+export function koboSpanPointToCanonical(
+  epubDoc: ChapterDocument,
+  kepubDoc: ChapterDocument,
+  spanIndex: KoboSpanIndex,
+  chapterIndex: number,
+  spanId: string,
+): SpanPointToCanonicalResult {
+  const aligned = kepubDoc.index.collapsed === epubDoc.index.collapsed;
+  const span = spanIndex.byId.get(spanId);
+  if (!span || span.collapsedStart < 0) return { status: 'failed', reason: 'span_not_found' };
+
+  let cp = span.collapsedStart;
+  let status: 'exact' | 'repaired' = span.synthetic ? 'repaired' : 'exact';
+  if (!aligned) {
+    if (kepubDoc.index.collapsedCpLength === 0) return { status: 'failed', reason: 'kepub_text_mismatch' };
+    cp = Math.round((cp * epubDoc.index.collapsedCpLength) / kepubDoc.index.collapsedCpLength);
+    status = 'repaired';
+  }
+  cp = Math.max(0, Math.min(cp, Math.max(0, epubDoc.index.collapsedCpLength - 1)));
+
+  const cfi = collapsedPointToCfi(epubDoc, chapterIndex, cp);
+  const xpointer = collapsedPointToXPointer(epubDoc, chapterIndex, cp);
+  if (!cfi || !xpointer) return { status: 'failed', reason: 'position_generation_failed' };
+
+  const chapterFraction = epubDoc.index.collapsedCpLength > 0 ? cp / epubDoc.index.collapsedCpLength : 0;
+  return { status, cfi, xpointer, cp, chapterFraction };
+}
+
+export interface CfiPointToSpanSuccess {
+  status: 'exact' | 'repaired';
+  spanId: string;
+  /** Position within the chapter's collapsed text, 0..1 (kepub space). */
+  chapterFraction: number;
+}
+
+export type CfiPointToSpanResult = CfiPointToSpanSuccess | ConversionFailure;
+
+/** Converts a canonical point CFI to the nearest Kobo span id for a progress bookmark. */
+export function cfiPointToKoboSpanPoint(
+  epubDoc: ChapterDocument,
+  kepubDoc: ChapterDocument,
+  spanIndex: KoboSpanIndex,
+  cfi: string,
+): CfiPointToSpanResult {
+  const aligned = kepubDoc.index.collapsed === epubDoc.index.collapsed;
+
+  let cp: number | null = null;
+  let status: 'exact' | 'repaired' = 'exact';
+  const fromEpub = cfiPointToCollapsedCp(epubDoc, cfi);
+  if (fromEpub != null) {
+    if (aligned) {
+      cp = fromEpub;
+    } else if (epubDoc.index.collapsedCpLength > 0) {
+      cp = Math.round((fromEpub * kepubDoc.index.collapsedCpLength) / epubDoc.index.collapsedCpLength);
+      status = 'repaired';
+    }
+  }
+  if (cp == null) {
+    cp = cfiPointToCollapsedCp(kepubDoc, cfi);
+    if (cp != null && !aligned) status = 'repaired';
+  }
+  if (cp == null) return { status: 'failed', reason: 'unresolvable_structure' };
+
+  const spans = spanIndex.ordered;
+  if (spans.length === 0) return { status: 'failed', reason: 'span_not_found' };
+  const span = spans.find((s) => s.collapsedEnd > cp!) ?? spans[spans.length - 1];
+
+  const chapterFraction = kepubDoc.index.collapsedCpLength > 0 ? Math.max(0, Math.min(1, cp / kepubDoc.index.collapsedCpLength)) : 0;
+  return { status, spanId: span.id, chapterFraction };
+}
diff --git a/server/src/modules/position-converter/position-converter.core.test.ts b/server/src/modules/position-converter/position-converter.core.test.ts
new file mode 100644
index 000000000..be60e1b02
--- /dev/null
+++ b/server/src/modules/position-converter/position-converter.core.test.ts
@@ -0,0 +1,289 @@
+import { describe, expect, it } from 'vitest';
+
+import { chapterIndexFromSpineStep, parseCfi } from './cfi.utils';
+import { cfiRangeToXPointer, parseChapterDocument, xpointerRangeToCfi } from './position-converter.core';
+import { parseXPointer } from './xpointer.utils';
+
+const SIMPLE_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body>
+  <p>The quick brown fox jumps over the lazy dog.</p>
+  <p>Second <em>paragraph</em> with <strong>nested</strong> text.</p>
+</body>
+</html>`;
+
+const INDENTED_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body>
+  <p>
+    Hello   world
+  </p>
+</body>
+</html>`;
+
+const ASTRAL_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><p>ab\u{1F600}cd efgh</p></body>
+</html>`;
+
+const MULTI_TEXT_CHAPTER = `<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head><title>T</title></head>
+<body><p>one <em>two</em> three</p></body>
+</html>`;
+
+describe('parseXPointer', () => {
+  it('parses a plain text pointer', () => {
+    const parsed = parseXPointer('/body/DocFragment[8]/body/p[20]/text().249');
+    expect(parsed).toEqual({
+      docFragmentIndex: 8,
+      steps: [
+        { name: 'body', index: 1 },
+        { name: 'p', index: 20 },
+      ],
+      textIndex: 1,
+      offset: 249,
+    });
+  });
+
+  it('parses an indexed text node pointer', () => {
+    const parsed = parseXPointer('/body/DocFragment[56]/body/section/p[2]/text()[1].72');
+    expect(parsed).toMatchObject({ docFragmentIndex: 56, textIndex: 1, offset: 72 });
+    expect(parsed!.steps).toEqual([
+      { name: 'body', index: 1 },
+      { name: 'section', index: 1 },
+      { name: 'p', index: 2 },
+    ]);
+  });
+
+  it('parses an element pointer without text or offset', () => {
+    const parsed = parseXPointer('/body/DocFragment[3]/body/h1');
+    expect(parsed).toMatchObject({ docFragmentIndex: 3, textIndex: null, offset: null });
+  });
+
+  it('defaults DocFragment index to 1 when unindexed', () => {
+    expect(parseXPointer('/body/DocFragment/body/p/text().5')).toMatchObject({ docFragmentIndex: 1 });
+  });
+
+  it('rejects non-crengine pointers', () => {
+    expect(parseXPointer('#point(/1/2)')).toBeNull();
+    expect(parseXPointer('/html/body/p[1]')).toBeNull();
+    expect(parseXPointer('')).toBeNull();
+  });
+});
+
+describe('parseCfi', () => {
+  it('parses a plain CFI with indirection and id assertion', () => {
+    const parsed = parseCfi('epubcfi(/6/12[chap]!/4/2[para]/1:5)');
+    expect(parsed!.spineStep).toBe(12);
+    expect(parsed!.start).toEqual([{ index: 4 }, { index: 2, id: 'para' }, { index: 1, offset: 5 }]);
+    expect(parsed!.end).toEqual(parsed!.start);
+  });
+
+  it('parses a range CFI, merging the parent into both endpoints', () => {
+    const parsed = parseCfi('epubcfi(/6/2!/4/2,/1:4,/1:9)');
+    expect(parsed!.spineStep).toBe(2);
+    expect(parsed!.start).toEqual([{ index: 4 }, { index: 2 }, { index: 1, offset: 4 }]);
+    expect(parsed!.end).toEqual([{ index: 4 }, { index: 2 }, { index: 1, offset: 9 }]);
+  });
+
+  it('maps spine steps to chapter indexes', () => {
+    expect(chapterIndexFromSpineStep(2)).toBe(0);
+    expect(chapterIndexFromSpineStep(12)).toBe(5);
+    expect(chapterIndexFromSpineStep(null)).toBeNull();
+    expect(chapterIndexFromSpineStep(3)).toBeNull();
+  });
+});
+
+describe('xpointerRangeToCfi', () => {
+  it('converts a simple in-paragraph range exactly', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p[1]/text().4', '/body/DocFragment[1]/body/p[1]/text().9', 'quick');
+    expect(result).toEqual({ status: 'exact', pos0: 'epubcfi(/6/2!/4/2,/1:4,/1:9)', pos1: null });
+  });
+
+  it('maps collapsed crengine offsets back to raw offsets in indented source', () => {
+    const doc = parseChapterDocument(INDENTED_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p/text().6', '/body/DocFragment[1]/body/p/text().11', 'world');
+    expect(result.status).toBe('exact');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/2,/1:13,/1:18)');
+  });
+
+  it('handles astral characters with code-point offsets', () => {
+    const doc = parseChapterDocument(ASTRAL_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p/text().3', '/body/DocFragment[1]/body/p/text().5', 'cd');
+    expect(result.status).toBe('exact');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/2,/1:4,/1:6)');
+  });
+
+  it('resolves text()[2] among multiple direct text nodes', () => {
+    const doc = parseChapterDocument(MULTI_TEXT_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p/text()[2].1', '/body/DocFragment[1]/body/p/text()[2].6', 'three');
+    expect(result.status).toBe('exact');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/2,/3:1,/3:6)');
+  });
+
+  it('resolves ranges inside nested inline elements', () => {
+    const doc = parseChapterDocument(MULTI_TEXT_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p/em/text().0', '/body/DocFragment[1]/body/p/em/text().3', 'two');
+    expect(result.status).toBe('exact');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/2/2,/1:0,/1:3)');
+  });
+
+  it('repairs wrong offsets by anchoring on the highlight text', () => {
+    const doc = parseChapterDocument(INDENTED_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p/text().40', '/body/DocFragment[1]/body/p/text().45', 'world');
+    expect(result.status).toBe('repaired');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/2,/1:13,/1:18)');
+  });
+
+  it('repairs a stale element path via text search', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p[7]/text().4', '/body/DocFragment[1]/body/p[7]/text().9', 'nested');
+    expect(result.status).toBe('repaired');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4/4/4,/1:0,/1:6)');
+  });
+
+  it('converts cross-element ranges structurally when no text is stored', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p[1]/text().40', '/body/DocFragment[1]/body/p[2]/text()[1].6', null);
+    expect(result.status).toBe('exact');
+    expect((result as { pos0: string }).pos0).toBe('epubcfi(/6/2!/4,/2/1:40,/4/1:6)');
+  });
+
+  it('fails when the text cannot be found and structure does not resolve', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(
+      doc,
+      0,
+      '/body/DocFragment[1]/body/div[9]/text().0',
+      '/body/DocFragment[1]/body/div[9]/text().5',
+      'absent words entirely',
+    );
+    expect(result).toEqual({ status: 'failed', reason: 'text_not_found' });
+  });
+
+  it('fails on cross-fragment ranges', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[1]/body/p[1]/text().0', '/body/DocFragment[2]/body/p[1]/text().5', 'x');
+    expect(result).toEqual({ status: 'failed', reason: 'cross_fragment_range' });
+  });
+
+  it('fails when the fragment does not match the chapter', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = xpointerRangeToCfi(doc, 0, '/body/DocFragment[4]/body/p[1]/text().0', null, 'x');
+    expect(result).toEqual({ status: 'failed', reason: 'fragment_mismatch' });
+  });
+});
+
+describe('cfiRangeToXPointer', () => {
+  it('converts a simple range with collapsed offsets', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/1:4,/1:9)', 'quick');
+    expect(result).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p[1]/text().4',
+      pos1: '/body/DocFragment[1]/body/p[1]/text().9',
+    });
+  });
+
+  it('emits crengine collapsed offsets for indented raw source', () => {
+    const doc = parseChapterDocument(INDENTED_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/1:13,/1:18)', 'world');
+    expect(result).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p/text().6',
+      pos1: '/body/DocFragment[1]/body/p/text().11',
+    });
+  });
+
+  it('round-trips astral offsets', () => {
+    const doc = parseChapterDocument(ASTRAL_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/1:4,/1:6)', 'cd');
+    expect(result).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p/text().3',
+      pos1: '/body/DocFragment[1]/body/p/text().5',
+    });
+  });
+
+  it('emits text()[k] for later text runs and plain text() inside single-run elements', () => {
+    const doc = parseChapterDocument(MULTI_TEXT_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/3:1,/3:6)', 'three');
+    expect(result).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p/text()[2].1',
+      pos1: '/body/DocFragment[1]/body/p/text()[2].6',
+    });
+
+    const nested = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2/2,/1:0,/1:3)', 'two');
+    expect(nested).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p/em/text().0',
+      pos1: '/body/DocFragment[1]/body/p/em/text().3',
+    });
+  });
+
+  it('repairs a CFI whose offsets do not match the stored text', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/1:0,/1:3)', 'lazy');
+    expect(result.status).toBe('repaired');
+    expect(result).toMatchObject({
+      pos0: '/body/DocFragment[1]/body/p[1]/text().35',
+      pos1: '/body/DocFragment[1]/body/p[1]/text().39',
+    });
+  });
+
+  it('converts cross-paragraph ranges', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    const result = cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4,/2/1:40,/4/1:6)', null);
+    expect(result).toEqual({
+      status: 'exact',
+      pos0: '/body/DocFragment[1]/body/p[1]/text().40',
+      pos1: '/body/DocFragment[1]/body/p[2]/text()[1].6',
+    });
+  });
+
+  it('fails for unparsable or empty inputs', () => {
+    const doc = parseChapterDocument(SIMPLE_CHAPTER);
+    expect(cfiRangeToXPointer(doc, 0, 'not-a-cfi', 'x').status).toBe('failed');
+    expect(cfiRangeToXPointer(doc, 0, 'epubcfi(/6/2!/4/2,/1:4,/1:4)', null).status).toBe('failed');
+  });
+});
+
+describe('round trips', () => {
+  const cases: Array<{ chapter: string; pos0: string; pos1: string; text: string }> = [
+    {
+      chapter: SIMPLE_CHAPTER,
+      pos0: '/body/DocFragment[1]/body/p[1]/text().10',
+      pos1: '/body/DocFragment[1]/body/p[1]/text().19',
+      text: 'brown fox',
+    },
+    {
+      chapter: INDENTED_CHAPTER,
+      pos0: '/body/DocFragment[1]/body/p/text().0',
+      pos1: '/body/DocFragment[1]/body/p/text().5',
+      text: 'Hello',
+    },
+    {
+      chapter: MULTI_TEXT_CHAPTER,
+      pos0: '/body/DocFragment[1]/body/p/text()[1].0',
+      pos1: '/body/DocFragment[1]/body/p/text()[2].6',
+      text: 'one two three',
+    },
+  ];
+
+  it('xpointer -> cfi -> xpointer preserves positions', () => {
+    for (const testCase of cases) {
+      const doc = parseChapterDocument(testCase.chapter);
+      const toCfi = xpointerRangeToCfi(doc, 0, testCase.pos0, testCase.pos1, testCase.text);
+      expect(toCfi.status).toBe('exact');
+      const back = cfiRangeToXPointer(doc, 0, (toCfi as { pos0: string }).pos0, testCase.text);
+      expect(back.status).toBe('exact');
+      expect(back).toMatchObject({ pos0: testCase.pos0, pos1: testCase.pos1 });
+    }
+  });
+});
diff --git a/server/src/modules/position-converter/position-converter.core.ts b/server/src/modules/position-converter/position-converter.core.ts
new file mode 100644
index 000000000..aad3ae711
--- /dev/null
+++ b/server/src/modules/position-converter/position-converter.core.ts
@@ -0,0 +1,289 @@
+/**
+ * Pure conversion core between KOReader XPointer ranges and EPUB CFI ranges over a
+ * parsed chapter document. Structure resolves positions, but the stored highlight
+ * text is the truth: every conversion is verified by extracting the resolved range
+ * and comparing normalized text, with search-based re-anchoring as repair.
+ */
+
+import * as cheerio from 'cheerio';
+
+import { ChapterTextIndex, normalizeForSearch, TextRun } from './chapter-text-index';
+import {
+  CfiNode,
+  ResolvedCfiPoint,
+  cfiFromPoint,
+  cfiFromRangePoints,
+  isTextNode,
+  joinCfiIndirection,
+  parseCfi,
+  resolveCfiParts,
+  spineCfiForChapterIndex,
+} from './cfi.utils';
+import { buildXPointer, parseXPointer, resolveXPointerElement } from './xpointer.utils';
+
+export const CONVERTER_VERSION = 1;
+
+/** KOReader sidecar text is truncated at 10000 chars; treat near-limit text as a prefix. */
+const TRUNCATED_TEXT_THRESHOLD = 9990;
+const EXACT_HINT_TOLERANCE_CP = 2;
+
+export interface ChapterDocument {
+  root: CfiNode;
+  index: ChapterTextIndex;
+}
+
+export interface ConversionSuccess {
+  status: 'exact' | 'repaired';
+  pos0: string;
+  pos1: string | null;
+}
+
+export interface ConversionFailure {
+  status: 'failed';
+  reason: string;
+}
+
+export type ConversionResult = ConversionSuccess | ConversionFailure;
+
+export function parseChapterDocument(xhtml: string): ChapterDocument {
+  const $ = cheerio.load(xhtml, { xml: true });
+  const root = $.root()[0] as unknown as CfiNode;
+  return { root, index: new ChapterTextIndex(root) };
+}
+
+interface StructuralAnchor {
+  cp: number;
+  resolved: boolean;
+}
+
+function xpointerAnchor(doc: ChapterDocument, pos: string, exclusiveEnd: boolean): StructuralAnchor | null {
+  const parsed = parseXPointer(pos);
+  if (!parsed) return null;
+  const element = resolveXPointerElement(doc.root, parsed.steps);
+  if (!element) return null;
+
+  const directRuns = doc.index.runsOfParent(element);
+  const run: TextRun | null = (parsed.textIndex != null ? directRuns[parsed.textIndex - 1] : null) ?? doc.index.firstRunWithin(element);
+  if (!run) return null;
+
+  if (parsed.offset == null) {
+    return { cp: exclusiveEnd ? run.collapsedStart + run.collapsedLength : run.collapsedStart, resolved: false };
+  }
+  const withinRange = parsed.offset <= run.collapsedLength;
+  return { cp: doc.index.collapsedForRunOffset(run, parsed.offset), resolved: withinRange };
+}
+
+/**
+ * Converts a KOReader xpointer range to a foliate range CFI.
+ * The returned pos0 carries the full range CFI; pos1 is always null.
+ */
+export function xpointerRangeToCfi(
+  doc: ChapterDocument,
+  chapterIndex: number,
+  pos0: string,
+  pos1: string | null,
+  text: string | null,
+): ConversionResult {
+  const p0 = parseXPointer(pos0);
+  if (!p0) return { status: 'failed', reason: 'unparsable_pos0' };
+  if (p0.docFragmentIndex !== chapterIndex + 1) return { status: 'failed', reason: 'fragment_mismatch' };
+  const p1 = pos1 ? parseXPointer(pos1) : null;
+  if (pos1 && !p1) return { status: 'failed', reason: 'unparsable_pos1' };
+  if (p1 && p1.docFragmentIndex !== p0.docFragmentIndex) return { status: 'failed', reason: 'cross_fragment_range' };
+
+  const anchor0 = xpointerAnchor(doc, pos0, false);
+  const anchor1 = pos1 ? xpointerAnchor(doc, pos1, true) : null;
+
+  let startCp: number | null;
+  let endCp: number | null;
+  let status: 'exact' | 'repaired';
+
+  const normalizedText = text ? normalizeForSearch(text) : '';
+  if (normalizedText) {
+    const truncated = text!.length >= TRUNCATED_TEXT_THRESHOLD;
+    const match = doc.index.searchNormalized(normalizedText, anchor0?.cp ?? null);
+    if (match) {
+      startCp = match.startCp;
+      endCp = truncated && anchor1 ? anchor1.cp : match.endCp;
+      const startAgrees = anchor0 != null && anchor0.resolved && Math.abs(match.startCp - anchor0.cp) <= EXACT_HINT_TOLERANCE_CP;
+      status = startAgrees && (!truncated || (anchor1?.resolved ?? false)) ? 'exact' : 'repaired';
+    } else if (anchor0 && anchor1) {
+      startCp = anchor0.cp;
+      endCp = anchor1.cp;
+      const extracted = doc.index.extractCollapsed(startCp, endCp);
+      if (normalizeForSearch(extracted) !== normalizedText) return { status: 'failed', reason: 'text_mismatch' };
+      status = 'exact';
+    } else {
+      return { status: 'failed', reason: 'text_not_found' };
+    }
+  } else {
+    if (!anchor0 || !anchor1) return { status: 'failed', reason: 'unresolvable_structure' };
+    startCp = anchor0.cp;
+    endCp = anchor1.cp;
+    status = anchor0.resolved && anchor1.resolved ? 'exact' : 'repaired';
+  }
+
+  if (startCp == null || endCp == null || endCp <= startCp) return { status: 'failed', reason: 'empty_range' };
+
+  const cfi = collapsedRangeToCfi(doc, chapterIndex, startCp, endCp);
+  if (!cfi) return { status: 'failed', reason: 'cfi_generation_failed' };
+  return { status, pos0: cfi, pos1: null };
+}
+
+/** Builds a full range CFI (with spine indirection) from a collapsed cp range. */
+export function collapsedRangeToCfi(doc: ChapterDocument, chapterIndex: number, startCp: number, endCp: number): string | null {
+  const startPoint = doc.index.startPointFromCollapsed(startCp);
+  const endPoint = doc.index.endPointFromCollapsed(endCp);
+  if (!startPoint || !endPoint) return null;
+  try {
+    const localCfi = cfiFromRangePoints(startPoint, endPoint);
+    return joinCfiIndirection(spineCfiForChapterIndex(chapterIndex), localCfi);
+  } catch {
+    return null;
+  }
+}
+
+/** Builds a full point CFI (with spine indirection) from a collapsed cp index. */
+export function collapsedPointToCfi(doc: ChapterDocument, chapterIndex: number, cp: number): string | null {
+  const point = doc.index.startPointFromCollapsed(cp);
+  if (!point) return null;
+  try {
+    return joinCfiIndirection(spineCfiForChapterIndex(chapterIndex), cfiFromPoint(point));
+  } catch {
+    return null;
+  }
+}
+
+/** Builds a point xpointer from a collapsed cp index. */
+export function collapsedPointToXPointer(doc: ChapterDocument, chapterIndex: number, cp: number): string | null {
+  const run = doc.index.runAtCollapsed(cp, 'forward') ?? doc.index.runAtCollapsed(cp, 'backward');
+  if (!run) return null;
+  return buildXPointer(run.parent, chapterIndex + 1, run.runIndex, run.runCount, doc.index.runOffsetOfCollapsed(cp, run));
+}
+
+/** Resolves a point xpointer to its collapsed cp index (null when structure is unresolvable). */
+export function xpointerPointToCollapsed(doc: ChapterDocument, pos: string): number | null {
+  return xpointerAnchor(doc, pos, false)?.cp ?? null;
+}
+
+function cfiPointToCollapsed(doc: ChapterDocument, point: ResolvedCfiPoint | null, exclusiveEnd: boolean): number | null {
+  if (!point?.node) return null;
+  if (isTextNode(point.node)) {
+    return doc.index.collapsedFromNodePoint(point.node, point.offset ?? 0);
+  }
+  const run = doc.index.firstRunWithin(point.node);
+  if (!run) return null;
+  if (exclusiveEnd) {
+    const last = lastRunWithin(doc, point.node) ?? run;
+    return last.collapsedStart + last.collapsedLength;
+  }
+  return run.collapsedStart;
+}
+
+function lastRunWithin(doc: ChapterDocument, element: CfiNode): TextRun | null {
+  if (isTextNode(element)) return doc.index.runOfTextNode(element);
+  const children = element.children ?? [];
+  for (let i = children.length - 1; i >= 0; i -= 1) {
+    const found = lastRunWithin(doc, children[i]);
+    if (found) return found;
+  }
+  return null;
+}
+
+export interface XPointerPair {
+  status: 'exact' | 'repaired';
+  pos0: string;
+  pos1: string;
+}
+
+export type CfiToXPointerResult = XPointerPair | ConversionFailure;
+
+export interface CollapsedRange {
+  startCp: number;
+  endCp: number;
+}
+
+/** Structurally resolves a range (or point) CFI to its collapsed cp range, without text repair. */
+export function cfiRangeToCollapsed(doc: ChapterDocument, cfi: string): CollapsedRange | null {
+  const parsed = parseCfi(cfi);
+  if (!parsed) return null;
+  const startResolved = resolveCfiParts(doc.root, parsed.start);
+  const endResolved = resolveCfiParts(doc.root, parsed.end);
+  const startCp = cfiPointToCollapsed(doc, startResolved, false);
+  const endCp = cfiPointToCollapsed(doc, endResolved, true);
+  if (startCp == null || endCp == null || endCp <= startCp) return null;
+  return { startCp, endCp };
+}
+
+/** Structurally resolves a point CFI (or range start) to its collapsed cp index. */
+export function cfiPointToCollapsedCp(doc: ChapterDocument, cfi: string): number | null {
+  const parsed = parseCfi(cfi);
+  if (!parsed) return null;
+  const startResolved = resolveCfiParts(doc.root, parsed.start);
+  return cfiPointToCollapsed(doc, startResolved, false);
+}
+
+/** Builds an xpointer pair from a collapsed cp range. */
+export function collapsedRangeToXPointerPair(
+  doc: ChapterDocument,
+  chapterIndex: number,
+  startCp: number,
+  endCp: number,
+): { pos0: string; pos1: string } | null {
+  const startRun = doc.index.runAtCollapsed(startCp, 'forward');
+  const endRun = doc.index.runAtCollapsed(endCp - 1, 'backward');
+  if (!startRun || !endRun) return null;
+
+  const docFragmentIndex = chapterIndex + 1;
+  const pos0 = buildXPointer(
+    startRun.parent,
+    docFragmentIndex,
+    startRun.runIndex,
+    startRun.runCount,
+    doc.index.runOffsetOfCollapsed(startCp, startRun),
+  );
+  const pos1 = buildXPointer(endRun.parent, docFragmentIndex, endRun.runIndex, endRun.runCount, doc.index.runOffsetOfCollapsed(endCp, endRun));
+  if (!pos0 || !pos1) return null;
+  return { pos0, pos1 };
+}
+
+/** Converts a foliate range CFI (doc-local parts already split by caller) to xpointers. */
+export function cfiRangeToXPointer(doc: ChapterDocument, chapterIndex: number, cfi: string, text: string | null): CfiToXPointerResult {
+  const parsed = parseCfi(cfi);
+  if (!parsed) return { status: 'failed', reason: 'unparsable_cfi' };
+
+  const startResolved = resolveCfiParts(doc.root, parsed.start);
+  const endResolved = resolveCfiParts(doc.root, parsed.end);
+  let startCp = cfiPointToCollapsed(doc, startResolved, false);
+  let endCp = cfiPointToCollapsed(doc, endResolved, true);
+  const structuralOk = startCp != null && endCp != null && endCp > startCp;
+
+  let status: 'exact' | 'repaired' = 'repaired';
+  const normalizedText = text ? normalizeForSearch(text) : '';
+  if (normalizedText) {
+    const extracted = structuralOk ? doc.index.extractCollapsed(startCp!, endCp!) : '';
+    if (structuralOk && normalizeForSearch(extracted) === normalizedText) {
+      status = 'exact';
+    } else {
+      const match = doc.index.searchNormalized(normalizedText, startCp);
+      if (match) {
+        startCp = match.startCp;
+        endCp = match.endCp;
+        status = 'repaired';
+      } else if (!structuralOk) {
+        return { status: 'failed', reason: 'text_not_found' };
+      }
+    }
+  } else if (!structuralOk) {
+    return { status: 'failed', reason: 'unresolvable_structure' };
+  } else {
+    status = 'exact';
+  }
+
+  if (startCp == null || endCp == null || endCp <= startCp) return { status: 'failed', reason: 'empty_range' };
+
+  const pair = collapsedRangeToXPointerPair(doc, chapterIndex, startCp, endCp);
+  if (!pair) return { status: 'failed', reason: 'xpointer_generation_failed' };
+
+  return { status, pos0: pair.pos0, pos1: pair.pos1 };
+}
diff --git a/server/src/modules/position-converter/position-converter.module.ts b/server/src/modules/position-converter/position-converter.module.ts
new file mode 100644
index 000000000..8ae5b0c57
--- /dev/null
+++ b/server/src/modules/position-converter/position-converter.module.ts
@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+
+import { EpubDomService } from './epub-dom.service';
+import { KepubDomService } from './kepub-dom.service';
+import { KoboSpanConverterService } from './kobo-span-converter.service';
+import { PositionConverterService } from './position-converter.service';
+
+@Module({
+  providers: [EpubDomService, KepubDomService, KoboSpanConverterService, PositionConverterService],
+  exports: [PositionConverterService, KoboSpanConverterService],
+})
+export class PositionConverterModule {}
diff --git a/server/src/modules/position-converter/position-converter.service.ts b/server/src/modules/position-converter/position-converter.service.ts
new file mode 100644
index 000000000..a41b788b3
--- /dev/null
+++ b/server/src/modules/position-converter/position-converter.service.ts
@@ -0,0 +1,94 @@
+import { Injectable } from '@nestjs/common';
+
+import { chapterIndexFromSpineStep, parseCfi } from './cfi.utils';
+import { EpubDomService } from './epub-dom.service';
+import {
+  CfiToXPointerResult,
+  ConversionResult,
+  CONVERTER_VERSION,
+  cfiRangeToXPointer,
+  collapsedPointToCfi,
+  xpointerPointToCollapsed,
+  xpointerRangeToCfi,
+} from './position-converter.core';
+import { parseXPointer } from './xpointer.utils';
+
+export interface XPointerToCfiParams {
+  bookFileId: number;
+  pos0: string;
+  pos1: string | null;
+  text: string | null;
+}
+
+export interface CfiToXPointerParams {
+  bookFileId: number;
+  cfi: string;
+  text: string | null;
+}
+
+export interface XPointerToCfiOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  cfi?: string;
+  chapterIndex?: number;
+  reason?: string;
+}
+
+export interface CfiToXPointerOutcome extends Record<string, unknown> {
+  status: 'exact' | 'repaired' | 'failed';
+  pos0?: string;
+  pos1?: string;
+  chapterIndex?: number;
+  reason?: string;
+}
+
+@Injectable()
+export class PositionConverterService {
+  readonly version = CONVERTER_VERSION;
+
+  constructor(private readonly epubDom: EpubDomService) {}
+
+  async xpointerToCfi(params: XPointerToCfiParams): Promise<XPointerToCfiOutcome> {
+    const parsed = parseXPointer(params.pos0);
+    if (!parsed) return { status: 'failed', reason: 'unparsable_pos0' };
+    const chapterIndex = parsed.docFragmentIndex - 1;
+    if (chapterIndex < 0) return { status: 'failed', reason: 'invalid_fragment' };
+
+    const doc = await this.epubDom.getChapter(params.bookFileId, chapterIndex);
+    if (!doc) return { status: 'failed', reason: 'chapter_unavailable', chapterIndex };
+
+    const result: ConversionResult = xpointerRangeToCfi(doc, chapterIndex, params.pos0, params.pos1, params.text);
+    if (result.status === 'failed') return { status: 'failed', reason: result.reason, chapterIndex };
+    return { status: result.status, cfi: result.pos0, chapterIndex };
+  }
+
+  /** Converts a single reading-position xpointer (point, not range) to a point CFI. */
+  async xpointerPointToCfi(params: { bookFileId: number; pos: string }): Promise<XPointerToCfiOutcome> {
+    const parsed = parseXPointer(params.pos);
+    if (!parsed) return { status: 'failed', reason: 'unparsable_pos0' };
+    const chapterIndex = parsed.docFragmentIndex - 1;
+    if (chapterIndex < 0) return { status: 'failed', reason: 'invalid_fragment' };
+
+    const doc = await this.epubDom.getChapter(params.bookFileId, chapterIndex);
+    if (!doc) return { status: 'failed', reason: 'chapter_unavailable', chapterIndex };
+
+    const cp = xpointerPointToCollapsed(doc, params.pos);
+    if (cp == null) return { status: 'failed', reason: 'unresolvable_structure', chapterIndex };
+    const cfi = collapsedPointToCfi(doc, chapterIndex, cp);
+    if (!cfi) return { status: 'failed', reason: 'cfi_generation_failed', chapterIndex };
+    return { status: 'exact', cfi, chapterIndex };
+  }
+
+  async cfiToXpointer(params: CfiToXPointerParams): Promise<CfiToXPointerOutcome> {
+    const parsed = parseCfi(params.cfi);
+    if (!parsed) return { status: 'failed', reason: 'unparsable_cfi' };
+    const chapterIndex = chapterIndexFromSpineStep(parsed.spineStep);
+    if (chapterIndex == null) return { status: 'failed', reason: 'missing_spine_step' };
+
+    const doc = await this.epubDom.getChapter(params.bookFileId, chapterIndex);
+    if (!doc) return { status: 'failed', reason: 'chapter_unavailable', chapterIndex };
+
+    const result: CfiToXPointerResult = cfiRangeToXPointer(doc, chapterIndex, params.cfi, params.text);
+    if (result.status === 'failed') return { status: 'failed', reason: result.reason, chapterIndex };
+    return { status: result.status, pos0: result.pos0, pos1: result.pos1, chapterIndex };
+  }
+}
diff --git a/server/src/modules/position-converter/xpointer.utils.ts b/server/src/modules/position-converter/xpointer.utils.ts
new file mode 100644
index 000000000..835bc720a
--- /dev/null
+++ b/server/src/modules/position-converter/xpointer.utils.ts
@@ -0,0 +1,136 @@
+/**
+ * crengine XPointer utilities (KOReader EPUB positions), matching lvtinydom's
+ * toStringV2 serialization: /body/DocFragment[N]/body/.../p[k]/text()[t].offset
+ * - element steps are 1-based among SAME-NAME element siblings; [k] is emitted
+ *   only when more than one same-named sibling exists
+ * - text() steps are 1-based among text-node children; [t] only when more than one
+ * - offsets count Unicode CODE POINTS in crengine's (whitespace-collapsed) text node
+ */
+
+import { CfiNode, getDocumentElement, isElementNode, isTextNode } from './cfi.utils';
+
+export interface XPointerStep {
+  name: string;
+  index: number;
+}
+
+export interface ParsedXPointer {
+  docFragmentIndex: number;
+  steps: XPointerStep[];
+  textIndex: number | null;
+  offset: number | null;
+}
+
+const XPOINTER_RE = /^\/body\/DocFragment(?:\[(\d+)\])?(.*)$/;
+const STEP_RE = /^([A-Za-z][\w:-]*)(?:\[(\d+)\])?$/;
+const TEXT_STEP_RE = /^text\(\)(?:\[(\d+)\])?$/;
+
+export function parseXPointer(raw: string): ParsedXPointer | null {
+  if (!raw) return null;
+  const match = XPOINTER_RE.exec(raw.trim());
+  if (!match) return null;
+  const docFragmentIndex = match[1] ? parseInt(match[1], 10) : 1;
+
+  let rest = match[2] ?? '';
+  let offset: number | null = null;
+  const offsetMatch = /\.(\d+)$/.exec(rest);
+  if (offsetMatch) {
+    offset = parseInt(offsetMatch[1], 10);
+    rest = rest.slice(0, -offsetMatch[0].length);
+  }
+
+  const steps: XPointerStep[] = [];
+  let textIndex: number | null = null;
+  for (const segment of rest.split('/')) {
+    if (!segment) continue;
+    const textMatch = TEXT_STEP_RE.exec(segment);
+    if (textMatch) {
+      textIndex = textMatch[1] ? parseInt(textMatch[1], 10) : 1;
+      continue;
+    }
+    if (textIndex != null) return null;
+    const stepMatch = STEP_RE.exec(segment);
+    if (!stepMatch) return null;
+    steps.push({ name: stepMatch[1], index: stepMatch[2] ? parseInt(stepMatch[2], 10) : 1 });
+  }
+
+  if (offset != null && textIndex == null) {
+    // crengine can emit element-level offsets (rare); treat as first text node.
+    textIndex = 1;
+  }
+
+  return { docFragmentIndex, steps, textIndex, offset };
+}
+
+/**
+ * Resolves the element path of a parsed xpointer against a chapter document.
+ * The first step (usually "body") is resolved among the document element's children,
+ * mirroring crengine's DocFragment > body nesting.
+ */
+export function resolveXPointerElement(root: CfiNode, steps: XPointerStep[]): CfiNode | null {
+  const documentElement = getDocumentElement(root);
+  if (!documentElement) return null;
+  let current: CfiNode = documentElement;
+
+  for (const step of steps) {
+    const children = (current.children ?? []).filter(
+      (child): child is CfiNode => isElementNode(child) && (child.name ?? '').toLowerCase() === step.name.toLowerCase(),
+    );
+    const next = children[step.index - 1];
+    if (!next) return null;
+    current = next;
+  }
+  return current;
+}
+
+function sameNameElementIndex(element: CfiNode): { index: number; count: number } {
+  const name = (element.name ?? '').toLowerCase();
+  const siblings = (element.parent?.children ?? []).filter(
+    (child): child is CfiNode => isElementNode(child) && (child.name ?? '').toLowerCase() === name,
+  );
+  return { index: siblings.indexOf(element) + 1, count: siblings.length };
+}
+
+/**
+ * Serializes the path from the chapter's document element down to the given element,
+ * crengine style. The document element itself (html) is not part of the path; the
+ * first emitted step is its child (body).
+ */
+export function buildXPointerPath(element: CfiNode, docFragmentIndex: number): string | null {
+  const documentElement = getDocumentElement(element);
+  if (!documentElement) return null;
+
+  const segments: string[] = [];
+  let current: CfiNode | null = element;
+  while (current && current !== documentElement) {
+    if (!isElementNode(current)) return null;
+    const { index, count } = sameNameElementIndex(current);
+    if (index === 0) return null;
+    const name = current.name ?? '';
+    segments.unshift(count > 1 ? `${name}[${index}]` : name);
+    current = current.parent ?? null;
+  }
+  if (current !== documentElement) return null;
+
+  return `/body/DocFragment[${docFragmentIndex}]/${segments.join('/')}`;
+}
+
+export function buildXPointer(
+  element: CfiNode,
+  docFragmentIndex: number,
+  textIndex: number | null,
+  textNodeCount: number,
+  offset: number | null,
+): string | null {
+  const path = buildXPointerPath(element, docFragmentIndex);
+  if (!path) return null;
+  if (textIndex == null) return path;
+  const textStep = textNodeCount > 1 ? `text()[${textIndex}]` : 'text()';
+  const suffix = offset != null ? `.${offset}` : '';
+  return `${path}/${textStep}${suffix}`;
+}
+
+/** Text-node children of an element, in document order (crengine text node candidates). */
+export function elementTextNodes(element: CfiNode): CfiNode[] {
+  return (element.children ?? []).filter((child) => isTextNode(child));
+}
diff --git a/server/src/modules/reader/epub/epub.module.test.ts b/server/src/modules/reader/epub/epub.module.test.ts
index 43c9ccd19..d2a4e760e 100644
--- a/server/src/modules/reader/epub/epub.module.test.ts
+++ b/server/src/modules/reader/epub/epub.module.test.ts
@@ -1,11 +1,9 @@
 import 'reflect-metadata';
 
 vi.mock('../../book/book.module', () => ({ BookModule: class BookModule {} }));
-vi.mock('../../kobo/kobo.module', () => ({ KoboModule: class KoboModule {} }));
 vi.mock('../../library/library.module', () => ({ LibraryModule: class LibraryModule {} }));
 
 import { BookModule } from '../../book/book.module';
-import { KoboModule } from '../../kobo/kobo.module';
 import { LibraryModule } from '../../library/library.module';
 import { EpubController } from './epub.controller';
 import { EpubModule } from './epub.module';
@@ -13,7 +11,7 @@ import { EpubService } from './epub.service';
 
 describe('EpubModule', () => {
   it('registers expected imports/controllers/providers', () => {
-    expect(Reflect.getMetadata('imports', EpubModule)).toEqual([BookModule, LibraryModule, KoboModule]);
+    expect(Reflect.getMetadata('imports', EpubModule)).toEqual([BookModule, LibraryModule]);
     expect(Reflect.getMetadata('controllers', EpubModule)).toEqual([EpubController]);
     expect(Reflect.getMetadata('providers', EpubModule)).toEqual([EpubService]);
   });
diff --git a/server/src/modules/reader/epub/epub.module.ts b/server/src/modules/reader/epub/epub.module.ts
index db300ecc5..f19058dc0 100644
--- a/server/src/modules/reader/epub/epub.module.ts
+++ b/server/src/modules/reader/epub/epub.module.ts
@@ -1,13 +1,12 @@
 import { Module } from '@nestjs/common';
 
 import { BookModule } from '../../book/book.module';
-import { KoboModule } from '../../kobo/kobo.module';
 import { LibraryModule } from '../../library/library.module';
 import { EpubController } from './epub.controller';
 import { EpubService } from './epub.service';
 
 @Module({
-  imports: [BookModule, LibraryModule, KoboModule],
+  imports: [BookModule, LibraryModule],
   controllers: [EpubController],
   providers: [EpubService],
 })
diff --git a/server/src/modules/reader/epub/epub.service.test.ts b/server/src/modules/reader/epub/epub.service.test.ts
index 7f4128567..2560c7ace 100644
--- a/server/src/modules/reader/epub/epub.service.test.ts
+++ b/server/src/modules/reader/epub/epub.service.test.ts
@@ -156,27 +156,14 @@ describe('EpubService', () => {
   const libraryService = {
     verifyUserAccess: vi.fn(),
   };
-  const koboSettingsService = {
-    getSettings: vi.fn(),
-  };
-  const kepubConversionService = {
-    getKepubPath: vi.fn(),
-  };
-
   let service: EpubService;
 
   beforeEach(() => {
     vi.resetAllMocks();
-    service = new EpubService(bookReadService as any, libraryService as any, koboSettingsService as any, kepubConversionService as any);
+    service = new EpubService(bookReadService as any, libraryService as any);
     bookReadService.findLibraryIdByBookId.mockResolvedValue(3);
     bookReadService.findPrimaryFilesByBookIds.mockResolvedValue([{ format: 'epub', absolutePath: '/books/book.epub', sizeBytes: null }]);
     libraryService.verifyUserAccess.mockResolvedValue(undefined);
-    koboSettingsService.getSettings.mockResolvedValue({
-      convertToKepub: true,
-      forceEnableHyphenation: false,
-      kepubConversionLimitMb: 100,
-      twoWayProgressSync: false,
-    });
     mockStat.mockResolvedValue({ mtimeMs: 100 } as Awaited<ReturnType<typeof stat>>);
   });
 
@@ -358,60 +345,12 @@ describe('EpubService', () => {
     expect(bookReadService.findPrimaryFilesByBookIds).not.toHaveBeenCalled();
   });
 
-  it('uses the converted kepub path for reader endpoints when two-way Kobo progress sync is enabled', async () => {
+  it('always serves the original EPUB regardless of Kobo settings', async () => {
     bookReadService.findFileById.mockResolvedValue({ bookId: 5, format: 'epub', absolutePath: '/books/alt.epub', fileHash: 'hash1', sizeBytes: 123 });
-    koboSettingsService.getSettings.mockResolvedValueOnce({
-      convertToKepub: true,
-      forceEnableHyphenation: true,
-      kepubConversionLimitMb: 100,
-      twoWayProgressSync: true,
-    });
-    kepubConversionService.getKepubPath.mockResolvedValue('/app-data/.kepub-cache/5/hash1-hyph.kepub.epub');
     mockOpenFile.mockResolvedValueOnce(makeEpubArchive() as any);
 
     await service.getBookInfo(5, 88, user);
 
-    expect(kepubConversionService.getKepubPath).toHaveBeenCalledWith({
-      sourcePath: '/books/alt.epub',
-      fileHash: 'hash1',
-      bookId: 5,
-      hyphenate: true,
-    });
-    expect(mockStat).toHaveBeenCalledWith('/app-data/.kepub-cache/5/hash1-hyph.kepub.epub');
-    expect(mockOpenFile).toHaveBeenCalledWith('/app-data/.kepub-cache/5/hash1-hyph.kepub.epub');
-  });
-
-  it('falls back to the original EPUB path when Kobo settings lookup fails', async () => {
-    bookReadService.findFileById.mockResolvedValue({ bookId: 5, format: 'epub', absolutePath: '/books/alt.epub', fileHash: 'hash1', sizeBytes: 123 });
-    koboSettingsService.getSettings.mockRejectedValueOnce(new Error('settings unavailable'));
-    mockOpenFile.mockResolvedValueOnce(makeEpubArchive() as any);
-
-    await service.getBookInfo(5, 88, user);
-
-    expect(kepubConversionService.getKepubPath).not.toHaveBeenCalled();
-    expect(mockStat).toHaveBeenCalledWith('/books/alt.epub');
-    expect(mockOpenFile).toHaveBeenCalledWith('/books/alt.epub');
-  });
-
-  it('falls back to the original EPUB path when KEPUB conversion fails', async () => {
-    bookReadService.findFileById.mockResolvedValue({ bookId: 5, format: 'epub', absolutePath: '/books/alt.epub', fileHash: 'hash1', sizeBytes: 123 });
-    koboSettingsService.getSettings.mockResolvedValueOnce({
-      convertToKepub: true,
-      forceEnableHyphenation: true,
-      kepubConversionLimitMb: 100,
-      twoWayProgressSync: true,
-    });
-    kepubConversionService.getKepubPath.mockRejectedValueOnce(new Error('conversion failed'));
-    mockOpenFile.mockResolvedValueOnce(makeEpubArchive() as any);
-
-    await service.getBookInfo(5, 88, user);
-
-    expect(kepubConversionService.getKepubPath).toHaveBeenCalledWith({
-      sourcePath: '/books/alt.epub',
-      fileHash: 'hash1',
-      bookId: 5,
-      hyphenate: true,
-    });
     expect(mockStat).toHaveBeenCalledWith('/books/alt.epub');
     expect(mockOpenFile).toHaveBeenCalledWith('/books/alt.epub');
   });
diff --git a/server/src/modules/reader/epub/epub.service.ts b/server/src/modules/reader/epub/epub.service.ts
index d246aab99..e0e41aad5 100644
--- a/server/src/modules/reader/epub/epub.service.ts
+++ b/server/src/modules/reader/epub/epub.service.ts
@@ -4,10 +4,7 @@ import * as unzipper from 'unzipper';
 import { XMLParser } from 'fast-xml-parser';
 
 import type { EpubBookInfo, EpubManifestItem, EpubSpineItem, EpubTocItem } from '@bookorbit/types';
-import { sanitizeLogValue } from '../../../common/utils/log-sanitize.utils';
 import { BookReadService } from '../../book/book-read.service';
-import { KepubConversionService } from '../../kobo/services/kepub-conversion.service';
-import { KoboSettingsService } from '../../kobo/services/kobo-settings.service';
 import { LibraryService } from '../../library/library.service';
 import type { RequestUser } from '../../../common/types/request-user';
 
@@ -287,8 +284,6 @@ export class EpubService {
   constructor(
     private readonly bookReadService: BookReadService,
     private readonly libraryService: LibraryService,
-    private readonly koboSettingsService: KoboSettingsService,
-    private readonly kepubConversionService: KepubConversionService,
   ) {}
 
   async getBookInfo(bookId: number, fileId: number | undefined, user: RequestUser): Promise<EpubBookInfo> {
@@ -321,6 +316,9 @@ export class EpubService {
     return { stream: entry.stream(), contentType, size: entry.uncompressedSize };
   }
 
+  // The web reader always renders the original EPUB: every stored CFI is epub-DOM.
+  // Precise Kobo positions are produced server-side by the kepub span codec, which
+  // replaced the earlier kepub-serving mechanism (BO-249).
   private async resolveEpubPath(bookId: number, fileId: number | undefined, user: RequestUser): Promise<string> {
     const libraryId = await this.bookReadService.findLibraryIdByBookId(bookId);
     if (libraryId === null) throw new NotFoundException(`Book ${bookId} not found`);
@@ -330,56 +328,12 @@ export class EpubService {
       const file = await this.bookReadService.findFileById(fileId);
       if (!file || file.bookId !== bookId) throw new NotFoundException(`File ${fileId} not found for book ${bookId}`);
       if (file.format !== 'epub') throw new NotFoundException(`File ${fileId} is not an EPUB file`);
-      return this.resolveReaderEpubPath(user.id, bookId, {
-        absolutePath: file.absolutePath,
-        fileHash: file.fileHash,
-        sizeBytes: file.sizeBytes,
-      });
+      return file.absolutePath;
     }
 
     const [file] = await this.bookReadService.findPrimaryFilesByBookIds([bookId]);
     if (!file || file.format !== 'epub') throw new NotFoundException(`No primary EPUB file for book ${bookId}`);
-    return this.resolveReaderEpubPath(user.id, bookId, {
-      absolutePath: file.absolutePath,
-      sizeBytes: file.sizeBytes,
-    });
-  }
-
-  private async resolveReaderEpubPath(
-    userId: number,
-    bookId: number,
-    file: { absolutePath: string; fileHash?: string | null; sizeBytes?: number | null },
-  ): Promise<string> {
-    const start = Date.now();
-    let settings: Awaited<ReturnType<KoboSettingsService['getSettings']>>;
-    try {
-      settings = await this.koboSettingsService.getSettings(userId);
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.logger.warn(
-        `[epub.reader_kepub] [fail] bookId=${bookId} userId=${userId} durationMs=${Date.now() - start} errorClass=${error.constructor.name} error="${sanitizeLogValue(error.message)}" - Kobo settings lookup failed, using original epub`,
-      );
-      return file.absolutePath;
-    }
-    if (!settings.twoWayProgressSync || !settings.convertToKepub) return file.absolutePath;
-
-    const limitBytes = settings.kepubConversionLimitMb * 1024 * 1024;
-    if (file.sizeBytes && file.sizeBytes > limitBytes) return file.absolutePath;
-
-    try {
-      return await this.kepubConversionService.getKepubPath({
-        sourcePath: file.absolutePath,
-        fileHash: file.fileHash,
-        bookId,
-        hyphenate: settings.forceEnableHyphenation,
-      });
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.logger.warn(
-        `[epub.reader_kepub] [fail] bookId=${bookId} userId=${userId} durationMs=${Date.now() - start} errorClass=${error.constructor.name} error="${sanitizeLogValue(error.message)}" - kepub conversion failed, using original epub`,
-      );
-      return file.absolutePath;
-    }
+    return file.absolutePath;
   }
 
   private async getCachedEntry(epubPath: string): Promise<CacheEntry> {
diff --git a/server/src/modules/reading-session/book-reading-session.controller.test.ts b/server/src/modules/reading-session/book-reading-session.controller.test.ts
index 45620afc8..f8d90b84e 100644
--- a/server/src/modules/reading-session/book-reading-session.controller.test.ts
+++ b/server/src/modules/reading-session/book-reading-session.controller.test.ts
@@ -16,6 +16,19 @@ describe('BookReadingSessionController', () => {
     expect(result).toBe(mockResult);
   });
 
+  it('delegates createSession to service.createManualSession', async () => {
+    const created = { id: 1, source: 'manual' };
+    const service = { createManualSession: vi.fn().mockResolvedValue(created) };
+    const controller = new BookReadingSessionController(service as never);
+    const user = { id: 7 } as never;
+    const dto = { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 };
+
+    const result = await controller.createSession(10, dto, user);
+
+    expect(service.createManualSession).toHaveBeenCalledWith(10, dto, user);
+    expect(result).toBe(created);
+  });
+
   it('delegates deleteSession to service.deleteSessionByBook', async () => {
     const service = { deleteSessionByBook: vi.fn().mockResolvedValue(undefined) };
     const controller = new BookReadingSessionController(service as never);
diff --git a/server/src/modules/reading-session/book-reading-session.controller.ts b/server/src/modules/reading-session/book-reading-session.controller.ts
index 35272859c..4349ce2e6 100644
--- a/server/src/modules/reading-session/book-reading-session.controller.ts
+++ b/server/src/modules/reading-session/book-reading-session.controller.ts
@@ -1,7 +1,8 @@
-import { Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Query } from '@nestjs/common';
+import { Body, Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Post, Query } from '@nestjs/common';
 
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
 import type { RequestUser } from '../../common/types/request-user';
+import { CreateManualReadingSessionDto } from './dto/create-manual-reading-session.dto';
 import { ListBookReadingSessionsDto } from './dto/list-book-reading-sessions.dto';
 import { ReadingSessionService } from './reading-session.service';
 
@@ -14,6 +15,11 @@ export class BookReadingSessionController {
     return this.service.listByBook(bookId, user, query);
   }
 
+  @Post(':bookId/sessions')
+  createSession(@Param('bookId', ParseIntPipe) bookId: number, @Body() dto: CreateManualReadingSessionDto, @CurrentUser() user: RequestUser) {
+    return this.service.createManualSession(bookId, dto, user);
+  }
+
   @Delete(':bookId/sessions/:sessionId')
   @HttpCode(204)
   async deleteSession(
diff --git a/server/src/modules/reading-session/dto/create-manual-reading-session.dto.test.ts b/server/src/modules/reading-session/dto/create-manual-reading-session.dto.test.ts
new file mode 100644
index 000000000..479278624
--- /dev/null
+++ b/server/src/modules/reading-session/dto/create-manual-reading-session.dto.test.ts
@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+
+import { CreateManualReadingSessionDto } from './create-manual-reading-session.dto';
+
+async function errorsFor(value: Record<string, unknown>) {
+  return validate(plainToInstance(CreateManualReadingSessionDto, value));
+}
+
+describe('CreateManualReadingSessionDto', () => {
+  it('accepts a minimal payload', async () => {
+    expect(await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 })).toEqual([]);
+  });
+
+  it('accepts optional endProgress and format', async () => {
+    expect(await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: 55.5, format: 'EPUB' })).toEqual([]);
+  });
+
+  it('rejects a missing or malformed startedAt', async () => {
+    expect((await errorsFor({ durationMinutes: 30 })).length).toBeGreaterThan(0);
+    expect((await errorsFor({ startedAt: 'not-a-date', durationMinutes: 30 })).length).toBeGreaterThan(0);
+  });
+
+  it('rejects out-of-range durations', async () => {
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 0 })).length).toBeGreaterThan(0);
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 1441 })).length).toBeGreaterThan(0);
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 12.5 })).length).toBeGreaterThan(0);
+  });
+
+  it('rejects out-of-range endProgress', async () => {
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: 101 })).length).toBeGreaterThan(0);
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: -1 })).length).toBeGreaterThan(0);
+  });
+
+  it('rejects an over-long format', async () => {
+    expect((await errorsFor({ startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, format: 'x'.repeat(13) })).length).toBeGreaterThan(0);
+  });
+});
diff --git a/server/src/modules/reading-session/dto/create-manual-reading-session.dto.ts b/server/src/modules/reading-session/dto/create-manual-reading-session.dto.ts
new file mode 100644
index 000000000..68409e2fe
--- /dev/null
+++ b/server/src/modules/reading-session/dto/create-manual-reading-session.dto.ts
@@ -0,0 +1,23 @@
+import { IsDateString, IsInt, IsNumber, IsOptional, IsString, Max, MaxLength, Min } from 'class-validator';
+
+export class CreateManualReadingSessionDto {
+  @IsDateString()
+  startedAt!: string;
+
+  @IsInt()
+  @Min(1)
+  @Max(1440)
+  durationMinutes!: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(100)
+  endProgress?: number | null;
+
+  // Only meaningful when the book has multiple file formats.
+  @IsOptional()
+  @IsString()
+  @MaxLength(12)
+  format?: string;
+}
diff --git a/server/src/modules/reading-session/reading-session.repository.test.ts b/server/src/modules/reading-session/reading-session.repository.test.ts
index 54bb150d9..52e7da19d 100644
--- a/server/src/modules/reading-session/reading-session.repository.test.ts
+++ b/server/src/modules/reading-session/reading-session.repository.test.ts
@@ -3,11 +3,11 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { readingSessions, userReadingDailyStats } from '../../db/schema';
 import { ReadingSessionRepository } from './reading-session.repository';
 
-function makeDbHarness(options?: { fileLibraryId?: number | null; insertedIds?: Array<{ id: number }> }) {
-  const fileLibraryId = options?.fileLibraryId === undefined ? 11 : options.fileLibraryId;
+function makeDbHarness(options?: { fileRow?: { bookId: number; libraryId: number } | null; insertedIds?: Array<{ id: number }> }) {
+  const fileRow = options?.fileRow === undefined ? { bookId: 7, libraryId: 11 } : options.fileRow;
   const insertedIds = options?.insertedIds ?? [{ id: 1 }];
 
-  const limit = vi.fn().mockResolvedValue(fileLibraryId == null ? [] : [{ libraryId: fileLibraryId }]);
+  const limit = vi.fn().mockResolvedValue(fileRow == null ? [] : [fileRow]);
   const where = vi.fn().mockReturnValue({ limit });
   const innerJoin = vi.fn().mockReturnValue({ where });
   const from = vi.fn().mockReturnValue({ innerJoin });
@@ -21,6 +21,7 @@ function makeDbHarness(options?: { fileLibraryId?: number | null; insertedIds?:
   const dailyValues = vi.fn().mockReturnValue({ onConflictDoUpdate: dailyConflictUpdate });
 
   const tx = {
+    execute: vi.fn().mockResolvedValue(undefined),
     insert: vi.fn((table: unknown) => {
       if (table === readingSessions) return { values: sessionValues };
       if (table === userReadingDailyStats) return { values: dailyValues };
@@ -42,6 +43,7 @@ function makeDbHarness(options?: { fileLibraryId?: number | null; insertedIds?:
     sessionReturning,
     dailyValues,
     dailyConflictUpdate,
+    tx,
   };
 }
 
@@ -61,7 +63,7 @@ describe('ReadingSessionRepository', () => {
   });
 
   it('skips when no book file row is found', async () => {
-    const { repo, transaction } = makeDbHarness({ fileLibraryId: null });
+    const { repo, transaction } = makeDbHarness({ fileRow: null });
 
     const result = await repo.saveSession(
       1,
@@ -96,8 +98,11 @@ describe('ReadingSessionRepository', () => {
     expect(dailyValues).not.toHaveBeenCalled();
   });
 
-  it('persists session and upserts daily stats when insert succeeds', async () => {
-    const { repo, sessionValues, sessionConflict, dailyValues, dailyConflictUpdate } = makeDbHarness({ fileLibraryId: 3, insertedIds: [{ id: 99 }] });
+  it('persists session with bookId and explicit source, then upserts daily stats', async () => {
+    const { repo, sessionValues, sessionConflict, dailyValues, dailyConflictUpdate, tx } = makeDbHarness({
+      fileRow: { bookId: 9, libraryId: 3 },
+      insertedIds: [{ id: 99 }],
+    });
 
     const result = await repo.saveSession(
       2,
@@ -116,6 +121,7 @@ describe('ReadingSessionRepository', () => {
       expect.objectContaining({
         userId: 2,
         bookFileId: 4,
+        bookId: 9,
         sessionId: 'new-session',
         durationSeconds: 60,
         progressDelta: null,
@@ -124,19 +130,160 @@ describe('ReadingSessionRepository', () => {
       }),
     );
     expect(sessionConflict).toHaveBeenCalledWith({ target: [readingSessions.userId, readingSessions.sessionId] });
-    expect(dailyValues).toHaveBeenCalledWith(
+    expect(tx.execute).toHaveBeenCalledOnce();
+    expect(dailyValues).toHaveBeenCalledWith([
       expect.objectContaining({
         userId: 2,
         libraryId: 3,
+        day: '2026-04-15',
         readingSeconds: 60,
         progressDelta: 0,
         sessionsCount: 1,
         updatedAt: expect.any(Date),
       }),
-    );
-    expect(dailyValues.mock.calls[0]?.[0]).toHaveProperty('day');
+    ]);
     expect(dailyConflictUpdate).toHaveBeenCalledOnce();
   });
+
+  it('persists the provided source (e.g. kobo) instead of the web default', async () => {
+    const { repo, sessionValues } = makeDbHarness({ fileRow: { bookId: 9, libraryId: 3 }, insertedIds: [{ id: 100 }] });
+
+    const result = await repo.saveSession(
+      2,
+      4,
+      'kobo-session',
+      new Date('2026-04-15T10:00:00.000Z'),
+      new Date('2026-04-15T10:01:00.000Z'),
+      60,
+      null,
+      null,
+      'kobo',
+    );
+
+    expect(result).toEqual({ kind: 'saved' });
+    expect(sessionValues).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'kobo-session', source: 'kobo' }));
+  });
+});
+
+describe('ReadingSessionRepository - insertManualSession', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function makeManualHarness() {
+    const sessionReturning = vi.fn().mockResolvedValue([{ id: 321 }]);
+    const sessionValues = vi.fn().mockReturnValue({ returning: sessionReturning });
+
+    const dailyConflictUpdate = vi.fn().mockResolvedValue(undefined);
+    const dailyValues = vi.fn().mockReturnValue({ onConflictDoUpdate: dailyConflictUpdate });
+
+    const tx = {
+      execute: vi.fn().mockResolvedValue(undefined),
+      insert: vi.fn((table: unknown) => {
+        if (table === readingSessions) return { values: sessionValues };
+        if (table === userReadingDailyStats) return { values: dailyValues };
+        throw new Error('Unexpected table in insert');
+      }),
+    };
+
+    const transaction = vi.fn(async (callback: (trx: typeof tx) => Promise<unknown>) => callback(tx));
+    const db = { transaction };
+    const repo = new ReadingSessionRepository(db as never);
+
+    return { repo, sessionValues, dailyValues, dailyConflictUpdate, tx };
+  }
+
+  it('inserts with manual source and upserts daily stats in one transaction', async () => {
+    const { repo, sessionValues, dailyValues, dailyConflictUpdate, tx } = makeManualHarness();
+
+    const result = await repo.insertManualSession({
+      userId: 5,
+      bookId: 10,
+      libraryId: 3,
+      bookFileId: null,
+      sessionId: 'manual:abc',
+      startedAt: new Date('2026-04-15T10:00:00.000Z'),
+      endedAt: new Date('2026-04-15T10:30:00.000Z'),
+      durationSeconds: 1800,
+      progressDelta: 12.5,
+      endProgress: 60,
+      timeZone: 'UTC',
+    });
+
+    expect(result).toEqual({ id: 321 });
+    expect(sessionValues).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 5,
+        bookId: 10,
+        bookFileId: null,
+        sessionId: 'manual:abc',
+        source: 'manual',
+        durationSeconds: 1800,
+        progressDelta: 12.5,
+        endProgress: 60,
+      }),
+    );
+    expect(dailyValues).toHaveBeenCalledWith([
+      expect.objectContaining({ userId: 5, libraryId: 3, day: '2026-04-15', readingSeconds: 1800, progressDelta: 12.5, sessionsCount: 1 }),
+    ]);
+    expect(tx.execute).toHaveBeenCalledOnce();
+    expect(dailyConflictUpdate).toHaveBeenCalledOnce();
+  });
+});
+
+describe('ReadingSessionRepository - findLatestEndProgressBefore', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function makeLookupHarness(rows: Array<{ endProgress: number | null }>) {
+    const limit = vi.fn().mockResolvedValue(rows);
+    const orderBy = vi.fn().mockReturnValue({ limit });
+    const where = vi.fn().mockReturnValue({ orderBy });
+    const from = vi.fn().mockReturnValue({ where });
+    const select = vi.fn().mockReturnValue({ from });
+    const db = { select };
+    return new ReadingSessionRepository(db as never);
+  }
+
+  it('returns the latest end progress when present', async () => {
+    const repo = makeLookupHarness([{ endProgress: 42.5 }]);
+    await expect(repo.findLatestEndProgressBefore(1, 2, new Date())).resolves.toBe(42.5);
+  });
+
+  it('returns null when no prior session exists', async () => {
+    const repo = makeLookupHarness([]);
+    await expect(repo.findLatestEndProgressBefore(1, 2, new Date())).resolves.toBeNull();
+  });
+});
+
+describe('ReadingSessionRepository - findBookContext', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns libraryId and files for an existing book', async () => {
+    const bookLimit = vi.fn().mockResolvedValue([{ libraryId: 3 }]);
+    const bookWhere = vi.fn().mockReturnValue({ limit: bookLimit });
+    const filesWhere = vi.fn().mockResolvedValue([{ id: 42, format: 'epub' }]);
+    const from = vi.fn().mockReturnValueOnce({ where: bookWhere }).mockReturnValueOnce({ where: filesWhere });
+    const select = vi.fn().mockReturnValue({ from });
+    const repo = new ReadingSessionRepository({ select } as never);
+
+    const result = await repo.findBookContext(10);
+
+    expect(result).toEqual({ libraryId: 3, files: [{ id: 42, format: 'epub' }] });
+  });
+
+  it('returns null when the book does not exist', async () => {
+    const bookLimit = vi.fn().mockResolvedValue([]);
+    const bookWhere = vi.fn().mockReturnValue({ limit: bookLimit });
+    const from = vi.fn().mockReturnValue({ where: bookWhere });
+    const select = vi.fn().mockReturnValue({ from });
+    const repo = new ReadingSessionRepository({ select } as never);
+
+    await expect(repo.findBookContext(10)).resolves.toBeNull();
+  });
 });
 
 describe('ReadingSessionRepository - listByBook', () => {
@@ -147,7 +294,7 @@ describe('ReadingSessionRepository - listByBook', () => {
   function makeQueryChain(result: unknown) {
     const self: Record<string, unknown> = {};
     const terminal = Promise.resolve(result);
-    for (const m of ['from', 'innerJoin', 'where', 'orderBy', 'limit', 'offset', 'groupBy']) {
+    for (const m of ['from', 'innerJoin', 'leftJoin', 'where', 'orderBy', 'limit', 'offset', 'groupBy']) {
       self[m] = vi.fn().mockReturnValue(self);
     }
     self['then'] = (onFulfilled: (v: unknown) => unknown, onRejected: (e: unknown) => unknown) => terminal.then(onFulfilled, onRejected);
@@ -155,23 +302,37 @@ describe('ReadingSessionRepository - listByBook', () => {
     return self;
   }
 
+  function makeListDb(results: { rows?: unknown[]; count?: unknown[]; stats?: unknown[]; summary?: unknown[]; bySource?: unknown[] }) {
+    const select = vi
+      .fn()
+      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(results.rows ?? [])) })
+      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(results.count ?? [])) })
+      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(results.stats ?? [])) })
+      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(results.summary ?? [])) })
+      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(results.bySource ?? [])) });
+    return { db: { select }, select };
+  }
+
   it('returns items, total, and stats with correct structure', async () => {
     const now = new Date('2026-04-15T10:00:00.000Z');
     const later = new Date('2026-04-15T10:30:00.000Z');
 
-    const rowData = [{ id: 1, startedAt: now, endedAt: later, durationSeconds: 1800, progressDelta: 5, endProgress: 50, format: 'epub' }];
-    const countData = [{ total: 1 }];
-    const statsData = [{ totalSessions: 1, totalSeconds: 1800, avgDurationSeconds: 1800, firstSessionAt: now, lastSessionAt: now }];
-    const dailyData = [{ day: '2026-04-15', totalMinutes: 30 }];
-
-    const select = vi
-      .fn()
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(rowData)) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(countData)) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(statsData)) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(dailyData)) });
-
-    const db = { select };
+    const { db } = makeListDb({
+      rows: [{ id: 1, startedAt: now, endedAt: later, durationSeconds: 1800, progressDelta: 5, endProgress: 50, format: 'epub', source: 'web' }],
+      count: [{ total: 1 }],
+      stats: [
+        {
+          totalSessions: 1,
+          totalSeconds: 1800,
+          avgDurationSeconds: 1800,
+          firstSessionAt: now,
+          lastSessionAt: now,
+          paceProgressDelta: 5,
+          paceDurationSeconds: 1800,
+        },
+      ],
+      summary: [{ startedAt: now, endedAt: later, durationSeconds: 1800, progressDelta: 5, endProgress: 50 }],
+    });
     const repo = new ReadingSessionRepository(db as never);
 
     const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
@@ -179,30 +340,44 @@ describe('ReadingSessionRepository - listByBook', () => {
     expect(result.total).toBe(1);
     expect(result.stats.totalSessions).toBe(1);
     expect(result.stats.dailySummary).toEqual([{ day: '2026-04-15', totalMinutes: 30 }]);
+    expect(result.stats.paceProgressDelta).toBe(5);
+    expect(result.stats.paceDurationSeconds).toBe(1800);
+    expect(result.stats.progressSummary).toEqual([{ day: '2026-04-15', endProgress: 50 }]);
     expect(result.items).toHaveLength(1);
     expect(result.items[0]?.startedAt).toBe(now.toISOString());
+    expect(result.items[0]?.source).toBe('web');
   });
 
-  it('fires all four queries when called', async () => {
-    const select = vi.fn().mockReturnValue({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+  it('fires five select queries', async () => {
+    const { db, select } = makeListDb({});
     const repo = new ReadingSessionRepository(db as never);
 
     await repo.listByBook(1, 2, 2, 25, 'startedAt', 'desc');
 
-    expect(select).toHaveBeenCalledTimes(4);
+    expect(select).toHaveBeenCalledTimes(5);
+  });
+
+  it('splits per-book daily summaries across local midnight', async () => {
+    const startedAt = new Date('2026-04-16T03:00:00.000Z');
+    const endedAt = new Date('2026-04-16T04:30:00.000Z');
+    const { db } = makeListDb({
+      count: [{ total: 1 }],
+      stats: [{ totalSessions: 1, totalSeconds: 5400, avgDurationSeconds: 5400, firstSessionAt: startedAt, lastSessionAt: startedAt }],
+      summary: [{ startedAt, endedAt, durationSeconds: 5400, progressDelta: 9, endProgress: 12 }],
+    });
+    const repo = new ReadingSessionRepository(db as never);
+
+    const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc', undefined, undefined, undefined, 'America/New_York');
+
+    expect(result.stats.dailySummary).toEqual([
+      { day: '2026-04-15', totalMinutes: 60 },
+      { day: '2026-04-16', totalMinutes: 30 },
+    ]);
+    expect(result.stats.progressSummary).toEqual([{ day: '2026-04-16', endProgress: 12 }]);
   });
 
   it('returns empty items and zero stats when no data', async () => {
-    const select = vi
-      .fn()
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+    const { db } = makeListDb({});
     const repo = new ReadingSessionRepository(db as never);
 
     const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
@@ -211,17 +386,13 @@ describe('ReadingSessionRepository - listByBook', () => {
     expect(result.total).toBe(0);
     expect(result.stats.totalSessions).toBe(0);
     expect(result.stats.dailySummary).toEqual([]);
+    expect(result.stats.paceProgressDelta).toBe(0);
+    expect(result.stats.paceDurationSeconds).toBe(0);
+    expect(result.stats.progressSummary).toEqual([]);
   });
 
   it('handles null statsRow gracefully', async () => {
-    const select = vi
-      .fn()
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+    const { db } = makeListDb({});
     const repo = new ReadingSessionRepository(db as never);
 
     const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
@@ -233,16 +404,10 @@ describe('ReadingSessionRepository - listByBook', () => {
 
   it('converts Date stats fields to ISO strings', async () => {
     const now = new Date('2026-04-15T10:00:00.000Z');
-    const statsData = [{ totalSessions: 1, totalSeconds: 60, avgDurationSeconds: 60, firstSessionAt: now, lastSessionAt: now }];
-
-    const select = vi
-      .fn()
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([{ total: 1 }])) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(statsData)) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+    const { db } = makeListDb({
+      count: [{ total: 1 }],
+      stats: [{ totalSessions: 1, totalSeconds: 60, avgDurationSeconds: 60, firstSessionAt: now, lastSessionAt: now }],
+    });
     const repo = new ReadingSessionRepository(db as never);
 
     const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
@@ -251,57 +416,65 @@ describe('ReadingSessionRepository - listByBook', () => {
     expect(result.stats.lastSessionAt).toBe(now.toISOString());
   });
 
-  it('uses desc order when sortDir is desc', async () => {
-    const select = vi.fn().mockReturnValue({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
-    const repo = new ReadingSessionRepository(db as never);
-
-    await expect(repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc')).resolves.toBeDefined();
-  });
-
-  it('uses asc order when sortDir is asc', async () => {
-    const select = vi.fn().mockReturnValue({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
-    const repo = new ReadingSessionRepository(db as never);
-
-    await expect(repo.listByBook(1, 2, 1, 25, 'startedAt', 'asc')).resolves.toBeDefined();
-  });
-
-  it('maps null format to null in items', async () => {
+  it('maps null format and null source to null in items', async () => {
     const now = new Date('2026-04-15T10:00:00.000Z');
-    const rowData = [{ id: 1, startedAt: now, endedAt: now, durationSeconds: 60, progressDelta: null, endProgress: null, format: null }];
-
-    const select = vi
-      .fn()
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain(rowData)) })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([{ total: 1 }])) })
-      .mockReturnValueOnce({
-        from: vi
-          .fn()
-          .mockReturnValue(
-            makeQueryChain([{ totalSessions: 1, totalSeconds: 60, avgDurationSeconds: 60, firstSessionAt: null, lastSessionAt: null }]),
-          ),
-      })
-      .mockReturnValueOnce({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+    const { db } = makeListDb({
+      rows: [{ id: 1, startedAt: now, endedAt: now, durationSeconds: 60, progressDelta: null, endProgress: null, format: null, source: null }],
+      count: [{ total: 1 }],
+      stats: [{ totalSessions: 1, totalSeconds: 60, avgDurationSeconds: 60, firstSessionAt: null, lastSessionAt: null }],
+    });
     const repo = new ReadingSessionRepository(db as never);
 
     const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
 
     expect(result.items[0]?.format).toBeNull();
+    expect(result.items[0]?.source).toBeNull();
   });
 
   it('applies dateFrom and dateTo when provided', async () => {
-    const select = vi.fn().mockReturnValue({ from: vi.fn().mockReturnValue(makeQueryChain([])) });
-
-    const db = { select };
+    const { db } = makeListDb({});
     const repo = new ReadingSessionRepository(db as never);
 
     await expect(repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc', '2026-01-01', '2026-12-31')).resolves.toBeDefined();
   });
+
+  it('supports asc sort direction', async () => {
+    const { db } = makeListDb({});
+    const repo = new ReadingSessionRepository(db as never);
+
+    await expect(repo.listByBook(1, 2, 1, 25, 'startedAt', 'asc')).resolves.toBeDefined();
+  });
+
+  it('folds sessions into the 3 display buckets, ordered and excluding empty buckets', async () => {
+    const { db } = makeListDb({
+      count: [{ total: 5 }],
+      stats: [{ totalSessions: 5, totalSeconds: 380, avgDurationSeconds: 76, firstSessionAt: null, lastSessionAt: null }],
+      bySource: [
+        { source: 'web', totalSeconds: 100, totalSessions: 1 },
+        { source: 'manual', totalSeconds: 50, totalSessions: 1 },
+        { source: null, totalSeconds: 30, totalSessions: 1 },
+        { source: 'kobo', totalSeconds: 200, totalSessions: 2 },
+      ],
+    });
+    const repo = new ReadingSessionRepository(db as never);
+
+    const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
+
+    // web + manual + null collapse into bookorbit; koreader has no rows and is omitted.
+    expect(result.stats.bySource).toEqual([
+      { bucket: 'bookorbit', totalSeconds: 180, totalSessions: 3 },
+      { bucket: 'kobo', totalSeconds: 200, totalSessions: 2 },
+    ]);
+  });
+
+  it('returns an empty bySource when there are no sessions', async () => {
+    const { db } = makeListDb({});
+    const repo = new ReadingSessionRepository(db as never);
+
+    const result = await repo.listByBook(1, 2, 1, 25, 'startedAt', 'desc');
+
+    expect(result.stats.bySource).toEqual([]);
+  });
 });
 
 describe('ReadingSessionRepository - deleteSessionByBook', () => {
@@ -309,89 +482,106 @@ describe('ReadingSessionRepository - deleteSessionByBook', () => {
     vi.clearAllMocks();
   });
 
-  it('returns { found: false } when session not found', async () => {
-    const limit = vi.fn().mockResolvedValue([]);
-    const where = vi.fn().mockReturnValue({ limit });
-    const innerJoin2 = vi.fn().mockReturnValue({ where });
-    const innerJoin1 = vi.fn().mockReturnValue({ innerJoin: innerJoin2 });
-    const from = vi.fn().mockReturnValue({ innerJoin: innerJoin1 });
-    const select = vi.fn().mockReturnValue({ from });
+  function makeDeleteHarness(
+    sessionRow: { id: number; startedAt: Date; endedAt: Date; durationSeconds: number; progressDelta: number | null; libraryId: number } | null,
+    recomputeRows: Array<{ startedAt: Date; endedAt: Date; durationSeconds: number; progressDelta: number | null }> = [],
+  ) {
+    const limit = vi.fn().mockResolvedValue(sessionRow ? [sessionRow] : []);
+    const lookupWhere = vi.fn().mockReturnValue({ limit });
+    const lookupInnerJoin = vi.fn().mockReturnValue({ where: lookupWhere });
+    const lookupFrom = vi.fn().mockReturnValue({ innerJoin: lookupInnerJoin });
 
-    const tx = { select };
+    const recomputeWhere = vi.fn().mockResolvedValue(recomputeRows);
+    const recomputeInnerJoin = vi.fn().mockReturnValue({ where: recomputeWhere });
+    const recomputeFrom = vi.fn().mockReturnValue({ innerJoin: recomputeInnerJoin });
+    const select = vi.fn().mockReturnValueOnce({ from: lookupFrom }).mockReturnValue({ from: recomputeFrom });
+
+    const deleteWhere = vi.fn().mockResolvedValue(undefined);
+    const deleteFn = vi.fn().mockReturnValue({ where: deleteWhere });
+    const dailyConflictUpdate = vi.fn().mockResolvedValue(undefined);
+    const dailyValues = vi.fn().mockReturnValue({ onConflictDoUpdate: dailyConflictUpdate });
+    const insert = vi.fn((table: unknown) => {
+      if (table === userReadingDailyStats) return { values: dailyValues };
+      throw new Error('Unexpected table in insert');
+    });
+
+    const tx = { execute: vi.fn().mockResolvedValue(undefined), select, delete: deleteFn, insert };
     const transaction = vi.fn(async (cb: (trx: typeof tx) => Promise<unknown>) => cb(tx));
     const db = { transaction };
     const repo = new ReadingSessionRepository(db as never);
 
+    return { repo, innerJoin: lookupInnerJoin, deleteFn, dailyValues, transaction, tx };
+  }
+
+  it('returns { found: false } when session not found', async () => {
+    const { repo } = makeDeleteHarness(null);
+
     const result = await repo.deleteSessionByBook(1, 2, 99);
 
     expect(result).toEqual({ found: false });
   });
 
+  it('looks up the session with a single books join', async () => {
+    const { repo, innerJoin } = makeDeleteHarness(null);
+
+    await repo.deleteSessionByBook(1, 2, 99);
+
+    expect(innerJoin).toHaveBeenCalledOnce();
+  });
+
   it('returns { found: true } and deletes when session found', async () => {
-    const sessionRow = { id: 5, startedAt: new Date('2026-04-15T10:00:00.000Z'), libraryId: 3 };
-    const limit = vi.fn().mockResolvedValue([sessionRow]);
-    const where = vi.fn().mockReturnValue({ limit });
-    const innerJoin2 = vi.fn().mockReturnValue({ where });
-    const innerJoin1 = vi.fn().mockReturnValue({ innerJoin: innerJoin2 });
-    const from = vi.fn().mockReturnValue({ innerJoin: innerJoin1 });
-    const select = vi.fn().mockReturnValue({ from });
-
-    const deleteWhere = vi.fn().mockResolvedValue(undefined);
-    const deleteFn = vi.fn().mockReturnValue({ where: deleteWhere });
-
-    const execute = vi.fn().mockResolvedValue(undefined);
-
-    const tx = { select, delete: deleteFn, execute };
-    const transaction = vi.fn(async (cb: (trx: typeof tx) => Promise<unknown>) => cb(tx));
-    const db = { transaction };
-    const repo = new ReadingSessionRepository(db as never);
+    const { repo, deleteFn, tx } = makeDeleteHarness({
+      id: 5,
+      startedAt: new Date('2026-04-15T10:00:00.000Z'),
+      endedAt: new Date('2026-04-15T10:30:00.000Z'),
+      durationSeconds: 1800,
+      progressDelta: null,
+      libraryId: 3,
+    });
 
     const result = await repo.deleteSessionByBook(1, 2, 5);
 
     expect(result).toEqual({ found: true });
     expect(deleteFn).toHaveBeenCalledWith(readingSessions);
+    expect(tx.execute).toHaveBeenCalledOnce();
   });
 
-  it('calls execute to re-aggregate daily stats after deletion', async () => {
-    const sessionRow = { id: 5, startedAt: new Date('2026-04-15T10:00:00.000Z'), libraryId: 3 };
-    const limit = vi.fn().mockResolvedValue([sessionRow]);
-    const where = vi.fn().mockReturnValue({ limit });
-    const innerJoin2 = vi.fn().mockReturnValue({ where });
-    const innerJoin1 = vi.fn().mockReturnValue({ innerJoin: innerJoin2 });
-    const from = vi.fn().mockReturnValue({ innerJoin: innerJoin1 });
-    const select = vi.fn().mockReturnValue({ from });
-
-    const deleteWhere = vi.fn().mockResolvedValue(undefined);
-    const deleteFn = vi.fn().mockReturnValue({ where: deleteWhere });
-    const execute = vi.fn().mockResolvedValue(undefined);
-
-    const tx = { select, delete: deleteFn, execute };
-    const transaction = vi.fn(async (cb: (trx: typeof tx) => Promise<unknown>) => cb(tx));
-    const db = { transaction };
-    const repo = new ReadingSessionRepository(db as never);
+  it('re-inserts re-aggregated daily stats after deletion when other sessions remain', async () => {
+    const { repo, dailyValues } = makeDeleteHarness(
+      {
+        id: 5,
+        startedAt: new Date('2026-04-15T10:00:00.000Z'),
+        endedAt: new Date('2026-04-15T10:30:00.000Z'),
+        durationSeconds: 1800,
+        progressDelta: null,
+        libraryId: 3,
+      },
+      [
+        {
+          startedAt: new Date('2026-04-15T11:00:00.000Z'),
+          endedAt: new Date('2026-04-15T11:20:00.000Z'),
+          durationSeconds: 1200,
+          progressDelta: 2,
+        },
+      ],
+    );
 
     await repo.deleteSessionByBook(1, 2, 5);
 
-    expect(execute).toHaveBeenCalledOnce();
+    expect(dailyValues).toHaveBeenCalledWith([
+      expect.objectContaining({ day: '2026-04-15', readingSeconds: 1200, progressDelta: 2, sessionsCount: 1 }),
+    ]);
   });
 
   it('deletes the userReadingDailyStats row for the session day', async () => {
-    const sessionRow = { id: 5, startedAt: new Date('2026-04-15T10:00:00.000Z'), libraryId: 3 };
-    const limit = vi.fn().mockResolvedValue([sessionRow]);
-    const where = vi.fn().mockReturnValue({ limit });
-    const innerJoin2 = vi.fn().mockReturnValue({ where });
-    const innerJoin1 = vi.fn().mockReturnValue({ innerJoin: innerJoin2 });
-    const from = vi.fn().mockReturnValue({ innerJoin: innerJoin1 });
-    const select = vi.fn().mockReturnValue({ from });
-
-    const deleteWhere = vi.fn().mockResolvedValue(undefined);
-    const deleteFn = vi.fn().mockReturnValue({ where: deleteWhere });
-    const execute = vi.fn().mockResolvedValue(undefined);
-
-    const tx = { select, delete: deleteFn, execute };
-    const transaction = vi.fn(async (cb: (trx: typeof tx) => Promise<unknown>) => cb(tx));
-    const db = { transaction };
-    const repo = new ReadingSessionRepository(db as never);
+    const { repo, deleteFn } = makeDeleteHarness({
+      id: 5,
+      startedAt: new Date('2026-04-15T10:00:00.000Z'),
+      endedAt: new Date('2026-04-15T10:30:00.000Z'),
+      durationSeconds: 1800,
+      progressDelta: null,
+      libraryId: 3,
+    });
 
     await repo.deleteSessionByBook(1, 2, 5);
 
@@ -400,17 +590,7 @@ describe('ReadingSessionRepository - deleteSessionByBook', () => {
   });
 
   it('uses a transaction for the entire delete', async () => {
-    const limit = vi.fn().mockResolvedValue([]);
-    const where = vi.fn().mockReturnValue({ limit });
-    const innerJoin2 = vi.fn().mockReturnValue({ where });
-    const innerJoin1 = vi.fn().mockReturnValue({ innerJoin: innerJoin2 });
-    const from = vi.fn().mockReturnValue({ innerJoin: innerJoin1 });
-    const select = vi.fn().mockReturnValue({ from });
-
-    const tx = { select };
-    const transaction = vi.fn(async (cb: (trx: typeof tx) => Promise<unknown>) => cb(tx));
-    const db = { transaction };
-    const repo = new ReadingSessionRepository(db as never);
+    const { repo, transaction } = makeDeleteHarness(null);
 
     await repo.deleteSessionByBook(1, 2, 99);
 
diff --git a/server/src/modules/reading-session/reading-session.repository.ts b/server/src/modules/reading-session/reading-session.repository.ts
index e91b54d58..71fb266c1 100644
--- a/server/src/modules/reading-session/reading-session.repository.ts
+++ b/server/src/modules/reading-session/reading-session.repository.ts
@@ -1,14 +1,29 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { and, asc, count, desc, eq, gte, lte, max, min, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, lt, lte, max, min, sql } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
-import type { BookReadingSession, BookReadingSessionListResponse, BookReadingSessionStats } from '@bookorbit/types';
+import type {
+  BookReadingSession,
+  BookReadingSessionListResponse,
+  BookReadingSessionStats,
+  BookReadingSourceSlice,
+  ReadingSessionSource,
+} from '@bookorbit/types';
+import { READING_SESSION_SOURCE_BUCKETS, emptySourceBucketRecord, toReadingSessionSourceBucket } from '@bookorbit/types';
+import {
+  aggregateReadingSessionDailyStats,
+  getDayRangeForDateKeys,
+  getReadingSessionDayKeys,
+  splitReadingSessionByDay,
+  type ReadingDailyStatsSegment,
+} from '../../common/utils/reading-daily-stats.utils';
+import { toDateKeyInTimeZone } from '../../common/utils/timezone.utils';
 import { DB } from '../../db';
 import * as schema from '../../db/schema';
 import { bookFiles, books, readingSessions, userReadingDailyStats } from '../../db/schema';
-import type { ReadingSessionSource } from '../../db/schema/reader';
 
 type Db = NodePgDatabase<typeof schema>;
+type Tx = Parameters<Parameters<Db['transaction']>[0]>[0];
 
 const MIN_READING_SESSION_SECONDS = 10;
 
@@ -19,6 +34,20 @@ export type SaveReadingSessionResult =
       reason: 'duration_below_minimum' | 'book_file_not_found' | 'duplicate_session_id';
     };
 
+export interface InsertManualSessionParams {
+  userId: number;
+  bookId: number;
+  libraryId: number;
+  bookFileId: number | null;
+  sessionId: string;
+  startedAt: Date;
+  endedAt: Date;
+  durationSeconds: number;
+  progressDelta: number | null;
+  endProgress: number | null;
+  timeZone: string;
+}
+
 @Injectable()
 export class ReadingSessionRepository {
   constructor(@Inject(DB) private readonly db: Db) {}
@@ -32,14 +61,15 @@ export class ReadingSessionRepository {
     durationSeconds: number,
     progressDelta: number | null,
     endProgress: number | null,
-    source: ReadingSessionSource,
+    source: ReadingSessionSource = 'web',
+    timeZone = 'UTC',
   ): Promise<SaveReadingSessionResult> {
     if (durationSeconds < MIN_READING_SESSION_SECONDS) {
       return { kind: 'skipped', reason: 'duration_below_minimum' };
     }
 
     const [fileRow] = await this.db
-      .select({ libraryId: books.libraryId })
+      .select({ bookId: books.id, libraryId: books.libraryId })
       .from(bookFiles)
       .innerJoin(books, eq(books.id, bookFiles.bookId))
       .where(eq(bookFiles.id, bookFileId))
@@ -49,12 +79,12 @@ export class ReadingSessionRepository {
       return { kind: 'skipped', reason: 'book_file_not_found' };
     }
 
-    const { libraryId } = fileRow;
+    const { bookId, libraryId } = fileRow;
 
     return this.db.transaction(async (tx): Promise<SaveReadingSessionResult> => {
       const inserted = await tx
         .insert(readingSessions)
-        .values({ userId, bookFileId, sessionId, startedAt, endedAt, durationSeconds, progressDelta, endProgress, source })
+        .values({ userId, bookFileId, bookId, sessionId, source, startedAt, endedAt, durationSeconds, progressDelta, endProgress })
         .onConflictDoNothing({ target: [readingSessions.userId, readingSessions.sessionId] })
         .returning({ id: readingSessions.id });
 
@@ -62,31 +92,57 @@ export class ReadingSessionRepository {
         return { kind: 'skipped', reason: 'duplicate_session_id' };
       }
 
-      await tx
-        .insert(userReadingDailyStats)
-        .values({
-          userId,
-          libraryId,
-          day: sql<string>`date_trunc('day', ${startedAt}::timestamp)::date`,
-          readingSeconds: durationSeconds,
-          progressDelta: progressDelta ?? 0,
-          sessionsCount: 1,
-          updatedAt: new Date(),
-        })
-        .onConflictDoUpdate({
-          target: [userReadingDailyStats.userId, userReadingDailyStats.libraryId, userReadingDailyStats.day],
-          set: {
-            readingSeconds: sql`${userReadingDailyStats.readingSeconds} + ${durationSeconds}`,
-            progressDelta: sql`${userReadingDailyStats.progressDelta} + ${progressDelta ?? 0}`,
-            sessionsCount: sql`${userReadingDailyStats.sessionsCount} + 1`,
-            updatedAt: new Date(),
-          },
-        });
+      await this.upsertDailyStats(tx, { userId, libraryId, startedAt, endedAt, durationSeconds, progressDelta, timeZone });
 
       return { kind: 'saved' };
     });
   }
 
+  async insertManualSession(params: InsertManualSessionParams): Promise<{ id: number }> {
+    const { userId, bookId, libraryId, bookFileId, sessionId, startedAt, endedAt, durationSeconds, progressDelta, endProgress, timeZone } = params;
+
+    return this.db.transaction(async (tx) => {
+      const [inserted] = await tx
+        .insert(readingSessions)
+        .values({ userId, bookId, bookFileId, sessionId, source: 'manual', startedAt, endedAt, durationSeconds, progressDelta, endProgress })
+        .returning({ id: readingSessions.id });
+
+      await this.upsertDailyStats(tx, { userId, libraryId, startedAt, endedAt, durationSeconds, progressDelta, timeZone });
+
+      return { id: inserted.id };
+    });
+  }
+
+  async findBookContext(bookId: number): Promise<{ libraryId: number; files: { id: number; format: string | null }[] } | null> {
+    const [bookRow] = await this.db.select({ libraryId: books.libraryId }).from(books).where(eq(books.id, bookId)).limit(1);
+    if (!bookRow) return null;
+
+    const files = await this.db
+      .select({ id: bookFiles.id, format: sql<string | null>`nullif(${bookFiles.format}, '')` })
+      .from(bookFiles)
+      .where(eq(bookFiles.bookId, bookId));
+
+    return { libraryId: bookRow.libraryId, files };
+  }
+
+  async findLatestEndProgressBefore(userId: number, bookId: number, before: Date): Promise<number | null> {
+    const [row] = await this.db
+      .select({ endProgress: readingSessions.endProgress })
+      .from(readingSessions)
+      .where(
+        and(
+          eq(readingSessions.userId, userId),
+          eq(readingSessions.bookId, bookId),
+          lt(readingSessions.startedAt, before),
+          isNotNull(readingSessions.endProgress),
+        ),
+      )
+      .orderBy(desc(readingSessions.startedAt))
+      .limit(1);
+
+    return row?.endProgress ?? null;
+  }
+
   async listByBook(
     userId: number,
     bookId: number,
@@ -97,8 +153,9 @@ export class ReadingSessionRepository {
     dateFrom?: string,
     dateTo?: string,
     format?: string,
+    timeZone = 'UTC',
   ): Promise<BookReadingSessionListResponse> {
-    const conditions = [eq(books.id, bookId), eq(readingSessions.userId, userId)];
+    const conditions = [eq(readingSessions.bookId, bookId), eq(readingSessions.userId, userId)];
     if (dateFrom) conditions.push(gte(readingSessions.startedAt, new Date(dateFrom)));
     if (dateTo) conditions.push(lte(readingSessions.startedAt, new Date(dateTo)));
     if (format) conditions.push(eq(sql`upper(${bookFiles.format})`, format.toUpperCase()));
@@ -122,7 +179,7 @@ export class ReadingSessionRepository {
     const orderExpr = sortDir === 'asc' ? asc(orderCol) : desc(orderCol);
     const offset = (page - 1) * pageSize;
 
-    const [rows, countRows, statsRows, dailyRows] = await Promise.all([
+    const [rows, countRows, statsRows, summaryRows, sourceRows] = await Promise.all([
       this.db
         .select({
           id: readingSessions.id,
@@ -132,21 +189,16 @@ export class ReadingSessionRepository {
           progressDelta: readingSessions.progressDelta,
           endProgress: readingSessions.endProgress,
           format: sql<string | null>`nullif(${bookFiles.format}, '')`,
+          source: readingSessions.source,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
         .where(whereClause)
         .orderBy(orderExpr)
         .limit(pageSize)
         .offset(offset),
 
-      this.db
-        .select({ total: count() })
-        .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
-        .where(whereClause),
+      this.db.select({ total: count() }).from(readingSessions).leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId)).where(whereClause),
 
       this.db
         .select({
@@ -155,35 +207,92 @@ export class ReadingSessionRepository {
           avgDurationSeconds: sql<number>`coalesce(avg(${readingSessions.durationSeconds}), 0)::int`,
           firstSessionAt: min(readingSessions.startedAt),
           lastSessionAt: max(readingSessions.startedAt),
+          paceProgressDelta: sql<number>`coalesce(sum(${readingSessions.progressDelta}) filter (where ${readingSessions.progressDelta} > 0), 0)::real`,
+          paceDurationSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}) filter (where ${readingSessions.progressDelta} > 0), 0)::int`,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
         .where(whereClause),
 
       this.db
         .select({
-          day: sql<string>`date_trunc('day', ${readingSessions.startedAt})::date::text`,
-          totalMinutes: sql<number>`round(sum(${readingSessions.durationSeconds}) / 60.0, 1)::real`,
+          startedAt: readingSessions.startedAt,
+          endedAt: readingSessions.endedAt,
+          durationSeconds: readingSessions.durationSeconds,
+          progressDelta: readingSessions.progressDelta,
+          endProgress: readingSessions.endProgress,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
+        .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
         .where(whereClause)
-        .groupBy(sql`date_trunc('day', ${readingSessions.startedAt})::date`)
-        .orderBy(asc(sql`date_trunc('day', ${readingSessions.startedAt})::date`)),
+        .orderBy(asc(readingSessions.startedAt)),
+
+      this.db
+        .select({
+          source: readingSessions.source,
+          totalSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::int`,
+          totalSessions: count(),
+        })
+        .from(readingSessions)
+        .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+        .where(whereClause)
+        .groupBy(readingSessions.source),
     ]);
 
     const total = countRows[0]?.total ?? 0;
     const statsRow = statsRows[0];
 
+    const bucketSeconds = emptySourceBucketRecord();
+    const bucketSessions = emptySourceBucketRecord();
+    for (const row of sourceRows) {
+      const bucket = toReadingSessionSourceBucket(row.source);
+      bucketSeconds[bucket] += row.totalSeconds;
+      bucketSessions[bucket] += row.totalSessions;
+    }
+    const bySource: BookReadingSourceSlice[] = READING_SESSION_SOURCE_BUCKETS.filter((bucket) => bucketSessions[bucket] > 0).map((bucket) => ({
+      bucket,
+      totalSeconds: bucketSeconds[bucket],
+      totalSessions: bucketSessions[bucket],
+    }));
+
+    const dailySummary = aggregateReadingSessionDailyStats(
+      summaryRows.map((row) => ({
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        durationSeconds: row.durationSeconds,
+        progressDelta: row.progressDelta ?? null,
+      })),
+      timeZone,
+    ).map((segment) => ({
+      day: segment.day,
+      totalMinutes: Math.round((segment.readingSeconds / 60) * 10) / 10,
+    }));
+
+    const progressByDay = new Map<string, { day: string; endProgress: number; endedAtMs: number }>();
+    for (const row of summaryRows) {
+      if (row.endProgress == null) continue;
+      const day = toDateKeyInTimeZone(row.endedAt, timeZone);
+      const endedAtMs = row.endedAt.getTime();
+      const existing = progressByDay.get(day);
+      if (!existing || endedAtMs > existing.endedAtMs) {
+        progressByDay.set(day, { day, endProgress: row.endProgress, endedAtMs });
+      }
+    }
+    const progressSummary = [...progressByDay.values()]
+      .sort((a, b) => a.day.localeCompare(b.day))
+      .map(({ day, endProgress }) => ({ day, endProgress }));
+
     const stats: BookReadingSessionStats = {
       totalSessions: statsRow?.totalSessions ?? 0,
       totalSeconds: statsRow?.totalSeconds ?? 0,
       avgDurationSeconds: statsRow?.avgDurationSeconds ?? 0,
       firstSessionAt: statsRow?.firstSessionAt ? (statsRow.firstSessionAt as Date).toISOString() : null,
       lastSessionAt: statsRow?.lastSessionAt ? (statsRow.lastSessionAt as Date).toISOString() : null,
-      dailySummary: dailyRows.map((r) => ({ day: r.day, totalMinutes: r.totalMinutes })),
+      dailySummary,
+      paceProgressDelta: statsRow?.paceProgressDelta ?? 0,
+      paceDurationSeconds: statsRow?.paceDurationSeconds ?? 0,
+      progressSummary,
+      bySource,
     };
 
     const items: BookReadingSession[] = rows.map((r) => ({
@@ -194,63 +303,152 @@ export class ReadingSessionRepository {
       progressDelta: r.progressDelta ?? null,
       endProgress: r.endProgress ?? null,
       format: r.format ?? null,
+      source: r.source ?? null,
     }));
 
     return { items, total, page, pageSize, stats };
   }
 
-  async deleteSessionByBook(userId: number, bookId: number, sessionId: number): Promise<{ found: boolean }> {
+  async deleteSessionByBook(userId: number, bookId: number, sessionId: number, timeZone = 'UTC'): Promise<{ found: boolean }> {
     return this.db.transaction(async (tx) => {
       const [row] = await tx
         .select({
           id: readingSessions.id,
           startedAt: readingSessions.startedAt,
+          endedAt: readingSessions.endedAt,
+          durationSeconds: readingSessions.durationSeconds,
+          progressDelta: readingSessions.progressDelta,
           libraryId: books.libraryId,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
-        .where(and(eq(readingSessions.id, sessionId), eq(readingSessions.userId, userId), eq(books.id, bookId)))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
+        .where(and(eq(readingSessions.id, sessionId), eq(readingSessions.userId, userId), eq(readingSessions.bookId, bookId)))
         .limit(1);
 
       if (!row) return { found: false };
 
-      const { startedAt, libraryId } = row;
+      const { startedAt, endedAt, durationSeconds, progressDelta, libraryId } = row;
+      const affectedDays = getReadingSessionDayKeys({ startedAt, endedAt, durationSeconds, progressDelta: progressDelta ?? null }, timeZone);
 
       await tx.delete(readingSessions).where(eq(readingSessions.id, sessionId));
 
-      const dayKey = this.formatDayKey(startedAt as Date);
-
-      await tx
-        .delete(userReadingDailyStats)
-        .where(and(eq(userReadingDailyStats.userId, userId), eq(userReadingDailyStats.libraryId, libraryId), eq(userReadingDailyStats.day, dayKey)));
-
-      const dayDateSql = sql`${dayKey}::date`;
-
-      await tx.execute(sql`
-        insert into user_reading_daily_stats (user_id, library_id, day, reading_seconds, progress_delta, sessions_count, updated_at)
-        select
-          rs.user_id,
-          b.library_id,
-          date_trunc('day', rs.started_at)::date as day,
-          coalesce(sum(rs.duration_seconds), 0)::int as reading_seconds,
-          coalesce(sum(rs.progress_delta), 0)::real as progress_delta,
-          count(*)::int as sessions_count,
-          now() as updated_at
-        from reading_sessions rs
-        inner join book_files bf on bf.id = rs.book_file_id
-        inner join books b on b.id = bf.book_id
-        where rs.user_id = ${userId}
-          and b.library_id = ${libraryId}
-          and date_trunc('day', rs.started_at)::date in (${dayDateSql})
-        group by rs.user_id, b.library_id, date_trunc('day', rs.started_at)::date
-      `);
+      await this.recomputeDailyStats(tx, userId, libraryId, affectedDays, timeZone);
 
       return { found: true };
     });
   }
 
-  private formatDayKey(date: Date): string {
-    return date.toISOString().slice(0, 10);
+  private async upsertDailyStats(
+    tx: Tx,
+    params: {
+      userId: number;
+      libraryId: number;
+      startedAt: Date;
+      endedAt: Date;
+      durationSeconds: number;
+      progressDelta: number | null;
+      timeZone: string;
+    },
+  ): Promise<void> {
+    const { userId, libraryId, startedAt, endedAt, durationSeconds, progressDelta, timeZone } = params;
+    await this.lockDailyStats(tx, userId, libraryId);
+    const segments = splitReadingSessionByDay({ startedAt, endedAt, durationSeconds, progressDelta }, timeZone);
+    await this.insertDailyStatsSegments(tx, userId, libraryId, segments, 'increment');
+  }
+
+  private async recomputeDailyStats(tx: Tx, userId: number, libraryId: number, days: string[], timeZone: string): Promise<void> {
+    const affectedDays = [...new Set(days)].sort();
+    if (affectedDays.length === 0) return;
+
+    await this.lockDailyStats(tx, userId, libraryId);
+
+    await tx
+      .delete(userReadingDailyStats)
+      .where(
+        and(
+          eq(userReadingDailyStats.userId, userId),
+          eq(userReadingDailyStats.libraryId, libraryId),
+          inArray(userReadingDailyStats.day, affectedDays),
+        ),
+      );
+
+    const range = getDayRangeForDateKeys(affectedDays, timeZone);
+    if (!range) return;
+
+    const rows = await tx
+      .select({
+        startedAt: readingSessions.startedAt,
+        endedAt: readingSessions.endedAt,
+        durationSeconds: readingSessions.durationSeconds,
+        progressDelta: readingSessions.progressDelta,
+      })
+      .from(readingSessions)
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
+      .where(
+        and(
+          eq(readingSessions.userId, userId),
+          eq(books.libraryId, libraryId),
+          lt(readingSessions.startedAt, range.end),
+          gt(readingSessions.endedAt, range.start),
+        ),
+      );
+
+    const segments = aggregateReadingSessionDailyStats(
+      rows.map((row) => ({
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        durationSeconds: row.durationSeconds,
+        progressDelta: row.progressDelta ?? null,
+      })),
+      timeZone,
+      new Set(affectedDays),
+    );
+    await this.insertDailyStatsSegments(tx, userId, libraryId, segments, 'replace');
+  }
+
+  private async lockDailyStats(tx: Tx, userId: number, libraryId: number): Promise<void> {
+    await tx.execute(sql`select pg_advisory_xact_lock(${userId}::int, ${libraryId}::int)`);
+  }
+
+  private async insertDailyStatsSegments(
+    tx: Tx,
+    userId: number,
+    libraryId: number,
+    segments: ReadingDailyStatsSegment[],
+    mode: 'increment' | 'replace',
+  ): Promise<void> {
+    if (segments.length === 0) return;
+
+    const now = new Date();
+    await tx
+      .insert(userReadingDailyStats)
+      .values(
+        segments.map((segment) => ({
+          userId,
+          libraryId,
+          day: segment.day,
+          readingSeconds: segment.readingSeconds,
+          progressDelta: segment.progressDelta,
+          sessionsCount: segment.sessionsCount,
+          updatedAt: now,
+        })),
+      )
+      .onConflictDoUpdate({
+        target: [userReadingDailyStats.userId, userReadingDailyStats.libraryId, userReadingDailyStats.day],
+        set:
+          mode === 'increment'
+            ? {
+                readingSeconds: sql`${userReadingDailyStats.readingSeconds} + excluded.reading_seconds`,
+                progressDelta: sql`${userReadingDailyStats.progressDelta} + excluded.progress_delta`,
+                sessionsCount: sql`${userReadingDailyStats.sessionsCount} + excluded.sessions_count`,
+                updatedAt: now,
+              }
+            : {
+                readingSeconds: sql`excluded.reading_seconds`,
+                progressDelta: sql`excluded.progress_delta`,
+                sessionsCount: sql`excluded.sessions_count`,
+                updatedAt: now,
+              },
+      });
   }
 }
diff --git a/server/src/modules/reading-session/reading-session.service.test.ts b/server/src/modules/reading-session/reading-session.service.test.ts
index 6f18c24cc..e30c2a63e 100644
--- a/server/src/modules/reading-session/reading-session.service.test.ts
+++ b/server/src/modules/reading-session/reading-session.service.test.ts
@@ -5,7 +5,7 @@ import type { RequestUser } from '../../common/types/request-user';
 import { BookService } from '../book/book.service';
 import { ReadingSessionRepository, type SaveReadingSessionResult } from './reading-session.repository';
 import { ReadingSessionService } from './reading-session.service';
-import { EMPTY_CONTENT_FILTER_RULES } from '@bookorbit/types';
+import { EMPTY_CONTENT_FILTER_RULES, type ReadingSessionSource } from '@bookorbit/types';
 
 function makeUser(overrides?: Partial<RequestUser>): RequestUser {
   return {
@@ -29,7 +29,11 @@ function makeUser(overrides?: Partial<RequestUser>): RequestUser {
 
 const mockRepo = {
   saveSession:
-    vi.fn<(...args: [number, number, string, Date, Date, number, number | null, number | null, string]) => Promise<SaveReadingSessionResult>>(),
+    vi.fn<
+      (
+        ...args: [number, number, string, Date, Date, number, number | null, number | null, ReadingSessionSource, string]
+      ) => Promise<SaveReadingSessionResult>
+    >(),
 };
 
 const mockBookService = {
@@ -77,6 +81,7 @@ describe('ReadingSessionService', () => {
       2.5,
       10,
       'web',
+      'UTC',
     );
   });
 
@@ -104,34 +109,36 @@ describe('ReadingSessionService', () => {
       null,
       null,
       'web',
+      'UTC',
     );
   });
 
-  it('threads an explicit source through to the repository', async () => {
+  it('forwards an explicit source to the repository', async () => {
     await service.save(
       42,
       {
-        sessionId: 'session-kobo',
+        sessionId: 'kobo-session',
         startedAt: '2026-04-15T10:00:00.000Z',
-        endedAt: '2026-04-15T10:02:00.000Z',
-        durationSeconds: 120,
-        progressDelta: 5,
-        endProgress: 20,
+        endedAt: '2026-04-15T10:01:00.000Z',
+        durationSeconds: 60,
+        progressDelta: null,
+        endProgress: null,
       },
-      makeUser({ id: 7 }),
+      makeUser({ id: 33 }),
       'kobo',
     );
 
     expect(mockRepo.saveSession).toHaveBeenCalledWith(
-      7,
+      33,
       42,
-      'session-kobo',
+      'kobo-session',
       new Date('2026-04-15T10:00:00.000Z'),
-      new Date('2026-04-15T10:02:00.000Z'),
-      120,
-      5,
-      20,
+      new Date('2026-04-15T10:01:00.000Z'),
+      60,
+      null,
+      null,
       'kobo',
+      'UTC',
     );
   });
 
@@ -210,6 +217,9 @@ const mockRepoExtended = {
   saveSession: vi.fn(),
   listByBook: vi.fn(),
   deleteSessionByBook: vi.fn(),
+  findBookContext: vi.fn(),
+  findLatestEndProgressBefore: vi.fn(),
+  insertManualSession: vi.fn(),
 };
 
 const mockBookServiceExtended = {
@@ -262,7 +272,7 @@ describe('ReadingSessionService - listByBook', () => {
     mockRepoExtended.listByBook.mockResolvedValue({ items: [], total: 0, page: 2, pageSize: 10, stats: emptyStats });
 
     const svc = makeServiceExtended();
-    await svc.listByBook(10, makeUser({ id: 5 }), {
+    await svc.listByBook(10, makeUser({ id: 5, settings: { timezone: 'Asia/Kolkata' } }), {
       page: 2,
       pageSize: 10,
       sortBy: 'durationSeconds',
@@ -272,7 +282,18 @@ describe('ReadingSessionService - listByBook', () => {
       format: 'EPUB',
     });
 
-    expect(mockRepoExtended.listByBook).toHaveBeenCalledWith(5, 10, 2, 10, 'durationSeconds', 'asc', '2026-01-01', '2026-12-31', 'EPUB');
+    expect(mockRepoExtended.listByBook).toHaveBeenCalledWith(
+      5,
+      10,
+      2,
+      10,
+      'durationSeconds',
+      'asc',
+      '2026-01-01',
+      '2026-12-31',
+      'EPUB',
+      'Asia/Kolkata',
+    );
   });
 
   it('uses defaults when optional params are missing', async () => {
@@ -282,7 +303,155 @@ describe('ReadingSessionService - listByBook', () => {
     const svc = makeServiceExtended();
     await svc.listByBook(10, makeUser({ id: 5 }), {});
 
-    expect(mockRepoExtended.listByBook).toHaveBeenCalledWith(5, 10, 1, 25, 'startedAt', 'desc', undefined, undefined, undefined);
+    expect(mockRepoExtended.listByBook).toHaveBeenCalledWith(5, 10, 1, 25, 'startedAt', 'desc', undefined, undefined, undefined, 'UTC');
+  });
+});
+
+describe('ReadingSessionService - createManualSession', () => {
+  const achievementEmit = vi.fn();
+
+  function makeManualService() {
+    return new ReadingSessionService(
+      mockRepoExtended as unknown as ReadingSessionRepository,
+      mockBookServiceExtended as unknown as BookService,
+      { emit: achievementEmit } as never,
+    );
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockBookServiceExtended.verifyBookAccess.mockResolvedValue(undefined);
+    mockRepoExtended.findBookContext.mockResolvedValue({ libraryId: 3, files: [{ id: 42, format: 'epub' }] });
+    mockRepoExtended.findLatestEndProgressBefore.mockResolvedValue(null);
+    mockRepoExtended.insertManualSession.mockResolvedValue({ id: 555 });
+    vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+  });
+
+  it('verifies access and inserts a manual session with server-computed duration', async () => {
+    const svc = makeManualService();
+    const result = await svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 45 }, makeUser({ id: 5 }));
+
+    expect(mockBookServiceExtended.verifyBookAccess).toHaveBeenCalledWith(10, expect.objectContaining({ id: 5 }));
+    expect(mockRepoExtended.insertManualSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 5,
+        bookId: 10,
+        libraryId: 3,
+        bookFileId: 42,
+        startedAt: new Date('2026-04-15T10:00:00.000Z'),
+        endedAt: new Date('2026-04-15T10:45:00.000Z'),
+        durationSeconds: 2700,
+        progressDelta: null,
+        endProgress: null,
+      }),
+    );
+    const { sessionId } = mockRepoExtended.insertManualSession.mock.calls[0][0] as { sessionId: string };
+    expect(sessionId.startsWith('manual:')).toBe(true);
+    expect(result).toMatchObject({ id: 555, durationSeconds: 2700, format: 'epub', source: 'manual' });
+  });
+
+  it('computes progressDelta from the latest prior endProgress', async () => {
+    mockRepoExtended.findLatestEndProgressBefore.mockResolvedValue(40);
+
+    const svc = makeManualService();
+    const result = await svc.createManualSession(
+      10,
+      { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: 55.5 },
+      makeUser({ id: 5 }),
+    );
+
+    expect(mockRepoExtended.findLatestEndProgressBefore).toHaveBeenCalledWith(5, 10, new Date('2026-04-15T10:00:00.000Z'));
+    expect(result.progressDelta).toBe(15.5);
+    expect(result.endProgress).toBe(55.5);
+  });
+
+  it('treats missing prior progress as zero', async () => {
+    mockRepoExtended.findLatestEndProgressBefore.mockResolvedValue(null);
+
+    const svc = makeManualService();
+    const result = await svc.createManualSession(
+      10,
+      { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, endProgress: 20 },
+      makeUser({ id: 5 }),
+    );
+
+    expect(result.progressDelta).toBe(20);
+  });
+
+  it('skips the prior-progress lookup when endProgress is omitted', async () => {
+    const svc = makeManualService();
+    await svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 }, makeUser({ id: 5 }));
+
+    expect(mockRepoExtended.findLatestEndProgressBefore).not.toHaveBeenCalled();
+  });
+
+  it('rejects a future startedAt', async () => {
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+
+    const svc = makeManualService();
+    await expect(svc.createManualSession(10, { startedAt: future, durationMinutes: 30 }, makeUser())).rejects.toThrow(BadRequestException);
+    expect(mockRepoExtended.insertManualSession).not.toHaveBeenCalled();
+  });
+
+  it('rejects an unknown format', async () => {
+    const svc = makeManualService();
+    await expect(
+      svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, format: 'pdf' }, makeUser()),
+    ).rejects.toThrow(BadRequestException);
+    expect(mockRepoExtended.insertManualSession).not.toHaveBeenCalled();
+  });
+
+  it('resolves the file case-insensitively when a format is given', async () => {
+    mockRepoExtended.findBookContext.mockResolvedValue({
+      libraryId: 3,
+      files: [
+        { id: 42, format: 'epub' },
+        { id: 43, format: 'pdf' },
+      ],
+    });
+
+    const svc = makeManualService();
+    const result = await svc.createManualSession(
+      10,
+      { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30, format: 'PDF' },
+      makeUser({ id: 5 }),
+    );
+
+    expect(mockRepoExtended.insertManualSession).toHaveBeenCalledWith(expect.objectContaining({ bookFileId: 43 }));
+    expect(result.format).toBe('pdf');
+  });
+
+  it('leaves bookFileId null for multi-format books without a format hint', async () => {
+    mockRepoExtended.findBookContext.mockResolvedValue({
+      libraryId: 3,
+      files: [
+        { id: 42, format: 'epub' },
+        { id: 43, format: 'pdf' },
+      ],
+    });
+
+    const svc = makeManualService();
+    const result = await svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 }, makeUser({ id: 5 }));
+
+    expect(mockRepoExtended.insertManualSession).toHaveBeenCalledWith(expect.objectContaining({ bookFileId: null }));
+    expect(result.format).toBeNull();
+  });
+
+  it('throws NotFoundException when the book context is missing', async () => {
+    mockRepoExtended.findBookContext.mockResolvedValue(null);
+
+    const svc = makeManualService();
+    await expect(svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 }, makeUser())).rejects.toThrow(
+      NotFoundException,
+    );
+  });
+
+  it('does not emit achievement events for manual sessions', async () => {
+    const svc = makeManualService();
+    await svc.createManualSession(10, { startedAt: '2026-04-15T10:00:00.000Z', durationMinutes: 30 }, makeUser({ id: 5 }));
+
+    expect(achievementEmit).not.toHaveBeenCalled();
   });
 });
 
diff --git a/server/src/modules/reading-session/reading-session.service.ts b/server/src/modules/reading-session/reading-session.service.ts
index a55483730..625379165 100644
--- a/server/src/modules/reading-session/reading-session.service.ts
+++ b/server/src/modules/reading-session/reading-session.service.ts
@@ -1,11 +1,14 @@
+import { randomUUID } from 'node:crypto';
+
 import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
 
-import type { BookReadingSessionListResponse, UserSettings } from '@bookorbit/types';
+import type { BookReadingSession, BookReadingSessionListResponse, ReadingSessionSource, UserSettings } from '@bookorbit/types';
 import type { RequestUser } from '../../common/types/request-user';
 import { sanitizeLogValue } from '../../common/utils/log-sanitize.utils';
+import { resolveTimeZone } from '../../common/utils/timezone.utils';
 import { BookService } from '../book/book.service';
 import { AchievementEventsService, ACHIEVEMENT_EVENT_READING_SESSION_SAVED } from '../achievement/achievement-events.service';
-import type { ReadingSessionSource } from '../../db/schema/reader';
+import type { CreateManualReadingSessionDto } from './dto/create-manual-reading-session.dto';
 import type { ListBookReadingSessionsDto } from './dto/list-book-reading-sessions.dto';
 import type { SaveReadingSessionDto } from './dto/save-reading-session.dto';
 import { ReadingSessionRepository } from './reading-session.repository';
@@ -20,6 +23,10 @@ export class ReadingSessionService {
     private readonly achievementEvents: AchievementEventsService,
   ) {}
 
+  private resolveUserTimeZone(user: RequestUser): string {
+    return resolveTimeZone((user.settings as { timezone?: unknown } | undefined)?.timezone, 'UTC');
+  }
+
   async save(fileId: number, dto: SaveReadingSessionDto, user: RequestUser, source: ReadingSessionSource = 'web'): Promise<void> {
     const event = 'reading_session.save';
     const startedAtMs = Date.now();
@@ -55,6 +62,7 @@ export class ReadingSessionService {
         dto.progressDelta ?? null,
         dto.endProgress ?? null,
         source,
+        this.resolveUserTimeZone(user),
       );
 
       this.logger.log(
@@ -83,6 +91,92 @@ export class ReadingSessionService {
     }
   }
 
+  async createManualSession(bookId: number, dto: CreateManualReadingSessionDto, user: RequestUser): Promise<BookReadingSession> {
+    const event = 'book.reading_session.create_manual';
+    const startedAtMs = Date.now();
+    this.logger.log(
+      `[${event}] [start] bookId=${bookId} userId=${user.id} durationMinutes=${dto.durationMinutes} - create manual reading session started`,
+    );
+
+    try {
+      await this.bookService.verifyBookAccess(bookId, user);
+
+      const startedAt = new Date(dto.startedAt);
+      if (Number.isNaN(startedAt.getTime())) {
+        throw new BadRequestException('Invalid startedAt timestamp');
+      }
+      if (startedAt.getTime() > Date.now()) {
+        throw new BadRequestException('startedAt cannot be in the future');
+      }
+
+      const durationSeconds = dto.durationMinutes * 60;
+      const endedAt = new Date(startedAt.getTime() + durationSeconds * 1000);
+
+      const context = await this.repo.findBookContext(bookId);
+      if (!context) {
+        throw new NotFoundException('Book not found');
+      }
+
+      let bookFileId: number | null = null;
+      if (dto.format) {
+        const match = context.files.find((f) => f.format?.toUpperCase() === dto.format!.toUpperCase());
+        if (!match) {
+          throw new BadRequestException(`No ${dto.format.toUpperCase()} file on this book`);
+        }
+        bookFileId = match.id;
+      } else if (context.files.length === 1) {
+        bookFileId = context.files[0].id;
+      }
+
+      let progressDelta: number | null = null;
+      const endProgress = dto.endProgress ?? null;
+      if (endProgress !== null) {
+        const previous = (await this.repo.findLatestEndProgressBefore(user.id, bookId, startedAt)) ?? 0;
+        progressDelta = Math.round(Math.max(-100, Math.min(100, endProgress - previous)) * 100) / 100;
+      }
+
+      const created = await this.repo.insertManualSession({
+        userId: user.id,
+        bookId,
+        libraryId: context.libraryId,
+        bookFileId,
+        sessionId: `manual:${randomUUID()}`,
+        startedAt,
+        endedAt,
+        durationSeconds,
+        progressDelta,
+        endProgress,
+        timeZone: this.resolveUserTimeZone(user),
+      });
+
+      // No achievement event: the payload requires a non-null bookFileId, and retroactive
+      // manual entries would allow farming time-based achievements.
+
+      this.logger.log(
+        `[${event}] [end] bookId=${bookId} userId=${user.id} sessionId=${created.id} durationMs=${Date.now() - startedAtMs} - create manual reading session completed`,
+      );
+
+      const format = bookFileId !== null ? (context.files.find((f) => f.id === bookFileId)?.format ?? null) : null;
+
+      return {
+        id: created.id,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        durationSeconds,
+        progressDelta,
+        endProgress,
+        format,
+        source: 'manual',
+      };
+    } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[${event}] [fail] bookId=${bookId} userId=${user.id} durationMs=${Date.now() - startedAtMs} errorClass=${errorClass} error="${sanitizeLogValue(error instanceof Error ? error.message : 'unknown error')}" - create manual reading session failed`,
+      );
+      throw error;
+    }
+  }
+
   async listByBook(bookId: number, user: RequestUser, query: ListBookReadingSessionsDto): Promise<BookReadingSessionListResponse> {
     const event = 'book.reading_sessions.list';
     const startedAtMs = Date.now();
@@ -99,6 +193,7 @@ export class ReadingSessionService {
         query.dateFrom,
         query.dateTo,
         query.format,
+        this.resolveUserTimeZone(user),
       );
       this.logger.log(
         `[${event}] [end] bookId=${bookId} userId=${user.id} durationMs=${Date.now() - startedAtMs} total=${result.total} - list reading sessions completed`,
@@ -119,7 +214,7 @@ export class ReadingSessionService {
     this.logger.log(`[${event}] [start] bookId=${bookId} sessionId=${sessionId} userId=${user.id} - delete reading session started`);
     try {
       await this.bookService.verifyBookAccess(bookId, user);
-      const result = await this.repo.deleteSessionByBook(user.id, bookId, sessionId);
+      const result = await this.repo.deleteSessionByBook(user.id, bookId, sessionId, this.resolveUserTimeZone(user));
       if (!result.found) throw new NotFoundException('Reading session not found');
       this.logger.log(
         `[${event}] [end] bookId=${bookId} sessionId=${sessionId} userId=${user.id} durationMs=${Date.now() - startedAtMs} - delete reading session completed`,
diff --git a/server/src/modules/user-book-status/user-book-status.repository.test.ts b/server/src/modules/user-book-status/user-book-status.repository.test.ts
index f832d1426..d156c4206 100644
--- a/server/src/modules/user-book-status/user-book-status.repository.test.ts
+++ b/server/src/modules/user-book-status/user-book-status.repository.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import type { UserBookStatusRow } from '../../db/schema';
 import { deriveLifecycle } from './user-book-status.repository';
+import type { SessionBoundaries } from './user-book-status.repository';
 
 function makeRow(overrides: Partial<UserBookStatusRow> = {}): UserBookStatusRow {
   return {
@@ -51,3 +52,45 @@ describe('deriveLifecycle', () => {
     expect(deriveLifecycle('abandoned', now, withoutStarted)).toEqual({ startedAt: now, finishedAt: null });
   });
 });
+
+describe('deriveLifecycle with sessionBoundaries', () => {
+  const now = new Date('2025-01-15T12:00:00.000Z');
+  const firstSession = new Date('2024-03-01T08:00:00.000Z');
+  const lastSession = new Date('2024-12-20T22:00:00.000Z');
+  const boundaries: SessionBoundaries = { firstStartedAt: firstSession, lastEndedAt: lastSession };
+
+  it('uses firstStartedAt from boundaries when existing is null', () => {
+    expect(deriveLifecycle('reading', now, null, boundaries)).toEqual({ startedAt: firstSession, finishedAt: null });
+  });
+
+  it('uses firstStartedAt from boundaries when existing.startedAt is null', () => {
+    const withNullStarted = makeRow({ startedAt: null, finishedAt: null, status: 'unread' });
+    expect(deriveLifecycle('reading', now, withNullStarted, boundaries)).toEqual({ startedAt: firstSession, finishedAt: null });
+  });
+
+  it('does not override a non-null existing startedAt with boundaries', () => {
+    const existingStarted = new Date('2024-01-01T00:00:00.000Z');
+    const existing = makeRow({ startedAt: existingStarted, finishedAt: null, status: 'reading' });
+    expect(deriveLifecycle('reading', now, existing, boundaries)).toEqual({ startedAt: existingStarted, finishedAt: null });
+  });
+
+  it('applies firstStartedAt for read status and still sets finishedAt to now', () => {
+    expect(deriveLifecycle('read', now, null, boundaries)).toEqual({ startedAt: firstSession, finishedAt: now });
+  });
+
+  it('falls back to now when boundaries contain null timestamps', () => {
+    const emptyBoundaries: SessionBoundaries = { firstStartedAt: null, lastEndedAt: null };
+    expect(deriveLifecycle('reading', now, null, emptyBoundaries)).toEqual({ startedAt: now, finishedAt: null });
+  });
+
+  it('ignores boundaries for unread and want_to_read', () => {
+    expect(deriveLifecycle('unread', now, null, boundaries)).toEqual({ startedAt: null, finishedAt: null });
+    expect(deriveLifecycle('want_to_read', now, null, boundaries)).toEqual({ startedAt: null, finishedAt: null });
+  });
+
+  it('applies boundaries for all active statuses', () => {
+    for (const status of ['reading', 'on_hold', 'rereading', 'skimmed', 'abandoned'] as const) {
+      expect(deriveLifecycle(status, now, null, boundaries)).toEqual({ startedAt: firstSession, finishedAt: null });
+    }
+  });
+});
diff --git a/server/src/modules/user-book-status/user-book-status.repository.ts b/server/src/modules/user-book-status/user-book-status.repository.ts
index 1274fe46a..4c95a85c8 100644
--- a/server/src/modules/user-book-status/user-book-status.repository.ts
+++ b/server/src/modules/user-book-status/user-book-status.repository.ts
@@ -1,10 +1,10 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { and, eq, inArray } from 'drizzle-orm';
+import { and, eq, inArray, max, min } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 import { DB } from '../../db';
 import * as schema from '../../db/schema';
-import { userBookStatus } from '../../db/schema';
+import { readingSessions, userBookStatus } from '../../db/schema';
 import type { ReadStatus, ReadStatusSource } from '@bookorbit/types';
 import type { UserBookStatusRow } from '../../db/schema';
 
@@ -13,7 +13,17 @@ type Db = NodePgDatabase<typeof schema>;
 export type UserBookStatusLifecycle = Pick<UserBookStatusRow, 'startedAt' | 'finishedAt'>;
 export type UserBookStatusState = Pick<UserBookStatusRow, 'status' | 'source' | 'startedAt' | 'finishedAt' | 'updatedAt'>;
 
-export function deriveLifecycle(status: ReadStatus, now: Date, existing: UserBookStatusRow | null): UserBookStatusLifecycle {
+export interface SessionBoundaries {
+  firstStartedAt: Date | null;
+  lastEndedAt: Date | null;
+}
+
+export function deriveLifecycle(
+  status: ReadStatus,
+  now: Date,
+  existing: UserBookStatusRow | null,
+  sessionBoundaries?: SessionBoundaries,
+): UserBookStatusLifecycle {
   switch (status) {
     case 'unread':
     case 'want_to_read':
@@ -23,9 +33,9 @@ export function deriveLifecycle(status: ReadStatus, now: Date, existing: UserBoo
     case 'rereading':
     case 'skimmed':
     case 'abandoned':
-      return { startedAt: existing?.startedAt ?? now, finishedAt: null };
+      return { startedAt: existing?.startedAt ?? sessionBoundaries?.firstStartedAt ?? now, finishedAt: null };
     case 'read':
-      return { startedAt: existing?.startedAt ?? now, finishedAt: now };
+      return { startedAt: existing?.startedAt ?? sessionBoundaries?.firstStartedAt ?? now, finishedAt: now };
   }
 }
 
@@ -50,6 +60,21 @@ export class UserBookStatusRepository {
       .where(and(eq(userBookStatus.userId, userId), inArray(userBookStatus.bookId, bookIds)));
   }
 
+  async findSessionBoundariesForBook(userId: number, bookId: number): Promise<SessionBoundaries> {
+    const [row] = await this.db
+      .select({
+        firstStartedAt: min(readingSessions.startedAt),
+        lastEndedAt: max(readingSessions.endedAt),
+      })
+      .from(readingSessions)
+      .where(and(eq(readingSessions.userId, userId), eq(readingSessions.bookId, bookId)));
+
+    return {
+      firstStartedAt: (row?.firstStartedAt as Date | null | undefined) ?? null,
+      lastEndedAt: (row?.lastEndedAt as Date | null | undefined) ?? null,
+    };
+  }
+
   async upsert(
     userId: number,
     bookId: number,
@@ -59,7 +84,11 @@ export class UserBookStatusRepository {
     existing?: Awaited<ReturnType<typeof this.findOne>>,
   ): Promise<void> {
     const row = existing !== undefined ? existing : await this.findOne(userId, bookId);
-    const { startedAt, finishedAt } = deriveLifecycle(status, now, row);
+
+    const needsSessionBoundaries = status !== 'unread' && status !== 'want_to_read' && row?.startedAt == null;
+    const sessionBoundaries = needsSessionBoundaries ? await this.findSessionBoundariesForBook(userId, bookId) : undefined;
+
+    const { startedAt, finishedAt } = deriveLifecycle(status, now, row, sessionBoundaries);
 
     await this.db
       .insert(userBookStatus)
diff --git a/server/src/modules/user-book-status/user-book-status.service.test.ts b/server/src/modules/user-book-status/user-book-status.service.test.ts
index 237bdb2c7..a51d86137 100644
--- a/server/src/modules/user-book-status/user-book-status.service.test.ts
+++ b/server/src/modules/user-book-status/user-book-status.service.test.ts
@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { UserBookStatusRow } from '../../db/schema';
 import { UserBookStatusRepository } from './user-book-status.repository';
+import type { SessionBoundaries } from './user-book-status.repository';
 import { UserBookStatusService } from './user-book-status.service';
 
 function makeRow(overrides: Partial<UserBookStatusRow> = {}): UserBookStatusRow {
@@ -29,6 +30,7 @@ const mockRepo = {
         ...args: [number, number, { status: ReadStatus; source: ReadStatusSource; startedAt: Date | null; finishedAt: Date | null; updatedAt: Date }]
       ) => Promise<void>
     >(),
+  findSessionBoundariesForBook: vi.fn<(...args: [number, number]) => Promise<SessionBoundaries>>(),
 };
 const mockAchievementEvents = {
   emit: vi.fn(),
@@ -42,6 +44,7 @@ beforeEach(() => {
   mockRepo.findByBookIds.mockResolvedValue([]);
   mockRepo.upsert.mockResolvedValue(undefined);
   mockRepo.upsertState.mockResolvedValue(undefined);
+  mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: null, lastEndedAt: null });
   service = new UserBookStatusService(mockRepo as unknown as UserBookStatusRepository, mockAchievementEvents as never);
 });
 
@@ -67,6 +70,49 @@ describe('setManual', () => {
     expect(mockRepo.upsert).not.toHaveBeenCalled();
     expect(mockAchievementEvents.emit).not.toHaveBeenCalled();
   });
+
+  it('seeds startedAt from sessions when no existing row has a date', async () => {
+    const firstSession = new Date('2024-06-01T10:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(null);
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: firstSession, lastEndedAt: new Date('2024-12-01T22:00:00.000Z') });
+
+    await service.setManual(1, 10, 'reading');
+
+    expect(mockRepo.findSessionBoundariesForBook).toHaveBeenCalledOnce();
+    expect(mockRepo.upsertState).toHaveBeenCalledOnce();
+    expect(mockRepo.upsertState.mock.calls[0]?.[2]).toMatchObject({
+      status: 'reading',
+      source: 'manual',
+      startedAt: firstSession,
+      finishedAt: null,
+    });
+  });
+
+  it('seeds startedAt and finishedAt from sessions when status is read and existing has null dates', async () => {
+    const firstSession = new Date('2024-06-01T10:00:00.000Z');
+    const lastSession = new Date('2024-12-01T22:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(makeRow({ startedAt: null, finishedAt: null, status: 'reading', source: 'auto' }));
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: firstSession, lastEndedAt: lastSession });
+
+    await service.setManual(1, 10, 'read');
+
+    expect(mockRepo.findSessionBoundariesForBook).toHaveBeenCalledOnce();
+    expect(mockRepo.upsertState.mock.calls[0]?.[2]).toMatchObject({
+      status: 'read',
+      source: 'manual',
+      startedAt: firstSession,
+      finishedAt: lastSession,
+    });
+  });
+
+  it('does not fetch session boundaries when existing row already has startedAt', async () => {
+    const started = new Date('2026-04-01T00:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(makeRow({ startedAt: started, finishedAt: null, status: 'reading', source: 'auto' }));
+
+    await service.setManual(1, 10, 'reading');
+
+    expect(mockRepo.findSessionBoundariesForBook).not.toHaveBeenCalled();
+  });
 });
 
 describe('updateManual', () => {
@@ -134,6 +180,95 @@ describe('updateManual', () => {
     await service.updateManual(1, 10, { startedAt: new Date('2026-04-01T00:00:00.000Z') });
     expect(mockAchievementEvents.emit).not.toHaveBeenCalled();
   });
+
+  it('does not seed dates or fetch boundaries for unread and want_to_read statuses', async () => {
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({
+      firstStartedAt: new Date('2024-06-01T10:00:00.000Z'),
+      lastEndedAt: new Date('2024-12-01T22:00:00.000Z'),
+    });
+
+    for (const status of ['unread', 'want_to_read'] as const) {
+      vi.clearAllMocks();
+      mockRepo.findOne.mockResolvedValue(makeRow({ startedAt: null, finishedAt: null, status: 'reading', source: 'auto' }));
+      mockRepo.upsertState.mockResolvedValue(undefined);
+      mockRepo.findSessionBoundariesForBook.mockResolvedValue({
+        firstStartedAt: new Date('2024-06-01T10:00:00.000Z'),
+        lastEndedAt: new Date('2024-12-01T22:00:00.000Z'),
+      });
+
+      const result = await service.updateManual(1, 10, { status });
+
+      expect(mockRepo.findSessionBoundariesForBook).not.toHaveBeenCalled();
+      expect(result.startedAt).toBeNull();
+      expect(result.finishedAt).toBeNull();
+    }
+  });
+
+  it('does not seed finishedAt when the last session ended before the explicit startedAt', async () => {
+    mockRepo.findOne.mockResolvedValue(null);
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({
+      firstStartedAt: new Date('2024-06-01T10:00:00.000Z'),
+      lastEndedAt: new Date('2024-12-01T22:00:00.000Z'),
+    });
+
+    const explicitStartedAt = new Date('2025-06-01T00:00:00.000Z');
+    const result = await service.updateManual(1, 10, { status: 'read', startedAt: explicitStartedAt });
+
+    expect(result.startedAt).toBe(explicitStartedAt.toISOString());
+    expect(result.finishedAt).toBeNull();
+  });
+
+  it('seeds finishedAt when the last session ended after the seeded startedAt', async () => {
+    const firstSession = new Date('2024-06-01T10:00:00.000Z');
+    const lastSession = new Date('2024-12-01T22:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(makeRow({ status: 'reading', source: 'auto', startedAt: null, finishedAt: null }));
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: firstSession, lastEndedAt: lastSession });
+
+    const result = await service.updateManual(1, 10, { status: 'read' });
+
+    expect(result.startedAt).toBe(firstSession.toISOString());
+    expect(result.finishedAt).toBe(lastSession.toISOString());
+  });
+
+  it('does not fetch session boundaries when explicit null is provided for startedAt', async () => {
+    mockRepo.findOne.mockResolvedValue(makeRow({ status: 'reading', source: 'manual', startedAt: null, finishedAt: null }));
+
+    const result = await service.updateManual(1, 10, { startedAt: null });
+
+    expect(mockRepo.findSessionBoundariesForBook).not.toHaveBeenCalled();
+    expect(result.startedAt).toBeNull();
+  });
+
+  it('does not fetch session boundaries when startedAt is already set on existing row', async () => {
+    const existing = new Date('2026-01-01T00:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(makeRow({ status: 'unread', source: 'auto', startedAt: existing, finishedAt: null }));
+
+    await service.updateManual(1, 10, { status: 'reading' });
+
+    expect(mockRepo.findSessionBoundariesForBook).not.toHaveBeenCalled();
+    const state = mockRepo.upsertState.mock.calls[0]?.[2];
+    expect(state?.startedAt).toEqual(existing);
+  });
+
+  it('does not seed finishedAt for non-read statuses even when session boundaries exist', async () => {
+    const lastSession = new Date('2024-12-01T22:00:00.000Z');
+    mockRepo.findOne.mockResolvedValue(makeRow({ status: 'unread', source: 'auto', startedAt: null, finishedAt: null }));
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: new Date('2024-06-01T10:00:00.000Z'), lastEndedAt: lastSession });
+
+    const result = await service.updateManual(1, 10, { status: 'reading' });
+
+    expect(result.finishedAt).toBeNull();
+  });
+
+  it('leaves finishedAt null when sessions have no data and status is read', async () => {
+    mockRepo.findOne.mockResolvedValue(makeRow({ status: 'reading', source: 'auto', startedAt: null, finishedAt: null }));
+    mockRepo.findSessionBoundariesForBook.mockResolvedValue({ firstStartedAt: null, lastEndedAt: null });
+
+    const result = await service.updateManual(1, 10, { status: 'read' });
+
+    expect(result.startedAt).toBeNull();
+    expect(result.finishedAt).toBeNull();
+  });
 });
 
 describe('bulkSetManual', () => {
diff --git a/server/src/modules/user-book-status/user-book-status.service.ts b/server/src/modules/user-book-status/user-book-status.service.ts
index fea7a58e7..412157b8b 100644
--- a/server/src/modules/user-book-status/user-book-status.service.ts
+++ b/server/src/modules/user-book-status/user-book-status.service.ts
@@ -35,8 +35,25 @@ export class UserBookStatusService {
     const hasFinishedAt = Object.prototype.hasOwnProperty.call(patch, 'finishedAt');
 
     const nextStatus = patch.status ?? existing?.status ?? 'unread';
-    const nextStartedAt = hasStartedAt ? (patch.startedAt ?? null) : (existing?.startedAt ?? null);
-    const nextFinishedAt = hasFinishedAt ? (patch.finishedAt ?? null) : (existing?.finishedAt ?? null);
+    let nextStartedAt = hasStartedAt ? (patch.startedAt ?? null) : (existing?.startedAt ?? null);
+    let nextFinishedAt = hasFinishedAt ? (patch.finishedAt ?? null) : (existing?.finishedAt ?? null);
+
+    // When dates were not explicitly provided and would be null, seed from session history.
+    // Explicit null patches (user clearing a date) are preserved as-is.
+    // Mirror the same status guard used in repo.upsert(): unread/want_to_read always have null dates.
+    const needsStartedAt = !hasStartedAt && nextStartedAt === null && nextStatus !== 'unread' && nextStatus !== 'want_to_read';
+    const needsFinishedAt = !hasFinishedAt && nextFinishedAt === null && nextStatus === 'read';
+    if (needsStartedAt || needsFinishedAt) {
+      const boundaries = await this.repo.findSessionBoundariesForBook(userId, bookId);
+      if (needsStartedAt) nextStartedAt = boundaries.firstStartedAt;
+      if (needsFinishedAt) {
+        const seeded = boundaries.lastEndedAt;
+        // Only apply if the seeded end is not before the current startedAt.
+        if (seeded !== null && (nextStartedAt === null || seeded >= nextStartedAt)) {
+          nextFinishedAt = seeded;
+        }
+      }
+    }
 
     const shouldPersist = existing !== null || hasStatus || nextStartedAt !== null || nextFinishedAt !== null;
     if (shouldPersist) {
diff --git a/server/src/modules/user-statistics/user-statistics.controller.test.ts b/server/src/modules/user-statistics/user-statistics.controller.test.ts
index f4c2e5715..25ecd7d9d 100644
--- a/server/src/modules/user-statistics/user-statistics.controller.test.ts
+++ b/server/src/modules/user-statistics/user-statistics.controller.test.ts
@@ -5,6 +5,7 @@ function makeService() {
     getSummary: vi.fn().mockResolvedValue('summary'),
     getDailyReading: vi.fn().mockResolvedValue('daily'),
     getReadingHeatmap: vi.fn().mockResolvedValue('heatmap'),
+    getReadingSourceDistribution: vi.fn().mockResolvedValue('source-distribution'),
     getPeakReadingHours: vi.fn().mockResolvedValue('peak-hours'),
     getFavoriteReadingDays: vi.fn().mockResolvedValue('favorite-days'),
     getSessionTimeline: vi.fn().mockResolvedValue('timeline'),
@@ -36,6 +37,7 @@ describe('UserStatisticsController', () => {
     await expect(controller.getSummary(user, filter)).resolves.toBe('summary');
     await expect(controller.getDailyReading(user, daily)).resolves.toBe('daily');
     await expect(controller.getReadingHeatmap(user, daily)).resolves.toBe('heatmap');
+    await expect(controller.getReadingSourceDistribution(user, daily)).resolves.toBe('source-distribution');
     await expect(controller.getPeakHours(user, daily)).resolves.toBe('peak-hours');
     await expect(controller.getFavoriteDays(user, daily)).resolves.toBe('favorite-days');
     await expect(controller.getSessionTimeline(user, timeline)).resolves.toBe('timeline');
@@ -54,6 +56,7 @@ describe('UserStatisticsController', () => {
     expect(service.getSummary).toHaveBeenCalledWith(user, filter);
     expect(service.getDailyReading).toHaveBeenCalledWith(user, daily);
     expect(service.getReadingHeatmap).toHaveBeenCalledWith(user, daily);
+    expect(service.getReadingSourceDistribution).toHaveBeenCalledWith(user, daily);
     expect(service.getPeakReadingHours).toHaveBeenCalledWith(user, daily);
     expect(service.getFavoriteReadingDays).toHaveBeenCalledWith(user, daily);
     expect(service.getSessionTimeline).toHaveBeenCalledWith(user, timeline);
diff --git a/server/src/modules/user-statistics/user-statistics.controller.ts b/server/src/modules/user-statistics/user-statistics.controller.ts
index 1db08c48c..807daf397 100644
--- a/server/src/modules/user-statistics/user-statistics.controller.ts
+++ b/server/src/modules/user-statistics/user-statistics.controller.ts
@@ -28,6 +28,11 @@ export class UserStatisticsController {
     return this.userStatisticsService.getReadingHeatmap(user, query);
   }
 
+  @Get('reading-source-distribution')
+  getReadingSourceDistribution(@CurrentUser() user: RequestUser, @Query() query: UserDailyReadingQueryDto) {
+    return this.userStatisticsService.getReadingSourceDistribution(user, query);
+  }
+
   @Get('peak-hours')
   getPeakHours(@CurrentUser() user: RequestUser, @Query() query: UserDailyReadingQueryDto) {
     return this.userStatisticsService.getPeakReadingHours(user, query);
diff --git a/server/src/modules/user-statistics/user-statistics.repository.test.ts b/server/src/modules/user-statistics/user-statistics.repository.test.ts
index 795ee2c52..64a631665 100644
--- a/server/src/modules/user-statistics/user-statistics.repository.test.ts
+++ b/server/src/modules/user-statistics/user-statistics.repository.test.ts
@@ -84,8 +84,8 @@ describe('UserStatisticsRepository', () => {
   it('returns daily/peak/favorite aggregates and monthly completion timeline', async () => {
     const db = makeDb([
       [{ day: '2026-04-15', readingSeconds: 120, progressDelta: 1.5, eventsCount: 2 }],
-      [{ hour: 9, format: 'EPUB', readingSeconds: 500, eventsCount: 3 }],
-      [{ dayOfWeek: 2, readingSeconds: 900, eventsCount: 4 }],
+      [{ hour: 9, format: 'EPUB', source: 'koreader', readingSeconds: 500, eventsCount: 3 }],
+      [{ dayOfWeek: 2, source: 'manual', format: 'EPUB', readingSeconds: 900, eventsCount: 4 }],
       [],
       [{ year: 2026, month: 4, count: 2 }],
       [],
@@ -97,18 +97,39 @@ describe('UserStatisticsRepository', () => {
     await expect(repo.getDailyReadingStats(5, false, [2], 30)).resolves.toEqual([
       { day: '2026-04-15', readingSeconds: 120, progressDelta: 1.5, eventsCount: 2 },
     ]);
-    await expect(repo.getPeakReadingHours(5, false, [2], 30)).resolves.toEqual([{ hour: 9, format: 'EPUB', readingSeconds: 500, eventsCount: 3 }]);
-    await expect(repo.getFavoriteReadingDays(5, false, [2], 30)).resolves.toEqual([{ dayOfWeek: 2, readingSeconds: 900, eventsCount: 4 }]);
+    await expect(repo.getPeakReadingHours(5, false, [2], 30)).resolves.toEqual([
+      { hour: 9, format: 'EPUB', source: 'koreader', readingSeconds: 500, eventsCount: 3 },
+    ]);
+    await expect(repo.getFavoriteReadingDays(5, false, [2], 30)).resolves.toEqual([
+      { dayOfWeek: 2, source: 'manual', format: 'EPUB', readingSeconds: 900, eventsCount: 4 },
+    ]);
     await expect(repo.getCompletionTimeline(5, false, [2], 365)).resolves.toEqual([{ year: 2026, month: 4, count: 2 }]);
     await expect(repo.getMonthlyCompletions(5, false, [2], 365)).resolves.toEqual([{ year: 2026, month: 4, count: 2 }]);
   });
 
+  it('returns per-source daily reading seconds for the heatmap tooltip', async () => {
+    const db = makeDb([
+      [
+        { day: '2026-04-15', source: 'web', readingSeconds: 120 },
+        { day: '2026-04-15', source: 'kobo', readingSeconds: 60 },
+      ],
+    ]);
+    const repo = new UserStatisticsRepository(db as never);
+    vi.spyOn(repo as any, 'getAccessibleLibraryIds').mockResolvedValue([2]);
+
+    await expect(repo.getDailyReadingSecondsBySource(5, false, [2], 30)).resolves.toEqual([
+      { day: '2026-04-15', source: 'web', readingSeconds: 120 },
+      { day: '2026-04-15', source: 'kobo', readingSeconds: 60 },
+    ]);
+  });
+
   it('returns timeline items and timeline session by id', async () => {
     const timelineRow = {
       sessionId: 10,
       bookId: 4,
       bookTitle: 'Dune',
       bookFormat: 'EPUB',
+      source: 'koreader',
       startedAt: new Date('2026-04-15T10:00:00.000Z'),
       endedAt: new Date('2026-04-15T10:30:00.000Z'),
       durationSeconds: 1800,
@@ -129,6 +150,7 @@ describe('UserStatisticsRepository', () => {
         bookId: 4,
         bookTitle: 'Dune',
         bookFormat: 'EPUB',
+        source: 'koreader',
         startedAt: new Date('2026-04-15T10:00:00.000Z'),
         endedAt: new Date('2026-04-15T10:30:00.000Z'),
         durationSeconds: 1800,
@@ -155,6 +177,7 @@ describe('UserStatisticsRepository', () => {
       10,
       3,
       new Date('2026-04-15T09:00:00.000Z'),
+      new Date('2026-04-15T09:30:00.000Z'),
       new Date('2026-04-15T10:20:00.000Z'),
       new Date('2026-04-15T10:50:00.000Z'),
       1800,
@@ -194,6 +217,7 @@ describe('UserStatisticsRepository', () => {
       10,
       3,
       new Date('2026-04-15T09:00:00.000Z'),
+      new Date('2026-04-15T09:30:00.000Z'),
       new Date('2026-04-15T10:00:00.000Z'),
       new Date('2026-04-15T10:30:00.000Z'),
       1800,
@@ -210,13 +234,19 @@ describe('UserStatisticsRepository', () => {
       bookId: 4,
       bookTitle: 'Dune',
       bookFormat: 'EPUB',
+      source: 'web',
       startedAt: new Date('2026-04-15T11:00:00.000Z'),
       endedAt: new Date('2026-04-15T11:30:00.000Z'),
       durationSeconds: 1800,
     };
-    const txSelectQueue = [[], [updatedRow]];
+    const txSelectQueue = [
+      [],
+      [{ startedAt: new Date('2026-04-15T11:00:00.000Z'), endedAt: new Date('2026-04-15T11:30:00.000Z'), durationSeconds: 1800, progressDelta: 3 }],
+      [updatedRow],
+    ];
     const returning = vi.fn().mockResolvedValue([{ id: 10 }]);
     const deleteWhere = vi.fn().mockResolvedValue(undefined);
+    const dailyValues = vi.fn().mockReturnValue({ onConflictDoUpdate: vi.fn().mockResolvedValue(undefined) });
     const tx = {
       execute: vi.fn().mockResolvedValue(undefined),
       select: vi.fn((fields?: Record<string, unknown>) => makeChain(txSelectQueue.shift() ?? [], fields)),
@@ -230,6 +260,9 @@ describe('UserStatisticsRepository', () => {
       delete: vi.fn().mockReturnValue({
         where: deleteWhere,
       }),
+      insert: vi.fn().mockReturnValue({
+        values: dailyValues,
+      }),
     };
     const db = {
       transaction: vi.fn(async (callback: (trx: typeof tx) => Promise<unknown>) => callback(tx)),
@@ -241,6 +274,7 @@ describe('UserStatisticsRepository', () => {
       10,
       3,
       new Date('2026-04-14T09:00:00.000Z'),
+      new Date('2026-04-14T09:30:00.000Z'),
       new Date('2026-04-15T11:00:00.000Z'),
       new Date('2026-04-15T11:30:00.000Z'),
       1800,
@@ -248,7 +282,9 @@ describe('UserStatisticsRepository', () => {
 
     expect(result).toEqual({ updated: updatedRow, conflict: null });
     expect(deleteWhere).toHaveBeenCalledOnce();
-    expect(tx.execute).toHaveBeenCalledTimes(2);
+    expect(dailyValues).toHaveBeenCalledWith([
+      expect.objectContaining({ day: '2026-04-15', readingSeconds: 1800, progressDelta: 3, sessionsCount: 1 }),
+    ]);
   });
 
   it('returns progress funnel values and defaults when aggregate row is missing', async () => {
@@ -280,7 +316,7 @@ describe('UserStatisticsRepository', () => {
       [],
       [],
       [{ days: '3.5' }, { days: -1 }, { days: 'not-a-number' }, { days: 7 }],
-      [{ durationSeconds: 300, progressDelta: 1.25 }],
+      [{ durationSeconds: 300, progressDelta: 1.25, source: 'kobo', format: 'PDF' }],
       [],
       [{ maxProgress: 50 }, { maxProgress: 'bad' }],
       [{ bookId: 1 }],
@@ -289,20 +325,22 @@ describe('UserStatisticsRepository', () => {
         { bookId: 1, title: 'Dune', startedAt: new Date('2026-04-02T10:00:00.000Z'), endProgress: 70 },
       ],
       [{ hour: '9.5', durationMinutes: '15', dayOfWeek: '2' }],
-      [{ genre: 'Sci-Fi', readingSeconds: 1200 }],
+      [{ genre: 'Sci-Fi', source: 'web', readingSeconds: 1200 }],
     ]);
     const repo = new UserStatisticsRepository(db as never);
     vi.spyOn(repo as any, 'getAccessibleLibraryIds').mockResolvedValue([1]);
 
     await expect(repo.getCompletionLatencyDays(5, false, [1], 365)).resolves.toEqual([3.5, 7]);
-    await expect(repo.getReadingPacePoints(5, false, [1], 365)).resolves.toEqual([{ durationSeconds: 300, progressDelta: 1.25 }]);
+    await expect(repo.getReadingPacePoints(5, false, [1], 365)).resolves.toEqual([
+      { durationSeconds: 300, progressDelta: 1.25, bucket: 'kobo', format: 'PDF' },
+    ]);
     await expect(repo.getReadingSurvivalMaxProgress(5, false, [1], 365)).resolves.toEqual([50]);
     await expect(repo.getCompletionRaceRawSessions(5, false, [1], 365, 15)).resolves.toEqual([
       { bookId: 1, title: 'Dune', startedAt: new Date('2026-04-01T10:00:00.000Z'), endProgress: 40 },
       { bookId: 1, title: 'Dune', startedAt: new Date('2026-04-02T10:00:00.000Z'), endProgress: 70 },
     ]);
     await expect(repo.getSessionArchetypePoints(5, false, [1], 365)).resolves.toEqual([{ hour: 9.5, durationMinutes: 15, dayOfWeek: 2 }]);
-    await expect(repo.getGenreReadingTime(5, false, [1], 365)).resolves.toEqual([{ genre: 'Sci-Fi', readingSeconds: 1200 }]);
+    await expect(repo.getGenreReadingTime(5, false, [1], 365)).resolves.toEqual([{ genre: 'Sci-Fi', source: 'web', readingSeconds: 1200 }]);
   });
 
   it('returns empty completion race when no top books exist', async () => {
@@ -328,20 +366,45 @@ describe('UserStatisticsRepository', () => {
     });
   });
 
-  it('recomputes recent daily stats inside a transaction and returns row counts', async () => {
+  it('recomputes recent daily stats with timezone-aware day segments inside a transaction', async () => {
+    const dailyValues = vi.fn().mockReturnValue({ onConflictDoUpdate: vi.fn().mockResolvedValue(undefined) });
+    const txSelectQueue = [
+      [],
+      [{ userId: 5, libraryId: 3, settings: { timezone: 'Asia/Kolkata' } }],
+      [
+        {
+          startedAt: new Date('2026-04-13T19:00:00.000Z'),
+          endedAt: new Date('2026-04-13T20:00:00.000Z'),
+          durationSeconds: 3600,
+          progressDelta: 2,
+        },
+      ],
+    ];
+    const tx = {
+      execute: vi.fn().mockResolvedValueOnce({ rowCount: 0 }).mockResolvedValueOnce({ rowCount: 4 }),
+      select: vi.fn((fields?: Record<string, unknown>) => makeChain(txSelectQueue.shift() ?? [], fields)),
+      insert: vi.fn().mockReturnValue({ values: dailyValues }),
+    };
     const db = {
-      transaction: vi.fn(async (callback: (tx: { execute: ReturnType<typeof vi.fn> }) => Promise<unknown>) =>
-        callback({
-          execute: vi.fn().mockResolvedValueOnce({ rowCount: 4 }).mockResolvedValueOnce({ rowCount: 7 }),
-        }),
-      ),
+      transaction: vi.fn(async (callback: (trx: typeof tx) => Promise<unknown>) => callback(tx)),
     };
     const repo = new UserStatisticsRepository(db as never);
 
     await expect(repo.recomputeRecentDailyStats(2)).resolves.toEqual({
       deleted: 4,
-      inserted: 7,
+      inserted: 1,
       since: '2026-04-14',
     });
+    expect(tx.execute).toHaveBeenCalledTimes(2);
+    expect(dailyValues).toHaveBeenCalledWith([
+      expect.objectContaining({
+        userId: 5,
+        libraryId: 3,
+        day: '2026-04-14',
+        readingSeconds: 3600,
+        progressDelta: 2,
+        sessionsCount: 1,
+      }),
+    ]);
   });
 });
diff --git a/server/src/modules/user-statistics/user-statistics.repository.ts b/server/src/modules/user-statistics/user-statistics.repository.ts
index 7ef51d59f..67da32534 100644
--- a/server/src/modules/user-statistics/user-statistics.repository.ts
+++ b/server/src/modules/user-statistics/user-statistics.repository.ts
@@ -4,16 +4,23 @@ import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 import type {
   ChordDiagramData,
+  ReadingSessionSource,
   UserCompletionTimelinePoint,
   UserDailyReadingStat,
-  UserFavoriteDayStat,
-  UserGenreReadingTimeItem,
   UserProgressFunnel,
   UserReadingPacePoint,
   UserSessionArchetypePoint,
   UserStatisticsSummary,
 } from '@bookorbit/types';
+import { toReadingSessionSourceBucket } from '@bookorbit/types';
 
+import {
+  aggregateReadingSessionDailyStats,
+  getDayRangeForDateKeys,
+  getReadingSessionDayKeys,
+  type ReadingDailyStatsSegment,
+} from '../../common/utils/reading-daily-stats.utils';
+import { resolveTimeZone } from '../../common/utils/timezone.utils';
 import { DB } from '../../db';
 import * as schema from '../../db/schema';
 import {
@@ -27,14 +34,17 @@ import {
   userBookStatus,
   userLibraryAccess,
   userReadingDailyStats,
+  users,
 } from '../../db/schema';
 
 type Db = NodePgDatabase<typeof schema>;
+type Tx = Parameters<Parameters<Db['transaction']>[0]>[0];
 type SessionTimelineItemRow = {
   sessionId: number;
   bookId: number;
   bookTitle: string | null;
   bookFormat: string | null;
+  source: ReadingSessionSource | null;
   startedAt: Date;
   endedAt: Date;
   durationSeconds: number;
@@ -161,7 +171,7 @@ export class UserStatisticsRepository {
     isSuperuser: boolean,
     filterLibraryIds?: number[],
     days = 365,
-  ): Promise<{ hour: number; format: string; readingSeconds: number; eventsCount: number }[]> {
+  ): Promise<{ hour: number; format: string; source: ReadingSessionSource | null; readingSeconds: number; eventsCount: number }[]> {
     const accessible = await this.getAccessibleLibraryIds(userId, isSuperuser);
     const libraryFilter = this.libraryFilter(this.intersectLibraryIds(accessible, filterLibraryIds));
     const since = this.sinceDateForDays(days);
@@ -172,14 +182,15 @@ export class UserStatisticsRepository {
       .select({
         hour: hourExpr,
         format: formatExpr,
+        source: readingSessions.source,
         readingSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::int`,
         eventsCount: sql<number>`count(*)::int`,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), libraryFilter))
-      .groupBy(hourExpr, formatExpr)
+      .groupBy(hourExpr, formatExpr, readingSessions.source)
       .orderBy(hourExpr);
   }
 
@@ -197,17 +208,18 @@ export class UserStatisticsRepository {
     return this.db
       .select({
         sessionId: readingSessions.id,
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         bookTitle: bookMetadata.title,
         bookFormat: sql<string | null>`nullif(${bookFiles.format}, '')`,
+        source: readingSessions.source,
         startedAt: readingSessions.startedAt,
         endedAt: readingSessions.endedAt,
         durationSeconds: readingSessions.durationSeconds,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
-      .leftJoin(bookMetadata, eq(bookMetadata.bookId, bookFiles.bookId))
+      .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, readingSessions.bookId))
       .where(
         and(
           eq(readingSessions.userId, userId),
@@ -233,17 +245,18 @@ export class UserStatisticsRepository {
       .select({
         sessionId: readingSessions.id,
         libraryId: books.libraryId,
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         bookTitle: bookMetadata.title,
         bookFormat: sql<string | null>`nullif(${bookFiles.format}, '')`,
+        source: readingSessions.source,
         startedAt: readingSessions.startedAt,
         endedAt: readingSessions.endedAt,
         durationSeconds: readingSessions.durationSeconds,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
-      .leftJoin(bookMetadata, eq(bookMetadata.bookId, bookFiles.bookId))
+      .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), eq(readingSessions.id, sessionId), libraryFilter))
       .limit(1);
 
@@ -255,9 +268,11 @@ export class UserStatisticsRepository {
     sessionId: number,
     libraryId: number,
     previousStartedAt: Date,
+    previousEndedAt: Date,
     startedAt: Date,
     endedAt: Date,
     durationSeconds: number,
+    timeZone = 'UTC',
   ): Promise<{ updated: SessionTimelineSessionRow | null; conflict: SessionTimelineConflictRow | null }> {
     return this.db.transaction(async (tx) => {
       // Serialize edits per user to avoid race conditions between concurrent drags.
@@ -290,58 +305,32 @@ export class UserStatisticsRepository {
         .returning({ id: readingSessions.id });
       if (touched.length === 0) return { updated: null, conflict: null };
 
-      const uniqueDays = [...new Set([this.formatDayKey(previousStartedAt), this.formatDayKey(startedAt)])];
+      const uniqueDays = [
+        ...new Set([
+          ...getReadingSessionDayKeys({ startedAt: previousStartedAt, endedAt: previousEndedAt, durationSeconds, progressDelta: null }, timeZone),
+          ...getReadingSessionDayKeys({ startedAt, endedAt, durationSeconds, progressDelta: null }, timeZone),
+        ]),
+      ];
       if (uniqueDays.length > 0) {
-        const dayDateList = sql.join(
-          uniqueDays.map((day) => sql`${day}::date`),
-          sql`, `,
-        );
-
-        await tx
-          .delete(userReadingDailyStats)
-          .where(
-            and(
-              eq(userReadingDailyStats.userId, userId),
-              eq(userReadingDailyStats.libraryId, libraryId),
-              inArray(userReadingDailyStats.day, uniqueDays),
-            ),
-          );
-
-        await tx.execute(sql`
-          insert into user_reading_daily_stats (user_id, library_id, day, reading_seconds, progress_delta, sessions_count, updated_at)
-          select
-            rs.user_id,
-            b.library_id,
-            date_trunc('day', rs.started_at)::date as day,
-            coalesce(sum(rs.duration_seconds), 0)::int as reading_seconds,
-            coalesce(sum(rs.progress_delta), 0)::real as progress_delta,
-            count(*)::int as sessions_count,
-            now() as updated_at
-          from reading_sessions rs
-          inner join book_files bf on bf.id = rs.book_file_id
-          inner join books b on b.id = bf.book_id
-          where rs.user_id = ${userId}
-            and b.library_id = ${libraryId}
-            and date_trunc('day', rs.started_at)::date in (${dayDateList})
-          group by rs.user_id, b.library_id, date_trunc('day', rs.started_at)::date
-        `);
+        await this.recomputeDailyStats(tx, userId, libraryId, uniqueDays, timeZone);
       }
 
       const [updated] = await tx
         .select({
           sessionId: readingSessions.id,
           libraryId: books.libraryId,
-          bookId: bookFiles.bookId,
+          bookId: readingSessions.bookId,
           bookTitle: bookMetadata.title,
           bookFormat: sql<string | null>`nullif(${bookFiles.format}, '')`,
+          source: readingSessions.source,
           startedAt: readingSessions.startedAt,
           endedAt: readingSessions.endedAt,
           durationSeconds: readingSessions.durationSeconds,
         })
         .from(readingSessions)
-        .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-        .innerJoin(books, eq(books.id, bookFiles.bookId))
-        .leftJoin(bookMetadata, eq(bookMetadata.bookId, bookFiles.bookId))
+        .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
+        .leftJoin(bookMetadata, eq(bookMetadata.bookId, readingSessions.bookId))
         .where(and(eq(readingSessions.userId, userId), eq(readingSessions.id, sessionId)))
         .limit(1);
 
@@ -349,23 +338,113 @@ export class UserStatisticsRepository {
     });
   }
 
-  async getFavoriteReadingDays(userId: number, isSuperuser: boolean, filterLibraryIds?: number[], days = 365): Promise<UserFavoriteDayStat[]> {
+  private async recomputeDailyStats(tx: Tx, userId: number, libraryId: number, days: string[], timeZone: string): Promise<void> {
+    const affectedDays = [...new Set(days)].sort();
+    if (affectedDays.length === 0) return;
+
+    await this.lockDailyStats(tx, userId, libraryId);
+
+    await tx
+      .delete(userReadingDailyStats)
+      .where(
+        and(
+          eq(userReadingDailyStats.userId, userId),
+          eq(userReadingDailyStats.libraryId, libraryId),
+          inArray(userReadingDailyStats.day, affectedDays),
+        ),
+      );
+
+    const range = getDayRangeForDateKeys(affectedDays, timeZone);
+    if (!range) return;
+
+    const rows = await tx
+      .select({
+        startedAt: readingSessions.startedAt,
+        endedAt: readingSessions.endedAt,
+        durationSeconds: readingSessions.durationSeconds,
+        progressDelta: readingSessions.progressDelta,
+      })
+      .from(readingSessions)
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
+      .where(
+        and(
+          eq(readingSessions.userId, userId),
+          eq(books.libraryId, libraryId),
+          lt(readingSessions.startedAt, range.end),
+          gt(readingSessions.endedAt, range.start),
+        ),
+      );
+
+    const segments = aggregateReadingSessionDailyStats(
+      rows.map((row) => ({
+        startedAt: row.startedAt,
+        endedAt: row.endedAt,
+        durationSeconds: row.durationSeconds,
+        progressDelta: row.progressDelta ?? null,
+      })),
+      timeZone,
+      new Set(affectedDays),
+    );
+    await this.insertDailyStatsSegments(tx, userId, libraryId, segments);
+  }
+
+  private async lockDailyStats(tx: Tx, userId: number, libraryId: number): Promise<void> {
+    await tx.execute(sql`select pg_advisory_xact_lock(${userId}::int, ${libraryId}::int)`);
+  }
+
+  private async insertDailyStatsSegments(tx: Tx, userId: number, libraryId: number, segments: ReadingDailyStatsSegment[]): Promise<void> {
+    if (segments.length === 0) return;
+
+    const now = new Date();
+    await tx
+      .insert(userReadingDailyStats)
+      .values(
+        segments.map((segment) => ({
+          userId,
+          libraryId,
+          day: segment.day,
+          readingSeconds: segment.readingSeconds,
+          progressDelta: segment.progressDelta,
+          sessionsCount: segment.sessionsCount,
+          updatedAt: now,
+        })),
+      )
+      .onConflictDoUpdate({
+        target: [userReadingDailyStats.userId, userReadingDailyStats.libraryId, userReadingDailyStats.day],
+        set: {
+          readingSeconds: sql`excluded.reading_seconds`,
+          progressDelta: sql`excluded.progress_delta`,
+          sessionsCount: sql`excluded.sessions_count`,
+          updatedAt: now,
+        },
+      });
+  }
+
+  async getFavoriteReadingDays(
+    userId: number,
+    isSuperuser: boolean,
+    filterLibraryIds?: number[],
+    days = 365,
+  ): Promise<{ dayOfWeek: number; source: ReadingSessionSource | null; format: string; readingSeconds: number; eventsCount: number }[]> {
     const accessible = await this.getAccessibleLibraryIds(userId, isSuperuser);
     const libraryFilter = this.libraryFilter(this.intersectLibraryIds(accessible, filterLibraryIds));
     const since = this.sinceDateForDays(days);
     const dayOfWeekExpr = sql<number>`extract(dow from ${readingSessions.startedAt})::int`;
+    const formatExpr = sql<string>`upper(coalesce(${bookFiles.format}, 'UNKNOWN'))`;
 
     return this.db
       .select({
         dayOfWeek: dayOfWeekExpr,
+        source: readingSessions.source,
+        format: formatExpr,
         readingSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::int`,
         eventsCount: sql<number>`count(*)::int`,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), libraryFilter))
-      .groupBy(dayOfWeekExpr)
+      .groupBy(dayOfWeekExpr, readingSessions.source, formatExpr)
       .orderBy(dayOfWeekExpr);
   }
 
@@ -381,14 +460,13 @@ export class UserStatisticsRepository {
 
     const firstCompletion = this.db
       .select({
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         firstCompletedAt: sql<Date>`min(${readingSessions.endedAt})`.as('first_completed_at'),
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.endProgress, 99), libraryFilter))
-      .groupBy(bookFiles.bookId)
+      .groupBy(readingSessions.bookId)
       .as('first_completion');
 
     const yearExpr = sql<number>`extract(year from ${firstCompletion.firstCompletedAt})::int`;
@@ -425,14 +503,13 @@ export class UserStatisticsRepository {
 
     const perBookProgress = this.db
       .select({
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         maxPercentage: sql<number>`max(${readingSessions.endProgress})`.as('max_percentage'),
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), timeFilter, libraryFilter, isNotNull(readingSessions.endProgress)))
-      .groupBy(bookFiles.bookId)
+      .groupBy(readingSessions.bookId)
       .as('per_book_progress');
 
     const [row] = await this.db
@@ -461,14 +538,13 @@ export class UserStatisticsRepository {
 
     const completedInWindow = this.db
       .select({
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         completedAt: sql<Date>`min(${readingSessions.endedAt})`.as('completed_at'),
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), gte(readingSessions.endProgress, 99), libraryFilter))
-      .groupBy(bookFiles.bookId)
+      .groupBy(readingSessions.bookId)
       .as('completed_in_window');
 
     const startedAndCompleted = this.db
@@ -477,8 +553,7 @@ export class UserStatisticsRepository {
         startedAt: sql<Date | null>`min(${readingSessions.startedAt})`.as('started_at'),
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(completedInWindow, eq(completedInWindow.bookId, bookFiles.bookId))
+      .innerJoin(completedInWindow, eq(completedInWindow.bookId, readingSessions.bookId))
       .where(eq(readingSessions.userId, userId))
       .groupBy(completedInWindow.bookId, completedInWindow.completedAt)
       .as('started_and_completed');
@@ -495,25 +570,53 @@ export class UserStatisticsRepository {
       .filter((daysValue) => Number.isFinite(daysValue) && daysValue >= 0);
   }
 
-  async getGenreReadingTime(userId: number, isSuperuser: boolean, filterLibraryIds?: number[], days = 365): Promise<UserGenreReadingTimeItem[]> {
+  async getGenreReadingTime(
+    userId: number,
+    isSuperuser: boolean,
+    filterLibraryIds?: number[],
+    days = 365,
+  ): Promise<{ genre: string; source: ReadingSessionSource | null; readingSeconds: number }[]> {
     const accessible = await this.getAccessibleLibraryIds(userId, isSuperuser);
     const libraryFilter = this.libraryFilter(this.intersectLibraryIds(accessible, filterLibraryIds));
     const since = this.sinceDateForDays(days);
 
+    // Grouped by source so the genre treemap can show a per-source tooltip breakdown;
+    // the top-N limit and ordering are applied in the service after folding by genre.
     return this.db
       .select({
         genre: genres.name,
+        source: readingSessions.source,
         readingSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::int`,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .innerJoin(bookGenres, eq(bookGenres.bookId, books.id))
       .innerJoin(genres, eq(genres.id, bookGenres.genreId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), libraryFilter))
-      .groupBy(genres.name)
-      .orderBy(sql`sum(${readingSessions.durationSeconds}) desc`)
-      .limit(30);
+      .groupBy(genres.name, readingSessions.source);
+  }
+
+  async getDailyReadingSecondsBySource(
+    userId: number,
+    isSuperuser: boolean,
+    filterLibraryIds: number[] | undefined,
+    days: number,
+  ): Promise<{ day: string; source: ReadingSessionSource | null; readingSeconds: number }[]> {
+    const accessible = await this.getAccessibleLibraryIds(userId, isSuperuser);
+    const libraryFilter = this.libraryFilter(this.intersectLibraryIds(accessible, filterLibraryIds));
+    const since = this.sinceDateForDays(days);
+    const dayExpr = sql<string>`date_trunc('day', ${readingSessions.startedAt})::date::text`;
+
+    return this.db
+      .select({
+        day: dayExpr,
+        source: readingSessions.source,
+        readingSeconds: sql<number>`coalesce(sum(${readingSessions.durationSeconds}), 0)::int`,
+      })
+      .from(readingSessions)
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
+      .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), libraryFilter))
+      .groupBy(dayExpr, readingSessions.source);
   }
 
   async getReadingPacePoints(userId: number, isSuperuser: boolean, filterLibraryIds?: number[], days = 1825): Promise<UserReadingPacePoint[]> {
@@ -525,10 +628,12 @@ export class UserStatisticsRepository {
       .select({
         durationSeconds: readingSessions.durationSeconds,
         progressDelta: readingSessions.progressDelta,
+        source: readingSessions.source,
+        format: sql<string>`upper(coalesce(${bookFiles.format}, 'UNKNOWN'))`,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .leftJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(
         and(
           eq(readingSessions.userId, userId),
@@ -541,7 +646,12 @@ export class UserStatisticsRepository {
       .orderBy(readingSessions.startedAt)
       .limit(2000);
 
-    return rows.map((r) => ({ durationSeconds: r.durationSeconds, progressDelta: r.progressDelta! }));
+    return rows.map((r) => ({
+      durationSeconds: r.durationSeconds,
+      progressDelta: r.progressDelta!,
+      bucket: toReadingSessionSourceBucket(r.source),
+      format: r.format,
+    }));
   }
 
   async getReadingSurvivalMaxProgress(userId: number, isSuperuser: boolean, filterLibraryIds?: number[], days = 1825): Promise<number[]> {
@@ -551,14 +661,13 @@ export class UserStatisticsRepository {
 
     const perBook = this.db
       .select({
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         maxProgress: sql<number>`max(${readingSessions.endProgress})`.as('max_progress'),
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), isNotNull(readingSessions.endProgress), libraryFilter))
-      .groupBy(bookFiles.bookId)
+      .groupBy(readingSessions.bookId)
       .as('per_book');
 
     const rows = await this.db.select({ maxProgress: perBook.maxProgress }).from(perBook);
@@ -577,12 +686,11 @@ export class UserStatisticsRepository {
     const since = this.sinceDateForDays(days);
 
     const topBookIds = await this.db
-      .select({ bookId: bookFiles.bookId })
+      .select({ bookId: readingSessions.bookId })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), isNotNull(readingSessions.endProgress), libraryFilter))
-      .groupBy(bookFiles.bookId)
+      .groupBy(readingSessions.bookId)
       .orderBy(sql`count(*) desc`)
       .limit(limit)
       .then((rows) => rows.map((r) => r.bookId));
@@ -591,16 +699,15 @@ export class UserStatisticsRepository {
 
     return this.db
       .select({
-        bookId: bookFiles.bookId,
+        bookId: readingSessions.bookId,
         title: bookMetadata.title,
         startedAt: readingSessions.startedAt,
         endProgress: readingSessions.endProgress,
       })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .leftJoin(bookMetadata, eq(bookMetadata.bookId, bookFiles.bookId))
-      .where(and(eq(readingSessions.userId, userId), inArray(bookFiles.bookId, topBookIds), isNotNull(readingSessions.endProgress)))
-      .orderBy(bookFiles.bookId, readingSessions.startedAt)
+      .leftJoin(bookMetadata, eq(bookMetadata.bookId, readingSessions.bookId))
+      .where(and(eq(readingSessions.userId, userId), inArray(readingSessions.bookId, topBookIds), isNotNull(readingSessions.endProgress)))
+      .orderBy(readingSessions.bookId, readingSessions.startedAt)
       .then((rows) => rows.map((r) => ({ ...r, endProgress: r.endProgress! })));
   }
 
@@ -621,8 +728,7 @@ export class UserStatisticsRepository {
     const rows = await this.db
       .select({ hour: hourExpr, durationMinutes: durationExpr, dayOfWeek: dowExpr })
       .from(readingSessions)
-      .innerJoin(bookFiles, eq(bookFiles.id, readingSessions.bookFileId))
-      .innerJoin(books, eq(books.id, bookFiles.bookId))
+      .innerJoin(books, eq(books.id, readingSessions.bookId))
       .where(and(eq(readingSessions.userId, userId), gte(readingSessions.startedAt, since), gte(readingSessions.durationSeconds, 300), libraryFilter))
       .orderBy(readingSessions.startedAt)
       .limit(2000);
@@ -653,8 +759,7 @@ export class UserStatisticsRepository {
       with top_authors as (
         select a.name, sum(rs.duration_seconds) as total
         from reading_sessions rs
-        inner join book_files bf on bf.id = rs.book_file_id
-        inner join books b on b.id = bf.book_id
+        inner join books b on b.id = rs.book_id
         inner join book_authors ba on ba.book_id = b.id
         inner join authors a on a.id = ba.author_id
         where rs.user_id = ${userId}
@@ -667,8 +772,7 @@ export class UserStatisticsRepository {
       top_genres as (
         select g.name, sum(rs.duration_seconds) as total
         from reading_sessions rs
-        inner join book_files bf on bf.id = rs.book_file_id
-        inner join books b on b.id = bf.book_id
+        inner join books b on b.id = rs.book_id
         inner join book_genres bg on bg.book_id = b.id
         inner join genres g on g.id = bg.genre_id
         where rs.user_id = ${userId}
@@ -683,8 +787,7 @@ export class UserStatisticsRepository {
         g.name as genre,
         sum(rs.duration_seconds)::int as reading_seconds
       from reading_sessions rs
-      inner join book_files bf on bf.id = rs.book_file_id
-      inner join books b on b.id = bf.book_id
+      inner join books b on b.id = rs.book_id
       inner join book_authors ba on ba.book_id = b.id
       inner join top_authors a on a.name = (
         select a2.name from book_authors ba2 inner join authors a2 on a2.id = ba2.author_id where ba2.book_id = b.id order by ba2.display_order, ba2.author_id limit 1
@@ -714,29 +817,80 @@ export class UserStatisticsRepository {
 
   async recomputeRecentDailyStats(days = RECENT_DAILY_AGGREGATION_DAYS): Promise<{ deleted: number; inserted: number; since: string }> {
     const sinceDay = this.sinceDateForDays(days).toISOString().slice(0, 10);
+    const broadSince = new Date(Date.parse(`${sinceDay}T00:00:00.000Z`) - 14 * 60 * 60 * 1000);
 
     return this.db.transaction(async (tx) => {
-      const deleteResult = await tx.execute(sql`delete from user_reading_daily_stats where day >= ${sinceDay}::date`);
+      const existingGroups = await tx
+        .select({
+          userId: userReadingDailyStats.userId,
+          libraryId: userReadingDailyStats.libraryId,
+          settings: users.settings,
+        })
+        .from(userReadingDailyStats)
+        .innerJoin(users, eq(users.id, userReadingDailyStats.userId))
+        .where(gte(userReadingDailyStats.day, sinceDay))
+        .groupBy(userReadingDailyStats.userId, userReadingDailyStats.libraryId, users.settings);
 
-      const insertResult = await tx.execute(sql`
-        insert into user_reading_daily_stats (user_id, library_id, day, reading_seconds, progress_delta, sessions_count, updated_at)
-        select
-          rs.user_id,
-          b.library_id,
-          date_trunc('day', rs.started_at)::date as day,
-          coalesce(sum(rs.duration_seconds), 0)::int as reading_seconds,
-          coalesce(sum(rs.progress_delta), 0)::real as progress_delta,
-          count(*)::int as sessions_count,
-          now() as updated_at
-        from reading_sessions rs
-        inner join book_files bf on bf.id = rs.book_file_id
-        inner join books b on b.id = bf.book_id
-        where rs.started_at >= ${sinceDay}::timestamp
-        group by rs.user_id, b.library_id, date_trunc('day', rs.started_at)::date
-      `);
+      const sessionGroups = await tx
+        .select({
+          userId: readingSessions.userId,
+          libraryId: books.libraryId,
+          settings: users.settings,
+        })
+        .from(readingSessions)
+        .innerJoin(books, eq(books.id, readingSessions.bookId))
+        .innerJoin(users, eq(users.id, readingSessions.userId))
+        .where(gt(readingSessions.endedAt, broadSince))
+        .groupBy(readingSessions.userId, books.libraryId, users.settings);
+
+      const groups = new Map<string, { userId: number; libraryId: number; settings: unknown }>();
+      for (const group of [...existingGroups, ...sessionGroups]) {
+        groups.set(`${group.userId}:${group.libraryId}`, group);
+      }
+
+      let deleted = 0;
+      let inserted = 0;
+
+      for (const group of groups.values()) {
+        await this.lockDailyStats(tx, group.userId, group.libraryId);
+
+        const deleteResult = await tx.execute(sql`
+          delete from user_reading_daily_stats
+          where user_id = ${group.userId}
+            and library_id = ${group.libraryId}
+            and day >= ${sinceDay}::date
+        `);
+        deleted += Number((deleteResult as { rowCount?: number }).rowCount ?? 0);
+
+        const timeZone = resolveTimeZone((group.settings as { timezone?: unknown } | undefined)?.timezone, 'UTC');
+        const range = getDayRangeForDateKeys([sinceDay], timeZone);
+        if (!range) continue;
+
+        const rows = await tx
+          .select({
+            startedAt: readingSessions.startedAt,
+            endedAt: readingSessions.endedAt,
+            durationSeconds: readingSessions.durationSeconds,
+            progressDelta: readingSessions.progressDelta,
+          })
+          .from(readingSessions)
+          .innerJoin(books, eq(books.id, readingSessions.bookId))
+          .where(and(eq(readingSessions.userId, group.userId), eq(books.libraryId, group.libraryId), gt(readingSessions.endedAt, range.start)));
+
+        const segments = aggregateReadingSessionDailyStats(
+          rows.map((row) => ({
+            startedAt: row.startedAt,
+            endedAt: row.endedAt,
+            durationSeconds: row.durationSeconds,
+            progressDelta: row.progressDelta ?? null,
+          })),
+          timeZone,
+        ).filter((segment) => segment.day >= sinceDay);
+
+        await this.insertDailyStatsSegments(tx, group.userId, group.libraryId, segments);
+        inserted += segments.length;
+      }
 
-      const deleted = Number((deleteResult as { rowCount?: number }).rowCount ?? 0);
-      const inserted = Number((insertResult as { rowCount?: number }).rowCount ?? 0);
       return { deleted, inserted, since: sinceDay };
     });
   }
diff --git a/server/src/modules/user-statistics/user-statistics.service.test.ts b/server/src/modules/user-statistics/user-statistics.service.test.ts
index e8e7a3fb6..8634b03f2 100644
--- a/server/src/modules/user-statistics/user-statistics.service.test.ts
+++ b/server/src/modules/user-statistics/user-statistics.service.test.ts
@@ -38,24 +38,64 @@ describe('UserStatisticsService', () => {
   it('returns a contiguous daily heatmap window with zero-filled days', async () => {
     const repo = {
       getDailyReadingStats: vi.fn().mockResolvedValue([{ day: '2026-04-06', readingSeconds: 120, progressDelta: 1.23456, eventsCount: 2 }]),
+      getDailyReadingSecondsBySource: vi.fn().mockResolvedValue([
+        { day: '2026-04-06', source: 'web', readingSeconds: 90 },
+        { day: '2026-04-06', source: 'kobo', readingSeconds: 30 },
+      ]),
     };
 
     const service = new UserStatisticsService(repo as any);
     const result = await service.getReadingHeatmap({ id: 123, isSuperuser: false } as any, { days: 3, libraryIds: [] });
 
     expect(repo.getDailyReadingStats).toHaveBeenCalledWith(123, false, [], 3);
+    expect(repo.getDailyReadingSecondsBySource).toHaveBeenCalledWith(123, false, [], 3);
     expect(result).toEqual([
-      { day: '2026-04-06', readingSeconds: 120, progressDelta: 1.2346, eventsCount: 2 },
-      { day: '2026-04-07', readingSeconds: 0, progressDelta: 0, eventsCount: 0 },
-      { day: '2026-04-08', readingSeconds: 0, progressDelta: 0, eventsCount: 0 },
+      { day: '2026-04-06', readingSeconds: 120, progressDelta: 1.2346, eventsCount: 2, bySource: { bookorbit: 90, koreader: 0, kobo: 30 } },
+      { day: '2026-04-07', readingSeconds: 0, progressDelta: 0, eventsCount: 0, bySource: { bookorbit: 0, koreader: 0, kobo: 0 } },
+      { day: '2026-04-08', readingSeconds: 0, progressDelta: 0, eventsCount: 0, bySource: { bookorbit: 0, koreader: 0, kobo: 0 } },
     ]);
   });
 
+  it('buckets the reading-source distribution and excludes empty buckets', async () => {
+    const repo = {
+      getDailyReadingSecondsBySource: vi.fn().mockResolvedValue([
+        { day: '2026-04-06', source: 'web', readingSeconds: 100 },
+        { day: '2026-04-06', source: 'manual', readingSeconds: 50 },
+        { day: '2026-04-07', source: null, readingSeconds: 30 },
+        { day: '2026-04-06', source: 'kobo', readingSeconds: 200 },
+      ]),
+    };
+
+    const service = new UserStatisticsService(repo as any);
+    const result = await service.getReadingSourceDistribution({ id: 123, isSuperuser: false } as any, { libraryIds: [] });
+
+    expect(repo.getDailyReadingSecondsBySource).toHaveBeenCalledWith(123, false, [], 365);
+    // web + manual + null collapse into bookorbit; koreader has no activity and is omitted.
+    expect(result).toEqual({
+      totalSeconds: 380,
+      slices: [
+        { bucket: 'bookorbit', readingSeconds: 180 },
+        { bucket: 'kobo', readingSeconds: 200 },
+      ],
+    });
+  });
+
+  it('returns an empty source distribution and honours the days override', async () => {
+    const repo = { getDailyReadingSecondsBySource: vi.fn().mockResolvedValue([]) };
+    const service = new UserStatisticsService(repo as any);
+
+    const result = await service.getReadingSourceDistribution({ id: 7, isSuperuser: true } as any, { days: 30, libraryIds: [1] });
+
+    expect(repo.getDailyReadingSecondsBySource).toHaveBeenCalledWith(7, true, [1], 30);
+    expect(result).toEqual({ totalSeconds: 0, slices: [] });
+  });
+
   it('returns all 24 hour buckets for peak reading hours', async () => {
     const repo = {
       getPeakReadingHours: vi.fn().mockResolvedValue([
-        { hour: 8, readingSeconds: 600, eventsCount: 3 },
-        { hour: 21, readingSeconds: 900, eventsCount: 4 },
+        { hour: 8, format: 'EPUB', source: 'web', readingSeconds: 400, eventsCount: 2 },
+        { hour: 8, format: 'EPUB', source: 'kobo', readingSeconds: 200, eventsCount: 1 },
+        { hour: 21, format: 'EPUB', source: 'koreader', readingSeconds: 900, eventsCount: 4 },
       ]),
     };
 
@@ -64,14 +104,23 @@ describe('UserStatisticsService', () => {
 
     expect(repo.getPeakReadingHours).toHaveBeenCalledWith(123, false, [], 365);
     expect(result).toHaveLength(24);
-    expect(result[8]).toEqual(expect.objectContaining({ hour: 8, readingSeconds: 600, eventsCount: 3 }));
-    expect(result[21]).toEqual(expect.objectContaining({ hour: 21, readingSeconds: 900, eventsCount: 4 }));
-    expect(result[0]).toEqual(expect.objectContaining({ hour: 0, readingSeconds: 0, eventsCount: 0 }));
+    expect(result[8]).toEqual(
+      expect.objectContaining({ hour: 8, readingSeconds: 600, eventsCount: 3, bySource: { bookorbit: 400, koreader: 0, kobo: 200 } }),
+    );
+    expect(result[21]).toEqual(
+      expect.objectContaining({ hour: 21, readingSeconds: 900, eventsCount: 4, bySource: { bookorbit: 0, koreader: 900, kobo: 0 } }),
+    );
+    expect(result[0]).toEqual(
+      expect.objectContaining({ hour: 0, readingSeconds: 0, eventsCount: 0, bySource: { bookorbit: 0, koreader: 0, kobo: 0 } }),
+    );
   });
 
   it('returns all weekday buckets for favorite reading days', async () => {
     const repo = {
-      getFavoriteReadingDays: vi.fn().mockResolvedValue([{ dayOfWeek: 1, readingSeconds: 1800, eventsCount: 6 }]),
+      getFavoriteReadingDays: vi.fn().mockResolvedValue([
+        { dayOfWeek: 1, source: 'koreader', format: 'EPUB', readingSeconds: 1200, eventsCount: 4 },
+        { dayOfWeek: 1, source: 'web', format: 'PDF', readingSeconds: 600, eventsCount: 2 },
+      ]),
     };
 
     const service = new UserStatisticsService(repo as any);
@@ -79,8 +128,20 @@ describe('UserStatisticsService', () => {
 
     expect(repo.getFavoriteReadingDays).toHaveBeenCalledWith(123, false, [], 365);
     expect(result).toHaveLength(7);
-    expect(result[1]).toEqual({ dayOfWeek: 1, readingSeconds: 1800, eventsCount: 6 });
-    expect(result[0]).toEqual({ dayOfWeek: 0, readingSeconds: 0, eventsCount: 0 });
+    expect(result[1]).toEqual({
+      dayOfWeek: 1,
+      readingSeconds: 1800,
+      eventsCount: 6,
+      byFormat: { EPUB: 1200, PDF: 600 },
+      bySource: { bookorbit: 600, koreader: 1200, kobo: 0 },
+    });
+    expect(result[0]).toEqual({
+      dayOfWeek: 0,
+      readingSeconds: 0,
+      eventsCount: 0,
+      byFormat: {},
+      bySource: { bookorbit: 0, koreader: 0, kobo: 0 },
+    });
   });
 
   it('returns a contiguous monthly completion timeline', async () => {
@@ -242,6 +303,7 @@ describe('UserStatisticsService', () => {
           bookId: 55,
           bookTitle: 'Deep Work',
           bookFormat: 'EPUB',
+          source: 'kobo',
           startedAt: new Date('2026-04-07T02:30:00.000Z'),
           endedAt: new Date('2026-04-07T03:00:00.000Z'),
           durationSeconds: 1800,
@@ -261,6 +323,7 @@ describe('UserStatisticsService', () => {
       bookId: 55,
       bookTitle: 'Deep Work',
       bookFormat: 'EPUB',
+      bookSource: 'kobo',
       startedAt: '2026-04-07T02:30:00.000Z',
       endedAt: '2026-04-07T03:00:00.000Z',
       durationSeconds: 1800,
@@ -314,9 +377,11 @@ describe('UserStatisticsService', () => {
       101,
       4,
       new Date('2026-04-07T08:00:00.000Z'),
+      new Date('2026-04-07T08:30:00.000Z'),
       new Date('2026-04-08T09:00:00.000Z'),
       new Date('2026-04-08T09:30:00.000Z'),
       1800,
+      'UTC',
     );
     expect(result.startedAt).toBe('2026-04-08T09:00:00.000Z');
     expect(result.endedAt).toBe('2026-04-08T09:30:00.000Z');
@@ -531,16 +596,23 @@ describe('UserStatisticsService', () => {
   it('delegates and caches archetype/genre/pace/chord queries', async () => {
     const repo = {
       getSessionArchetypePoints: vi.fn().mockResolvedValue([{ hour: 9, durationMinutes: 20, dayOfWeek: 2 }]),
-      getGenreReadingTime: vi.fn().mockResolvedValue([{ genre: 'Sci-Fi', readingSeconds: 300 }]),
-      getReadingPacePoints: vi.fn().mockResolvedValue([{ durationSeconds: 240, progressDelta: 1.4 }]),
+      getGenreReadingTime: vi.fn().mockResolvedValue([
+        { genre: 'Sci-Fi', source: 'web', readingSeconds: 200 },
+        { genre: 'Sci-Fi', source: 'kobo', readingSeconds: 100 },
+      ]),
+      getReadingPacePoints: vi.fn().mockResolvedValue([{ durationSeconds: 240, progressDelta: 1.4, bucket: 'bookorbit', format: 'EPUB' }]),
       getAuthorGenreChord: vi.fn().mockResolvedValue({ nodes: [{ name: 'A' }, { name: 'G' }], links: [{ source: 'A', target: 'G', value: 10 }] }),
     };
     const service = new UserStatisticsService(repo as any);
     const user = { id: 9, isSuperuser: false } as any;
 
     await expect(service.getSessionArchetypes(user, { libraryIds: [1] })).resolves.toEqual([{ hour: 9, durationMinutes: 20, dayOfWeek: 2 }]);
-    await expect(service.getGenreReadingTime(user, { libraryIds: [1] })).resolves.toEqual([{ genre: 'Sci-Fi', readingSeconds: 300 }]);
-    await expect(service.getReadingPace(user, { libraryIds: [1] })).resolves.toEqual([{ durationSeconds: 240, progressDelta: 1.4 }]);
+    await expect(service.getGenreReadingTime(user, { libraryIds: [1] })).resolves.toEqual([
+      { genre: 'Sci-Fi', readingSeconds: 300, bySource: { bookorbit: 200, koreader: 0, kobo: 100 } },
+    ]);
+    await expect(service.getReadingPace(user, { libraryIds: [1] })).resolves.toEqual([
+      { durationSeconds: 240, progressDelta: 1.4, bucket: 'bookorbit', format: 'EPUB' },
+    ]);
     await expect(service.getAuthorGenreChord(user, { libraryIds: [1] })).resolves.toEqual({
       nodes: [{ name: 'A' }, { name: 'G' }],
       links: [{ source: 'A', target: 'G', value: 10 }],
diff --git a/server/src/modules/user-statistics/user-statistics.service.ts b/server/src/modules/user-statistics/user-statistics.service.ts
index a305238a2..82d2a405e 100644
--- a/server/src/modules/user-statistics/user-statistics.service.ts
+++ b/server/src/modules/user-statistics/user-statistics.service.ts
@@ -2,6 +2,8 @@ import { BadRequestException, ConflictException, Injectable, NotFoundException }
 
 import type {
   ChordDiagramData,
+  ReadingSessionSource,
+  ReadingSessionSourceBucket,
   UserCompletionLatencyDistribution,
   UserCompletionRaceBook,
   UserCompletionTimelinePoint,
@@ -16,13 +18,16 @@ import type {
   UserReadingPacePoint,
   UserReadingSessionTimeline,
   UserReadingSessionTimelineItem,
+  UserReadingSourceDistribution,
   UserReadingSurvivalPoint,
   UserSessionArchetypePoint,
   UserStatisticsSummary,
 } from '@bookorbit/types';
+import { READING_SESSION_SOURCE_BUCKETS, emptySourceBucketRecord, toReadingSessionSourceBucket } from '@bookorbit/types';
 
 import type { RequestUser } from '../../common/types/request-user';
 import { StatsCache } from '../../common/cache/stats-cache';
+import { resolveTimeZone } from '../../common/utils/timezone.utils';
 import type { UserDailyReadingQueryDto } from './dto/user-daily-reading-query.dto';
 import type { UserGoalTrajectoryQueryDto } from './dto/user-goal-trajectory-query.dto';
 import type { UserSessionTimelineQueryDto } from './dto/user-session-timeline-query.dto';
@@ -162,7 +167,17 @@ export class UserStatisticsService {
     const key = this.buildUserCacheKey('reading-heatmap', user, { libraries: this.normalizeLibraryIds(query.libraryIds), days });
     return this.cache.get(String(user.id), key, async () => {
       const items = await this.repo.getDailyReadingStats(user.id, user.isSuperuser, query.libraryIds, days);
+      const bySourceRows = await this.repo.getDailyReadingSecondsBySource(user.id, user.isSuperuser, query.libraryIds, days);
       const byDay = new Map(items.map((item) => [item.day, item]));
+      const bySourceByDay = new Map<string, Record<ReadingSessionSourceBucket, number>>();
+      for (const row of bySourceRows) {
+        let record = bySourceByDay.get(row.day);
+        if (!record) {
+          record = emptySourceBucketRecord();
+          bySourceByDay.set(row.day, record);
+        }
+        record[toReadingSessionSourceBucket(row.source)] += row.readingSeconds;
+      }
       const start = this.sinceDateForDays(days);
       const end = this.startOfUtcDay(new Date());
       const result: UserDailyReadingStat[] = [];
@@ -175,6 +190,7 @@ export class UserStatisticsService {
           readingSeconds: value?.readingSeconds ?? 0,
           progressDelta: this.roundProgressDelta(value?.progressDelta ?? 0),
           eventsCount: value?.eventsCount ?? 0,
+          bySource: bySourceByDay.get(day) ?? emptySourceBucketRecord(),
         });
       }
 
@@ -182,21 +198,44 @@ export class UserStatisticsService {
     });
   }
 
+  async getReadingSourceDistribution(user: RequestUser, query: UserDailyReadingQueryDto): Promise<UserReadingSourceDistribution> {
+    const days = query.days ?? BEHAVIOR_DEFAULT_DAYS;
+    const key = this.buildUserCacheKey('source-distribution', user, { libraries: this.normalizeLibraryIds(query.libraryIds), days });
+    return this.cache.get(String(user.id), key, async () => {
+      const rows = await this.repo.getDailyReadingSecondsBySource(user.id, user.isSuperuser, query.libraryIds, days);
+      const totals = emptySourceBucketRecord();
+      for (const row of rows) {
+        totals[toReadingSessionSourceBucket(row.source)] += row.readingSeconds;
+      }
+      const slices = READING_SESSION_SOURCE_BUCKETS.filter((bucket) => totals[bucket] > 0).map((bucket) => ({
+        bucket,
+        readingSeconds: totals[bucket],
+      }));
+      const totalSeconds = slices.reduce((sum, slice) => sum + slice.readingSeconds, 0);
+      return { totalSeconds, slices };
+    });
+  }
+
   async getPeakReadingHours(user: RequestUser, query: UserDailyReadingQueryDto): Promise<UserPeakHourStat[]> {
     const days = query.days ?? BEHAVIOR_DEFAULT_DAYS;
     const key = this.buildUserCacheKey('peak-hours', user, { libraries: this.normalizeLibraryIds(query.libraryIds), days });
     return this.cache.get(String(user.id), key, async () => {
       const rows = await this.repo.getPeakReadingHours(user.id, user.isSuperuser, query.libraryIds, days);
 
-      const byHour = new Map<number, { readingSeconds: number; eventsCount: number; byFormat: Record<string, number> }>();
+      const byHour = new Map<
+        number,
+        { readingSeconds: number; eventsCount: number; byFormat: Record<string, number>; bySource: Record<ReadingSessionSourceBucket, number> }
+      >();
       for (const row of rows) {
         if (!byHour.has(row.hour)) {
-          byHour.set(row.hour, { readingSeconds: 0, eventsCount: 0, byFormat: {} });
+          byHour.set(row.hour, { readingSeconds: 0, eventsCount: 0, byFormat: {}, bySource: emptySourceBucketRecord() });
         }
         const entry = byHour.get(row.hour)!;
         entry.readingSeconds += row.readingSeconds;
         entry.eventsCount += row.eventsCount;
-        entry.byFormat[row.format] = row.readingSeconds;
+        // Grouping now splits each hour by (format, source), so accumulate rather than assign.
+        entry.byFormat[row.format] = (entry.byFormat[row.format] ?? 0) + row.readingSeconds;
+        entry.bySource[toReadingSessionSourceBucket(row.source)] += row.readingSeconds;
       }
 
       return Array.from({ length: 24 }, (_, hour) => {
@@ -206,6 +245,7 @@ export class UserStatisticsService {
           readingSeconds: entry?.readingSeconds ?? 0,
           eventsCount: entry?.eventsCount ?? 0,
           byFormat: entry?.byFormat ?? {},
+          bySource: entry?.bySource ?? emptySourceBucketRecord(),
         };
       });
     });
@@ -216,14 +256,30 @@ export class UserStatisticsService {
     const key = this.buildUserCacheKey('favorite-days', user, { libraries: this.normalizeLibraryIds(query.libraryIds), days });
     return this.cache.get(String(user.id), key, async () => {
       const rows = await this.repo.getFavoriteReadingDays(user.id, user.isSuperuser, query.libraryIds, days);
-      const byDay = new Map(rows.map((row) => [row.dayOfWeek, row]));
+      const byDay = new Map<
+        number,
+        { readingSeconds: number; eventsCount: number; byFormat: Record<string, number>; bySource: Record<ReadingSessionSourceBucket, number> }
+      >();
+      for (const row of rows) {
+        let entry = byDay.get(row.dayOfWeek);
+        if (!entry) {
+          entry = { readingSeconds: 0, eventsCount: 0, byFormat: {}, bySource: emptySourceBucketRecord() };
+          byDay.set(row.dayOfWeek, entry);
+        }
+        entry.readingSeconds += row.readingSeconds;
+        entry.eventsCount += row.eventsCount;
+        entry.byFormat[row.format] = (entry.byFormat[row.format] ?? 0) + row.readingSeconds;
+        entry.bySource[toReadingSessionSourceBucket(row.source)] += row.readingSeconds;
+      }
 
       return Array.from({ length: 7 }, (_, dayOfWeek) => {
-        const row = byDay.get(dayOfWeek);
+        const entry = byDay.get(dayOfWeek);
         return {
           dayOfWeek,
-          readingSeconds: row?.readingSeconds ?? 0,
-          eventsCount: row?.eventsCount ?? 0,
+          readingSeconds: entry?.readingSeconds ?? 0,
+          eventsCount: entry?.eventsCount ?? 0,
+          byFormat: entry?.byFormat ?? {},
+          bySource: entry?.bySource ?? emptySourceBucketRecord(),
         };
       });
     });
@@ -234,6 +290,7 @@ export class UserStatisticsService {
     bookId: number;
     bookTitle: string | null;
     bookFormat: string | null;
+    source: ReadingSessionSource | null;
     startedAt: Date;
     endedAt: Date;
     durationSeconds: number;
@@ -243,6 +300,7 @@ export class UserStatisticsService {
       bookId: row.bookId,
       bookTitle: row.bookTitle,
       bookFormat: row.bookFormat,
+      bookSource: toReadingSessionSourceBucket(row.source),
       startedAt: row.startedAt.toISOString(),
       endedAt: row.endedAt.toISOString(),
       durationSeconds: row.durationSeconds,
@@ -318,9 +376,11 @@ export class UserStatisticsService {
       sessionId,
       existing.libraryId,
       existing.startedAt,
+      existing.endedAt,
       startedAt,
       endedAt,
       proposedDuration,
+      resolveTimeZone((user.settings as { timezone?: unknown } | undefined)?.timezone, 'UTC'),
     );
     if (moveResult.conflict) {
       const conflictStart = moveResult.conflict.startedAt.toISOString();
@@ -521,7 +581,23 @@ export class UserStatisticsService {
   async getGenreReadingTime(user: RequestUser, query: UserDailyReadingQueryDto): Promise<UserGenreReadingTimeItem[]> {
     const days = query.days ?? GENRE_READING_TIME_DEFAULT_DAYS;
     const key = this.buildUserCacheKey('genre-reading-time', user, { libraries: this.normalizeLibraryIds(query.libraryIds), days });
-    return this.cache.get(String(user.id), key, () => this.repo.getGenreReadingTime(user.id, user.isSuperuser, query.libraryIds, days));
+    return this.cache.get(String(user.id), key, async () => {
+      const rows = await this.repo.getGenreReadingTime(user.id, user.isSuperuser, query.libraryIds, days);
+      const byGenre = new Map<string, { readingSeconds: number; bySource: Record<ReadingSessionSourceBucket, number> }>();
+      for (const row of rows) {
+        let entry = byGenre.get(row.genre);
+        if (!entry) {
+          entry = { readingSeconds: 0, bySource: emptySourceBucketRecord() };
+          byGenre.set(row.genre, entry);
+        }
+        entry.readingSeconds += row.readingSeconds;
+        entry.bySource[toReadingSessionSourceBucket(row.source)] += row.readingSeconds;
+      }
+
+      return Array.from(byGenre, ([genre, entry]) => ({ genre, readingSeconds: entry.readingSeconds, bySource: entry.bySource }))
+        .sort((a, b) => b.readingSeconds - a.readingSeconds)
+        .slice(0, 30);
+    });
   }
 
   async getReadingPace(user: RequestUser, query: UserDailyReadingQueryDto): Promise<UserReadingPacePoint[]> {
diff --git a/server/src/scripts/annotation-conversion-smoke.ts b/server/src/scripts/annotation-conversion-smoke.ts
new file mode 100644
index 000000000..881743634
--- /dev/null
+++ b/server/src/scripts/annotation-conversion-smoke.ts
@@ -0,0 +1,101 @@
+/**
+ * Read-only smoke test for the position converter: converts every koreader-origin
+ * annotation in the database from xpointer to CFI (verified against the stored
+ * highlight text), then round-trips back, and prints per-annotation results.
+ *
+ * Usage: cd server && npx tsx src/scripts/annotation-conversion-smoke.ts
+ */
+import { existsSync } from 'fs';
+import { loadEnvFile } from 'node:process';
+import { Client } from 'pg';
+import * as unzipper from 'unzipper';
+
+import { loadChapterFromZip, readEpubSpine } from '../modules/position-converter/epub-dom.service';
+import { cfiRangeToXPointer, xpointerRangeToCfi } from '../modules/position-converter/position-converter.core';
+import { parseXPointer } from '../modules/position-converter/xpointer.utils';
+
+if (existsSync('.env')) {
+  loadEnvFile('.env');
+}
+
+async function main() {
+  const client = new Client({ connectionString: process.env.DATABASE_URL });
+  await client.connect();
+  const { rows } = await client.query<{
+    id: number;
+    text: string | null;
+    pos0: string;
+    pos1: string | null;
+    absolute_path: string;
+  }>(`
+    select a.id, a.text, ap.pos0, ap.pos1, bf.absolute_path
+    from annotations a
+    join annotation_positions ap on ap.annotation_id = a.id and ap.format = 'xpointer'
+    join book_files bf on bf.id = ap.book_file_id
+    where a.origin = 'koreader'
+    order by a.id
+  `);
+  await client.end();
+
+  const zipCache = new Map<string, { zip: unzipper.CentralDirectory; spine: string[] }>();
+  let exact = 0;
+  let repaired = 0;
+  let failed = 0;
+  let roundTripOk = 0;
+
+  for (const row of rows) {
+    let entry = zipCache.get(row.absolute_path);
+    if (!entry) {
+      const zip = await unzipper.Open.file(row.absolute_path);
+      const spine = (await readEpubSpine(zip)).hrefs;
+      entry = { zip, spine };
+      zipCache.set(row.absolute_path, entry);
+    }
+    const parsed = parseXPointer(row.pos0);
+    if (!parsed) {
+      console.log(`#${row.id} UNPARSABLE ${row.pos0}`);
+      failed += 1;
+      continue;
+    }
+    const chapterIndex = parsed.docFragmentIndex - 1;
+    const href = entry.spine[chapterIndex];
+    if (!href) {
+      console.log(`#${row.id} NO_CHAPTER idx=${chapterIndex} spineLen=${entry.spine.length}`);
+      failed += 1;
+      continue;
+    }
+    const doc = await loadChapterFromZip(entry.zip, href);
+    if (!doc) {
+      console.log(`#${row.id} CHAPTER_LOAD_FAILED ${href}`);
+      failed += 1;
+      continue;
+    }
+    const result = xpointerRangeToCfi(doc, chapterIndex, row.pos0, row.pos1, row.text);
+    if (result.status === 'failed') {
+      console.log(`#${row.id} FAILED reason=${result.reason} pos0=${row.pos0} text="${(row.text ?? '').slice(0, 50)}"`);
+      failed += 1;
+      continue;
+    }
+    if (result.status === 'exact') exact += 1;
+    else repaired += 1;
+
+    const back = cfiRangeToXPointer(doc, chapterIndex, result.pos0, row.text);
+    const rt = back.status !== 'failed' && back.pos0 === row.pos0 && back.pos1 === row.pos1;
+    if (rt) roundTripOk += 1;
+    console.log(`#${row.id} ${result.status.toUpperCase()} rt=${rt ? 'OK' : 'DIFF'} cfi=${result.pos0.slice(0, 70)}`);
+    if (!rt) {
+      if (back.status === 'failed') {
+        console.log(`    back FAILED reason=${back.reason}`);
+      } else {
+        console.log(`    orig0=${row.pos0}\n    back0=${back.pos0}\n    orig1=${row.pos1}\n    back1=${back.pos1}`);
+      }
+    }
+  }
+
+  console.log(`\nTotal=${rows.length} exact=${exact} repaired=${repaired} failed=${failed} roundTrip=${roundTripOk}`);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/server/src/scripts/backfill-reading-session-events.ts b/server/src/scripts/backfill-reading-session-events.ts
index e72cd4769..9419cdb69 100644
--- a/server/src/scripts/backfill-reading-session-events.ts
+++ b/server/src/scripts/backfill-reading-session-events.ts
@@ -1,9 +1,13 @@
 import { drizzle } from 'drizzle-orm/node-postgres';
-import { sql } from 'drizzle-orm';
+import { and, eq, sql } from 'drizzle-orm';
 import { Pool } from 'pg';
 
+import { aggregateReadingSessionDailyStats } from '../common/utils/reading-daily-stats.utils';
+import { resolveTimeZone } from '../common/utils/timezone.utils';
 import * as schema from '../db/schema';
 
+const INSERT_CHUNK_SIZE = 1_000;
+
 async function runBackfill() {
   const connectionString = process.env.DATABASE_URL;
   if (!connectionString) {
@@ -21,26 +25,64 @@ async function runBackfill() {
 
   try {
     const rebuildDailyDelete = await db.execute(sql`delete from user_reading_daily_stats`);
-    const rebuildDailyInsert = await db.execute(sql`
-      insert into user_reading_daily_stats (user_id, library_id, day, reading_seconds, progress_delta, sessions_count, updated_at)
-      select
-        rs.user_id,
-        b.library_id,
-        date_trunc('day', rs.started_at)::date as day,
-        coalesce(sum(rs.duration_seconds), 0)::int as reading_seconds,
-        coalesce(sum(rs.progress_delta), 0)::real as progress_delta,
-        count(*)::int as sessions_count,
-        now() as updated_at
-      from reading_sessions rs
-      inner join book_files bf on bf.id = rs.book_file_id
-      inner join books b on b.id = bf.book_id
-      group by rs.user_id, b.library_id, date_trunc('day', rs.started_at)::date
-    `);
+    const groups = await db
+      .select({
+        userId: schema.readingSessions.userId,
+        libraryId: schema.books.libraryId,
+        settings: schema.users.settings,
+        sessionsCount: sql<number>`count(*)::int`,
+      })
+      .from(schema.readingSessions)
+      .innerJoin(schema.books, eq(schema.books.id, schema.readingSessions.bookId))
+      .innerJoin(schema.users, eq(schema.users.id, schema.readingSessions.userId))
+      .groupBy(schema.readingSessions.userId, schema.books.libraryId, schema.users.settings);
+
+    let insertedDaily = 0;
+    let sessionsCount = 0;
+
+    for (const group of groups) {
+      const timeZone = resolveTimeZone((group.settings as { timezone?: unknown } | undefined)?.timezone, 'UTC');
+      const sessions = await db
+        .select({
+          startedAt: schema.readingSessions.startedAt,
+          endedAt: schema.readingSessions.endedAt,
+          durationSeconds: schema.readingSessions.durationSeconds,
+          progressDelta: schema.readingSessions.progressDelta,
+        })
+        .from(schema.readingSessions)
+        .innerJoin(schema.books, eq(schema.books.id, schema.readingSessions.bookId))
+        .where(and(eq(schema.readingSessions.userId, group.userId), eq(schema.books.libraryId, group.libraryId)));
+
+      const now = new Date();
+      const values = aggregateReadingSessionDailyStats(
+        sessions.map((session) => ({
+          startedAt: session.startedAt,
+          endedAt: session.endedAt,
+          durationSeconds: session.durationSeconds,
+          progressDelta: session.progressDelta ?? null,
+        })),
+        timeZone,
+      ).map((segment) => ({
+        userId: group.userId,
+        libraryId: group.libraryId,
+        day: segment.day,
+        readingSeconds: segment.readingSeconds,
+        progressDelta: segment.progressDelta,
+        sessionsCount: segment.sessionsCount,
+        updatedAt: now,
+      }));
+
+      for (let offset = 0; offset < values.length; offset += INSERT_CHUNK_SIZE) {
+        await db.insert(schema.userReadingDailyStats).values(values.slice(offset, offset + INSERT_CHUNK_SIZE));
+      }
+
+      insertedDaily += values.length;
+      sessionsCount += group.sessionsCount;
+    }
 
     const deletedDaily = Number((rebuildDailyDelete as { rowCount?: number }).rowCount ?? 0);
-    const insertedDaily = Number((rebuildDailyInsert as { rowCount?: number }).rowCount ?? 0);
 
-    console.log(`Reading session backfill complete: deletedDaily=${deletedDaily}, insertedDaily=${insertedDaily}`);
+    console.log(`Reading session backfill complete: deletedDaily=${deletedDaily}, insertedDaily=${insertedDaily}, sessions=${sessionsCount}`);
   } finally {
     await pool.end();
   }
diff --git a/server/test/annotations-hub.e2e-spec.ts b/server/test/annotations-hub.e2e-spec.ts
new file mode 100644
index 000000000..f36ab24b5
--- /dev/null
+++ b/server/test/annotations-hub.e2e-spec.ts
@@ -0,0 +1,167 @@
+import { randomUUID } from 'crypto';
+
+import { createEpubFixture } from './e2e/reader-state-isolation/reader-state-isolation-fixture-builder';
+import {
+  authHeader,
+  closeReaderStateIsolationE2EContext,
+  createLibraryWithFolder,
+  createReaderStateIsolationE2EContext,
+  createUserAndLogin,
+  grantLibraryAccess,
+  locateBookByAbsolutePath,
+  triggerAndWaitForLibraryScan,
+  type LocatedBookFile,
+  type ReaderStateIsolationE2EContext,
+  type TestUserSession,
+} from './e2e/reader-state-isolation/reader-state-isolation-harness';
+
+const FIXTURE_CFI = 'epubcfi(/6/2!/4/2,/1:0,/1:7)';
+
+describe('Annotations hub (e2e)', { timeout: 120_000 }, () => {
+  let ctx!: ReaderStateIsolationE2EContext;
+  let epub!: LocatedBookFile;
+  let owner!: TestUserSession;
+  let outsider!: TestUserSession;
+  const createdIds: number[] = [];
+
+  beforeAll(async () => {
+    ctx = await createReaderStateIsolationE2EContext();
+    const library = await createLibraryWithFolder(ctx, { name: `annotations-hub-${randomUUID()}` });
+    const epubPath = await createEpubFixture(library.folderPath, 'hub-book.epub', {
+      title: `Hub Book ${randomUUID()}`,
+      uid: `urn:uuid:${randomUUID()}`,
+    });
+    await triggerAndWaitForLibraryScan(ctx, library.libraryId);
+    epub = await locateBookByAbsolutePath(ctx, epubPath);
+
+    owner = await createUserAndLogin(ctx);
+    outsider = await createUserAndLogin(ctx);
+    await grantLibraryAccess(ctx, owner.userId, library.libraryId, 'viewer');
+
+    for (const note of ['first', 'second', 'third']) {
+      const created = await ctx.app.inject({
+        method: 'POST',
+        url: `/api/v1/books/${epub.bookId}/annotations`,
+        headers: authHeader(owner.accessToken),
+        payload: { cfi: FIXTURE_CFI, text: 'fixture', color: '#FACC15', style: 'highlight', note },
+      });
+      expect(created.statusCode).toBe(201);
+      createdIds.push((created.json() as { id: number }).id);
+    }
+  }, 120_000);
+
+  afterAll(async () => {
+    if (ctx) await closeReaderStateIsolationE2EContext(ctx);
+  });
+
+  it('lists annotations across books with book titles and filters', async () => {
+    const response = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations?status=active&search=second',
+      headers: authHeader(owner.accessToken),
+    });
+    expect(response.statusCode).toBe(200);
+    const body = response.json() as { items: { note: string | null; bookTitle: string | null; jumpFileId: number | null }[]; total: number };
+    expect(body.total).toBe(1);
+    expect(body.items[0].note).toBe('second');
+    // The e2e harness mocks metadata extraction, so the title may be null here.
+    expect(body.items[0]).toHaveProperty('bookTitle');
+    expect(body.items[0].jumpFileId).toBe(epub.bookFileId);
+  });
+
+  it('is isolated per user', async () => {
+    const response = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations',
+      headers: authHeader(outsider.accessToken),
+    });
+    expect(response.statusCode).toBe(200);
+    expect((response.json() as { total: number }).total).toBe(0);
+
+    const bulk = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/annotations/bulk',
+      headers: authHeader(outsider.accessToken),
+      payload: { ids: createdIds, action: 'trash' },
+    });
+    expect(bulk.statusCode).toBe(200);
+    expect((bulk.json() as { affected: number }).affected).toBe(0);
+  });
+
+  it('bulk trashes, lists in trash, restores and purges', async () => {
+    const bulk = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/annotations/bulk',
+      headers: authHeader(owner.accessToken),
+      payload: { ids: [createdIds[0], createdIds[1]], action: 'trash' },
+    });
+    expect(bulk.statusCode).toBe(200);
+    expect((bulk.json() as { affected: number }).affected).toBe(2);
+
+    const trash = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations?status=trashed',
+      headers: authHeader(owner.accessToken),
+    });
+    expect((trash.json() as { total: number }).total).toBe(2);
+
+    const restore = await ctx.app.inject({
+      method: 'POST',
+      url: `/api/v1/annotations/${createdIds[0]}/restore`,
+      headers: authHeader(owner.accessToken),
+    });
+    expect(restore.statusCode).toBe(200);
+    expect((restore.json() as { deletedAt: string | null }).deletedAt).toBeNull();
+
+    // No device ever synced these, so the purge is not blocked.
+    const purge = await ctx.app.inject({
+      method: 'DELETE',
+      url: `/api/v1/annotations/${createdIds[1]}`,
+      headers: authHeader(owner.accessToken),
+    });
+    expect(purge.statusCode).toBe(204);
+
+    const trashAfter = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations?status=trashed',
+      headers: authHeader(owner.accessToken),
+    });
+    expect((trashAfter.json() as { total: number }).total).toBe(0);
+  });
+
+  it('bulk recolors active annotations', async () => {
+    const bulk = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/annotations/bulk',
+      headers: authHeader(owner.accessToken),
+      payload: { ids: createdIds, action: 'restyle', color: '#4ADE80' },
+    });
+    expect(bulk.statusCode).toBe(200);
+    expect((bulk.json() as { affected: number }).affected).toBeGreaterThan(0);
+
+    const list = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations?colors=%234ADE80',
+      headers: authHeader(owner.accessToken),
+    });
+    expect((list.json() as { total: number }).total).toBeGreaterThan(0);
+  });
+
+  it('exports markdown with attachment headers', async () => {
+    const response = await ctx.app.inject({
+      method: 'GET',
+      url: '/api/v1/annotations/export?format=md',
+      headers: authHeader(owner.accessToken),
+    });
+    expect(response.statusCode).toBe(200);
+    expect(response.headers['content-type']).toContain('markdown');
+    expect(response.headers['content-disposition']).toContain('attachment');
+    expect(response.body).toContain('# Annotations');
+    expect(response.body).toContain('> fixture');
+  });
+
+  it('rejects unauthenticated access', async () => {
+    const response = await ctx.app.inject({ method: 'GET', url: '/api/v1/annotations' });
+    expect(response.statusCode).toBe(401);
+  });
+});
diff --git a/server/test/kobo-annotation-sync.e2e-spec.ts b/server/test/kobo-annotation-sync.e2e-spec.ts
new file mode 100644
index 000000000..47eccc018
--- /dev/null
+++ b/server/test/kobo-annotation-sync.e2e-spec.ts
@@ -0,0 +1,442 @@
+import { randomUUID } from 'crypto';
+import { and, eq } from 'drizzle-orm';
+
+import * as schema from '../src/db/schema';
+import { createEpubFixture } from './e2e/reader-state-isolation/reader-state-isolation-fixture-builder';
+import {
+  authHeader,
+  closeReaderStateIsolationE2EContext,
+  createLibraryWithFolder,
+  createReaderStateIsolationE2EContext,
+  locateBookByAbsolutePath,
+  triggerAndWaitForLibraryScan,
+  type CreatedLibrary,
+  type LocatedBookFile,
+  type ReaderStateIsolationE2EContext,
+} from './e2e/reader-state-isolation/reader-state-isolation-harness';
+
+// The fixture chapter (OPS/chapter.xhtml) body is exactly <p>fixture</p>; kepubify
+// wraps it in a single koboSpan with id kobo.1.1.
+const FIXTURE_CFI = 'epubcfi(/6/2!/4/2,/1:0,/1:7)';
+const FIXTURE_XPOINTER_0 = '/body/DocFragment[1]/body/p/text().0';
+const FIXTURE_XPOINTER_1 = '/body/DocFragment[1]/body/p/text().7';
+const KOBO_LOCATION = {
+  span: {
+    startPath: 'span#kobo\\.1\\.1',
+    startChar: 0,
+    endPath: 'span#kobo\\.1\\.1',
+    endChar: 7,
+    chapterFilename: 'OPS/chapter.xhtml',
+    chapterProgress: 0,
+    chapterTitle: 'Chapter 1',
+  },
+};
+
+const KOREADER_USERNAME = `kobo-mesh-device-${randomUUID().slice(0, 8)}`;
+const KOREADER_PASSWORD = 'KoboMeshDevicePass123';
+
+function flushTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 150));
+}
+
+describe('Kobo annotation sync (e2e)', { timeout: 180_000 }, () => {
+  let ctx!: ReaderStateIsolationE2EContext;
+  let library!: CreatedLibrary;
+  let epub!: LocatedBookFile;
+  let deviceToken!: string;
+  let deviceDbId!: number;
+  let contentId!: string;
+  let deviceAnnotationId!: string;
+  let fileHash!: string;
+  let adminUserId!: number;
+
+  function v3Url(path: string): string {
+    return `/api/v1/kobo/${deviceToken}/${path}`;
+  }
+
+  async function getAnnotations() {
+    const response = await ctx.app.inject({
+      method: 'GET',
+      url: v3Url(`api/v3/content/${contentId}/annotations`),
+      headers: { 'if-none-match': 'W/"0"' },
+    });
+    expect(response.statusCode).toBe(200);
+    await flushTick();
+    return response.json() as { annotations: Record<string, unknown>[]; nextPageOffsetToken: null };
+  }
+
+  async function patchAnnotations(payload: Record<string, unknown>) {
+    const response = await ctx.app.inject({
+      method: 'PATCH',
+      url: v3Url(`api/v3/content/${contentId}/annotations`),
+      payload,
+    });
+    expect(response.statusCode).toBe(204);
+  }
+
+  async function checkForChanges(): Promise<string[]> {
+    const response = await ctx.app.inject({ method: 'POST', url: v3Url('api/v3/content/checkforchanges'), payload: {} });
+    expect(response.statusCode).toBe(200);
+    return response.json() as string[];
+  }
+
+  async function findCanonicalAnnotations() {
+    return ctx.db
+      .select()
+      .from(schema.annotations)
+      .where(and(eq(schema.annotations.userId, adminUserId), eq(schema.annotations.bookId, epub.bookId)));
+  }
+
+  async function findPositions(annotationId: number) {
+    const rows = await ctx.db.select().from(schema.annotationPositions).where(eq(schema.annotationPositions.annotationId, annotationId));
+    return new Map(rows.map((row) => [row.format, row]));
+  }
+
+  beforeAll(async () => {
+    ctx = await createReaderStateIsolationE2EContext();
+    library = await createLibraryWithFolder(ctx, { name: `kobo-annotations-${randomUUID()}` });
+    const epubPath = await createEpubFixture(library.folderPath, 'kobo-sync-book.epub', {
+      title: `Kobo Sync Book ${randomUUID()}`,
+      uid: `urn:uuid:${randomUUID()}`,
+    });
+    await triggerAndWaitForLibraryScan(ctx, library.libraryId);
+    epub = await locateBookByAbsolutePath(ctx, epubPath);
+
+    const [admin] = await ctx.db.select({ id: schema.users.id }).from(schema.users).where(eq(schema.users.username, 'reader-state-e2e-admin'));
+    adminUserId = admin!.id;
+
+    const [fileRow] = await ctx.db
+      .select({ fileHash: schema.bookFiles.fileHash })
+      .from(schema.bookFiles)
+      .where(eq(schema.bookFiles.id, epub.bookFileId));
+    fileHash = fileRow!.fileHash!;
+    expect(fileHash).toBeTruthy();
+
+    const device = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/kobo/devices',
+      headers: authHeader(ctx.adminToken),
+      payload: { name: 'E2E Kobo' },
+    });
+    expect([200, 201]).toContain(device.statusCode);
+    const deviceBody = device.json() as { id: number; token: string };
+    deviceToken = deviceBody.token;
+    deviceDbId = deviceBody.id;
+
+    const settings = await ctx.app.inject({
+      method: 'PATCH',
+      url: '/api/v1/kobo/settings',
+      headers: authHeader(ctx.adminToken),
+      payload: { convertToKepub: true },
+    });
+    expect(settings.statusCode).toBe(200);
+
+    // Kobo library sync only covers books in collections flagged syncToKobo.
+    const collection = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/collections',
+      headers: authHeader(ctx.adminToken),
+      payload: { name: `Kobo Sync ${randomUUID().slice(0, 8)}`, icon: 'book', syncToKobo: true },
+    });
+    expect([200, 201]).toContain(collection.statusCode);
+    const collectionId = (collection.json() as { id: number }).id;
+    const addBooks = await ctx.app.inject({
+      method: 'POST',
+      url: `/api/v1/collections/${collectionId}/books`,
+      headers: authHeader(ctx.adminToken),
+      payload: { bookIds: [epub.bookId] },
+    });
+    expect([200, 201]).toContain(addBooks.statusCode);
+
+    // Library sync mints the entitlement contentId the v3 API addresses books by.
+    const sync = await ctx.app.inject({ method: 'GET', url: v3Url('v1/library/sync') });
+    expect(sync.statusCode).toBe(200);
+
+    const [entitlement] = await ctx.db
+      .select({ entitlementId: schema.koboBookEntitlements.entitlementId })
+      .from(schema.koboBookEntitlements)
+      .where(and(eq(schema.koboBookEntitlements.userId, adminUserId), eq(schema.koboBookEntitlements.bookId, epub.bookId)));
+    expect(entitlement?.entitlementId).toBeTruthy();
+    contentId = entitlement!.entitlementId;
+  }, 180_000);
+
+  afterAll(async () => {
+    if (ctx) await closeReaderStateIsolationE2EContext(ctx);
+  });
+
+  it('ingests a device highlight into the hub with exact cfi and xpointer positions', async () => {
+    deviceAnnotationId = randomUUID();
+    await patchAnnotations({
+      updatedAnnotations: [
+        {
+          id: deviceAnnotationId,
+          type: 'highlight',
+          highlightColor: '#C6E09E',
+          highlightedText: 'fixture',
+          location: KOBO_LOCATION,
+          clientLastModifiedUtc: '2026-06-10T10:00:00Z',
+        },
+      ],
+    });
+
+    const canonical = await findCanonicalAnnotations();
+    expect(canonical).toHaveLength(1);
+    expect(canonical[0]).toMatchObject({
+      text: 'fixture',
+      origin: 'kobo',
+      color: '#4ADE80',
+      style: 'highlight',
+      deviceCreatedAt: '2026-06-10 10:00:00',
+    });
+
+    const positions = await findPositions(canonical[0].id);
+    expect(positions.get('kobo_span')).toMatchObject({ pos0: 'kobo.1.1:0', pos1: 'kobo.1.1:7', status: 'exact' });
+    expect(positions.get('cfi')).toMatchObject({ pos0: FIXTURE_CFI, status: 'exact' });
+    expect(positions.get('xpointer')).toMatchObject({ pos0: FIXTURE_XPOINTER_0, pos1: FIXTURE_XPOINTER_1, status: 'exact' });
+
+    const [state] = await ctx.db
+      .select()
+      .from(schema.annotationSyncState)
+      .where(and(eq(schema.annotationSyncState.annotationId, canonical[0].id), eq(schema.annotationSyncState.source, 'kobo')));
+    expect(state).toMatchObject({ externalKey: deviceAnnotationId, deviceId: String(deviceDbId) });
+  });
+
+  it('echoes the device annotation back on GET and converges checkforchanges', async () => {
+    const body = await getAnnotations();
+    expect(body.annotations).toHaveLength(1);
+    expect(body.annotations[0]).toMatchObject({
+      id: deviceAnnotationId,
+      highlightColor: '#C6E09E',
+      highlightedText: 'fixture',
+      type: 'highlight',
+    });
+    expect(body.annotations[0].location).toEqual(KOBO_LOCATION);
+
+    expect(await checkForChanges()).toEqual([]);
+  });
+
+  it('reports the content changed after a hub edit and serves the edit', async () => {
+    const [annotation] = await findCanonicalAnnotations();
+    const edit = await ctx.app.inject({
+      method: 'PATCH',
+      url: `/api/v1/books/${epub.bookId}/annotations/${annotation.id}`,
+      headers: authHeader(ctx.adminToken),
+      payload: { note: 'hub note', color: '#38BDF8' },
+    });
+    expect(edit.statusCode).toBe(200);
+
+    expect(await checkForChanges()).toEqual([contentId]);
+
+    const body = await getAnnotations();
+    expect(body.annotations[0]).toMatchObject({ noteText: 'hub note', highlightColor: '#B2E1E8', type: 'note' });
+
+    expect(await checkForChanges()).toEqual([]);
+  });
+
+  it('does not re-ingest the device echo of a served edit', async () => {
+    const body = await getAnnotations();
+    const served = body.annotations[0] as { clientLastModifiedUtc: string };
+    await patchAnnotations({
+      updatedAnnotations: [
+        {
+          id: deviceAnnotationId,
+          type: 'note',
+          highlightColor: '#B2E1E8',
+          highlightedText: 'fixture',
+          noteText: 'hub note',
+          location: KOBO_LOCATION,
+          clientLastModifiedUtc: served.clientLastModifiedUtc,
+        },
+      ],
+    });
+
+    const [annotation] = await findCanonicalAnnotations();
+    expect(annotation).toMatchObject({ note: 'hub note', color: '#38BDF8' });
+  });
+
+  it('serves web-origin annotations once push is enabled, with a synthesized location', async () => {
+    const enable = await ctx.app.inject({
+      method: 'PATCH',
+      url: '/api/v1/kobo/settings',
+      headers: authHeader(ctx.adminToken),
+      payload: { syncBookOrbitAnnotationsToKobo: true },
+    });
+    expect(enable.statusCode).toBe(200);
+
+    const create = await ctx.app.inject({
+      method: 'POST',
+      url: `/api/v1/books/${epub.bookId}/annotations`,
+      headers: authHeader(ctx.adminToken),
+      payload: { cfi: FIXTURE_CFI, bookFileId: epub.bookFileId, text: 'fixture', color: '#FB923C', style: 'highlight' },
+    });
+    expect(create.statusCode).toBe(201);
+
+    expect(await checkForChanges()).toEqual([contentId]);
+
+    const body = await getAnnotations();
+    expect(body.annotations).toHaveLength(2);
+    const webServed = body.annotations.find((a) => a.id !== deviceAnnotationId)!;
+    expect(webServed).toMatchObject({ highlightedText: 'fixture', highlightColor: '#F6F3B3', type: 'highlight' });
+    const location = webServed.location as typeof KOBO_LOCATION;
+    expect(location.span).toMatchObject({ startPath: 'span#kobo\\.1\\.1', startChar: 0, endPath: 'span#kobo\\.1\\.1', endChar: 7 });
+    expect(location.span.chapterFilename).toBe('OPS/chapter.xhtml');
+
+    expect(await checkForChanges()).toEqual([]);
+
+    const created = (await findCanonicalAnnotations()).find((row) => row.origin === 'web')!;
+    const positions = await findPositions(created.id);
+    expect(positions.get('kobo_span')).toMatchObject({ pos0: 'kobo.1.1:0', pos1: 'kobo.1.1:7' });
+  });
+
+  it('applies device deletes to the hub', async () => {
+    const body = await getAnnotations();
+    const webServedId = (body.annotations.find((a) => a.id !== deviceAnnotationId) as { id: string }).id;
+
+    await patchAnnotations({ deletedAnnotationIds: [webServedId] });
+
+    const remaining = (await findCanonicalAnnotations()).filter((row) => row.deletedAt === null);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0].origin).toBe('kobo');
+
+    const after = await getAnnotations();
+    expect(after.annotations.map((a) => a.id)).toEqual([deviceAnnotationId]);
+  });
+
+  it('propagates hub deletions by omission and acks the tombstone', async () => {
+    const [annotation] = (await findCanonicalAnnotations()).filter((row) => row.deletedAt === null);
+    const remove = await ctx.app.inject({
+      method: 'DELETE',
+      url: `/api/v1/books/${epub.bookId}/annotations/${annotation.id}`,
+      headers: authHeader(ctx.adminToken),
+    });
+    expect([200, 204]).toContain(remove.statusCode);
+
+    expect(await checkForChanges()).toEqual([contentId]);
+
+    const body = await getAnnotations();
+    expect(body.annotations).toHaveLength(0);
+
+    const [state] = await ctx.db
+      .select()
+      .from(schema.annotationSyncState)
+      .where(
+        and(
+          eq(schema.annotationSyncState.annotationId, annotation.id),
+          eq(schema.annotationSyncState.source, 'kobo'),
+          eq(schema.annotationSyncState.deviceId, String(deviceDbId)),
+        ),
+      );
+    expect(state.deleteAckedAt).not.toBeNull();
+
+    expect(await checkForChanges()).toEqual([]);
+  });
+
+  it('converts a KoboSpan reading-state bookmark to precise cfi and xpointer progress', async () => {
+    const enable = await ctx.app.inject({
+      method: 'PATCH',
+      url: '/api/v1/kobo/settings',
+      headers: authHeader(ctx.adminToken),
+      payload: { twoWayProgressSync: true },
+    });
+    expect(enable.statusCode).toBe(200);
+
+    const put = await ctx.app.inject({
+      method: 'PUT',
+      url: v3Url(`v1/library/${contentId}/state`),
+      payload: {
+        ReadingStates: [
+          {
+            EntitlementId: contentId,
+            LastModified: '2026-06-11T10:00:00Z',
+            CurrentBookmark: {
+              LastModified: '2026-06-11T10:00:00Z',
+              ProgressPercent: 42,
+              ContentSourceProgressPercent: 10,
+              Location: { Source: 'OPS/chapter.xhtml', Type: 'KoboSpan', Value: 'kobo.1.1' },
+            },
+          },
+        ],
+      },
+    });
+    expect(put.statusCode).toBe(200);
+
+    const [progress] = await ctx.db
+      .select()
+      .from(schema.readingProgress)
+      .where(and(eq(schema.readingProgress.userId, adminUserId), eq(schema.readingProgress.bookFileId, epub.bookFileId)));
+    expect(progress).toBeDefined();
+    expect(progress.percentage).toBe(42);
+    expect(progress.cfi).toBe('epubcfi(/6/2!/4/2/1:0)');
+    expect(progress.koreaderProgress).toBe(FIXTURE_XPOINTER_0);
+    expect(progress.koboLocationValue).toBe('kobo.1.1');
+  });
+
+  it('serves a recomputed KoboSpan Location after the web reader moves the position', async () => {
+    const save = await ctx.app.inject({
+      method: 'POST',
+      url: `/api/v1/books/files/${epub.bookFileId}/progress`,
+      headers: authHeader(ctx.adminToken),
+      payload: { percentage: 55, cfi: 'epubcfi(/6/2!/4/2/1:4)' },
+    });
+    expect([200, 201, 204]).toContain(save.statusCode);
+
+    const state = await ctx.app.inject({ method: 'GET', url: v3Url(`v1/library/${contentId}/state`) });
+    expect(state.statusCode).toBe(200);
+    const body = state.json() as { CurrentBookmark: { ProgressPercent: number; Location: { Source: string; Type: string; Value: string } } }[];
+    const bookmark = (Array.isArray(body) ? body[0] : body).CurrentBookmark;
+    expect(bookmark.ProgressPercent).toBe(55);
+    expect(bookmark.Location).toMatchObject({ Type: 'KoboSpan', Value: 'kobo.1.1', Source: 'OPS/chapter.xhtml' });
+  });
+
+  it('completes the mesh: a kobo upload reaches a koreader device as an xpointer add', async () => {
+    const credentials = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/credentials',
+      headers: authHeader(ctx.adminToken),
+      payload: { username: KOREADER_USERNAME, password: KOREADER_PASSWORD },
+    });
+    if (credentials.statusCode === 409) {
+      const updated = await ctx.app.inject({
+        method: 'PATCH',
+        url: '/api/v1/koreader/credentials',
+        headers: authHeader(ctx.adminToken),
+        payload: { username: KOREADER_USERNAME, password: KOREADER_PASSWORD },
+      });
+      expect(updated.statusCode).toBe(200);
+    } else {
+      expect([200, 201]).toContain(credentials.statusCode);
+    }
+
+    const koboUploadId = randomUUID();
+    await patchAnnotations({
+      updatedAnnotations: [
+        {
+          id: koboUploadId,
+          type: 'highlight',
+          highlightColor: '#E8AFCF',
+          highlightedText: 'fixture',
+          location: KOBO_LOCATION,
+          clientLastModifiedUtc: '2026-06-11T09:30:00Z',
+        },
+      ],
+    });
+
+    const exchange = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/plugin/annotations/exchange',
+      headers: { 'x-auth-user': KOREADER_USERNAME, 'x-auth-key': KOREADER_PASSWORD },
+      payload: {
+        deviceId: 'mesh-koreader-001',
+        deviceModel: 'E2E',
+        pluginVersion: '0.4.0',
+        books: [{ hash: fileHash, keys: [], keysComplete: true, changes: [] }],
+      },
+    });
+    expect(exchange.statusCode).toBe(201);
+    const result = (exchange.json() as { results: { toApply: { add: { text: string; posFormat: string; pos0: string }[] } }[] }).results[0];
+    const added = result.toApply.add.find((entry) => entry.text === 'fixture');
+    expect(added).toBeDefined();
+    expect(added!.posFormat).toBe('xpointer');
+    expect(added!.pos0).toBe(FIXTURE_XPOINTER_0);
+  });
+});
diff --git a/server/test/koreader-annotation-exchange.e2e-spec.ts b/server/test/koreader-annotation-exchange.e2e-spec.ts
new file mode 100644
index 000000000..cd34af48e
--- /dev/null
+++ b/server/test/koreader-annotation-exchange.e2e-spec.ts
@@ -0,0 +1,299 @@
+import { randomUUID } from 'crypto';
+import { and, eq } from 'drizzle-orm';
+
+import * as schema from '../src/db/schema';
+import { createEpubFixture } from './e2e/reader-state-isolation/reader-state-isolation-fixture-builder';
+import {
+  authHeader,
+  closeReaderStateIsolationE2EContext,
+  createLibraryWithFolder,
+  createReaderStateIsolationE2EContext,
+  locateBookByAbsolutePath,
+  triggerAndWaitForLibraryScan,
+  type CreatedLibrary,
+  type LocatedBookFile,
+  type ReaderStateIsolationE2EContext,
+} from './e2e/reader-state-isolation/reader-state-isolation-harness';
+
+const KOREADER_USERNAME = `exchange-device-${randomUUID().slice(0, 8)}`;
+const KOREADER_PASSWORD = 'ExchangeDevicePass123';
+const DEVICE_ID = 'e2e-device-0001';
+const OTHER_DEVICE_ID = 'e2e-device-0002';
+
+// The fixture chapter body is exactly <p>fixture</p>.
+const FIXTURE_CFI = 'epubcfi(/6/2!/4/2,/1:0,/1:7)';
+const FIXTURE_XPOINTER_0 = '/body/DocFragment[1]/body/p/text().0';
+const FIXTURE_XPOINTER_1 = '/body/DocFragment[1]/body/p/text().7';
+
+interface ExchangeBookPayload {
+  hash: string;
+  keys: { k: string; dt: string }[];
+  keysComplete: boolean;
+  changes: Record<string, unknown>[];
+}
+
+describe('KOReader annotation exchange (e2e)', { timeout: 120_000 }, () => {
+  let ctx!: ReaderStateIsolationE2EContext;
+  let library!: CreatedLibrary;
+  let epub!: LocatedBookFile;
+  let fileHash!: string;
+
+  function deviceHeaders(): Record<string, string> {
+    return { 'x-auth-user': KOREADER_USERNAME, 'x-auth-key': KOREADER_PASSWORD };
+  }
+
+  async function exchange(books: ExchangeBookPayload[], deviceId = DEVICE_ID) {
+    const response = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/plugin/annotations/exchange',
+      headers: deviceHeaders(),
+      payload: { deviceId, deviceModel: 'E2E', pluginVersion: '0.4.0', books },
+    });
+    expect(response.statusCode).toBe(201);
+    return response.json() as {
+      results: {
+        hash: string;
+        bookId: number;
+        applied: Record<string, number>;
+        toApply: { add: Record<string, unknown>[]; edit: Record<string, unknown>[]; delete: Record<string, unknown>[] };
+        more: boolean;
+        skippedNoPosition: number;
+      }[];
+      unmatched: string[];
+    };
+  }
+
+  async function exchangeAck(books: Record<string, unknown>[], deviceId = DEVICE_ID) {
+    const response = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/plugin/annotations/exchange-ack',
+      headers: deviceHeaders(),
+      payload: { deviceId, deviceModel: 'E2E', pluginVersion: '0.4.0', books },
+    });
+    expect(response.statusCode).toBe(201);
+    return response.json() as { results: { hash: string; acked: number }[]; unmatched: string[] };
+  }
+
+  beforeAll(async () => {
+    ctx = await createReaderStateIsolationE2EContext();
+    library = await createLibraryWithFolder(ctx, { name: `koreader-exchange-${randomUUID()}` });
+    const epubPath = await createEpubFixture(library.folderPath, 'exchange-book.epub', {
+      title: `Exchange Book ${randomUUID()}`,
+      uid: `urn:uuid:${randomUUID()}`,
+    });
+    await triggerAndWaitForLibraryScan(ctx, library.libraryId);
+    epub = await locateBookByAbsolutePath(ctx, epubPath);
+
+    const [fileRow] = await ctx.db
+      .select({ fileHash: schema.bookFiles.fileHash })
+      .from(schema.bookFiles)
+      .where(eq(schema.bookFiles.id, epub.bookFileId));
+    expect(fileRow?.fileHash).toBeTruthy();
+    fileHash = fileRow!.fileHash!;
+
+    const credentials = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/credentials',
+      headers: authHeader(ctx.adminToken),
+      payload: { username: KOREADER_USERNAME, password: KOREADER_PASSWORD },
+    });
+    if (credentials.statusCode === 409) {
+      const updated = await ctx.app.inject({
+        method: 'PATCH',
+        url: '/api/v1/koreader/credentials',
+        headers: authHeader(ctx.adminToken),
+        payload: { username: KOREADER_USERNAME, password: KOREADER_PASSWORD },
+      });
+      expect(updated.statusCode).toBe(200);
+    } else {
+      expect([200, 201]).toContain(credentials.statusCode);
+    }
+  }, 120_000);
+
+  afterAll(async () => {
+    if (ctx) await closeReaderStateIsolationE2EContext(ctx);
+  });
+
+  it('ingests device changes, then pushes nothing back to the same device', async () => {
+    const first = await exchange([
+      {
+        hash: fileHash,
+        keys: [],
+        keysComplete: false,
+        changes: [
+          {
+            datetime: '2026-06-01 10:00:00',
+            drawer: 'lighten',
+            color: 'yellow',
+            text: 'fixture',
+            posFormat: 'xpointer',
+            pos0: FIXTURE_XPOINTER_0,
+            pos1: FIXTURE_XPOINTER_1,
+          },
+        ],
+      },
+    ]);
+
+    expect(first.results[0].applied.created).toBe(1);
+    expect(first.results[0].toApply.add).toEqual([]);
+    expect(first.results[0].toApply.edit).toEqual([]);
+    expect(first.results[0].toApply.delete).toEqual([]);
+
+    const annotations = await ctx.app.inject({
+      method: 'GET',
+      url: `/api/v1/books/${epub.bookId}/annotations`,
+      headers: authHeader(ctx.adminToken),
+    });
+    expect(annotations.statusCode).toBe(200);
+    expect(annotations.json()).toHaveLength(1);
+
+    const retry = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    expect(retry.results[0].applied.created).toBe(0);
+    expect(retry.results[0].toApply.add).toEqual([]);
+  });
+
+  it('pushes the device-origin annotation to a second device and acks it', async () => {
+    const pull = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }], OTHER_DEVICE_ID);
+    const add = pull.results[0].toApply.add[0];
+    expect(add).toMatchObject({
+      datetime: '2026-06-01 10:00:00',
+      drawer: 'lighten',
+      posFormat: 'xpointer',
+      pos0: FIXTURE_XPOINTER_0,
+      pos1: FIXTURE_XPOINTER_1,
+      text: 'fixture',
+    });
+
+    const ack = await exchangeAck(
+      [
+        {
+          hash: fileHash,
+          applied: [{ serverId: add.serverId, version: add.version, status: 'applied', verified: true }],
+          deleted: [],
+        },
+      ],
+      OTHER_DEVICE_ID,
+    );
+    expect(ack.results[0].acked).toBe(1);
+
+    const after = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }], OTHER_DEVICE_ID);
+    expect(after.results[0].toApply.add).toEqual([]);
+  });
+
+  it('converts a web annotation and delivers it with a minted datetime, ack-gated', async () => {
+    const created = await ctx.app.inject({
+      method: 'POST',
+      url: `/api/v1/books/${epub.bookId}/annotations`,
+      headers: authHeader(ctx.adminToken),
+      payload: { cfi: FIXTURE_CFI, text: 'fixture', color: '#FACC15', style: 'squiggly', note: 'from web' },
+    });
+    expect(created.statusCode).toBe(201);
+    const webAnnotationId = (created.json() as { id: number }).id;
+
+    // First exchange spends the conversion budget and defers the entry.
+    const first = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    expect(first.results[0].toApply.add).toEqual([]);
+
+    const second = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    const add = second.results[0].toApply.add.find((entry) => entry.serverId === webAnnotationId);
+    expect(add).toBeDefined();
+    expect(add).toMatchObject({
+      drawer: 'underscore',
+      color: 'yellow',
+      text: 'fixture',
+      note: 'from web',
+      posFormat: 'xpointer',
+      pos0: FIXTURE_XPOINTER_0,
+      pos1: FIXTURE_XPOINTER_1,
+    });
+    expect(add!.datetime).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+
+    // Idempotent retry before ack: the same entry comes back.
+    const retry = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    const retryAdd = retry.results[0].toApply.add.find((entry) => entry.serverId === webAnnotationId);
+    expect(retryAdd?.datetime).toBe(add!.datetime);
+
+    const ack = await exchangeAck([
+      {
+        hash: fileHash,
+        applied: [{ serverId: webAnnotationId, version: add!.version, status: 'applied', verified: true }],
+        deleted: [],
+      },
+    ]);
+    expect(ack.results[0].acked).toBe(1);
+
+    const after = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    expect(after.results[0].toApply.add.find((entry) => entry.serverId === webAnnotationId)).toBeUndefined();
+
+    // The device echoing the applied annotation back must not duplicate or bump anything.
+    const echo = await exchange([
+      {
+        hash: fileHash,
+        keys: [],
+        keysComplete: false,
+        changes: [
+          {
+            datetime: add!.datetime,
+            drawer: 'underscore',
+            color: 'yellow',
+            text: 'fixture',
+            note: 'from web',
+            posFormat: 'xpointer',
+            pos0: FIXTURE_XPOINTER_0,
+            pos1: FIXTURE_XPOINTER_1,
+          },
+        ],
+      },
+    ]);
+    expect(echo.results[0].applied.created).toBe(0);
+    expect(echo.results[0].applied.unchanged).toBe(1);
+
+    const [row] = await ctx.db.select().from(schema.annotations).where(eq(schema.annotations.id, webAnnotationId));
+    expect(row.style).toBe('squiggly');
+    expect(row.color).toBe('#FACC15');
+  });
+
+  it('propagates a web deletion to the device and detects device deletions', async () => {
+    const listBefore = await ctx.app.inject({
+      method: 'GET',
+      url: `/api/v1/books/${epub.bookId}/annotations`,
+      headers: authHeader(ctx.adminToken),
+    });
+    const webAnnotation = (listBefore.json() as { id: number; note: string | null }[]).find((entry) => entry.note === 'from web');
+    expect(webAnnotation).toBeDefined();
+
+    const deletion = await ctx.app.inject({
+      method: 'DELETE',
+      url: `/api/v1/books/${epub.bookId}/annotations/${webAnnotation!.id}`,
+      headers: authHeader(ctx.adminToken),
+    });
+    expect(deletion.statusCode).toBe(204);
+
+    const pull = await exchange([{ hash: fileHash, keys: [], keysComplete: false, changes: [] }]);
+    const deleteEntry = pull.results[0].toApply.delete.find((entry) => entry.serverId === webAnnotation!.id);
+    expect(deleteEntry).toBeDefined();
+
+    const ack = await exchangeAck([{ hash: fileHash, applied: [], deleted: [{ serverId: webAnnotation!.id, status: 'applied' }] }]);
+    expect(ack.results[0].acked).toBe(1);
+
+    // Device-side deletion: the device reports a complete key set missing the
+    // device-origin annotation from the first test.
+    const detect = await exchange([{ hash: fileHash, keys: [], keysComplete: true, changes: [] }]);
+    expect(detect.results[0].applied.deviceDeleted).toBe(1);
+
+    const [deviceRow] = await ctx.db
+      .select()
+      .from(schema.annotations)
+      .where(and(eq(schema.annotations.deviceCreatedAt, '2026-06-01 10:00:00'), eq(schema.annotations.bookId, epub.bookId)));
+    expect(deviceRow.deletedAt).not.toBeNull();
+  });
+
+  it('rejects exchange calls without device credentials', async () => {
+    const response = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/koreader/plugin/annotations/exchange',
+      payload: { deviceId: DEVICE_ID, deviceModel: 'E2E', pluginVersion: '0.4.0', books: [] },
+    });
+    expect(response.statusCode).toBe(401);
+  });
+});