From 70e76600e0afccf01811ac87afab05479a5b774b Mon Sep 17 00:00:00 2001
From: neon <18559658+neonsolstice@users.noreply.github.com>
Date: Fri, 3 Apr 2026 20:48:11 -0600
Subject: [PATCH] feat(server): add Booklore migration with source adapter and
 executor

---
 .husky/pre-commit                             |    6 +
 .husky/pre-push                               |    6 +
 .../components/__tests__/DetailsTab.spec.ts   |   33 +-
 .../components/detail/tabs/DetailsTab.vue     |    3 +-
 .../components/AddToCollectionSheet.vue       |   13 +-
 .../components/CreateCollectionDialog.vue     |   19 +-
 .../components/EditCollectionDialog.vue       |   33 +-
 .../__tests__/useCollections.spec.ts          |   68 +
 .../collection/composables/useCollections.ts  |   13 +-
 .../features/migration/lib/migration-api.ts   |  266 ++++
 .../__tests__/useFoliateInput.spec.ts         |   32 +-
 .../__tests__/useFoliateSelection.spec.ts     |    4 +-
 .../composables/__tests__/useSearch.spec.ts   |    8 +-
 .../src/features/reader/pdf/PdfReaderView.vue |    5 +-
 .../features/settings/MigrationSettings.vue   | 1193 +++++++++++++++++
 .../src/features/settings/SettingsHeader.vue  |    3 +
 client/src/router/index.ts                    |    6 +
 client/src/views/CollectionView.vue           |   22 +-
 server/package.json                           |   21 +-
 server/src/app.module.ts                      |    2 +
 server/src/db/migrations/0000_baseline.sql    |   90 ++
 .../src/db/migrations/meta/0000_snapshot.json |  712 +++++++++-
 server/src/db/migrations/meta/_journal.json   |    2 +-
 server/src/db/schema/index.ts                 |    1 +
 server/src/db/schema/migration.ts             |  146 ++
 server/src/db/schema/schema.test.ts           |    6 +
 .../architecture-boundaries.test.ts           |    2 +
 .../auth/oidc/oidc-session.repository.test.ts |    1 +
 .../modules/catalog/catalog.service.test.ts   |    1 +
 .../modules/collection/collection.dto.test.ts |    4 +-
 .../modules/collection/collection.service.ts  |    2 +-
 .../collection/dto/create-collection.dto.ts   |   10 +-
 .../email/email-recipient.repository.test.ts  |    1 +
 .../booklore-connection-config.test.ts        |   30 +
 .../booklore/booklore-connection-config.ts    |   38 +
 .../adapters/booklore/booklore-connector.ts   |   65 +
 .../booklore/booklore-source.adapter.test.ts  |   29 +
 .../booklore/booklore-source.adapter.ts       | 1076 +++++++++++++++
 .../adapters/source-adapter.registry.ts       |   27 +
 .../adapters/source-adapter.types.ts          |  158 +++
 .../src/modules/migration/core/hash.test.ts   |   17 +
 server/src/modules/migration/core/hash.ts     |   18 +
 .../modules/migration/core/plan-hash.test.ts  |   56 +
 .../src/modules/migration/core/plan-hash.ts   |   46 +
 .../migration/dto/create-dry-run-plan.dto.ts  |   13 +
 .../dto/create-migration-profile.dto.ts       |   53 +
 .../dto/create-migration-source.dto.ts        |   16 +
 .../migration/dto/start-live-run.dto.ts       |   14 +
 .../dto/test-migration-source.dto.ts          |   11 +
 .../dto/validate-path-mappings.dto.ts         |   28 +
 .../migration-executor.service.test.ts        |  381 ++++++
 .../executor/migration-executor.service.ts    | 1146 ++++++++++++++++
 .../modules/migration/migration.controller.ts |   95 ++
 .../migration/migration.module.test.ts        |   33 +
 .../src/modules/migration/migration.module.ts |   31 +
 .../modules/migration/migration.repository.ts |  266 ++++
 .../migration/migration.service.test.ts       |  251 ++++
 .../modules/migration/migration.service.ts    |  576 ++++++++
 .../planner/matching.service.test.ts          |   32 +
 .../migration/planner/matching.service.ts     |  217 +++
 .../path-mapping-validation.service.test.ts   |   88 ++
 .../path-mapping-validation.service.ts        |  155 +++
 .../migration/planner/planner.service.ts      |  207 +++
 .../migration/planner/planner.types.ts        |   79 ++
 .../reporting/migration-reporting.service.ts  |  140 ++
 65 files changed, 8068 insertions(+), 58 deletions(-)
 create mode 100644 client/src/features/collection/composables/__tests__/useCollections.spec.ts
 create mode 100644 client/src/features/migration/lib/migration-api.ts
 create mode 100644 client/src/features/settings/MigrationSettings.vue
 create mode 100644 server/src/db/schema/migration.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-connection-config.test.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-connection-config.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-connector.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
 create mode 100644 server/src/modules/migration/adapters/source-adapter.registry.ts
 create mode 100644 server/src/modules/migration/adapters/source-adapter.types.ts
 create mode 100644 server/src/modules/migration/core/hash.test.ts
 create mode 100644 server/src/modules/migration/core/hash.ts
 create mode 100644 server/src/modules/migration/core/plan-hash.test.ts
 create mode 100644 server/src/modules/migration/core/plan-hash.ts
 create mode 100644 server/src/modules/migration/dto/create-dry-run-plan.dto.ts
 create mode 100644 server/src/modules/migration/dto/create-migration-profile.dto.ts
 create mode 100644 server/src/modules/migration/dto/create-migration-source.dto.ts
 create mode 100644 server/src/modules/migration/dto/start-live-run.dto.ts
 create mode 100644 server/src/modules/migration/dto/test-migration-source.dto.ts
 create mode 100644 server/src/modules/migration/dto/validate-path-mappings.dto.ts
 create mode 100644 server/src/modules/migration/executor/migration-executor.service.test.ts
 create mode 100644 server/src/modules/migration/executor/migration-executor.service.ts
 create mode 100644 server/src/modules/migration/migration.controller.ts
 create mode 100644 server/src/modules/migration/migration.module.test.ts
 create mode 100644 server/src/modules/migration/migration.module.ts
 create mode 100644 server/src/modules/migration/migration.repository.ts
 create mode 100644 server/src/modules/migration/migration.service.test.ts
 create mode 100644 server/src/modules/migration/migration.service.ts
 create mode 100644 server/src/modules/migration/planner/matching.service.test.ts
 create mode 100644 server/src/modules/migration/planner/matching.service.ts
 create mode 100644 server/src/modules/migration/planner/path-mapping-validation.service.test.ts
 create mode 100644 server/src/modules/migration/planner/path-mapping-validation.service.ts
 create mode 100644 server/src/modules/migration/planner/planner.service.ts
 create mode 100644 server/src/modules/migration/planner/planner.types.ts
 create mode 100644 server/src/modules/migration/reporting/migration-reporting.service.ts

diff --git a/.husky/pre-commit b/.husky/pre-commit
index 5ee7abd87..40b568f76 100644
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +1,7 @@
+# Load nvm/pnpm if not in PATH (needed for GUI clients like Sourcetree)
+export PATH="$PATH:/usr/local/bin"
+export PNPM_HOME="$HOME/Library/pnpm"
+export PATH="$PNPM_HOME:$PATH"
+[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
+
 pnpm exec lint-staged
diff --git a/.husky/pre-push b/.husky/pre-push
index e01991635..7d7fc4516 100755
--- a/.husky/pre-push
+++ b/.husky/pre-push
@@ -1 +1,7 @@
+# Load nvm/pnpm if not in PATH (needed for GUI clients like Sourcetree)
+export PATH="$PATH:/usr/local/bin"
+export PNPM_HOME="$HOME/Library/pnpm"
+export PATH="$PNPM_HOME:$PATH"
+[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
+
 pnpm run verify:fast
diff --git a/client/src/features/book/components/__tests__/DetailsTab.spec.ts b/client/src/features/book/components/__tests__/DetailsTab.spec.ts
index cb0d64980..5aa8a4b94 100644
--- a/client/src/features/book/components/__tests__/DetailsTab.spec.ts
+++ b/client/src/features/book/components/__tests__/DetailsTab.spec.ts
@@ -1,4 +1,4 @@
-import { mount } from '@vue/test-utils'
+import { flushPromises, mount } from '@vue/test-utils'
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 
 beforeEach(() => {
@@ -13,6 +13,7 @@ beforeEach(() => {
 })
 import DetailsTab from '../detail/tabs/DetailsTab.vue'
 import type { BookDetail } from '@projectx/types'
+import { api } from '@/lib/api'
 
 vi.mock('vue-router', async (importOriginal) => {
   const actual = await importOriginal<typeof import('vue-router')>()
@@ -92,6 +93,13 @@ function makeBook(overrides: Partial<BookDetail> = {}): BookDetail {
   }
 }
 
+function makeApiResponse(data: unknown, ok = true): Response {
+  return {
+    ok,
+    json: async () => data,
+  } as Response
+}
+
 describe('DetailsTab — missing state', () => {
   it('renders the amber warning banner', () => {
     const wrapper = mount(DetailsTab, {
@@ -146,4 +154,27 @@ describe('DetailsTab — present state', () => {
     expect(wrapper.find('a[title="Open in Goodreads"]').exists()).toBe(true)
     expect(wrapper.text()).not.toContain('Info Links')
   })
+
+  it('renders only collections that already contain the book', async () => {
+    vi.mocked(api).mockImplementation(async (input) => {
+      if (input === '/api/v1/collections?bookIds=1') {
+        return makeApiResponse([
+          { id: 10, name: 'Favorites', syncToKobo: false, memberCount: 1 },
+          { id: 11, name: 'Want to Read', syncToKobo: true, memberCount: 0 },
+        ])
+      }
+
+      return makeApiResponse({}, false)
+    })
+
+    const wrapper = mount(DetailsTab, {
+      props: { book: makeBook({ id: 1 }) },
+      global: globalStubs,
+    })
+
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Favorites')
+    expect(wrapper.text()).not.toContain('Want to Read')
+  })
 })
diff --git a/client/src/features/book/components/detail/tabs/DetailsTab.vue b/client/src/features/book/components/detail/tabs/DetailsTab.vue
index 3e4ad765d..ba4e6cc6e 100644
--- a/client/src/features/book/components/detail/tabs/DetailsTab.vue
+++ b/client/src/features/book/components/detail/tabs/DetailsTab.vue
@@ -605,7 +605,8 @@ async function loadSupplemental() {
       audiobookProgress.value = null
     }
 
-    collections.value = collectionsRes.ok ? ((await collectionsRes.json()) as CollectionMembership[]) : []
+    const fetchedCollections = collectionsRes.ok ? ((await collectionsRes.json()) as CollectionMembership[]) : []
+    collections.value = fetchedCollections.filter((collection) => (collection.memberCount ?? 0) > 0)
 
     if (canViewKobo.value) {
       const fallbackSyncCollections = collections.value.filter((c) => c.syncToKobo && (c.memberCount ?? 0) > 0).map((c) => c.name)
diff --git a/client/src/features/collection/components/AddToCollectionSheet.vue b/client/src/features/collection/components/AddToCollectionSheet.vue
index 4e0e90dfe..f6f0754b7 100644
--- a/client/src/features/collection/components/AddToCollectionSheet.vue
+++ b/client/src/features/collection/components/AddToCollectionSheet.vue
@@ -6,6 +6,7 @@ import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sh
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { useCollections } from '../composables/useCollections'
+import IconPicker from '@/components/IconPicker.vue'
 import type { Collection } from '@projectx/types'
 
 const props = defineProps<{
@@ -23,6 +24,7 @@ const { fetchCollectionsWithMembership, createCollection, addBooksToCollection }
 const localCollections = ref<Collection[]>([])
 const addedIds = ref<Set<number>>(new Set())
 const newName = ref('')
+const newIcon = ref('')
 const creating = ref(false)
 const addingTo = ref<number | null>(null)
 
@@ -52,11 +54,13 @@ function partialCount(collection: Collection): number {
 
 async function handleCreate() {
   const name = newName.value.trim()
-  if (!name) return
+  const icon = newIcon.value.trim()
+  if (!name || !icon) return
   creating.value = true
   try {
-    const collection = await createCollection(name)
+    const collection = await createCollection(name, icon)
     newName.value = ''
+    newIcon.value = ''
     localCollections.value = [...localCollections.value, collection]
     try {
       await addBooksToCollection(collection.id, props.bookIds)
@@ -119,9 +123,10 @@ function handleDone() {
         <!-- Create new collection -->
         <div class="space-y-2">
           <p class="text-xs font-medium text-foreground uppercase tracking-wider">New Collection</p>
-          <div class="flex gap-2">
+          <div class="space-y-2">
             <Input v-model="newName" placeholder="Collection name" class="flex-1" @keydown.enter="handleCreate" />
-            <Button :disabled="!newName.trim() || creating" size="sm" @click="handleCreate">
+            <IconPicker v-model="newIcon" placeholder="Choose an icon..." />
+            <Button :disabled="!newName.trim() || !newIcon.trim() || creating" size="sm" class="w-full" @click="handleCreate">
               <Loader2 v-if="creating" :size="14" class="animate-spin mr-1" />
               <Plus v-else :size="14" class="mr-1" />
               Create
diff --git a/client/src/features/collection/components/CreateCollectionDialog.vue b/client/src/features/collection/components/CreateCollectionDialog.vue
index e1103db03..b400fff07 100644
--- a/client/src/features/collection/components/CreateCollectionDialog.vue
+++ b/client/src/features/collection/components/CreateCollectionDialog.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useRouter } from 'vue-router'
 import { X } from 'lucide-vue-next'
 import { useCollections } from '../composables/useCollections'
@@ -15,13 +15,22 @@ const name = ref('')
 const icon = ref('')
 const saving = ref(false)
 const error = ref<string | null>(null)
+const trimmedName = computed(() => name.value.trim())
+const trimmedIcon = computed(() => icon.value.trim())
 
 async function submit() {
-  if (!name.value.trim()) return
+  if (!trimmedName.value) {
+    error.value = 'Name is required'
+    return
+  }
+  if (!trimmedIcon.value) {
+    error.value = 'Choose an icon'
+    return
+  }
   saving.value = true
   error.value = null
   try {
-    const collection = await createCollection(name.value.trim(), icon.value.trim() || undefined)
+    const collection = await createCollection(trimmedName.value, trimmedIcon.value)
     name.value = ''
     icon.value = ''
     emit('close')
@@ -59,7 +68,7 @@ async function submit() {
           </div>
 
           <div class="flex flex-col gap-1.5">
-            <label class="text-sm font-medium text-foreground"> Icon <span class="text-muted-foreground font-normal">(optional)</span> </label>
+            <label class="text-sm font-medium text-foreground">Icon</label>
             <IconPicker v-model="icon" placeholder="Choose an icon..." />
           </div>
 
@@ -75,7 +84,7 @@ async function submit() {
             </button>
             <button
               type="submit"
-              :disabled="!name.trim() || saving"
+              :disabled="!trimmedName || !trimmedIcon || 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 ? 'Creating...' : 'Create' }}
diff --git a/client/src/features/collection/components/EditCollectionDialog.vue b/client/src/features/collection/components/EditCollectionDialog.vue
index 6cef5e3d1..89d0ffa9a 100644
--- a/client/src/features/collection/components/EditCollectionDialog.vue
+++ b/client/src/features/collection/components/EditCollectionDialog.vue
@@ -6,14 +6,15 @@ import IconPicker from '@/components/IconPicker.vue'
 import type { Collection } from '@projectx/types'
 
 const props = defineProps<{ open: boolean; collection: Collection }>()
-const emit = defineEmits<{ close: [] }>()
+const emit = defineEmits<{ close: []; deleted: [id: number] }>()
 
-const { updateCollection } = useCollections()
+const { updateCollection, deleteCollection } = useCollections()
 
 const name = ref('')
 const icon = ref('')
 const syncToKobo = ref(false)
 const saving = ref(false)
+const deleting = ref(false)
 const error = ref<string | null>(null)
 
 watch(
@@ -41,6 +42,21 @@ async function submit() {
     saving.value = false
   }
 }
+
+async function handleDelete() {
+  if (!confirm(`Delete collection "${props.collection.name}"? This cannot be undone.`)) return
+  deleting.value = true
+  error.value = null
+  try {
+    await deleteCollection(props.collection.id)
+    emit('deleted', props.collection.id)
+    emit('close')
+  } catch {
+    error.value = 'Failed to delete collection'
+  } finally {
+    deleting.value = false
+  }
+}
 </script>
 
 <template>
@@ -91,7 +107,16 @@ async function submit() {
 
           <p v-if="error" class="text-sm text-destructive">{{ error }}</p>
 
-          <div class="flex justify-end gap-2 mt-1">
+          <div class="flex items-center justify-between gap-2 mt-1">
+            <button
+              type="button"
+              :disabled="saving || deleting"
+              class="h-9 px-4 rounded-md border border-destructive/30 bg-destructive/10 text-sm font-medium text-destructive hover:bg-destructive/15 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+              @click="handleDelete"
+            >
+              {{ deleting ? 'Deleting...' : 'Delete collection' }}
+            </button>
+
             <button
               type="button"
               @click="emit('close')"
@@ -101,7 +126,7 @@ async function submit() {
             </button>
             <button
               type="submit"
-              :disabled="!name.trim() || saving"
+              :disabled="!name.trim() || saving || deleting"
               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...' : 'Save' }}
diff --git a/client/src/features/collection/composables/__tests__/useCollections.spec.ts b/client/src/features/collection/composables/__tests__/useCollections.spec.ts
new file mode 100644
index 000000000..a7fcca488
--- /dev/null
+++ b/client/src/features/collection/composables/__tests__/useCollections.spec.ts
@@ -0,0 +1,68 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Collection } from '@projectx/types'
+
+const apiMock = vi.hoisted(() => vi.fn<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>())
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}))
+
+function makeCollection(overrides: Partial<Collection> = {}): Collection {
+  return {
+    id: 7,
+    name: 'Favorites',
+    icon: 'FolderOpen',
+    description: null,
+    syncToKobo: false,
+    displayOrder: 0,
+    bookCount: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  }
+}
+
+function makeResponse(data?: unknown, ok = true): Response {
+  return {
+    ok,
+    json: async () => data,
+  } as Response
+}
+
+describe('useCollections', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    apiMock.mockReset()
+  })
+
+  it('creates collections with the provided icon', async () => {
+    const created = makeCollection()
+    apiMock.mockResolvedValueOnce(makeResponse(created))
+
+    const { useCollections } = await import('../useCollections')
+    const { collections, createCollection } = useCollections()
+
+    await createCollection('Favorites', 'FolderOpen')
+
+    const [, request] = apiMock.mock.calls[0] as [string, RequestInit]
+    expect(JSON.parse(String(request.body))).toEqual({
+      name: 'Favorites',
+      icon: 'FolderOpen',
+    })
+    expect(collections.value).toEqual([created])
+  })
+
+  it('removes deleted collections from local state', async () => {
+    const created = makeCollection()
+    apiMock.mockResolvedValueOnce(makeResponse(created)).mockResolvedValueOnce(makeResponse())
+
+    const { useCollections } = await import('../useCollections')
+    const { collections, createCollection, deleteCollection } = useCollections()
+
+    await createCollection(created.name, created.icon ?? 'FolderOpen')
+    await deleteCollection(created.id)
+
+    expect(apiMock).toHaveBeenLastCalledWith(`/api/v1/collections/${created.id}`, { method: 'DELETE' })
+    expect(collections.value).toEqual([])
+  })
+})
diff --git a/client/src/features/collection/composables/useCollections.ts b/client/src/features/collection/composables/useCollections.ts
index c43819568..4eebf39b7 100644
--- a/client/src/features/collection/composables/useCollections.ts
+++ b/client/src/features/collection/composables/useCollections.ts
@@ -28,11 +28,11 @@ export function useCollections() {
     return res.json()
   }
 
-  async function createCollection(name: string, icon?: string, description?: string): Promise<Collection> {
+  async function createCollection(name: string, icon: string, description?: string): Promise<Collection> {
     const res = await api('/api/v1/collections', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ name, icon: icon || undefined, description }),
+      body: JSON.stringify({ name, icon, description }),
     })
     if (!res.ok) throw new Error('Failed to create collection')
     const created: Collection = await res.json()
@@ -85,6 +85,14 @@ export function useCollections() {
     if (!res.ok) throw new Error('Failed to reorder collections')
   }
 
+  async function deleteCollection(id: number): Promise<void> {
+    const res = await api(`/api/v1/collections/${id}`, {
+      method: 'DELETE',
+    })
+    if (!res.ok) throw new Error('Failed to delete collection')
+    collections.value = collections.value.filter((collection) => collection.id !== id)
+  }
+
   return {
     collections,
     fetchCollections,
@@ -94,5 +102,6 @@ export function useCollections() {
     addBooksToCollection,
     removeBooksFromCollection,
     reorderCollections,
+    deleteCollection,
   }
 }
diff --git a/client/src/features/migration/lib/migration-api.ts b/client/src/features/migration/lib/migration-api.ts
new file mode 100644
index 000000000..961856938
--- /dev/null
+++ b/client/src/features/migration/lib/migration-api.ts
@@ -0,0 +1,266 @@
+import { api } from '@/lib/api'
+
+export type MigrationRunState = 'draft' | 'preflight_failed' | 'dry_run_ready' | 'running' | 'failed' | 'completed'
+
+export interface MigrationSourceCapabilities {
+  sourceType: string
+  sourceVersion: string | null
+  missingTables: string[]
+  warnings: string[]
+  counts: Record<string, number>
+}
+
+export interface MigrationSource {
+  id: number
+  type: string
+  name: string
+  connectionConfig: Record<string, unknown>
+  capabilities: MigrationSourceCapabilities | null
+  lastValidatedAt: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MigrationProfile {
+  id: number
+  sourceId: number
+  name: string
+  userMappings: Array<{ sourceUserId: string; targetUserId: number }>
+  pathMappings: Array<{ sourcePrefix: string; targetPrefix: string }>
+  scope: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MigrationPlanArtifact {
+  id: number
+  sourceId: number
+  profileId: number
+  plan: Record<string, unknown>
+  summary: {
+    generatedAt?: string
+    status?: string
+    matchedBooks?: number
+    unresolvedBooks?: number
+    duplicateBookMatches?: number
+    unresolvedByReason?: Record<string, number>
+    mappedUsers?: number
+    perUserPreview?: Array<{ sourceUserId: string; targetUserId: number; username: string; counts: Record<string, number> }>
+  }
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MigrationRun {
+  id: number
+  sourceId: number
+  profileId: number
+  planArtifactId: number | null
+  state: MigrationRunState
+  currentStage: string | null
+  startedAt: string | null
+  endedAt: string | null
+  errorMessage: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MigrationRunMetric {
+  id: number
+  runId: number
+  stage: string
+  entityType: string
+  processed: number
+  imported: number
+  skipped: number
+  unresolved: number
+  failed: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface MigrationRunProgress {
+  run: MigrationRun
+  totals: {
+    processed: number
+    imported: number
+    skipped: number
+    unresolved: number
+    failed: number
+  }
+  metrics: MigrationRunMetric[]
+}
+
+export interface MigrationRunReport {
+  run: MigrationRun
+  metrics: MigrationRunMetric[]
+  plan: Record<string, unknown> | null
+  summary: MigrationPlanArtifact['summary'] | null
+}
+
+export interface MigrationWorkflowState {
+  active: {
+    source: MigrationSource
+    profile: MigrationProfile | null
+    plan: MigrationPlanArtifact | null
+    run: MigrationRun | null
+  } | null
+  hasActiveRun: boolean
+}
+
+export interface PathMappingValidation {
+  sourceId: number
+  validatedAt: string
+  summary: {
+    totalSourceBooks: number
+    booksWithFilePath: number
+    mappedByPrefix: number
+    matchedTargetPaths: number
+    unmatchedTargetPaths: number
+    unchangedPaths: number
+  }
+  mappings: Array<{
+    sourcePrefix: string
+    targetPrefix: string
+    affectedBooks: number
+    matchedTargetPaths: number
+    unmatchedTargetPaths: number
+    unmatchedSamples: string[]
+  }>
+}
+
+export interface MappingSuggestion {
+  sourceUserId: string
+  username: string
+  name: string | null
+  email: string | null
+  suggestedTargetUserId: number | null
+  confidence: 'high' | 'medium' | 'low' | null
+  candidates: Array<{
+    targetUserId: number
+    username: string
+    name: string
+    email: string | null
+    score: number
+    confidence: 'high' | 'medium' | 'low'
+  }>
+}
+
+async function expectJson<T>(response: Response, fallbackMessage: string): Promise<T> {
+  if (response.ok) return (await response.json()) as T
+  const payload = await response.json().catch(() => ({}))
+  const message =
+    payload && typeof payload === 'object' && 'message' in payload && typeof payload.message === 'string' ? payload.message : fallbackMessage
+  throw new Error(message)
+}
+
+export function listSupportedSourceTypes() {
+  return api('/api/v1/migration/supported-types').then((res) => expectJson<string[]>(res, 'Failed to load supported migration source types'))
+}
+
+export function getWorkflowState() {
+  return api('/api/v1/migration/state').then((res) => expectJson<MigrationWorkflowState>(res, 'Failed to load migration state'))
+}
+
+export function listTargetUsers() {
+  return api('/api/v1/migration/target-users').then((res) =>
+    expectJson<Array<{ id: number; username: string; name: string; email: string | null }>>(res, 'Failed to load target users'),
+  )
+}
+
+export function listSourcePathPrefixes(sourceId: number) {
+  return api(`/api/v1/migration/sources/${sourceId}/path-prefixes`).then((res) =>
+    expectJson<{ prefixes: string[] }>(res, 'Failed to load source path prefixes'),
+  )
+}
+
+export function listTargetLibraryFolders() {
+  return api('/api/v1/libraries').then(async (res) => {
+    if (!res.ok) throw new Error('Failed to load libraries')
+    const libs = (await res.json()) as Array<{ id: number; name: string; folders: Array<{ id: number; path: string }> }>
+    return libs.flatMap((lib) => lib.folders.map((f) => ({ libraryName: lib.name, path: f.path })))
+  })
+}
+
+export function createSource(payload: { type: string; name: string; connectionConfig: Record<string, unknown> }) {
+  return api('/api/v1/migration/sources', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<MigrationSource>(res, 'Failed to save migration source'))
+}
+
+export function testSource(payload: { type: string; connectionConfig: Record<string, unknown> }) {
+  return api('/api/v1/migration/sources/test', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<Record<string, unknown>>(res, 'Failed to test migration source'))
+}
+
+export function validateSourceById(sourceId: number) {
+  return api(`/api/v1/migration/sources/${sourceId}/validate`, { method: 'POST' }).then((res) =>
+    expectJson<Record<string, unknown>>(res, 'Failed to validate migration source'),
+  )
+}
+
+export function suggestUserMappings(sourceId: number) {
+  return api(`/api/v1/migration/sources/${sourceId}/user-mapping-suggestions`).then((res) =>
+    expectJson<{ sourceId: number; generatedAt: string; suggestions: MappingSuggestion[] }>(res, 'Failed to load user mapping suggestions'),
+  )
+}
+
+export function validatePathMappings(
+  sourceId: number,
+  payload: { pathMappings: Array<{ sourcePrefix: string; targetPrefix: string }>; sampleLimit?: number },
+) {
+  return api(`/api/v1/migration/sources/${sourceId}/path-mappings/validate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<PathMappingValidation>(res, 'Failed to validate path mappings'))
+}
+
+export function createProfile(payload: {
+  sourceId: number
+  name: string
+  userMappings: Array<{ sourceUserId: string; targetUserId: number }>
+  pathMappings?: Array<{ sourcePrefix: string; targetPrefix: string }>
+  scope?: Record<string, unknown>
+}) {
+  return api('/api/v1/migration/profiles', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<MigrationProfile>(res, 'Failed to save migration profile'))
+}
+
+export function createDryRunPlan(payload: { profileId: number; scopeOverride?: Record<string, unknown> }) {
+  return api('/api/v1/migration/plans/dry-run', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<MigrationPlanArtifact>(res, 'Failed to run dry-run plan'))
+}
+
+export function startLiveRun(payload: { planArtifactId: number; targetKey?: string }) {
+  return api('/api/v1/migration/runs/live', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((res) => expectJson<MigrationRun>(res, 'Failed to start migration run'))
+}
+
+export function getRunProgress(runId: number) {
+  return api(`/api/v1/migration/runs/${runId}/progress`).then((res) => expectJson<MigrationRunProgress>(res, 'Failed to load migration run progress'))
+}
+
+export function getRunReport(runId: number) {
+  return api(`/api/v1/migration/runs/${runId}/report`).then((res) => expectJson<MigrationRunReport>(res, 'Failed to load migration run report'))
+}
+
+export function exportRunReport(runId: number, format: 'json' | 'csv') {
+  return api(`/api/v1/migration/runs/${runId}/report/export?format=${format}`).then((res) =>
+    expectJson<{ format: 'json' | 'csv'; fileName: string; contentType: string; content: string }>(res, 'Failed to export migration report'),
+  )
+}
diff --git a/client/src/features/reader/epub/composables/__tests__/useFoliateInput.spec.ts b/client/src/features/reader/epub/composables/__tests__/useFoliateInput.spec.ts
index 98ed59f17..2f7739bd8 100644
--- a/client/src/features/reader/epub/composables/__tests__/useFoliateInput.spec.ts
+++ b/client/src/features/reader/epub/composables/__tests__/useFoliateInput.spec.ts
@@ -32,15 +32,15 @@ describe('useFoliateInput', () => {
   })
 
   it('navigates with document keyboard shortcuts', () => {
-    const prev = vi.fn()
-    const next = vi.fn()
+    const prev = vi.fn<() => void>()
+    const next = vi.fn<() => void>()
     const view: ViewLike = {
       prev,
       next,
       getBoundingClientRect: () => ({ left: 0, width: 100 }) as DOMRect,
     }
 
-    const input = useFoliateInput(() => view, undefined, vi.fn(), vi.fn())
+    const input = useFoliateInput(() => view, undefined, vi.fn<() => void>(), vi.fn<() => void>())
 
     document.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }))
     document.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }))
@@ -54,15 +54,15 @@ describe('useFoliateInput', () => {
   })
 
   it('ignores keyboard navigation while typing in editable inputs', () => {
-    const prev = vi.fn()
-    const next = vi.fn()
+    const prev = vi.fn<() => void>()
+    const next = vi.fn<() => void>()
     const view: ViewLike = {
       prev,
       next,
       getBoundingClientRect: () => ({ left: 0, width: 100 }) as DOMRect,
     }
 
-    const input = useFoliateInput(() => view, undefined, vi.fn(), vi.fn())
+    const input = useFoliateInput(() => view, undefined, vi.fn<() => void>(), vi.fn<() => void>())
 
     const textInput = document.createElement('input')
     document.body.appendChild(textInput)
@@ -78,15 +78,15 @@ describe('useFoliateInput', () => {
   })
 
   it('handles keyboard navigation from iframe document after attachIframeClicks', () => {
-    const prev = vi.fn()
-    const next = vi.fn()
+    const prev = vi.fn<() => void>()
+    const next = vi.fn<() => void>()
     const view: ViewLike = {
       prev,
       next,
       getBoundingClientRect: () => ({ left: 0, width: 100 }) as DOMRect,
     }
 
-    const input = useFoliateInput(() => view, undefined, vi.fn(), vi.fn())
+    const input = useFoliateInput(() => view, undefined, vi.fn<() => void>(), vi.fn<() => void>())
     const doc = makeDocTarget()
 
     input.attachIframeClicks(doc)
@@ -103,16 +103,16 @@ describe('useFoliateInput', () => {
   it('routes click-zone window messages to prev/next/middle actions', () => {
     vi.useFakeTimers()
 
-    const prev = vi.fn()
-    const next = vi.fn()
-    const onMiddleTap = vi.fn()
+    const prev = vi.fn<() => void>()
+    const next = vi.fn<() => void>()
+    const onMiddleTap = vi.fn<() => void>()
     const view: ViewLike = {
       prev,
       next,
       getBoundingClientRect: () => ({ left: 0, width: 100 }) as DOMRect,
     }
 
-    const input = useFoliateInput(() => view, onMiddleTap, vi.fn(), vi.fn())
+    const input = useFoliateInput(() => view, onMiddleTap, vi.fn<() => void>(), vi.fn<() => void>())
     const doc = makeDocTarget()
     input.attachIframeClicks(doc)
 
@@ -155,14 +155,14 @@ describe('useFoliateInput', () => {
   })
 
   it('stops responding to document keydown after cleanup', () => {
-    const next = vi.fn()
+    const next = vi.fn<() => void>()
     const view: ViewLike = {
-      prev: vi.fn(),
+      prev: vi.fn<() => void>(),
       next,
       getBoundingClientRect: () => ({ left: 0, width: 100 }) as DOMRect,
     }
 
-    const input = useFoliateInput(() => view, undefined, vi.fn(), vi.fn())
+    const input = useFoliateInput(() => view, undefined, vi.fn<() => void>(), vi.fn<() => void>())
     input.cleanup()
 
     document.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }))
diff --git a/client/src/features/reader/epub/composables/__tests__/useFoliateSelection.spec.ts b/client/src/features/reader/epub/composables/__tests__/useFoliateSelection.spec.ts
index 49ef6777d..4997c193e 100644
--- a/client/src/features/reader/epub/composables/__tests__/useFoliateSelection.spec.ts
+++ b/client/src/features/reader/epub/composables/__tests__/useFoliateSelection.spec.ts
@@ -82,7 +82,7 @@ describe('useFoliateSelection', () => {
 
     const getView = () => null
     const foliateSelection = useFoliateSelection(getView)
-    const onSelected = vi.fn()
+    const onSelected = vi.fn<(detail: unknown) => void>()
     foliateSelection.setHandler(onSelected)
 
     const collapsed = {
@@ -126,7 +126,7 @@ describe('useFoliateSelection', () => {
       getCFI: () => 'epubcfi(/6/10)',
     }))
 
-    const onSelected = vi.fn()
+    const onSelected = vi.fn<(detail: unknown) => void>()
     foliateSelection.setHandler(onSelected)
 
     const doc = makeDoc({ selection })
diff --git a/client/src/features/reader/epub/composables/__tests__/useSearch.spec.ts b/client/src/features/reader/epub/composables/__tests__/useSearch.spec.ts
index 06def19a6..18e88c5d4 100644
--- a/client/src/features/reader/epub/composables/__tests__/useSearch.spec.ts
+++ b/client/src/features/reader/epub/composables/__tests__/useSearch.spec.ts
@@ -4,10 +4,10 @@ import { useSearch, type FoliateView } from '../useSearch'
 describe('useSearch', () => {
   it('returns early for empty query and does not call foliate search', async () => {
     const view: FoliateView = {
-      search: vi.fn(async function* () {
+      search: vi.fn<(opts: { query: string }) => AsyncGenerator<Record<string, unknown>, void, unknown>>(async function* () {
         yield {}
       }),
-      clearSearch: vi.fn(),
+      clearSearch: vi.fn<() => void>(),
     }
 
     const store = useSearch()
@@ -33,7 +33,7 @@ describe('useSearch', () => {
           subitems: [{ cfi: 'epubcfi(/6/8)', excerpt: { pre: '', match: 'hit', post: '' } }],
         }
       },
-      clearSearch: vi.fn(),
+      clearSearch: vi.fn<() => void>(),
     }
 
     const store = useSearch()
@@ -62,7 +62,7 @@ describe('useSearch', () => {
   })
 
   it('clear resets local search state and clears foliate highlights', () => {
-    const clearSearch = vi.fn()
+    const clearSearch = vi.fn<() => void>()
     const view: FoliateView = {
       search: async function* () {
         yield {}
diff --git a/client/src/features/reader/pdf/PdfReaderView.vue b/client/src/features/reader/pdf/PdfReaderView.vue
index dde5a6150..a435a258d 100644
--- a/client/src/features/reader/pdf/PdfReaderView.vue
+++ b/client/src/features/reader/pdf/PdfReaderView.vue
@@ -42,15 +42,16 @@ function measure() {
 
 // ── Page dims ─────────────────────────────────────────────────────────────────
 const pageDims = ref<PageDim[]>([])
+const effectiveDims = computed(() => pageDims.value)
 
 // ── Spread ────────────────────────────────────────────────────────────────────
 const spread = ref<'none' | 'odd' | 'even'>('none')
 
 // ── Composables ───────────────────────────────────────────────────────────────
-const zoom = usePdfZoom(containerW, containerH, pageDims, spread)
+const zoom = usePdfZoom(containerW, containerH, effectiveDims, spread)
 const { scale, zoomMode, customScale, zoomLabel, adjustZoom, applyZoomPreset } = zoom
 
-const layout = usePdfLayout(scrollRef, totalPages, pageDims, scale, containerH, spread)
+const layout = usePdfLayout(scrollRef, totalPages, effectiveDims, scale, containerH, spread)
 const { scrollMode, currentPage, pageInput, pageRows, rowHeights, goToPage, onScroll } = layout
 
 function onDimUpdate(pageNum: number, dim: PageDim) {
diff --git a/client/src/features/settings/MigrationSettings.vue b/client/src/features/settings/MigrationSettings.vue
new file mode 100644
index 000000000..d670d8697
--- /dev/null
+++ b/client/src/features/settings/MigrationSettings.vue
@@ -0,0 +1,1193 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { Eye, EyeOff, Loader2 } from 'lucide-vue-next'
+import { toast } from 'vue-sonner'
+import SettingsPageHeader from './SettingsPageHeader.vue'
+import {
+  createDryRunPlan,
+  createProfile,
+  createSource,
+  exportRunReport,
+  getRunProgress,
+  getRunReport,
+  getWorkflowState,
+  listSourcePathPrefixes,
+  listSupportedSourceTypes,
+  listTargetLibraryFolders,
+  listTargetUsers,
+  startLiveRun,
+  suggestUserMappings,
+  testSource,
+  validatePathMappings,
+  validateSourceById,
+  type MigrationPlanArtifact,
+  type MigrationProfile,
+  type MigrationRun,
+  type MigrationRunProgress,
+  type MigrationRunReport,
+  type MigrationSource,
+  type MigrationSourceCapabilities,
+  type MigrationWorkflowState,
+  type PathMappingValidation,
+} from '@/features/migration/lib/migration-api'
+
+interface TargetUser {
+  id: number
+  username: string
+  name: string
+  email: string | null
+}
+
+interface UserMappingDraft {
+  sourceUserId: string
+  username: string
+  targetUserId: number | null
+}
+
+interface PathMappingDraft {
+  sourcePrefix: string
+  targetPrefix: string
+}
+
+interface ReportUnresolvedBook {
+  sourceBookId: string
+  title: string | null
+  reason: string | null
+}
+
+const loading = ref(true)
+const supportedTypes = ref<string[]>([])
+const targetUsers = ref<TargetUser[]>([])
+const targetLibraryFolders = ref<Array<{ libraryName: string; path: string }>>([])
+const sourcePathPrefixes = ref<string[]>([])
+
+const workflowState = ref<MigrationWorkflowState | null>(null)
+const runProgress = ref<MigrationRunProgress | null>(null)
+const runReport = ref<MigrationRunReport | null>(null)
+const pathValidation = ref<PathMappingValidation | null>(null)
+const suggestionsLoadedAt = ref<string | null>(null)
+
+const userMappings = ref<UserMappingDraft[]>([])
+const pathMappings = ref<PathMappingDraft[]>([{ sourcePrefix: '', targetPrefix: '' }])
+
+const sourceDraft = reactive({
+  type: 'booklore',
+  name: 'Booklore',
+  host: '',
+  port: 3306,
+  user: '',
+  password: '',
+  database: '',
+  ssl: false,
+  mediaRootPath: '',
+})
+
+const busy = reactive({
+  testingSource: false,
+  savingSource: false,
+  loadingSuggestions: false,
+  savingProfile: false,
+  dryRun: false,
+  startingRun: false,
+  loadingProgress: false,
+  loadingReport: false,
+  exporting: false,
+})
+
+const showPassword = ref(false)
+
+const active = computed(() => workflowState.value?.active ?? null)
+const source = computed<MigrationSource | null>(() => active.value?.source ?? null)
+const profile = computed<MigrationProfile | null>(() => active.value?.profile ?? null)
+const plan = computed<MigrationPlanArtifact | null>(() => active.value?.plan ?? null)
+const run = computed<MigrationRun | null>(() => active.value?.run ?? null)
+const hasActiveRun = computed(() => workflowState.value?.hasActiveRun === true)
+const sourceCapabilities = computed<MigrationSourceCapabilities | null>(() => source.value?.capabilities ?? null)
+const sourceValidationWarnings = computed(() => sourceCapabilities.value?.warnings ?? [])
+const sourceRowCounts = computed(() => Object.entries(sourceCapabilities.value?.counts ?? {}).sort(([left], [right]) => left.localeCompare(right)))
+
+const stepStatus = computed(() => {
+  const src = source.value
+  return {
+    source: !src ? ('pending' as const) : src.lastValidatedAt ? ('done' as const) : ('saved' as const),
+    mappings: profile.value ? ('done' as const) : ('pending' as const),
+    dryRun: preflight.value.dryRunFresh ? ('done' as const) : ('pending' as const),
+    migration: !run.value
+      ? ('pending' as const)
+      : run.value.state === 'completed'
+        ? ('done' as const)
+        : run.value.state === 'failed'
+          ? ('failed' as const)
+          : ('running' as const),
+  }
+})
+
+const unresolvedSummary = computed(() => Object.entries(plan.value?.summary?.unresolvedByReason ?? {}))
+
+const preflight = computed(() => {
+  const issues: string[] = []
+  const currentSource = source.value
+  const currentProfile = profile.value
+  const currentPlan = plan.value
+  const sourceValidated = !!currentSource?.lastValidatedAt
+  const pathMappingsValidated = hasValidatedPathMappings(currentProfile)
+
+  let dryRunFresh = false
+  if (currentPlan && currentProfile && currentSource?.lastValidatedAt) {
+    const planCreated = new Date(currentPlan.createdAt)
+    const profileUpdated = new Date(currentProfile.updatedAt)
+    const sourceValidatedAt = new Date(currentSource.lastValidatedAt)
+    dryRunFresh = currentPlan.profileId === currentProfile.id && planCreated >= profileUpdated && planCreated >= sourceValidatedAt
+  }
+
+  if (!currentSource) issues.push('Save source connection settings')
+  else if (!sourceValidated) issues.push('Validate source connection')
+  if (!currentProfile) issues.push('Save user and path mappings')
+  else if (!pathMappingsValidated) issues.push('Save path mappings to validate them')
+  if (!dryRunFresh) issues.push('Run a fresh dry-run')
+  else if ((currentPlan?.summary?.duplicateBookMatches ?? 0) > 0 || currentPlan?.summary?.status === 'blocked') {
+    issues.push('Resolve duplicate target book matches in the dry-run')
+  }
+  if (hasActiveRun.value) issues.push('Wait for active run to finish')
+
+  return { sourceValidated, pathMappingsValidated, dryRunFresh, ready: issues.length === 0, issues }
+})
+
+const reportData = computed(() => {
+  const metrics = runReport.value?.metrics ?? runProgress.value?.metrics ?? []
+  const m = (stage: string, entity: string) => metrics.find((r) => r.stage === stage && r.entityType === entity) ?? null
+  const bookCovers = m('shared_overlays', 'book_covers')
+  const coversSkippedAll =
+    !!bookCovers && bookCovers.imported === 0 && bookCovers.skipped > 0 && bookCovers.unresolved === 0 && bookCovers.failed === 0
+  const unresolvedBooks = extractPlanUnresolvedBooks(runReport.value?.plan ?? plan.value?.plan ?? null)
+  const startedAt = run.value?.startedAt ? new Date(run.value.startedAt) : null
+  const endedAt = run.value?.endedAt ? new Date(run.value.endedAt) : null
+  return {
+    durationMs: startedAt && endedAt ? endedAt.getTime() - startedAt.getTime() : null,
+    bookMetadata: m('shared_overlays', 'book_metadata'),
+    bookAuthors: m('shared_overlays', 'book_authors'),
+    bookNarrators: m('shared_overlays', 'book_narrators'),
+    bookGenres: m('shared_overlays', 'book_genres'),
+    bookTags: m('shared_overlays', 'book_tags'),
+    bookCovers,
+    coversSkippedAll,
+    userBookStatus: m('user_state', 'user_book_status'),
+    readingProgress: m('user_state', 'reading_progress'),
+    audiobookProgress: m('user_state', 'audiobook_progress'),
+    bookmarks: m('user_state', 'bookmarks'),
+    annotations: m('user_state', 'annotations'),
+    collections: m('user_state', 'collections'),
+    unresolvedBooks,
+    coverFailureCount: bookCovers?.failed ?? 0,
+  }
+})
+
+let runPollTimer: ReturnType<typeof setInterval> | null = null
+
+onMounted(async () => {
+  await initialize()
+})
+
+onBeforeUnmount(() => {
+  stopRunPolling()
+})
+
+watch(
+  () => run.value?.state,
+  (state) => {
+    if (state === 'running') {
+      startRunPolling()
+      return
+    }
+    stopRunPolling()
+  },
+)
+
+async function initialize() {
+  loading.value = true
+  try {
+    const [typesRes, usersRes, foldersRes] = await Promise.all([listSupportedSourceTypes(), listTargetUsers(), listTargetLibraryFolders()])
+    supportedTypes.value = typesRes
+    targetUsers.value = usersRes
+    targetLibraryFolders.value = foldersRes
+    await refreshWorkflowState()
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to initialize migration settings'))
+  } finally {
+    loading.value = false
+  }
+}
+
+async function refreshWorkflowState() {
+  workflowState.value = await getWorkflowState()
+  hydrateSourceDraft()
+  hydratePathMappings()
+  hydrateUserMappingsFromProfile()
+  if (source.value?.lastValidatedAt) {
+    await hydrateUserMappingsFromSuggestions(false)
+    await autoLoadPathPrefixes()
+  }
+  if (run.value?.state === 'running') {
+    await refreshRunProgress()
+  }
+}
+
+function hydrateSourceDraft() {
+  const currentSource = source.value
+  if (!currentSource) return
+  sourceDraft.type = currentSource.type || sourceDraft.type
+  sourceDraft.name = currentSource.name || sourceDraft.name
+  const cfg = asRecord(currentSource.connectionConfig)
+  sourceDraft.host = asString(cfg.host) ?? sourceDraft.host
+  sourceDraft.port = asNumber(cfg.port) ?? sourceDraft.port
+  sourceDraft.user = asString(cfg.user) ?? sourceDraft.user
+  sourceDraft.database = asString(cfg.database) ?? sourceDraft.database
+  sourceDraft.ssl = asBoolean(cfg.ssl) ?? sourceDraft.ssl
+  sourceDraft.mediaRootPath = asString(cfg.mediaRootPath) ?? ''
+}
+
+function hydratePathMappings() {
+  const existing = profile.value?.pathMappings ?? []
+  if (existing.length === 0) {
+    pathMappings.value = [{ sourcePrefix: '', targetPrefix: '' }]
+    return
+  }
+  pathMappings.value = existing.map((row) => ({ sourcePrefix: row.sourcePrefix, targetPrefix: row.targetPrefix }))
+}
+
+function hydrateUserMappingsFromProfile() {
+  const existing = profile.value?.userMappings ?? []
+  userMappings.value = existing.map((row) => ({
+    sourceUserId: row.sourceUserId,
+    username: row.sourceUserId,
+    targetUserId: row.targetUserId,
+  }))
+}
+
+async function hydrateUserMappingsFromSuggestions(showSuccessToast: boolean) {
+  const currentSource = source.value
+  if (!currentSource) return
+
+  busy.loadingSuggestions = true
+  try {
+    const response = await suggestUserMappings(currentSource.id)
+    suggestionsLoadedAt.value = response.generatedAt
+    const savedMappings = new Map((profile.value?.userMappings ?? []).map((row) => [row.sourceUserId, row.targetUserId]))
+
+    userMappings.value = response.suggestions.map((row) => ({
+      sourceUserId: row.sourceUserId,
+      username: row.username,
+      targetUserId: savedMappings.get(row.sourceUserId) ?? row.suggestedTargetUserId,
+    }))
+
+    if (showSuccessToast) {
+      if (userMappings.value.length === 0) {
+        toast.warning('No source users were returned')
+      } else {
+        toast.success('User mapping suggestions loaded')
+      }
+    }
+  } catch (error) {
+    if (showSuccessToast) {
+      toast.error(getErrorMessage(error, 'Failed to load user mapping suggestions'))
+    }
+  } finally {
+    busy.loadingSuggestions = false
+  }
+}
+
+function buildSourceConnectionConfig() {
+  return {
+    host: sourceDraft.host.trim(),
+    port: sourceDraft.port,
+    user: sourceDraft.user.trim(),
+    password: sourceDraft.password,
+    database: sourceDraft.database.trim(),
+    ssl: sourceDraft.ssl,
+    mediaRootPath: sourceDraft.mediaRootPath.trim(),
+  }
+}
+
+function hasValidSourceDraft() {
+  return !!sourceDraft.name.trim() && !!sourceDraft.host.trim() && !!sourceDraft.user.trim() && !!sourceDraft.database.trim()
+}
+
+async function onTestSource() {
+  if (!hasValidSourceDraft()) {
+    toast.error('Host, user, database, and source name are required')
+    return
+  }
+
+  busy.testingSource = true
+  try {
+    const result = await testSource({ type: sourceDraft.type, connectionConfig: buildSourceConnectionConfig() })
+    const missing = Array.isArray(result.missingTables) ? result.missingTables.length : 0
+    if (result.ok === true) {
+      toast.success('Connection test passed')
+    } else {
+      toast.warning(`Connection ok, but ${missing} required table(s) are missing`)
+    }
+  } catch (error) {
+    toast.error(friendlyConnectionError(error))
+  } finally {
+    busy.testingSource = false
+  }
+}
+
+async function onSaveAndValidate() {
+  if (hasActiveRun.value) {
+    toast.error('Cannot modify source while a run is active')
+    return
+  }
+  if (!hasValidSourceDraft()) {
+    toast.error('Host, user, database, and source name are required')
+    return
+  }
+
+  busy.savingSource = true
+  try {
+    await createSource({
+      type: sourceDraft.type,
+      name: sourceDraft.name.trim(),
+      connectionConfig: buildSourceConnectionConfig(),
+    })
+    await refreshWorkflowState()
+
+    const currentSource = source.value
+    if (currentSource) {
+      const result = await validateSourceById(currentSource.id)
+      const warnings = Array.isArray(result.warnings) ? (result.warnings as unknown[]).filter((w): w is string => typeof w === 'string') : []
+      await refreshWorkflowState()
+      await autoLoadPathPrefixes()
+      toast.success(warnings.length > 0 ? `Source saved and validated with ${warnings.length} warning(s)` : 'Source saved and validated')
+    }
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to save or validate source'))
+  } finally {
+    busy.savingSource = false
+  }
+}
+
+async function autoLoadPathPrefixes() {
+  const currentSource = source.value
+  if (!currentSource) return
+  try {
+    const result = await listSourcePathPrefixes(currentSource.id)
+    sourcePathPrefixes.value = result.prefixes
+  } catch {
+    // non-fatal - user can still select target folders without source prefixes
+  }
+}
+
+async function onReloadSuggestions() {
+  await hydrateUserMappingsFromSuggestions(true)
+}
+
+function addPathMapping() {
+  pathMappings.value.push({ sourcePrefix: '', targetPrefix: '' })
+}
+
+function removePathMapping(index: number) {
+  pathMappings.value = pathMappings.value.filter((_row, rowIndex) => rowIndex !== index)
+  if (pathMappings.value.length === 0) {
+    pathMappings.value = [{ sourcePrefix: '', targetPrefix: '' }]
+  }
+}
+
+function cleanedPathMappings() {
+  return pathMappings.value
+    .map((row) => ({
+      sourcePrefix: row.sourcePrefix.trim(),
+      targetPrefix: row.targetPrefix.trim(),
+    }))
+    .filter((row) => row.sourcePrefix.length > 0 && row.targetPrefix.length > 0)
+}
+
+function cleanedUserMappings() {
+  return userMappings.value
+    .map((row) => ({ sourceUserId: row.sourceUserId, targetUserId: row.targetUserId }))
+    .filter((row): row is { sourceUserId: string; targetUserId: number } => !!row.targetUserId)
+}
+
+async function onSaveMappings() {
+  if (hasActiveRun.value) {
+    toast.error('Cannot save mappings while a run is active')
+    return
+  }
+  const currentSource = source.value
+  if (!currentSource) {
+    toast.error('Save source first')
+    return
+  }
+
+  const mappings = cleanedUserMappings()
+  if (mappings.length === 0) {
+    toast.error('Map at least one source user to a target user')
+    return
+  }
+  if (mappings.length !== userMappings.value.length) {
+    toast.error('Map every source user before saving')
+    return
+  }
+
+  busy.savingProfile = true
+  try {
+    const cleanedPaths = cleanedPathMappings()
+    if (cleanedPaths.length > 0) {
+      try {
+        pathValidation.value = await validatePathMappings(currentSource.id, { pathMappings: cleanedPaths, sampleLimit: 10 })
+      } catch {
+        // non-blocking - path validation failure does not prevent saving
+      }
+    }
+
+    await createProfile({
+      sourceId: currentSource.id,
+      name: 'Booklore Migration',
+      userMappings: mappings,
+      pathMappings: cleanedPaths,
+      scope: {
+        preflight: {
+          pathValidatedAt: pathValidation.value?.validatedAt ?? getPersistedPathValidatedAt(profile.value),
+          suggestionsLoadedAt: suggestionsLoadedAt.value,
+        },
+      },
+    })
+    await refreshWorkflowState()
+    toast.success('Mappings saved')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to save mappings'))
+  } finally {
+    busy.savingProfile = false
+  }
+}
+
+async function onRunDryRun() {
+  if (hasActiveRun.value) {
+    toast.error('Cannot run dry-run while a run is active')
+    return
+  }
+  const currentProfile = profile.value
+  if (!currentProfile) {
+    toast.error('Save mappings first')
+    return
+  }
+
+  busy.dryRun = true
+  try {
+    const artifact = await createDryRunPlan({ profileId: currentProfile.id })
+    await refreshWorkflowState()
+    const matched = artifact.summary?.matchedBooks ?? 0
+    const unresolved = artifact.summary?.unresolvedBooks ?? 0
+    toast.success(`Dry-run completed: ${matched} matched, ${unresolved} unresolved`)
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Dry-run failed'))
+  } finally {
+    busy.dryRun = false
+  }
+}
+
+async function onStartMigration() {
+  if (!preflight.value.ready) {
+    toast.error(preflight.value.issues[0] ?? 'Migration preflight not ready')
+    return
+  }
+  const currentPlan = plan.value
+  if (!currentPlan) {
+    toast.error('Run dry-run first')
+    return
+  }
+
+  const confirmed = window.confirm('Start migration now?')
+  if (!confirmed) return
+
+  busy.startingRun = true
+  try {
+    await startLiveRun({ planArtifactId: currentPlan.id })
+    await refreshWorkflowState()
+    await refreshRunProgress()
+    toast.success('Migration run started')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to start migration'))
+  } finally {
+    busy.startingRun = false
+  }
+}
+
+async function refreshRunProgress() {
+  const currentRun = run.value
+  if (!currentRun) return
+
+  busy.loadingProgress = true
+  try {
+    runProgress.value = await getRunProgress(currentRun.id)
+    if (runProgress.value.run.state !== 'running') {
+      stopRunPolling()
+      await refreshWorkflowState()
+    }
+  } catch (error) {
+    stopRunPolling()
+    toast.error(getErrorMessage(error, 'Failed to load run progress'))
+  } finally {
+    busy.loadingProgress = false
+  }
+}
+
+async function onRefreshReport() {
+  const currentRun = run.value
+  if (!currentRun) {
+    toast.error('Start migration first')
+    return
+  }
+
+  busy.loadingReport = true
+  try {
+    runReport.value = await getRunReport(currentRun.id)
+    toast.success('Run report refreshed')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to load run report'))
+  } finally {
+    busy.loadingReport = false
+  }
+}
+
+async function onExportJson() {
+  await exportReport('json')
+}
+
+async function onExportCsv() {
+  await exportReport('csv')
+}
+
+function onTogglePassword() {
+  showPassword.value = !showPassword.value
+}
+
+async function exportReport(format: 'json' | 'csv') {
+  const currentRun = run.value
+  if (!currentRun) {
+    toast.error('Start migration first')
+    return
+  }
+
+  busy.exporting = true
+  try {
+    const exported = await exportRunReport(currentRun.id, format)
+    downloadTextFile(exported.fileName, exported.content, exported.contentType)
+    toast.success(`Report exported as ${format.toUpperCase()}`)
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to export migration report'))
+  } finally {
+    busy.exporting = false
+  }
+}
+
+function startRunPolling() {
+  stopRunPolling()
+  runPollTimer = setInterval(() => {
+    void refreshRunProgress()
+  }, 3000)
+}
+
+function stopRunPolling() {
+  if (runPollTimer == null) return
+  clearInterval(runPollTimer)
+  runPollTimer = null
+}
+
+function downloadTextFile(fileName: string, content: string, contentType: string) {
+  const blob = new Blob([content], { type: contentType })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = fileName
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+  URL.revokeObjectURL(url)
+}
+
+function getErrorMessage(error: unknown, fallback: string) {
+  return error instanceof Error ? error.message : fallback
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`
+  const mins = Math.floor(ms / 60000)
+  const secs = Math.floor((ms % 60000) / 1000)
+  return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`
+}
+
+function friendlyUnresolvedReason(reason: string | null): string {
+  if (reason === 'no_title_author_match') return 'No matching book found by title or author'
+  if (reason === 'no_file_path_match') return 'File path did not match any book in this library'
+  if (reason === 'no_file_hash_match') return 'File hash did not match any book in this library'
+  if (reason === 'no_isbn_match') return 'ISBN did not match any book in this library'
+  if (reason === 'insufficient_source_data') return 'Not enough metadata to attempt matching'
+  return reason ?? 'Could not determine reason'
+}
+
+function extractPlanUnresolvedBooks(planPayload: unknown): ReportUnresolvedBook[] {
+  const rows = asRecord(planPayload).unresolvedBooks
+  if (!Array.isArray(rows)) return []
+
+  return rows
+    .map((row) => {
+      const record = asRecord(row)
+      const sourceBookId = asString(record.sourceBookId)
+      if (!sourceBookId) return null
+      return {
+        sourceBookId,
+        title: asString(record.title),
+        reason: asString(record.reason),
+      }
+    })
+    .filter((row): row is ReportUnresolvedBook => row != null)
+}
+
+function friendlyConnectionError(error: unknown): string {
+  const msg = error instanceof Error ? error.message : String(error)
+  if (/ECONNREFUSED|ENOTFOUND|connect ETIMEDOUT/i.test(msg)) return 'Could not reach the database server. Check the host and port.'
+  if (/Access denied|authentication failed/i.test(msg)) return 'Authentication failed. Check the username and password.'
+  if (/Unknown database/i.test(msg)) return 'Database not found. Check the database name.'
+  if (/ETIMEDOUT|timeout/i.test(msg)) return 'Connection timed out. Check host and firewall settings.'
+  return msg || 'Connection test failed'
+}
+
+function runStateClass(state: string) {
+  if (state === 'completed') return 'bg-emerald-500/10 text-emerald-700 border-emerald-500/20'
+  if (state === 'running') return 'bg-sky-500/10 text-sky-700 border-sky-500/20'
+  if (state === 'failed') return 'bg-red-500/10 text-red-700 border-red-500/20'
+  return 'bg-muted text-muted-foreground border-border'
+}
+
+function getPersistedPathValidatedAt(currentProfile: MigrationProfile | null): string | null {
+  if (!currentProfile) return null
+  const scope = asRecord(currentProfile.scope)
+  const preflightScope = asRecord(scope.preflight)
+  return asString(preflightScope.pathValidatedAt)
+}
+
+function hasValidatedPathMappings(currentProfile: MigrationProfile | null): boolean {
+  if (!currentProfile) return false
+  if (currentProfile.pathMappings.length === 0) return true
+  return getPersistedPathValidatedAt(currentProfile) != null
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  return value as Record<string, unknown>
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    return trimmed.length > 0 ? trimmed : null
+  }
+  return null
+}
+
+function asNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+function asBoolean(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value
+  return null
+}
+
+function formatSourceCountLabel(key: string) {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .replace(/^./, (char) => char.toUpperCase())
+}
+</script>
+
+<template>
+  <SettingsPageHeader
+    title="Migration"
+    subtitle="One-time Booklore import: connect source, map users, dry-run, start migration, and export a report."
+  />
+
+  <div v-if="loading" class="flex items-center justify-center py-12">
+    <Loader2 class="size-5 animate-spin text-muted-foreground" />
+  </div>
+
+  <div v-else class="space-y-8">
+    <section class="rounded-lg border border-border bg-card p-4 space-y-3">
+      <div class="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <p class="text-sm font-medium">{{ source ? `Migration setup: ${source.name}` : 'Migration setup not saved yet' }}</p>
+          <p class="text-xs text-muted-foreground">
+            {{ hasActiveRun ? 'A migration run is in progress' : 'Configure the source, mappings, and dry-run before starting the import.' }}
+          </p>
+        </div>
+      </div>
+    </section>
+
+    <section class="space-y-4">
+      <div class="flex items-center gap-2">
+        <span class="settings-group-label mb-0">Step 1 · Source Connection</span>
+        <span v-if="stepStatus.source === 'done'" class="text-xs text-emerald-600">Validated</span>
+        <span v-else-if="stepStatus.source === 'saved'" class="text-xs text-amber-600">Saved - not validated</span>
+      </div>
+      <div class="rounded-lg border border-border bg-card p-4 space-y-4">
+        <div class="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
+          <label class="block">
+            <span class="settings-hint">Source Type</span>
+            <select v-model="sourceDraft.type" class="select-field mt-1 w-full" :disabled="hasActiveRun">
+              <option v-for="type in supportedTypes" :key="type" :value="type">{{ type }}</option>
+            </select>
+          </label>
+          <label class="block">
+            <span class="settings-hint">Source Name</span>
+            <input v-model="sourceDraft.name" class="input-field mt-1 w-full" placeholder="Booklore Import" :disabled="hasActiveRun" />
+          </label>
+          <label class="block">
+            <span class="settings-hint">Host</span>
+            <input v-model="sourceDraft.host" class="input-field mt-1 w-full" placeholder="127.0.0.1" :disabled="hasActiveRun" />
+          </label>
+          <label class="block">
+            <span class="settings-hint">Port</span>
+            <input v-model.number="sourceDraft.port" class="input-field mt-1 w-full" type="number" min="1" max="65535" :disabled="hasActiveRun" />
+          </label>
+          <label class="block">
+            <span class="settings-hint">User</span>
+            <input v-model="sourceDraft.user" class="input-field mt-1 w-full" placeholder="booklore" :disabled="hasActiveRun" />
+          </label>
+          <label class="block">
+            <span class="settings-hint">Password</span>
+            <div class="relative mt-1">
+              <input
+                v-model="sourceDraft.password"
+                class="input-field w-full pr-9"
+                :class="!sourceDraft.password && !source ? 'placeholder:text-amber-600' : ''"
+                :type="showPassword ? 'text' : 'password'"
+                :placeholder="sourceDraft.password ? '••••••••' : source ? 'Saved - enter to change' : 'No password set'"
+                :disabled="hasActiveRun"
+              />
+              <button
+                type="button"
+                class="absolute inset-y-0 right-0 flex items-center px-2.5 text-muted-foreground hover:text-foreground"
+                tabindex="-1"
+                @click="onTogglePassword"
+              >
+                <EyeOff v-if="showPassword" class="size-4" />
+                <Eye v-else class="size-4" />
+              </button>
+            </div>
+          </label>
+          <label class="block">
+            <span class="settings-hint">Database</span>
+            <input v-model="sourceDraft.database" class="input-field mt-1 w-full" placeholder="booklore" :disabled="hasActiveRun" />
+          </label>
+          <label class="block md:col-span-2 xl:col-span-2">
+            <span class="settings-hint">Media Root Path</span>
+            <input v-model="sourceDraft.mediaRootPath" class="input-field mt-1 w-full" placeholder="/data/booklore/media" :disabled="hasActiveRun" />
+            <p class="mt-1 text-xs" :class="sourceDraft.mediaRootPath.trim() ? 'text-muted-foreground' : 'text-amber-600'">
+              {{
+                sourceDraft.mediaRootPath.trim()
+                  ? 'Book cover images will be imported from this directory.'
+                  : 'Required for cover import. Without this, book covers will not be migrated.'
+              }}
+            </p>
+          </label>
+          <div class="block">
+            <span class="settings-hint opacity-0 select-none">_</span>
+            <label class="mt-1 flex h-9 cursor-pointer items-center gap-2">
+              <input v-model="sourceDraft.ssl" type="checkbox" class="size-4 rounded border-border" :disabled="hasActiveRun" />
+              <span class="settings-hint">Use TLS/SSL</span>
+            </label>
+          </div>
+        </div>
+
+        <div class="flex flex-wrap gap-2">
+          <button class="settings-btn-outline" :disabled="busy.testingSource || hasActiveRun" @click="onTestSource">
+            <Loader2 v-if="busy.testingSource" class="size-3.5 animate-spin" />
+            Test Connection
+          </button>
+          <button class="settings-btn-primary" :disabled="busy.savingSource || hasActiveRun" @click="onSaveAndValidate">
+            <Loader2 v-if="busy.savingSource" class="size-3.5 animate-spin" />
+            Save &amp; Validate
+          </button>
+        </div>
+
+        <div
+          v-if="sourceValidationWarnings.length > 0"
+          class="rounded border border-amber-500/20 bg-amber-500/10 p-3 text-xs text-amber-700 space-y-1"
+        >
+          <p class="font-medium">Source validated with warnings</p>
+          <p v-for="warn in sourceValidationWarnings" :key="warn">{{ warn }}</p>
+        </div>
+
+        <div v-if="sourceCapabilities" class="rounded border border-border bg-muted/40 p-3 text-xs space-y-2">
+          <p class="font-medium text-foreground">Last validation snapshot</p>
+          <p class="text-muted-foreground">Source version: {{ sourceCapabilities.sourceVersion ?? 'Unknown' }}</p>
+          <p v-if="sourceCapabilities.missingTables.length > 0" class="text-amber-600">
+            Missing required tables: {{ sourceCapabilities.missingTables.join(', ') }}
+          </p>
+          <div v-if="sourceRowCounts.length > 0" class="grid gap-1 text-muted-foreground sm:grid-cols-2 xl:grid-cols-3">
+            <p v-for="[key, count] in sourceRowCounts" :key="key">{{ formatSourceCountLabel(key) }}: {{ count }}</p>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <section class="space-y-4">
+      <div class="flex items-center gap-2">
+        <span class="settings-group-label mb-0">Step 2 · User and Path Mapping</span>
+        <span v-if="stepStatus.mappings === 'done'" class="text-xs text-emerald-600">Saved</span>
+      </div>
+      <div class="rounded-lg border border-border bg-card p-4 space-y-4">
+        <div class="flex items-center gap-2">
+          <p class="text-xs text-muted-foreground">User suggestions load automatically after source validation.</p>
+          <button
+            v-if="source"
+            class="text-xs text-primary underline-offset-2 hover:underline disabled:opacity-50"
+            :disabled="busy.loadingSuggestions || hasActiveRun"
+            @click="onReloadSuggestions"
+          >
+            <Loader2 v-if="busy.loadingSuggestions" class="size-3 animate-spin inline" />
+            Refresh
+          </button>
+        </div>
+
+        <div class="overflow-x-auto rounded border border-border">
+          <table class="w-full text-sm">
+            <thead class="bg-muted/40 text-left">
+              <tr>
+                <th class="px-3 py-2 font-medium">Source User</th>
+                <th class="px-3 py-2 font-medium">Target User</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr v-for="row in userMappings" :key="row.sourceUserId" class="border-t border-border">
+                <td class="px-3 py-2">
+                  <p class="font-medium">{{ row.username }}</p>
+                  <p class="text-xs text-muted-foreground">{{ row.sourceUserId }}</p>
+                </td>
+                <td class="px-3 py-2">
+                  <select v-model.number="row.targetUserId" class="select-field w-full min-w-48" :disabled="hasActiveRun">
+                    <option :value="null">Select user</option>
+                    <option v-for="user in targetUsers" :key="user.id" :value="user.id">{{ user.username }} · {{ user.name }}</option>
+                  </select>
+                </td>
+              </tr>
+              <tr v-if="userMappings.length === 0" class="border-t border-border">
+                <td colspan="2" class="px-3 py-4 text-sm text-muted-foreground">No source users loaded yet.</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+
+        <div class="space-y-2">
+          <div class="flex items-center justify-between">
+            <p class="settings-hint">Path Prefix Mappings</p>
+            <button class="settings-btn-outline" :disabled="hasActiveRun" @click="addPathMapping">Add Mapping</button>
+          </div>
+          <p class="text-xs text-muted-foreground">
+            Path mappings translate source file paths to target paths so books can be matched by file location. For example, if your Booklore library
+            stored files under <code class="font-mono">/books/Large</code> and the same files now live under
+            <code class="font-mono">/srv/projectx/books/Large</code>, add that mapping here. Books are also matched by ISBN, file hash, and
+            title/author regardless of path mappings - path mapping is only one of four strategies and does not limit which source books are included
+            in the migration.
+          </p>
+
+          <div v-for="(row, index) in pathMappings" :key="index" class="grid gap-2 md:grid-cols-[1fr_1fr_auto] items-center">
+            <select v-model="row.sourcePrefix" class="select-field" :disabled="hasActiveRun">
+              <option value="">
+                {{ sourcePathPrefixes.length === 0 ? 'No prefixes found - validate source first' : 'Select source prefix...' }}
+              </option>
+              <option v-for="prefix in sourcePathPrefixes" :key="prefix" :value="prefix">{{ prefix }}</option>
+            </select>
+
+            <select v-model="row.targetPrefix" class="select-field" :disabled="hasActiveRun">
+              <option value="">Select target folder...</option>
+              <option v-for="folder in targetLibraryFolders" :key="folder.path" :value="folder.path">
+                {{ folder.libraryName }} - {{ folder.path }}
+              </option>
+            </select>
+
+            <button class="settings-btn-outline" :disabled="hasActiveRun" @click="removePathMapping(index)">Remove</button>
+          </div>
+        </div>
+
+        <div v-if="pathValidation" class="rounded border border-border bg-muted/40 p-3 text-xs space-y-1">
+          <p class="font-medium text-foreground">Path validation</p>
+          <p class="text-muted-foreground">
+            {{ pathValidation.summary.mappedByPrefix }} of {{ pathValidation.summary.booksWithFilePath }} source books have a mapped path
+          </p>
+          <p v-if="pathValidation.summary.unmatchedTargetPaths > 0" class="text-amber-600">
+            {{ pathValidation.summary.unmatchedTargetPaths }} mapped paths not found on disk - those books will fall back to ISBN / title matching
+          </p>
+          <p v-else-if="pathValidation.summary.matchedTargetPaths > 0" class="text-emerald-600">
+            All {{ pathValidation.summary.matchedTargetPaths }} mapped paths found on disk
+          </p>
+        </div>
+
+        <button class="settings-btn-primary" :disabled="busy.savingProfile || source == null || hasActiveRun" @click="onSaveMappings">
+          <Loader2 v-if="busy.savingProfile" class="size-3.5 animate-spin" />
+          Save Mappings
+        </button>
+      </div>
+    </section>
+
+    <section class="space-y-4">
+      <div class="flex items-center gap-2">
+        <span class="settings-group-label mb-0">Step 3 · Dry-Run Summary</span>
+        <span v-if="stepStatus.dryRun === 'done'" class="text-xs text-emerald-600">Up to date</span>
+      </div>
+      <div class="rounded-lg border border-border bg-card p-4 space-y-4">
+        <button class="settings-btn-primary" :disabled="busy.dryRun || profile == null || hasActiveRun" @click="onRunDryRun">
+          <Loader2 v-if="busy.dryRun" class="size-3.5 animate-spin" />
+          Run Dry-Run
+        </button>
+
+        <div v-if="plan" class="rounded border border-border bg-muted/30 p-3 space-y-2 text-sm">
+          <p>
+            Matched: <span class="font-medium">{{ plan.summary?.matchedBooks ?? 0 }}</span> · Unresolved:
+            <span class="font-medium">{{ plan.summary?.unresolvedBooks ?? 0 }}</span> · Duplicate matches:
+            <span class="font-medium" :class="(plan.summary?.duplicateBookMatches ?? 0) > 0 ? 'text-red-600' : ''">
+              {{ plan.summary?.duplicateBookMatches ?? 0 }}
+            </span>
+          </p>
+          <div v-if="unresolvedSummary.length > 0" class="space-y-1 text-xs text-muted-foreground">
+            <p class="font-medium text-foreground">Unresolved summary</p>
+            <p v-for="[reason, count] in unresolvedSummary" :key="reason">{{ reason }}: {{ count }}</p>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <section class="space-y-4">
+      <div class="flex items-center gap-2">
+        <span class="settings-group-label mb-0">Step 4 · Start Migration</span>
+        <span v-if="stepStatus.migration === 'done'" class="text-xs text-emerald-600">Completed</span>
+        <span v-else-if="stepStatus.migration === 'running'" class="text-xs text-sky-600">Running</span>
+        <span v-else-if="stepStatus.migration === 'failed'" class="text-xs text-red-600">Failed</span>
+      </div>
+      <div class="rounded-lg border border-border bg-card p-4 space-y-4">
+        <div class="rounded border border-border bg-muted/20 p-3 text-xs space-y-1.5">
+          <p class="font-medium text-foreground">Preflight checks</p>
+          <p v-if="preflight.ready" class="text-emerald-600">All checks passed - ready to migrate</p>
+          <template v-else>
+            <div v-if="preflight.sourceValidated" class="flex items-center gap-1.5 text-emerald-600">
+              <span class="size-1.5 rounded-full bg-emerald-500 flex-none" />
+              Source validated
+            </div>
+            <div v-else class="flex items-center gap-1.5 text-muted-foreground">
+              <span class="size-1.5 rounded-full bg-muted-foreground/40 flex-none" />
+              {{ !source ? 'Save and validate source connection' : 'Validate source connection' }}
+            </div>
+            <div v-if="profile" class="flex items-center gap-1.5 text-emerald-600">
+              <span class="size-1.5 rounded-full bg-emerald-500 flex-none" />
+              Mappings saved
+            </div>
+            <div v-else class="flex items-center gap-1.5 text-muted-foreground">
+              <span class="size-1.5 rounded-full bg-muted-foreground/40 flex-none" />
+              Save user and path mappings
+            </div>
+            <div v-if="profile && preflight.pathMappingsValidated" class="flex items-center gap-1.5 text-emerald-600">
+              <span class="size-1.5 rounded-full bg-emerald-500 flex-none" />
+              Path mappings validated
+            </div>
+            <div v-else-if="profile" class="flex items-center gap-1.5 text-muted-foreground">
+              <span class="size-1.5 rounded-full bg-muted-foreground/40 flex-none" />
+              Save path mappings to validate them
+            </div>
+            <div v-if="preflight.dryRunFresh" class="flex items-center gap-1.5 text-emerald-600">
+              <span class="size-1.5 rounded-full bg-emerald-500 flex-none" />
+              Dry-run is up to date
+            </div>
+            <div v-else class="flex items-center gap-1.5 text-muted-foreground">
+              <span class="size-1.5 rounded-full bg-muted-foreground/40 flex-none" />
+              Run a fresh dry-run
+            </div>
+          </template>
+        </div>
+
+        <div class="flex flex-wrap gap-2">
+          <button class="settings-btn-primary" :disabled="busy.startingRun || !preflight.ready" @click="onStartMigration">
+            <Loader2 v-if="busy.startingRun" class="size-3.5 animate-spin" />
+            Start Migration
+          </button>
+          <button class="settings-btn-outline" :disabled="busy.loadingProgress || run == null" @click="refreshRunProgress">
+            <Loader2 v-if="busy.loadingProgress" class="size-3.5 animate-spin" />
+            Refresh Status
+          </button>
+        </div>
+
+        <div v-if="run" class="rounded border border-border bg-muted/30 px-4 py-3.5 flex items-center gap-3 text-xs">
+          <span class="inline-flex rounded-full border px-2 py-0.5" :class="runStateClass(run.state)">{{ run.state }}</span>
+          <span class="text-muted-foreground">
+            {{
+              run.state === 'running'
+                ? `Stage: ${run.currentStage ?? 'initializing'}`
+                : run.endedAt
+                  ? `Ended ${new Date(run.endedAt).toLocaleString()}`
+                  : ''
+            }}
+          </span>
+          <span v-if="run.state !== 'running'" class="text-muted-foreground ml-auto">See Step 5 for the full report</span>
+        </div>
+      </div>
+    </section>
+
+    <section class="space-y-4">
+      <span class="settings-group-label">Step 5 · Migration Report</span>
+
+      <div v-if="!run" class="rounded-lg border border-border bg-card p-4">
+        <p class="text-sm text-muted-foreground">No migration run yet. Complete the steps above to start.</p>
+      </div>
+
+      <div v-else class="rounded-lg border border-border bg-card p-4 space-y-6">
+        <!-- Run header -->
+        <div class="flex flex-wrap items-start justify-between gap-3">
+          <div class="space-y-0.5">
+            <p class="flex items-center gap-2 text-sm font-medium">
+              Run #{{ run.id }}
+              <span class="inline-flex rounded-full border px-2 py-0.5 text-xs" :class="runStateClass(run.state)">{{ run.state }}</span>
+            </p>
+            <p class="text-xs text-muted-foreground">
+              {{ run.startedAt ? new Date(run.startedAt).toLocaleString() : 'Not started' }}
+              <template v-if="reportData.durationMs != null"> &middot; {{ formatDuration(reportData.durationMs) }}</template>
+            </p>
+          </div>
+          <div class="flex flex-wrap gap-2">
+            <button class="settings-btn-outline" :disabled="busy.loadingReport" @click="onRefreshReport">
+              <Loader2 v-if="busy.loadingReport" class="size-3.5 animate-spin" />
+              {{ runReport ? 'Reload Report' : 'Load Full Report' }}
+            </button>
+            <button class="settings-btn-outline" :disabled="busy.exporting" @click="onExportJson">Export JSON</button>
+            <button class="settings-btn-outline" :disabled="busy.exporting" @click="onExportCsv">Export CSV</button>
+          </div>
+        </div>
+
+        <!-- Error (if failed) -->
+        <div v-if="run.errorMessage" class="rounded border border-red-500/20 bg-red-500/10 p-3 text-xs text-red-700 space-y-0.5">
+          <p class="font-medium">Migration failed</p>
+          <p>{{ run.errorMessage }}</p>
+        </div>
+
+        <!-- Stats grid — available from runProgress or full report -->
+        <template v-if="runReport || runProgress">
+          <div class="grid gap-3 sm:grid-cols-2">
+            <!-- Books card -->
+            <div class="rounded border border-border p-3 space-y-2">
+              <p class="text-sm font-semibold">Books</p>
+              <div class="space-y-1.5 text-xs">
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Metadata overlays applied</span>
+                  <span class="font-medium">{{ reportData.bookMetadata?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Author mappings replaced</span>
+                  <span class="font-medium">{{ reportData.bookAuthors?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Narrator mappings replaced</span>
+                  <span class="font-medium">{{ reportData.bookNarrators?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Genre mappings replaced</span>
+                  <span class="font-medium">{{ reportData.bookGenres?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Tag mappings replaced</span>
+                  <span class="font-medium">{{ reportData.bookTags?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between" :class="reportData.coversSkippedAll ? 'text-amber-600' : ''">
+                  <span>Covers imported</span>
+                  <span class="font-medium">{{ reportData.bookCovers?.imported ?? 0 }}</span>
+                </div>
+                <p v-if="reportData.coversSkippedAll" class="text-amber-600 leading-tight">
+                  Cover import was skipped - media root path is not configured on the source
+                </p>
+                <div v-if="reportData.unresolvedBooks.length > 0" class="flex justify-between text-amber-600">
+                  <span>Could not match</span>
+                  <span class="font-medium">{{ reportData.unresolvedBooks.length }}</span>
+                </div>
+              </div>
+            </div>
+
+            <!-- User data card -->
+            <div class="rounded border border-border p-3 space-y-2">
+              <p class="text-sm font-semibold">User Data</p>
+              <div class="space-y-1.5 text-xs">
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Reading statuses</span>
+                  <span class="font-medium">{{ reportData.userBookStatus?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Reading progress entries</span>
+                  <span class="font-medium">{{ reportData.readingProgress?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Audiobook progress entries</span>
+                  <span class="font-medium">{{ reportData.audiobookProgress?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Bookmarks</span>
+                  <span class="font-medium">{{ reportData.bookmarks?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Annotations</span>
+                  <span class="font-medium">{{ reportData.annotations?.imported ?? 0 }}</span>
+                </div>
+                <div class="flex justify-between">
+                  <span class="text-muted-foreground">Collection entries</span>
+                  <span class="font-medium">{{ reportData.collections?.imported ?? 0 }}</span>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <p v-if="!runReport && (run.state === 'completed' || run.state === 'failed')" class="text-xs text-muted-foreground">
+            Click "Load Full Report" to include the dry-run match summary in the exported report.
+          </p>
+        </template>
+
+        <!-- Full report: aggregate issues from current plan/report only. -->
+        <template v-if="runReport">
+          <div
+            v-if="run.state === 'completed' && reportData.unresolvedBooks.length === 0 && reportData.coverFailureCount === 0"
+            class="rounded border border-emerald-500/20 bg-emerald-500/5 p-3 text-xs text-emerald-700"
+          >
+            Migration completed with no unresolved books or failures.
+          </div>
+
+          <div v-if="reportData.unresolvedBooks.length > 0" class="space-y-2">
+            <div>
+              <p class="text-sm font-semibold text-amber-600">Unresolved books ({{ reportData.unresolvedBooks.length }})</p>
+              <p class="text-xs text-muted-foreground mt-0.5">
+                These books exist in the source but could not be matched to any book in your library.
+              </p>
+            </div>
+            <div class="space-y-1.5 max-h-64 overflow-y-auto">
+              <div
+                v-for="book in reportData.unresolvedBooks"
+                :key="book.sourceBookId"
+                class="rounded border border-amber-500/20 bg-amber-500/5 px-3 py-2 text-xs"
+              >
+                <p class="font-medium text-foreground">{{ book.title || `Source book ${book.sourceBookId}` }}</p>
+                <p class="text-muted-foreground mt-0.5">{{ friendlyUnresolvedReason(book.reason) }}</p>
+              </div>
+            </div>
+          </div>
+
+          <div v-if="reportData.coverFailureCount > 0" class="rounded border border-red-500/20 bg-red-500/5 px-3 py-2 text-xs text-red-700">
+            {{ reportData.coverFailureCount }} cover import(s) failed. Detailed failure rows are not stored.
+          </div>
+        </template>
+      </div>
+    </section>
+  </div>
+</template>
diff --git a/client/src/features/settings/SettingsHeader.vue b/client/src/features/settings/SettingsHeader.vue
index a1e01bc57..a65dffe52 100644
--- a/client/src/features/settings/SettingsHeader.vue
+++ b/client/src/features/settings/SettingsHeader.vue
@@ -52,6 +52,9 @@ const sections = computed<Section[]>(() => {
   if (su || perms.includes('manage_app_settings')) {
     result.push({ label: 'Maintenance', routeName: 'settings-admin-maintenance' })
   }
+  if (su || perms.includes('manage_app_settings')) {
+    result.push({ label: 'Migration', routeName: 'settings-admin-migration' })
+  }
 
   result.push({ label: 'Account', routeName: 'settings-account' })
 
diff --git a/client/src/router/index.ts b/client/src/router/index.ts
index 009d411f0..c83149dcb 100644
--- a/client/src/router/index.ts
+++ b/client/src/router/index.ts
@@ -152,6 +152,12 @@ export const routes: RouteRecordRaw[] = [
             component: () => import('@/features/settings/MaintenanceSettings.vue'),
             meta: { title: 'Maintenance' },
           },
+          {
+            path: 'admin/migration',
+            name: 'settings-admin-migration',
+            component: () => import('@/features/settings/MigrationSettings.vue'),
+            meta: { maxWidth: 'max-w-7xl', title: 'Migration' },
+          },
           {
             path: 'admin/audit-log',
             name: 'settings-admin-audit-log',
diff --git a/client/src/views/CollectionView.vue b/client/src/views/CollectionView.vue
index 46317545c..3082a8e92 100644
--- a/client/src/views/CollectionView.vue
+++ b/client/src/views/CollectionView.vue
@@ -116,6 +116,20 @@ async function handleRemoveFromCollection() {
   }
 }
 
+function handleCollectionDeleted(deletedId: number) {
+  editCollectionOpen.value = false
+  collectionNotFound.value = false
+
+  const nextCollection = collections.value.find((item) => item.id !== deletedId)
+  if (nextCollection) {
+    router.replace({ name: 'collection', params: { id: nextCollection.id } })
+  } else {
+    router.replace({ name: 'dashboard' })
+  }
+
+  toast.success('Collection deleted')
+}
+
 function handleEditSelected() {
   const ids = [...selectedIds.value]
   if (ids.length === 0) return
@@ -199,7 +213,13 @@ watch(
     @done="exitSelectionMode"
   />
 
-  <EditCollectionDialog v-if="collection" :open="editCollectionOpen" :collection="collection" @close="editCollectionOpen = false" />
+  <EditCollectionDialog
+    v-if="collection"
+    :open="editCollectionOpen"
+    :collection="collection"
+    @close="editCollectionOpen = false"
+    @deleted="handleCollectionDeleted"
+  />
   <SendBookDialog :open="sendBookOpen" :book-ids="[...selectedIds]" @update:open="sendBookOpen = $event" @sent="exitSelectionMode" />
   <DeleteBookDialog :open="deleteBookId !== null" :deleting="deletingBook" @confirm="confirmDelete" @cancel="cancelDelete" />
 
diff --git a/server/package.json b/server/package.json
index 11f100783..e25611c7b 100644
--- a/server/package.json
+++ b/server/package.json
@@ -40,16 +40,16 @@
     "@fastify/multipart": "^9.4.0",
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^9.0.0",
-    "@nestjs/common": "^11.1.17",
+    "@nestjs/common": "^11.1.18",
     "@nestjs/config": "^4.0.3",
-    "@nestjs/core": "^11.1.17",
+    "@nestjs/core": "^11.1.18",
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/passport": "^11.0.5",
-    "@nestjs/platform-fastify": "^11.1.17",
-    "@nestjs/platform-socket.io": "^11.1.17",
+    "@nestjs/platform-fastify": "^11.1.18",
+    "@nestjs/platform-socket.io": "^11.1.18",
     "@nestjs/schedule": "^6.1.1",
     "@nestjs/terminus": "^11.1.1",
-    "@nestjs/websockets": "^11.1.17",
+    "@nestjs/websockets": "^11.1.18",
     "@parcel/watcher": "^2.5.6",
     "@projectx/types": "workspace:*",
     "@types/archiver": "^7.0.0",
@@ -59,13 +59,14 @@
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
     "drizzle-orm": "^0.45.2",
-    "fast-xml-parser": "^5.5.9",
+    "fast-xml-parser": "^5.5.10",
     "fastest-levenshtein": "^1.0.16",
     "fastify": "^5.8.4",
     "jose": "^6.2.2",
     "mediainfo.js": "^0.3.7",
     "ms": "^2.1.3",
     "music-metadata": "^11.12.3",
+    "mysql2": "^3.20.0",
     "nestjs-pino": "^4.6.1",
     "node-unrar-js": "^2.0.2",
     "nodemailer": "^8.0.4",
@@ -86,12 +87,12 @@
     "@eslint/js": "^10.0.1",
     "@nestjs/cli": "^11.0.17",
     "@nestjs/schematics": "^11.0.10",
-    "@nestjs/testing": "^11.1.17",
+    "@nestjs/testing": "^11.1.18",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.21",
     "@types/bcrypt": "^6.0.0",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/nodemailer": "^6.4.23",
     "@types/passport-jwt": "^4.0.1",
     "@types/pg": "^8.18.0",
@@ -99,7 +100,7 @@
     "@types/unzipper": "^0.10.11",
     "@vitest/coverage-v8": "^4.1.2",
     "drizzle-kit": "^0.31.10",
-    "eslint": "^10.1.0",
+    "eslint": "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "globals": "^17.4.0",
@@ -107,7 +108,7 @@
     "prettier": "^3.8.1",
     "source-map-support": "^0.5.21",
     "supertest": "^7.2.2",
-    "ts-loader": "^9.5.4",
+    "ts-loader": "^9.5.7",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
     "tsx": "^4.21.0",
diff --git a/server/src/app.module.ts b/server/src/app.module.ts
index b3cbe36dd..979c0377d 100644
--- a/server/src/app.module.ts
+++ b/server/src/app.module.ts
@@ -50,6 +50,7 @@ import { UserStatisticsModule } from './modules/user-statistics/user-statistics.
 import { ReadingSessionModule } from './modules/reading-session/reading-session.module';
 import { UserBookStatusModule } from './modules/user-book-status/user-book-status.module';
 import { AuditModule } from './modules/audit/audit.module';
+import { MigrationModule } from './modules/migration/migration.module';
 
 @Module({
   imports: [
@@ -99,6 +100,7 @@ import { AuditModule } from './modules/audit/audit.module';
     ReadingSessionModule,
     UserBookStatusModule,
     AuditModule,
+    MigrationModule,
   ],
   providers: [
     { provide: APP_INTERCEPTOR, useClass: AuditInterceptor },
diff --git a/server/src/db/migrations/0000_baseline.sql b/server/src/db/migrations/0000_baseline.sql
index 1a77188c9..2c4a739fc 100644
--- a/server/src/db/migrations/0000_baseline.sql
+++ b/server/src/db/migrations/0000_baseline.sql
@@ -97,6 +97,75 @@ CREATE TABLE "comic_metadata" (
 	CONSTRAINT "comic_metadata_book_id_unique" UNIQUE("book_id")
 );
 --> statement-breakpoint
+CREATE TABLE "migration_plan_artifacts" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"source_id" integer NOT NULL,
+	"profile_id" integer NOT NULL,
+	"source_snapshot_hash" varchar(128) NOT NULL,
+	"profile_hash" varchar(128) NOT NULL,
+	"plan_hash" varchar(128) NOT NULL,
+	"plan" jsonb NOT NULL,
+	"summary" jsonb NOT NULL,
+	"created_by_user_id" integer,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "migration_profiles" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"source_id" integer NOT NULL,
+	"name" varchar(255) NOT NULL,
+	"version" integer DEFAULT 1 NOT NULL,
+	"user_mappings" jsonb NOT NULL,
+	"path_mappings" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"scope" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_by_user_id" integer,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "migration_run_metrics" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"run_id" integer NOT NULL,
+	"stage" varchar(64) NOT NULL,
+	"entity_type" varchar(64) NOT NULL,
+	"processed" integer DEFAULT 0 NOT NULL,
+	"imported" integer DEFAULT 0 NOT NULL,
+	"skipped" integer DEFAULT 0 NOT NULL,
+	"unresolved" integer DEFAULT 0 NOT NULL,
+	"failed" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "migration_runs" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"source_id" integer NOT NULL,
+	"profile_id" integer NOT NULL,
+	"plan_artifact_id" integer,
+	"target_key" varchar(100) DEFAULT 'projectx' NOT NULL,
+	"state" varchar(32) DEFAULT 'draft' NOT NULL,
+	"current_stage" varchar(64),
+	"triggered_by_user_id" integer,
+	"started_at" timestamp,
+	"ended_at" timestamp,
+	"error_message" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "migration_sources" (
+	"id" serial PRIMARY KEY NOT NULL,
+	"type" varchar(50) NOT NULL,
+	"name" varchar(255) NOT NULL,
+	"connection_config" jsonb NOT NULL,
+	"capabilities" jsonb,
+	"last_validated_at" timestamp,
+	"created_by_user_id" integer,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
 CREATE TABLE "libraries" (
 	"id" serial PRIMARY KEY NOT NULL,
 	"name" varchar(255) NOT NULL,
@@ -642,6 +711,17 @@ ALTER TABLE "user_library_access" ADD CONSTRAINT "user_library_access_user_id_us
 ALTER TABLE "user_library_access" ADD CONSTRAINT "user_library_access_library_id_libraries_id_fk" FOREIGN KEY ("library_id") REFERENCES "public"."libraries"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "user_permissions" ADD CONSTRAINT "user_permissions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "comic_metadata" ADD CONSTRAINT "comic_metadata_book_id_books_id_fk" FOREIGN KEY ("book_id") REFERENCES "public"."books"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_plan_artifacts" ADD CONSTRAINT "migration_plan_artifacts_source_id_migration_sources_id_fk" FOREIGN KEY ("source_id") REFERENCES "public"."migration_sources"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_plan_artifacts" ADD CONSTRAINT "migration_plan_artifacts_profile_id_migration_profiles_id_fk" FOREIGN KEY ("profile_id") REFERENCES "public"."migration_profiles"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_plan_artifacts" ADD CONSTRAINT "migration_plan_artifacts_created_by_user_id_users_id_fk" FOREIGN KEY ("created_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_profiles" ADD CONSTRAINT "migration_profiles_source_id_migration_sources_id_fk" FOREIGN KEY ("source_id") REFERENCES "public"."migration_sources"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_profiles" ADD CONSTRAINT "migration_profiles_created_by_user_id_users_id_fk" FOREIGN KEY ("created_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_run_metrics" ADD CONSTRAINT "migration_run_metrics_run_id_migration_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."migration_runs"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_runs" ADD CONSTRAINT "migration_runs_source_id_migration_sources_id_fk" FOREIGN KEY ("source_id") REFERENCES "public"."migration_sources"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_runs" ADD CONSTRAINT "migration_runs_profile_id_migration_profiles_id_fk" FOREIGN KEY ("profile_id") REFERENCES "public"."migration_profiles"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_runs" ADD CONSTRAINT "migration_runs_plan_artifact_id_migration_plan_artifacts_id_fk" FOREIGN KEY ("plan_artifact_id") REFERENCES "public"."migration_plan_artifacts"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_runs" ADD CONSTRAINT "migration_runs_triggered_by_user_id_users_id_fk" FOREIGN KEY ("triggered_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "migration_sources" ADD CONSTRAINT "migration_sources_created_by_user_id_users_id_fk" FOREIGN KEY ("created_by_user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "library_folders" ADD CONSTRAINT "library_folders_library_id_libraries_id_fk" FOREIGN KEY ("library_id") REFERENCES "public"."libraries"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "book_files" ADD CONSTRAINT "book_files_book_id_books_id_fk" FOREIGN KEY ("book_id") REFERENCES "public"."books"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "book_files" ADD CONSTRAINT "book_files_library_folder_id_library_folders_id_fk" FOREIGN KEY ("library_folder_id") REFERENCES "public"."library_folders"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
@@ -720,6 +800,16 @@ CREATE INDEX "idx_audit_ip" ON "audit_log" USING btree ("ip");--> statement-brea
 CREATE INDEX "idx_audit_created_at" ON "audit_log" USING btree ("created_at");--> statement-breakpoint
 CREATE INDEX "password_reset_tokens_user_id_idx" ON "password_reset_tokens" USING btree ("user_id");--> statement-breakpoint
 CREATE INDEX "refresh_tokens_user_id_idx" ON "refresh_tokens" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "migration_plan_artifacts_plan_hash_uidx" ON "migration_plan_artifacts" USING btree ("plan_hash");--> statement-breakpoint
+CREATE INDEX "migration_plan_artifacts_source_id_idx" ON "migration_plan_artifacts" USING btree ("source_id");--> statement-breakpoint
+CREATE INDEX "migration_plan_artifacts_profile_id_idx" ON "migration_plan_artifacts" USING btree ("profile_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "migration_profiles_source_name_version_uidx" ON "migration_profiles" USING btree ("source_id","name","version");--> statement-breakpoint
+CREATE INDEX "migration_profiles_source_id_idx" ON "migration_profiles" USING btree ("source_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "migration_run_metrics_run_stage_entity_uidx" ON "migration_run_metrics" USING btree ("run_id","stage","entity_type");--> statement-breakpoint
+CREATE INDEX "migration_run_metrics_run_id_idx" ON "migration_run_metrics" USING btree ("run_id");--> statement-breakpoint
+CREATE INDEX "migration_runs_source_target_state_idx" ON "migration_runs" USING btree ("source_id","target_key","state");--> statement-breakpoint
+CREATE INDEX "migration_runs_state_idx" ON "migration_runs" USING btree ("state");--> statement-breakpoint
+CREATE UNIQUE INDEX "migration_sources_type_name_uidx" ON "migration_sources" USING btree ("type","name");--> statement-breakpoint
 CREATE UNIQUE INDEX "books_library_id_folder_path_idx" ON "books" USING btree ("library_id","folder_path");--> statement-breakpoint
 CREATE INDEX "books_primary_file_id_idx" ON "books" USING btree ("primary_file_id");--> statement-breakpoint
 CREATE INDEX "author_enrichment_queue_status_next_attempt_idx" ON "author_enrichment_queue" USING btree ("status","next_attempt_at");--> statement-breakpoint
diff --git a/server/src/db/migrations/meta/0000_snapshot.json b/server/src/db/migrations/meta/0000_snapshot.json
index 435aedb74..3b7dcb4fe 100644
--- a/server/src/db/migrations/meta/0000_snapshot.json
+++ b/server/src/db/migrations/meta/0000_snapshot.json
@@ -1,5 +1,5 @@
 {
-  "id": "e4d220e7-8190-4aac-b2df-a9f4b8f8aa8c",
+  "id": "a3fd36da-da08-434e-89d4-d9e1389a0b9c",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -739,6 +739,716 @@
       "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
+        },
+        "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",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "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"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "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",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "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": {},
+      "policies": {},
+      "checkConstraints": {},
+      "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",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "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": {},
+      "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": "'projectx'"
+        },
+        "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",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "ended_at": {
+          "name": "ended_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "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"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "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",
+          "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",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "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": {}
+        }
+      },
+      "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": "",
diff --git a/server/src/db/migrations/meta/_journal.json b/server/src/db/migrations/meta/_journal.json
index 6923e180f..4323049ef 100644
--- a/server/src/db/migrations/meta/_journal.json
+++ b/server/src/db/migrations/meta/_journal.json
@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1775131468963,
+      "when": 1775280065541,
       "tag": "0000_baseline",
       "breakpoints": true
     }
diff --git a/server/src/db/schema/index.ts b/server/src/db/schema/index.ts
index 4697fe6e6..1b1053c87 100644
--- a/server/src/db/schema/index.ts
+++ b/server/src/db/schema/index.ts
@@ -1,6 +1,7 @@
 export * from './audit';
 export * from './auth';
 export * from './comic-metadata';
+export * from './migration';
 export * from './libraries';
 export * from './books';
 export * from './collections';
diff --git a/server/src/db/schema/migration.ts b/server/src/db/schema/migration.ts
new file mode 100644
index 000000000..9a7430a58
--- /dev/null
+++ b/server/src/db/schema/migration.ts
@@ -0,0 +1,146 @@
+import { index, integer, jsonb, pgTable, serial, text, timestamp, uniqueIndex, varchar } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+
+import { users } from './auth';
+
+export const migrationSources = pgTable(
+  'migration_sources',
+  {
+    id: serial('id').primaryKey(),
+    type: varchar('type', { length: 50 }).notNull(),
+    name: varchar('name', { length: 255 }).notNull(),
+    connectionConfig: jsonb('connection_config').notNull(),
+    capabilities: jsonb('capabilities'),
+    lastValidatedAt: timestamp('last_validated_at'),
+    createdByUserId: integer('created_by_user_id').references(() => users.id, { onDelete: 'set null' }),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at')
+      .defaultNow()
+      .notNull()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [uniqueIndex('migration_sources_type_name_uidx').on(t.type, t.name)],
+);
+
+export const migrationProfiles = pgTable(
+  'migration_profiles',
+  {
+    id: serial('id').primaryKey(),
+    sourceId: integer('source_id')
+      .notNull()
+      .references(() => migrationSources.id, { onDelete: 'cascade' }),
+    name: varchar('name', { length: 255 }).notNull(),
+    version: integer('version').notNull().default(1),
+    userMappings: jsonb('user_mappings').notNull(),
+    pathMappings: jsonb('path_mappings')
+      .notNull()
+      .default(sql`'[]'::jsonb`),
+    scope: jsonb('scope')
+      .notNull()
+      .default(sql`'{}'::jsonb`),
+    createdByUserId: integer('created_by_user_id').references(() => users.id, { onDelete: 'set null' }),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at')
+      .defaultNow()
+      .notNull()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [
+    uniqueIndex('migration_profiles_source_name_version_uidx').on(t.sourceId, t.name, t.version),
+    index('migration_profiles_source_id_idx').on(t.sourceId),
+  ],
+);
+
+export const migrationPlanArtifacts = pgTable(
+  'migration_plan_artifacts',
+  {
+    id: serial('id').primaryKey(),
+    sourceId: integer('source_id')
+      .notNull()
+      .references(() => migrationSources.id, { onDelete: 'cascade' }),
+    profileId: integer('profile_id')
+      .notNull()
+      .references(() => migrationProfiles.id, { onDelete: 'cascade' }),
+    sourceSnapshotHash: varchar('source_snapshot_hash', { length: 128 }).notNull(),
+    profileHash: varchar('profile_hash', { length: 128 }).notNull(),
+    planHash: varchar('plan_hash', { length: 128 }).notNull(),
+    plan: jsonb('plan').notNull(),
+    summary: jsonb('summary').notNull(),
+    createdByUserId: integer('created_by_user_id').references(() => users.id, { onDelete: 'set null' }),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at')
+      .defaultNow()
+      .notNull()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [
+    uniqueIndex('migration_plan_artifacts_plan_hash_uidx').on(t.planHash),
+    index('migration_plan_artifacts_source_id_idx').on(t.sourceId),
+    index('migration_plan_artifacts_profile_id_idx').on(t.profileId),
+  ],
+);
+
+export const migrationRuns = pgTable(
+  'migration_runs',
+  {
+    id: serial('id').primaryKey(),
+    sourceId: integer('source_id')
+      .notNull()
+      .references(() => migrationSources.id, { onDelete: 'cascade' }),
+    profileId: integer('profile_id')
+      .notNull()
+      .references(() => migrationProfiles.id, { onDelete: 'cascade' }),
+    planArtifactId: integer('plan_artifact_id').references(() => migrationPlanArtifacts.id, { onDelete: 'set null' }),
+    targetKey: varchar('target_key', { length: 100 }).notNull().default('projectx'),
+    state: varchar('state', { length: 32 }).notNull().default('draft'),
+    currentStage: varchar('current_stage', { length: 64 }),
+    triggeredByUserId: integer('triggered_by_user_id').references(() => users.id, { onDelete: 'set null' }),
+    startedAt: timestamp('started_at'),
+    endedAt: timestamp('ended_at'),
+    errorMessage: text('error_message'),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at')
+      .defaultNow()
+      .notNull()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [index('migration_runs_source_target_state_idx').on(t.sourceId, t.targetKey, t.state), index('migration_runs_state_idx').on(t.state)],
+);
+
+export const migrationRunMetrics = pgTable(
+  'migration_run_metrics',
+  {
+    id: serial('id').primaryKey(),
+    runId: integer('run_id')
+      .notNull()
+      .references(() => migrationRuns.id, { onDelete: 'cascade' }),
+    stage: varchar('stage', { length: 64 }).notNull(),
+    entityType: varchar('entity_type', { length: 64 }).notNull(),
+    processed: integer('processed').notNull().default(0),
+    imported: integer('imported').notNull().default(0),
+    skipped: integer('skipped').notNull().default(0),
+    unresolved: integer('unresolved').notNull().default(0),
+    failed: integer('failed').notNull().default(0),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at')
+      .defaultNow()
+      .notNull()
+      .$onUpdateFn(() => new Date()),
+  },
+  (t) => [
+    uniqueIndex('migration_run_metrics_run_stage_entity_uidx').on(t.runId, t.stage, t.entityType),
+    index('migration_run_metrics_run_id_idx').on(t.runId),
+  ],
+);
+
+export type MigrationSource = typeof migrationSources.$inferSelect;
+export type NewMigrationSource = typeof migrationSources.$inferInsert;
+
+export type MigrationProfile = typeof migrationProfiles.$inferSelect;
+export type NewMigrationProfile = typeof migrationProfiles.$inferInsert;
+
+export type MigrationPlanArtifact = typeof migrationPlanArtifacts.$inferSelect;
+export type NewMigrationPlanArtifact = typeof migrationPlanArtifacts.$inferInsert;
+
+export type MigrationRun = typeof migrationRuns.$inferSelect;
+export type NewMigrationRun = typeof migrationRuns.$inferInsert;
diff --git a/server/src/db/schema/schema.test.ts b/server/src/db/schema/schema.test.ts
index e70b45810..a1bb585b1 100644
--- a/server/src/db/schema/schema.test.ts
+++ b/server/src/db/schema/schema.test.ts
@@ -12,6 +12,7 @@ import { lenses } from './lenses';
 import { koboSyncSettings, koboLibrarySnapshots, koboReadingStates } from './kobo';
 import { emailRecipients, emailRecipientGroups } from './email-recipients';
 import { readerDefaultPreferences, readerPreferences, readingProgress, annotations, userReadingDailyStats } from './reader';
+import { migrationSources, migrationProfiles, migrationPlanArtifacts, migrationRuns, migrationRunMetrics } from './migration';
 
 describe('Database Schema Logic', () => {
   beforeAll(() => {
@@ -96,5 +97,10 @@ describe('Database Schema Logic', () => {
     testOnUpdate('annotations.updatedAt', annotations.updatedAt);
     testOnUpdate('readerDefaultPreferences.updatedAt', readerDefaultPreferences.updatedAt);
     testOnUpdate('readerPreferences.updatedAt', readerPreferences.updatedAt);
+    testOnUpdate('migrationSources.updatedAt', migrationSources.updatedAt);
+    testOnUpdate('migrationProfiles.updatedAt', migrationProfiles.updatedAt);
+    testOnUpdate('migrationPlanArtifacts.updatedAt', migrationPlanArtifacts.updatedAt);
+    testOnUpdate('migrationRuns.updatedAt', migrationRuns.updatedAt);
+    testOnUpdate('migrationRunMetrics.updatedAt', migrationRunMetrics.updatedAt);
   });
 });
diff --git a/server/src/modules/architecture/architecture-boundaries.test.ts b/server/src/modules/architecture/architecture-boundaries.test.ts
index bccbf3625..0be7b6573 100644
--- a/server/src/modules/architecture/architecture-boundaries.test.ts
+++ b/server/src/modules/architecture/architecture-boundaries.test.ts
@@ -57,6 +57,8 @@ describe('Architecture boundaries', () => {
       'src/modules/metadata/metadata.service.ts',
       'src/modules/metadata-preferences/metadata-preferences.service.ts',
       'src/modules/metadata-preferences/provider-config.service.ts',
+      'src/modules/migration/executor/migration-executor.service.ts',
+      'src/modules/migration/planner/matching.service.ts',
       'src/modules/opds/opds-book.service.ts',
       'src/modules/opds/opds-user.service.ts',
       'src/modules/scanner/file-watcher.service.ts',
diff --git a/server/src/modules/auth/oidc/oidc-session.repository.test.ts b/server/src/modules/auth/oidc/oidc-session.repository.test.ts
index 68dcafb07..6589e739a 100644
--- a/server/src/modules/auth/oidc/oidc-session.repository.test.ts
+++ b/server/src/modules/auth/oidc/oidc-session.repository.test.ts
@@ -1,6 +1,7 @@
 vi.mock('drizzle-orm', () => ({
   and: vi.fn((...clauses: unknown[]) => ({ op: 'and', clauses })),
   eq: vi.fn((left: unknown, right: unknown) => ({ op: 'eq', left, right })),
+  sql: vi.fn((parts: TemplateStringsArray, ...values: unknown[]) => ({ op: 'sql', parts, values })),
 }));
 
 import { and, eq } from 'drizzle-orm';
diff --git a/server/src/modules/catalog/catalog.service.test.ts b/server/src/modules/catalog/catalog.service.test.ts
index c13ea1628..0deaca3b5 100644
--- a/server/src/modules/catalog/catalog.service.test.ts
+++ b/server/src/modules/catalog/catalog.service.test.ts
@@ -3,6 +3,7 @@ vi.mock('drizzle-orm', () => ({
   eq: vi.fn((left: unknown, right: unknown) => ({ type: 'eq', left, right })),
   ilike: vi.fn((left: unknown, pattern: string) => ({ type: 'ilike', left, pattern })),
   isNotNull: vi.fn((value: unknown) => ({ type: 'isNotNull', value })),
+  sql: vi.fn((parts: TemplateStringsArray, ...values: unknown[]) => ({ type: 'sql', parts, values })),
 }));
 
 import { and, eq, ilike, isNotNull } from 'drizzle-orm';
diff --git a/server/src/modules/collection/collection.dto.test.ts b/server/src/modules/collection/collection.dto.test.ts
index f63dbe594..7deff8dc1 100644
--- a/server/src/modules/collection/collection.dto.test.ts
+++ b/server/src/modules/collection/collection.dto.test.ts
@@ -14,10 +14,12 @@ async function errorsFor<T extends object>(dtoClass: new () => T, value: Record<
 
 describe('Collection DTO validation', () => {
   describe('CreateCollectionDto', () => {
-    it('accepts valid payloads and rejects empty names', async () => {
+    it('accepts valid payloads and rejects empty names or missing icons', async () => {
       expect((await errorsFor(CreateCollectionDto, { name: 'Favorites', icon: '⭐', description: 'Best books', syncToKobo: true })).length).toBe(0);
       expect((await errorsFor(CreateCollectionDto, { name: '' })).length).toBeGreaterThan(0);
       expect((await errorsFor(CreateCollectionDto, {})).length).toBeGreaterThan(0);
+      expect((await errorsFor(CreateCollectionDto, { name: 'Favorites' })).length).toBeGreaterThan(0);
+      expect((await errorsFor(CreateCollectionDto, { name: 'Favorites', icon: '   ' })).length).toBeGreaterThan(0);
     });
 
     it('enforces field lengths', async () => {
diff --git a/server/src/modules/collection/collection.service.ts b/server/src/modules/collection/collection.service.ts
index 253183ae4..0f15b6d31 100644
--- a/server/src/modules/collection/collection.service.ts
+++ b/server/src/modules/collection/collection.service.ts
@@ -74,7 +74,7 @@ export class CollectionService {
     const [inserted] = await this.collectionRepo.insert({
       userId: user.id,
       name: dto.name,
-      icon: dto.icon?.trim() || null,
+      icon: dto.icon.trim(),
       description: dto.description ?? null,
       syncToKobo: dto.syncToKobo ?? false,
     });
diff --git a/server/src/modules/collection/dto/create-collection.dto.ts b/server/src/modules/collection/dto/create-collection.dto.ts
index 2156daeff..1242de8a9 100644
--- a/server/src/modules/collection/dto/create-collection.dto.ts
+++ b/server/src/modules/collection/dto/create-collection.dto.ts
@@ -1,15 +1,21 @@
+import { Transform } from 'class-transformer';
 import { IsBoolean, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
 
+function trimString(value: unknown): unknown {
+  return typeof value === 'string' ? value.trim() : value;
+}
+
 export class CreateCollectionDto {
   @IsString()
   @IsNotEmpty()
   @MaxLength(255)
   name: string;
 
-  @IsOptional()
+  @Transform(({ value }) => trimString(value))
   @IsString()
+  @IsNotEmpty()
   @MaxLength(100)
-  icon?: string;
+  icon: string;
 
   @IsOptional()
   @IsString()
diff --git a/server/src/modules/email/email-recipient.repository.test.ts b/server/src/modules/email/email-recipient.repository.test.ts
index 29572eab6..ce5f348ea 100644
--- a/server/src/modules/email/email-recipient.repository.test.ts
+++ b/server/src/modules/email/email-recipient.repository.test.ts
@@ -2,6 +2,7 @@ vi.mock('drizzle-orm', () => ({
   and: vi.fn((...clauses: unknown[]) => ({ op: 'and', clauses })),
   eq: vi.fn((left: unknown, right: unknown) => ({ op: 'eq', left, right })),
   inArray: vi.fn((left: unknown, values: unknown[]) => ({ op: 'inArray', left, values })),
+  sql: vi.fn((parts: TemplateStringsArray, ...values: unknown[]) => ({ op: 'sql', parts, values })),
 }));
 
 import { and, eq, inArray } from 'drizzle-orm';
diff --git a/server/src/modules/migration/adapters/booklore/booklore-connection-config.test.ts b/server/src/modules/migration/adapters/booklore/booklore-connection-config.test.ts
new file mode 100644
index 000000000..4b0763bc9
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-connection-config.test.ts
@@ -0,0 +1,30 @@
+import { BadRequestException } from '@nestjs/common';
+import { describe, expect, it } from 'vitest';
+
+import { parseBookloreConnectionConfig } from './booklore-connection-config';
+
+describe('parseBookloreConnectionConfig', () => {
+  it('parses optional absolute mediaRootPath', () => {
+    const parsed = parseBookloreConnectionConfig({
+      host: '127.0.0.1',
+      user: 'root',
+      password: 'rootpw',
+      database: 'booklore',
+      mediaRootPath: '/tmp/booklore-media',
+    });
+
+    expect(parsed.mediaRootPath).toBe('/tmp/booklore-media');
+  });
+
+  it('rejects relative mediaRootPath values', () => {
+    expect(() =>
+      parseBookloreConnectionConfig({
+        host: '127.0.0.1',
+        user: 'root',
+        password: 'rootpw',
+        database: 'booklore',
+        mediaRootPath: './booklore-media',
+      }),
+    ).toThrow(BadRequestException);
+  });
+});
diff --git a/server/src/modules/migration/adapters/booklore/booklore-connection-config.ts b/server/src/modules/migration/adapters/booklore/booklore-connection-config.ts
new file mode 100644
index 000000000..bcdc2d047
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-connection-config.ts
@@ -0,0 +1,38 @@
+import { BadRequestException } from '@nestjs/common';
+import { isAbsolute } from 'node:path';
+
+export interface BookloreConnectionConfig {
+  host: string;
+  port?: number;
+  user: string;
+  password: string;
+  database: string;
+  ssl?: boolean;
+  mediaRootPath?: string | null;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function parseBookloreConnectionConfig(raw: unknown): BookloreConnectionConfig {
+  if (!isObject(raw)) throw new BadRequestException('Invalid Booklore connection config: expected object');
+
+  const host = typeof raw.host === 'string' ? raw.host.trim() : '';
+  const user = typeof raw.user === 'string' ? raw.user.trim() : '';
+  const password = typeof raw.password === 'string' ? raw.password : '';
+  const database = typeof raw.database === 'string' ? raw.database.trim() : '';
+  const port = typeof raw.port === 'number' && Number.isFinite(raw.port) ? raw.port : 3306;
+  const ssl = raw.ssl === true;
+  const mediaRootPathRaw = typeof raw.mediaRootPath === 'string' ? raw.mediaRootPath.trim() : '';
+  const mediaRootPath = mediaRootPathRaw.length > 0 ? mediaRootPathRaw : null;
+
+  if (!host || !user || !database) {
+    throw new BadRequestException('Invalid Booklore connection config: host, user, and database are required');
+  }
+  if (mediaRootPath && !isAbsolute(mediaRootPath)) {
+    throw new BadRequestException('Invalid Booklore connection config: mediaRootPath must be an absolute path');
+  }
+
+  return { host, port, user, password, database, ssl, mediaRootPath };
+}
diff --git a/server/src/modules/migration/adapters/booklore/booklore-connector.ts b/server/src/modules/migration/adapters/booklore/booklore-connector.ts
new file mode 100644
index 000000000..9551c1162
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-connector.ts
@@ -0,0 +1,65 @@
+import { Injectable } from '@nestjs/common';
+import mysql from 'mysql2/promise';
+import type { RowDataPacket } from 'mysql2';
+
+import type { BookloreConnectionConfig } from './booklore-connection-config';
+
+type Row = RowDataPacket & Record<string, unknown>;
+
+@Injectable()
+export class BookloreConnector {
+  async withConnection<T>(config: BookloreConnectionConfig, fn: (conn: mysql.Connection) => Promise<T>): Promise<T> {
+    const connection = await mysql.createConnection({
+      host: config.host,
+      port: config.port ?? 3306,
+      user: config.user,
+      password: config.password,
+      database: config.database,
+      ssl: config.ssl ? {} : undefined,
+      supportBigNumbers: true,
+    });
+
+    try {
+      return await fn(connection);
+    } finally {
+      await connection.end();
+    }
+  }
+
+  async listTables(conn: mysql.Connection): Promise<Set<string>> {
+    const [rows] = await conn.query<Row[]>(
+      `
+      SELECT table_name AS tableName
+      FROM information_schema.tables
+      WHERE table_schema = DATABASE()
+      `,
+    );
+
+    return new Set(rows.map((row) => String(row.tableName).toLowerCase()));
+  }
+
+  async listColumns(conn: mysql.Connection, tableName: string): Promise<Set<string>> {
+    const [rows] = await conn.query<Row[]>(
+      `
+      SELECT column_name AS columnName
+      FROM information_schema.columns
+      WHERE table_schema = DATABASE() AND table_name = ?
+      `,
+      [tableName],
+    );
+
+    return new Set(rows.map((row) => String(row.columnName).toLowerCase()));
+  }
+
+  async countRows(conn: mysql.Connection, tableName: string): Promise<number> {
+    const [rows] = await conn.query<Row[]>(`SELECT COUNT(*) AS count FROM \`${tableName}\``);
+    const value = rows[0]?.count;
+    const count = typeof value === 'number' ? value : Number(value ?? 0);
+    return Number.isFinite(count) ? count : 0;
+  }
+
+  async queryRows(conn: mysql.Connection, sqlText: string, params: unknown[] = []): Promise<Row[]> {
+    const [rows] = await conn.query<Row[]>(sqlText, params);
+    return rows;
+  }
+}
diff --git a/server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts
new file mode 100644
index 000000000..75e6305fa
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { BookloreSourceAdapter } from './booklore-source.adapter';
+
+describe('BookloreSourceAdapter shelf export', () => {
+  it('carries the shelf owner through each shelf-book mapping', async () => {
+    const connector = {
+      listColumns: vi
+        .fn()
+        .mockResolvedValueOnce(new Set(['id', 'user_id', 'name']))
+        .mockResolvedValueOnce(new Set(['shelf_id', 'book_id']))
+        .mockResolvedValueOnce(new Set(['id'])),
+      queryRows: vi
+        .fn()
+        .mockResolvedValueOnce([{ sourceShelfId: 's1', sourceUserId: 'u1', name: 'Favorites' }])
+        .mockResolvedValueOnce([{ sourceShelfId: 's1', sourceUserId: 'u1', sourceBookId: 'b1' }]),
+    };
+
+    const adapter = new BookloreSourceAdapter(connector as never);
+
+    const result = await (adapter as any).fetchShelves({} as never, 'shelf', 'book_shelf_mapping', 'book');
+
+    expect(result).toEqual({
+      shelves: [{ sourceShelfId: 's1', sourceUserId: 'u1', name: 'Favorites' }],
+      shelfBooks: [{ sourceShelfId: 's1', sourceUserId: 'u1', sourceBookId: 'b1' }],
+    });
+    expect(connector.queryRows).toHaveBeenNthCalledWith(2, expect.anything(), expect.stringContaining('JOIN `shelf` s ON s.`id` = m.`shelf_id`'));
+  });
+});
diff --git a/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
new file mode 100644
index 000000000..5155a0f26
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
@@ -0,0 +1,1076 @@
+import { Injectable } from '@nestjs/common';
+import type mysql from 'mysql2/promise';
+
+import type {
+  SourceAdapter,
+  SourceAnnotation,
+  SourceBook,
+  SourceBookmark,
+  SourceContributor,
+  SourceExportData,
+  SourceShelf,
+  SourceShelfBook,
+  SourceSnapshot,
+  SourceUser,
+  SourceUserBookStatus,
+  SourceUserFileProgress,
+  SourceValidationResult,
+} from '../source-adapter.types';
+import type { BookloreConnectionConfig } from './booklore-connection-config';
+import { BookloreConnector } from './booklore-connector';
+
+const TABLE_CANDIDATES = {
+  users: ['users'],
+  book: ['book', 'books'],
+  bookFile: ['book_file', 'book_files'],
+  bookMetadata: ['book_metadata'],
+  libraryPath: ['library_path', 'library_paths'],
+  authors: ['author', 'authors'],
+  authorMapping: ['book_metadata_author_mapping', 'book_author_mapping'],
+  userBookProgress: ['user_book_progress'],
+  userBookFileProgress: ['user_book_file_progress'],
+  bookmarks: ['book_marks', 'bookmarks'],
+  annotations: ['annotations'],
+  pdfAnnotations: ['pdf_annotations'],
+  shelves: ['shelf', 'shelves'],
+  shelfBooks: ['book_shelf_mapping', 'shelf_book_mapping'],
+  categories: ['category', 'categories', 'genre', 'genres'],
+  categoryMapping: ['book_metadata_category_mapping', 'book_category_mapping', 'book_genre_mapping'],
+  tags: ['tag', 'tags'],
+  tagMapping: ['book_metadata_tag_mapping', 'book_tag_mapping'],
+  bookNotes: ['book_notes'],
+  bookNotesV2: ['book_notes_v2'],
+  epubViewerPreference: ['epub_viewer_preference'],
+  pdfViewerPreference: ['pdf_viewer_preference'],
+  cbxViewerPreference: ['cbx_viewer_preference'],
+  newPdfViewerPreference: ['new_pdf_viewer_preference'],
+  koboUserSettings: ['kobo_user_settings'],
+  koboReadingState: ['kobo_reading_state'],
+  comicMetadata: ['comic_metadata'],
+} as const;
+
+interface TableResolution {
+  users: string | null;
+  book: string | null;
+  bookFile: string | null;
+  bookMetadata: string | null;
+  libraryPath: string | null;
+  authors: string | null;
+  authorMapping: string | null;
+  userBookProgress: string | null;
+  userBookFileProgress: string | null;
+  bookmarks: string | null;
+  annotations: string | null;
+  pdfAnnotations: string | null;
+  shelves: string | null;
+  shelfBooks: string | null;
+  categories: string | null;
+  categoryMapping: string | null;
+  tags: string | null;
+  tagMapping: string | null;
+  bookNotes: string | null;
+  bookNotesV2: string | null;
+  epubViewerPreference: string | null;
+  pdfViewerPreference: string | null;
+  cbxViewerPreference: string | null;
+  newPdfViewerPreference: string | null;
+  koboUserSettings: string | null;
+  koboReadingState: string | null;
+  comicMetadata: string | null;
+}
+
+@Injectable()
+export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionConfig> {
+  readonly type = 'booklore';
+
+  constructor(private readonly connector: BookloreConnector) {}
+
+  async validate(config: BookloreConnectionConfig): Promise<SourceValidationResult> {
+    return this.connector.withConnection(config, async (conn) => {
+      const tables = await this.connector.listTables(conn);
+      const resolved = resolveTables(tables);
+      const sourceVersion = await this.readVersion(conn);
+
+      const missingTables: string[] = [];
+      if (!resolved.users) missingTables.push('users');
+      if (!resolved.book) missingTables.push('book');
+      if (!resolved.bookFile) missingTables.push('book_file');
+
+      const counts = await this.collectCounts(conn, resolved);
+      const warnings = this.buildWarnings(resolved, config);
+
+      return {
+        ok: missingTables.length === 0,
+        sourceType: this.type,
+        sourceVersion,
+        missingTables,
+        warnings,
+        counts,
+      };
+    });
+  }
+
+  async snapshot(config: BookloreConnectionConfig): Promise<SourceSnapshot> {
+    return this.connector.withConnection(config, async (conn) => {
+      const tables = await this.connector.listTables(conn);
+      const resolved = resolveTables(tables);
+      const counts = await this.collectCounts(conn, resolved);
+
+      return {
+        generatedAt: new Date().toISOString(),
+        sourceType: this.type,
+        sourceVersion: await this.readVersion(conn),
+        counts,
+      };
+    });
+  }
+
+  async exportData(config: BookloreConnectionConfig): Promise<SourceExportData> {
+    return this.connector.withConnection(config, async (conn) => {
+      const tables = await this.connector.listTables(conn);
+      const resolved = resolveTables(tables);
+
+      const users = await this.fetchUsers(conn, resolved.users);
+      const books = await this.fetchBooks(conn, resolved);
+      const userBookStatuses = await this.fetchUserBookStatuses(conn, resolved.userBookProgress);
+      const userFileProgress = await this.fetchUserFileProgress(conn, resolved.userBookFileProgress, resolved.bookFile);
+      const bookmarks = await this.fetchBookmarks(conn, resolved.bookmarks);
+      const annotations = await this.fetchAnnotations(conn, resolved.annotations);
+      const { shelves, shelfBooks } = await this.fetchShelves(conn, resolved.shelves, resolved.shelfBooks, resolved.book);
+      await this.attachCategoriesToBooks(conn, books, resolved.categories, resolved.categoryMapping);
+      await this.attachTagsToBooks(conn, books, resolved.tags, resolved.tagMapping);
+
+      return {
+        users,
+        books,
+        userBookStatuses,
+        userFileProgress,
+        bookmarks,
+        annotations,
+        shelves,
+        shelfBooks,
+      };
+    });
+  }
+
+  async fetchPathPrefixes(config: BookloreConnectionConfig): Promise<string[]> {
+    return this.connector.withConnection(config, async (conn) => {
+      const tables = await this.connector.listTables(conn);
+      if (!tables.has('library_path')) return [];
+
+      const rows = await this.connector.queryRows(
+        conn,
+        'SELECT DISTINCT CAST(`path` AS CHAR) AS path FROM `library_path` WHERE `path` IS NOT NULL ORDER BY `path`',
+      );
+
+      return rows.map((row) => asString(row.path)).filter((p): p is string => p !== null);
+    });
+  }
+
+  private async readVersion(conn: mysql.Connection): Promise<string | null> {
+    try {
+      const rows = await this.connector.queryRows(conn, 'SELECT VERSION() AS version');
+      const value = rows[0]?.version;
+      return typeof value === 'string' ? value : value == null ? null : String(value);
+    } catch {
+      return null;
+    }
+  }
+
+  private async collectCounts(conn: mysql.Connection, resolved: TableResolution): Promise<Record<string, number>> {
+    const out: Record<string, number> = {};
+    for (const [label, tableName] of Object.entries(resolved)) {
+      if (!tableName) continue;
+      out[label] = await this.connector.countRows(conn, tableName);
+    }
+    return out;
+  }
+
+  private buildWarnings(resolved: TableResolution, config: BookloreConnectionConfig): string[] {
+    const warnings: string[] = [];
+
+    if (!resolved.bookMetadata) warnings.push('book_metadata table not found; metadata overlays will be limited');
+    if (!resolved.authors || !resolved.authorMapping) warnings.push('author mapping tables not found; author migration disabled');
+    if (!resolved.userBookProgress) warnings.push('user_book_progress table not found; status migration disabled');
+    if (!resolved.userBookFileProgress) warnings.push('user_book_file_progress table not found; file progress migration disabled');
+    if (!resolved.bookmarks) warnings.push('book_marks/bookmarks table not found; bookmark migration disabled');
+    if (!resolved.annotations) warnings.push('annotations table not found; annotation migration disabled');
+    if (!resolved.shelves || !resolved.shelfBooks) warnings.push('shelf mapping tables not found; shelf-to-collection migration disabled');
+    if (!resolved.categories || !resolved.categoryMapping) warnings.push('category/genre tables not found; genre migration disabled');
+    if (!resolved.tags || !resolved.tagMapping) warnings.push('tag tables not found; tag migration disabled');
+    if (resolved.pdfAnnotations) warnings.push('pdf_annotations table detected; PDF annotation migration is deferred');
+    if (resolved.bookNotes || resolved.bookNotesV2) warnings.push('Booklore notes tables detected; notes migration is deferred');
+    if (resolved.koboUserSettings || resolved.koboReadingState) warnings.push('Booklore Kobo tables detected; Kobo migration is deferred');
+    if (resolved.comicMetadata) warnings.push('comic_metadata table detected; comic metadata migration is deferred');
+    if (resolved.epubViewerPreference || resolved.pdfViewerPreference || resolved.cbxViewerPreference || resolved.newPdfViewerPreference) {
+      warnings.push('Booklore viewer preference tables detected; reader preference migration is deferred');
+    }
+    if (!config.mediaRootPath) warnings.push('mediaRootPath not configured; book cover/thumbnail import disabled');
+
+    return warnings;
+  }
+
+  private async fetchUsers(conn: mysql.Connection, usersTable: string | null): Promise<SourceUser[]> {
+    if (!usersTable) return [];
+
+    const columns = await this.connector.listColumns(conn, usersTable);
+    const idCol = requiredColumn(columns, ['id', 'user_id']);
+    const usernameCol = firstColumn(columns, ['username', 'user_name', 'name']);
+    const nameCol = firstColumn(columns, ['name', 'display_name']);
+    const emailCol = firstColumn(columns, ['email', 'mail']);
+
+    const sqlText = `
+      SELECT
+        CAST(u.\`${idCol}\` AS CHAR) AS sourceUserId,
+        ${usernameCol ? `CAST(u.\`${usernameCol}\` AS CHAR)` : `CAST(u.\`${idCol}\` AS CHAR)`} AS username,
+        ${nameCol ? `CAST(u.\`${nameCol}\` AS CHAR)` : 'NULL'} AS name,
+        ${emailCol ? `CAST(u.\`${emailCol}\` AS CHAR)` : 'NULL'} AS email
+      FROM \`${usersTable}\` u
+      ORDER BY u.\`${idCol}\`
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+
+    return rows.map((row) => ({
+      sourceUserId: asString(row.sourceUserId) ?? '',
+      username: asString(row.username) ?? asString(row.sourceUserId) ?? 'unknown',
+      name: asString(row.name),
+      email: asString(row.email),
+    }));
+  }
+
+  private async fetchBooks(conn: mysql.Connection, resolved: TableResolution): Promise<SourceBook[]> {
+    const bookTable = resolved.book;
+    const metadataTable = resolved.bookMetadata;
+    const bookFileTable = resolved.bookFile;
+    if (!bookTable) return [];
+
+    const bookColumns = await this.connector.listColumns(conn, bookTable);
+    const bookIdCol = requiredColumn(bookColumns, ['id', 'book_id']);
+    const bookLibraryPathIdCol = firstColumn(bookColumns, ['library_path_id', 'librarypath_id']);
+
+    let metadataColumns: Set<string> | null = null;
+    let metadataJoinCol: string | null = null;
+    if (metadataTable) {
+      metadataColumns = await this.connector.listColumns(conn, metadataTable);
+      metadataJoinCol = firstColumn(metadataColumns, ['book_id', 'id']);
+    }
+
+    let fileColumns: Set<string> | null = null;
+    let fileJoinCol: string | null = null;
+    if (bookFileTable) {
+      fileColumns = await this.connector.listColumns(conn, bookFileTable);
+      fileJoinCol = firstColumn(fileColumns, ['book_id', 'bookid']);
+    }
+
+    let libraryPathIdCol: string | null = null;
+    let libraryPathValueCol: string | null = null;
+    if (resolved.libraryPath && bookLibraryPathIdCol) {
+      const libraryPathColumns = await this.connector.listColumns(conn, resolved.libraryPath);
+      libraryPathIdCol = firstColumn(libraryPathColumns, ['id', 'library_path_id']);
+      libraryPathValueCol = firstColumn(libraryPathColumns, ['path', 'absolute_path']);
+    }
+
+    const titleCol = metadataColumns ? firstColumn(metadataColumns, ['title']) : null;
+    const authorCol = metadataColumns ? firstColumn(metadataColumns, ['author', 'authors', 'author_name']) : null;
+    const subtitleCol = metadataColumns ? firstColumn(metadataColumns, ['subtitle']) : null;
+    const isbn10Col = metadataColumns ? firstColumn(metadataColumns, ['isbn10', 'isbn_10']) : null;
+    const isbn13Col = metadataColumns ? firstColumn(metadataColumns, ['isbn13', 'isbn_13']) : null;
+    const descriptionCol = metadataColumns ? firstColumn(metadataColumns, ['description']) : null;
+    const publisherCol = metadataColumns ? firstColumn(metadataColumns, ['publisher']) : null;
+    const publishedYearCol = metadataColumns ? firstColumn(metadataColumns, ['published_year', 'publishedyear', 'year']) : null;
+    const publishedDateCol = metadataColumns ? firstColumn(metadataColumns, ['published_date', 'publish_date', 'publication_date']) : null;
+    const languageCol = metadataColumns ? firstColumn(metadataColumns, ['language', 'lang']) : null;
+    const pageCountCol = metadataColumns ? firstColumn(metadataColumns, ['page_count', 'pagecount', 'pages']) : null;
+    const seriesNameCol = metadataColumns ? firstColumn(metadataColumns, ['series_name', 'series']) : null;
+    const seriesIndexCol = metadataColumns ? firstColumn(metadataColumns, ['series_number', 'series_index', 'series_position']) : null;
+    const ratingCol = metadataColumns ? firstColumn(metadataColumns, ['rating']) : null;
+    const googleBooksIdCol = metadataColumns ? firstColumn(metadataColumns, ['google_id', 'google_books_id']) : null;
+    const goodreadsIdCol = metadataColumns ? firstColumn(metadataColumns, ['goodreads_id']) : null;
+    const amazonIdCol = metadataColumns ? firstColumn(metadataColumns, ['asin', 'amazon_id']) : null;
+    const hardcoverIdCol = metadataColumns ? firstColumn(metadataColumns, ['hardcover_id']) : null;
+    const audibleIdCol = metadataColumns ? firstColumn(metadataColumns, ['audible_id']) : null;
+    const comicvineIdCol = metadataColumns ? firstColumn(metadataColumns, ['comicvine_id']) : null;
+    const durationSecondsCol = metadataColumns ? firstColumn(metadataColumns, ['duration_seconds', 'duration']) : null;
+    const abridgedCol = metadataColumns ? firstColumn(metadataColumns, ['abridged']) : null;
+    const narratorCol = metadataColumns ? firstColumn(metadataColumns, ['narrator', 'narrators']) : null;
+
+    const fileIdCol = fileColumns ? firstColumn(fileColumns, ['id', 'book_file_id']) : null;
+    const filePathCol = fileColumns ? firstColumn(fileColumns, ['absolute_path', 'path', 'file_path']) : null;
+    const fileNameCol = fileColumns ? firstColumn(fileColumns, ['file_name', 'filename', 'name']) : null;
+    const fileSubPathCol = fileColumns ? firstColumn(fileColumns, ['file_sub_path', 'file_subpath', 'sub_path', 'relative_path', 'rel_path']) : null;
+    const currentHashCol = fileColumns ? firstColumn(fileColumns, ['current_hash', 'hash', 'file_hash', 'sha256']) : null;
+    const initialHashCol = fileColumns ? firstColumn(fileColumns, ['initial_hash']) : null;
+    const fileDurationSecondsCol = fileColumns ? firstColumn(fileColumns, ['duration_seconds', 'duration']) : null;
+
+    const presentFields: string[] = (
+      [
+        ['title', titleCol],
+        ['subtitle', subtitleCol],
+        ['isbn10', isbn10Col],
+        ['isbn13', isbn13Col],
+        ['description', descriptionCol],
+        ['publisher', publisherCol],
+        ['publishedYear', publishedYearCol ?? publishedDateCol],
+        ['language', languageCol],
+        ['pageCount', pageCountCol],
+        ['seriesName', seriesNameCol],
+        ['seriesIndex', seriesIndexCol],
+        ['rating', ratingCol],
+        ['googleBooksId', googleBooksIdCol],
+        ['goodreadsId', goodreadsIdCol],
+        ['amazonId', amazonIdCol],
+        ['hardcoverId', hardcoverIdCol],
+        ['audibleId', audibleIdCol],
+        ['comicvineId', comicvineIdCol],
+        ['durationSeconds', durationSecondsCol],
+        ['abridged', abridgedCol],
+      ] as Array<[string, string | null]>
+    )
+      .filter(([, col]) => !!col)
+      .map(([field]) => field);
+
+    const selectParts = [
+      `CAST(b.\`${bookIdCol}\` AS CHAR) AS sourceBookId`,
+      sqlString('m', titleCol, 'title'),
+      sqlString('m', authorCol, 'author'),
+      sqlString('m', subtitleCol, 'subtitle'),
+      sqlString('m', isbn10Col, 'isbn10'),
+      sqlString('m', isbn13Col, 'isbn13'),
+      sqlString('m', descriptionCol, 'description'),
+      sqlString('m', publisherCol, 'publisher'),
+      sqlNumber('m', publishedYearCol, 'publishedYear'),
+      sqlString('m', publishedDateCol, 'publishedDate'),
+      sqlString('m', languageCol, 'language'),
+      sqlNumber('m', pageCountCol, 'pageCount'),
+      sqlString('m', seriesNameCol, 'seriesName'),
+      sqlNumber('m', seriesIndexCol, 'seriesIndex'),
+      sqlNumber('m', ratingCol, 'rating'),
+      sqlString('m', googleBooksIdCol, 'googleBooksId'),
+      sqlString('m', goodreadsIdCol, 'goodreadsId'),
+      sqlString('m', amazonIdCol, 'amazonId'),
+      sqlString('m', hardcoverIdCol, 'hardcoverId'),
+      sqlString('m', audibleIdCol, 'audibleId'),
+      sqlString('m', comicvineIdCol, 'comicvineId'),
+      sqlNumber('m', durationSecondsCol, 'durationSeconds'),
+      sqlNumber('m', abridgedCol, 'abridged'),
+      sqlString('m', narratorCol, 'narrator'),
+      fileIdCol ? `CAST(f.\`${fileIdCol}\` AS CHAR) AS sourceFileId` : 'NULL AS sourceFileId',
+      sqlString('f', filePathCol, 'directFilePath'),
+      sqlString('f', fileNameCol, 'fileName'),
+      sqlString('f', fileSubPathCol, 'fileSubPath'),
+      sqlString('f', currentHashCol, 'currentHash'),
+      sqlString('f', initialHashCol, 'initialHash'),
+      sqlNumber('f', fileDurationSecondsCol, 'fileDurationSeconds'),
+      libraryPathValueCol ? `CAST(lp.\`${libraryPathValueCol}\` AS CHAR) AS libraryRootPath` : 'NULL AS libraryRootPath',
+    ];
+
+    const joins: string[] = [];
+    if (metadataTable && metadataJoinCol) {
+      joins.push(`LEFT JOIN \`${metadataTable}\` m ON m.\`${metadataJoinCol}\` = b.\`${bookIdCol}\``);
+    }
+    if (bookFileTable && fileJoinCol) {
+      joins.push(`LEFT JOIN \`${bookFileTable}\` f ON f.\`${fileJoinCol}\` = b.\`${bookIdCol}\``);
+    }
+    if (resolved.libraryPath && bookLibraryPathIdCol && libraryPathIdCol && libraryPathValueCol) {
+      joins.push(`LEFT JOIN \`${resolved.libraryPath}\` lp ON lp.\`${libraryPathIdCol}\` = b.\`${bookLibraryPathIdCol}\``);
+    }
+
+    const sqlText = `
+      SELECT ${selectParts.join(',\n')}
+      FROM \`${bookTable}\` b
+      ${joins.join('\n')}
+      ORDER BY b.\`${bookIdCol}\`
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+    const byBook = new Map<string, SourceBook>();
+
+    for (const row of rows) {
+      const sourceBookId = asString(row.sourceBookId);
+      if (!sourceBookId) continue;
+
+      const existing = byBook.get(sourceBookId);
+      const next: SourceBook = existing ?? {
+        sourceBookId,
+        title: asString(row.title),
+        author: asString(row.author),
+        subtitle: asString(row.subtitle),
+        isbn10: asString(row.isbn10),
+        isbn13: asString(row.isbn13),
+        description: asString(row.description),
+        publisher: asString(row.publisher),
+        publishedYear: asInteger(row.publishedYear) ?? parsePublishedYear(row.publishedDate),
+        language: asString(row.language),
+        pageCount: asInteger(row.pageCount),
+        seriesName: asString(row.seriesName),
+        seriesIndex: asNumber(row.seriesIndex),
+        rating: asInteger(row.rating),
+        googleBooksId: asString(row.googleBooksId),
+        goodreadsId: asString(row.goodreadsId),
+        amazonId: asString(row.amazonId),
+        hardcoverId: asString(row.hardcoverId),
+        audibleId: asString(row.audibleId),
+        comicvineId: asString(row.comicvineId),
+        durationSeconds: asInteger(row.durationSeconds),
+        abridged: asBoolean(row.abridged),
+        authors: [],
+        narrators: parseContributorNames(asString(row.narrator)),
+        filePath: null,
+        fileHash: null,
+        files: [],
+        genres: [],
+        tags: [],
+        presentFields,
+      };
+
+      const sourceFileId = asString(row.sourceFileId);
+      const fileName = asString(row.fileName);
+      const fileSubPath = asString(row.fileSubPath);
+      const filePath = buildSourceFilePath({
+        directPath: asString(row.directFilePath),
+        libraryRootPath: asString(row.libraryRootPath),
+        fileSubPath,
+        fileName,
+      });
+      const fileHash = asString(row.currentHash) ?? asString(row.initialHash);
+      const fileDurationSeconds = asInteger(row.fileDurationSeconds);
+
+      if (sourceFileId && !next.files?.some((file) => file.sourceFileId === sourceFileId)) {
+        next.files?.push({
+          sourceFileId,
+          sourceBookId,
+          filePath,
+          fileHash,
+          fileName,
+          fileSubPath,
+          durationSeconds: fileDurationSeconds,
+        });
+      }
+
+      if (!next.filePath) next.filePath = filePath;
+      if (!next.fileHash) next.fileHash = fileHash;
+      if (next.durationSeconds == null && fileDurationSeconds != null) next.durationSeconds = fileDurationSeconds;
+      if (!next.title) next.title = asString(row.title);
+      if (!next.author) next.author = asString(row.author);
+      if (!next.isbn13) next.isbn13 = asString(row.isbn13);
+      if (!next.isbn10) next.isbn10 = asString(row.isbn10);
+
+      byBook.set(sourceBookId, next);
+    }
+
+    const books = [...byBook.values()];
+    await this.attachAuthorsToBooks(conn, books, resolved.authors, resolved.authorMapping);
+    return books;
+  }
+
+  private async attachAuthorsToBooks(
+    conn: mysql.Connection,
+    books: SourceBook[],
+    authorTable: string | null,
+    mappingTable: string | null,
+  ): Promise<void> {
+    if (!authorTable || !mappingTable) return;
+
+    const mappingCols = await this.connector.listColumns(conn, mappingTable);
+    const mapBookIdCol = firstColumn(mappingCols, ['book_id', 'bookid']);
+    const mapAuthorIdCol = firstColumn(mappingCols, ['author_id', 'authorid']);
+    const sortOrderCol = firstColumn(mappingCols, ['sort_order', 'display_order', 'position']);
+    if (!mapBookIdCol || !mapAuthorIdCol) return;
+
+    const authorCols = await this.connector.listColumns(conn, authorTable);
+    const authorIdCol = firstColumn(authorCols, ['id', 'author_id']);
+    const authorNameCol = firstColumn(authorCols, ['name', 'author_name']);
+    const sortNameCol = firstColumn(authorCols, ['sort_name', 'sortname']);
+    const descriptionCol = firstColumn(authorCols, ['description', 'bio']);
+    if (!authorIdCol || !authorNameCol) return;
+
+    const rows = await this.connector.queryRows(
+      conn,
+      `
+      SELECT
+        CAST(m.\`${mapBookIdCol}\` AS CHAR) AS bookId,
+        CAST(a.\`${authorIdCol}\` AS CHAR) AS sourceContributorId,
+        CAST(a.\`${authorNameCol}\` AS CHAR) AS name,
+        ${sqlString('a', sortNameCol, 'sortName')},
+        ${sqlString('a', descriptionCol, 'description')},
+        ${sqlNumber('m', sortOrderCol, 'displayOrder')}
+      FROM \`${mappingTable}\` m
+      JOIN \`${authorTable}\` a ON a.\`${authorIdCol}\` = m.\`${mapAuthorIdCol}\`
+      ORDER BY m.\`${mapBookIdCol}\`, ${sortOrderCol ? `m.\`${sortOrderCol}\`` : `a.\`${authorNameCol}\``}
+      `,
+    );
+
+    const byBookId = new Map<string, SourceContributor[]>();
+    for (const row of rows) {
+      const bookId = asString(row.bookId);
+      const name = asString(row.name);
+      if (!bookId || !name) continue;
+      const list = byBookId.get(bookId) ?? [];
+      list.push({
+        sourceContributorId: asString(row.sourceContributorId),
+        name,
+        sortName: asString(row.sortName),
+        description: asString(row.description),
+        displayOrder: asInteger(row.displayOrder) ?? list.length,
+      });
+      byBookId.set(bookId, list);
+    }
+
+    for (const book of books) {
+      const authors = byBookId.get(book.sourceBookId);
+      if (!authors) continue;
+      book.authors = authors.sort((a, b) => a.displayOrder - b.displayOrder);
+      book.author = book.authors.map((author) => author.name).join('; ');
+    }
+  }
+
+  private async fetchUserBookStatuses(conn: mysql.Connection, progressTable: string | null): Promise<SourceUserBookStatus[]> {
+    if (!progressTable) return [];
+
+    const cols = await this.connector.listColumns(conn, progressTable);
+    const userCol = firstColumn(cols, ['user_id', 'userid']);
+    const bookCol = firstColumn(cols, ['book_id', 'bookid']);
+    if (!userCol || !bookCol) return [];
+
+    const statusCol = firstColumn(cols, ['status', 'read_status']);
+    const pctCol = firstColumn(cols, [
+      'percentage',
+      'progress_percent',
+      'progress',
+      'percent_complete',
+      'epub_progress',
+      'pdf_progress',
+      'cbx_progress',
+      'koreader_progress',
+    ]);
+    const startedAtCol = firstColumn(cols, ['started_at', 'start_date', 'date_started']);
+    const finishedAtCol = firstColumn(cols, ['finished_at', 'finish_date', 'completed_at', 'date_finished']);
+    const updatedAtCol = firstColumn(cols, ['updated_at', 'modified_at', 'last_read_at', 'last_read_time']);
+
+    const sqlText = `
+      SELECT
+        CAST(p.\`${userCol}\` AS CHAR) AS sourceUserId,
+        CAST(p.\`${bookCol}\` AS CHAR) AS sourceBookId,
+        ${sqlString('p', statusCol, 'status')},
+        ${sqlNumber('p', pctCol, 'percentage')},
+        ${sqlDate('p', startedAtCol, 'startedAt')},
+        ${sqlDate('p', finishedAtCol, 'finishedAt')},
+        ${sqlDate('p', updatedAtCol, 'updatedAt')}
+      FROM \`${progressTable}\` p
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+
+    return rows
+      .map((row) => ({
+        sourceUserId: asString(row.sourceUserId) ?? '',
+        sourceBookId: asString(row.sourceBookId) ?? '',
+        status: asString(row.status),
+        percentage: asNumber(row.percentage),
+        startedAt: toIso(row.startedAt),
+        finishedAt: toIso(row.finishedAt),
+        updatedAt: toIso(row.updatedAt),
+      }))
+      .filter((row) => !!row.sourceUserId && !!row.sourceBookId);
+  }
+
+  private async fetchUserFileProgress(
+    conn: mysql.Connection,
+    progressTable: string | null,
+    bookFileTable: string | null,
+  ): Promise<SourceUserFileProgress[]> {
+    if (!progressTable) return [];
+
+    const cols = await this.connector.listColumns(conn, progressTable);
+    const userCol = firstColumn(cols, ['user_id', 'userid']);
+    if (!userCol) return [];
+
+    const directBookCol = firstColumn(cols, ['book_id', 'bookid']);
+    const bookFileIdCol = firstColumn(cols, ['book_file_id', 'bookfile_id', 'file_id']);
+
+    let joinSql = '';
+    let sourceBookExpr = directBookCol ? `CAST(p.\`${directBookCol}\` AS CHAR)` : 'NULL';
+    const sourceFileExpr = bookFileIdCol ? `CAST(p.\`${bookFileIdCol}\` AS CHAR)` : 'NULL';
+
+    if (!directBookCol && bookFileIdCol && bookFileTable) {
+      const fileCols = await this.connector.listColumns(conn, bookFileTable);
+      const fileIdCol = firstColumn(fileCols, ['id', 'book_file_id']);
+      const fileBookIdCol = firstColumn(fileCols, ['book_id', 'bookid']);
+      if (fileIdCol && fileBookIdCol) {
+        joinSql = `LEFT JOIN \`${bookFileTable}\` f ON f.\`${fileIdCol}\` = p.\`${bookFileIdCol}\``;
+        sourceBookExpr = `CAST(f.\`${fileBookIdCol}\` AS CHAR)`;
+      }
+    }
+
+    const pctCol = firstColumn(cols, ['percentage', 'progress_percent', 'progress', 'percent_complete']);
+    const cfiCol = firstColumn(cols, ['cfi', 'location', 'position_data', 'tts_position_cfi']);
+    const hrefCol = firstColumn(cols, ['position_href', 'href']);
+    const pageCol = firstColumn(cols, ['page_number', 'page', 'page_index']);
+    const positionCol = firstColumn(cols, ['position_seconds', 'position_ms', 'position']);
+    const updatedAtCol = firstColumn(cols, ['updated_at', 'modified_at', 'last_read_at', 'last_read_time']);
+
+    const sqlText = `
+      SELECT
+        CAST(p.\`${userCol}\` AS CHAR) AS sourceUserId,
+        ${sourceBookExpr} AS sourceBookId,
+        ${sourceFileExpr} AS sourceFileId,
+        ${sqlNumber('p', pctCol, 'percentage')},
+        ${sqlString('p', cfiCol, 'cfi')},
+        ${sqlString('p', hrefCol, 'href')},
+        ${sqlNumber('p', pageCol, 'pageNumber')},
+        ${sqlNumber('p', positionCol, 'positionSeconds')},
+        ${sqlDate('p', updatedAtCol, 'updatedAt')}
+      FROM \`${progressTable}\` p
+      ${joinSql}
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+
+    return rows
+      .map((row) => ({
+        sourceUserId: asString(row.sourceUserId) ?? '',
+        sourceBookId: asString(row.sourceBookId) ?? '',
+        sourceFileId: asString(row.sourceFileId),
+        percentage: asNumber(row.percentage),
+        cfi: asString(row.cfi),
+        href: asString(row.href),
+        pageNumber: asInteger(row.pageNumber),
+        positionSeconds: positionCol === 'position_ms' ? millisecondsToSeconds(asNumber(row.positionSeconds)) : asNumber(row.positionSeconds),
+        updatedAt: toIso(row.updatedAt),
+      }))
+      .filter((row) => !!row.sourceUserId && !!row.sourceBookId);
+  }
+
+  private async fetchBookmarks(conn: mysql.Connection, bookmarkTable: string | null): Promise<SourceBookmark[]> {
+    if (!bookmarkTable) return [];
+
+    const cols = await this.connector.listColumns(conn, bookmarkTable);
+    const userCol = firstColumn(cols, ['user_id', 'userid']);
+    const bookCol = firstColumn(cols, ['book_id', 'bookid']);
+    if (!userCol || !bookCol) return [];
+
+    const bookFileCol = firstColumn(cols, ['book_file_id', 'bookfile_id', 'file_id']);
+    const titleCol = firstColumn(cols, ['title', 'name']);
+    const cfiCol = firstColumn(cols, ['cfi', 'location']);
+    const posCol = firstColumn(cols, ['position_seconds', 'position_ms', 'position']);
+    const trackIndexCol = firstColumn(cols, ['track_index', 'track']);
+    const createdAtCol = firstColumn(cols, ['created_at', 'createdat']);
+
+    const sqlText = `
+      SELECT
+        CAST(b.\`${userCol}\` AS CHAR) AS sourceUserId,
+        CAST(b.\`${bookCol}\` AS CHAR) AS sourceBookId,
+        ${bookFileCol ? `CAST(b.\`${bookFileCol}\` AS CHAR)` : 'NULL'} AS sourceFileId,
+        ${sqlString('b', titleCol, 'title')},
+        ${sqlString('b', cfiCol, 'cfi')},
+        ${sqlNumber('b', posCol, 'positionSeconds')},
+        ${sqlNumber('b', trackIndexCol, 'trackIndex')},
+        ${sqlDate('b', createdAtCol, 'createdAt')}
+      FROM \`${bookmarkTable}\` b
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+
+    return rows
+      .map((row) => ({
+        sourceUserId: asString(row.sourceUserId) ?? '',
+        sourceBookId: asString(row.sourceBookId) ?? '',
+        sourceFileId: asString(row.sourceFileId),
+        title: asString(row.title),
+        cfi: asString(row.cfi),
+        positionSeconds: posCol === 'position_ms' ? millisecondsToSeconds(asNumber(row.positionSeconds)) : asNumber(row.positionSeconds),
+        trackIndex: asInteger(row.trackIndex),
+        createdAt: toIso(row.createdAt),
+      }))
+      .filter((row) => !!row.sourceUserId && !!row.sourceBookId);
+  }
+
+  private async fetchAnnotations(conn: mysql.Connection, annotationsTable: string | null): Promise<SourceAnnotation[]> {
+    if (!annotationsTable) return [];
+
+    const cols = await this.connector.listColumns(conn, annotationsTable);
+    const userCol = firstColumn(cols, ['user_id', 'userid']);
+    const bookCol = firstColumn(cols, ['book_id', 'bookid']);
+    const cfiCol = firstColumn(cols, ['cfi', 'location']);
+    const textCol = firstColumn(cols, ['text', 'highlight_text', 'value']);
+
+    if (!userCol || !bookCol || !cfiCol || !textCol) return [];
+
+    const colorCol = firstColumn(cols, ['color']);
+    const styleCol = firstColumn(cols, ['style', 'type']);
+    const noteCol = firstColumn(cols, ['note', 'comment']);
+    const chapterTitleCol = firstColumn(cols, ['chapter_title', 'chapter']);
+    const createdAtCol = firstColumn(cols, ['created_at', 'createdat']);
+    const updatedAtCol = firstColumn(cols, ['updated_at', 'updatedat']);
+
+    const sqlText = `
+      SELECT
+        CAST(a.\`${userCol}\` AS CHAR) AS sourceUserId,
+        CAST(a.\`${bookCol}\` AS CHAR) AS sourceBookId,
+        CAST(a.\`${cfiCol}\` AS CHAR) AS cfi,
+        CAST(a.\`${textCol}\` AS CHAR) AS text,
+        ${sqlString('a', colorCol, 'color')},
+        ${sqlString('a', styleCol, 'style')},
+        ${sqlString('a', noteCol, 'note')},
+        ${sqlString('a', chapterTitleCol, 'chapterTitle')},
+        ${sqlDate('a', createdAtCol, 'createdAt')},
+        ${sqlDate('a', updatedAtCol, 'updatedAt')}
+      FROM \`${annotationsTable}\` a
+    `;
+
+    const rows = await this.connector.queryRows(conn, sqlText);
+
+    return rows
+      .map((row) => ({
+        sourceUserId: asString(row.sourceUserId) ?? '',
+        sourceBookId: asString(row.sourceBookId) ?? '',
+        cfi: asString(row.cfi) ?? '',
+        text: asString(row.text) ?? '',
+        color: asString(row.color),
+        style: asString(row.style),
+        note: asString(row.note),
+        chapterTitle: asString(row.chapterTitle),
+        createdAt: toIso(row.createdAt),
+        updatedAt: toIso(row.updatedAt),
+      }))
+      .filter((row) => !!row.sourceUserId && !!row.sourceBookId && !!row.cfi && !!row.text);
+  }
+
+  private async fetchShelves(
+    conn: mysql.Connection,
+    shelvesTable: string | null,
+    shelfBooksTable: string | null,
+    bookTable: string | null,
+  ): Promise<{ shelves: SourceShelf[]; shelfBooks: SourceShelfBook[] }> {
+    if (!shelvesTable || !shelfBooksTable) return { shelves: [], shelfBooks: [] };
+
+    const shelfCols = await this.connector.listColumns(conn, shelvesTable);
+    const shelfIdCol = firstColumn(shelfCols, ['id', 'shelf_id']);
+    const shelfUserCol = firstColumn(shelfCols, ['user_id', 'userid']);
+    const shelfNameCol = firstColumn(shelfCols, ['name', 'title']);
+
+    if (!shelfIdCol || !shelfUserCol || !shelfNameCol) return { shelves: [], shelfBooks: [] };
+
+    const shelvesRows = await this.connector.queryRows(
+      conn,
+      `
+      SELECT
+        CAST(s.\`${shelfIdCol}\` AS CHAR) AS sourceShelfId,
+        CAST(s.\`${shelfUserCol}\` AS CHAR) AS sourceUserId,
+        CAST(s.\`${shelfNameCol}\` AS CHAR) AS name
+      FROM \`${shelvesTable}\` s
+      `,
+    );
+
+    const shelves = shelvesRows
+      .map((row) => ({
+        sourceShelfId: asString(row.sourceShelfId) ?? '',
+        sourceUserId: asString(row.sourceUserId) ?? '',
+        name: asString(row.name) ?? 'Untitled Shelf',
+      }))
+      .filter((row) => !!row.sourceShelfId && !!row.sourceUserId);
+
+    const mapCols = await this.connector.listColumns(conn, shelfBooksTable);
+    const mapShelfIdCol = firstColumn(mapCols, ['shelf_id']);
+    const mapBookIdCol = firstColumn(mapCols, ['book_id']);
+
+    if (!mapShelfIdCol || !mapBookIdCol) {
+      return {
+        shelves,
+        shelfBooks: [],
+      };
+    }
+
+    const bookCols = bookTable ? await this.connector.listColumns(conn, bookTable) : null;
+    const bookIdCol = bookCols ? firstColumn(bookCols, ['id', 'book_id']) : null;
+    const mappingJoins = [`INNER JOIN \`${shelvesTable}\` s ON s.\`${shelfIdCol}\` = m.\`${mapShelfIdCol}\``];
+    if (bookTable && bookIdCol) {
+      mappingJoins.push(`INNER JOIN \`${bookTable}\` b ON b.\`${bookIdCol}\` = m.\`${mapBookIdCol}\``);
+    }
+
+    const shelfBookRows = await this.connector.queryRows(
+      conn,
+      `
+      SELECT DISTINCT
+        CAST(m.\`${mapShelfIdCol}\` AS CHAR) AS sourceShelfId,
+        CAST(s.\`${shelfUserCol}\` AS CHAR) AS sourceUserId,
+        CAST(m.\`${mapBookIdCol}\` AS CHAR) AS sourceBookId
+      FROM \`${shelfBooksTable}\` m
+      ${mappingJoins.join('\n')}
+      ORDER BY m.\`${mapShelfIdCol}\`, m.\`${mapBookIdCol}\`
+      `,
+    );
+
+    return {
+      shelves,
+      shelfBooks: shelfBookRows
+        .map((row) => ({
+          sourceShelfId: asString(row.sourceShelfId) ?? '',
+          sourceUserId: asString(row.sourceUserId) ?? '',
+          sourceBookId: asString(row.sourceBookId) ?? '',
+        }))
+        .filter((row) => !!row.sourceShelfId && !!row.sourceUserId && !!row.sourceBookId),
+    };
+  }
+  private async attachCategoriesToBooks(
+    conn: mysql.Connection,
+    books: SourceBook[],
+    categoryTable: string | null,
+    mappingTable: string | null,
+  ): Promise<void> {
+    if (!categoryTable || !mappingTable) return;
+
+    const mappingCols = await this.connector.listColumns(conn, mappingTable);
+    const mapBookIdCol = firstColumn(mappingCols, ['book_id', 'bookid']);
+    const mapCategoryIdCol = firstColumn(mappingCols, ['category_id', 'genre_id']);
+    if (!mapBookIdCol || !mapCategoryIdCol) return;
+
+    const categoryCols = await this.connector.listColumns(conn, categoryTable);
+    const categoryIdCol = firstColumn(categoryCols, ['id']);
+    const categoryNameCol = firstColumn(categoryCols, ['name']);
+    if (!categoryIdCol || !categoryNameCol) return;
+
+    const rows = await this.connector.queryRows(
+      conn,
+      `SELECT CAST(m.\`${mapBookIdCol}\` AS CHAR) AS bookId, CAST(c.\`${categoryNameCol}\` AS CHAR) AS name
+       FROM \`${mappingTable}\` m
+       JOIN \`${categoryTable}\` c ON c.\`${categoryIdCol}\` = m.\`${mapCategoryIdCol}\``,
+    );
+
+    const byBookId = new Map<string, string[]>();
+    for (const row of rows) {
+      const bookId = asString(row.bookId);
+      const name = asString(row.name);
+      if (!bookId || !name) continue;
+      const existing = byBookId.get(bookId);
+      if (existing) {
+        existing.push(name);
+      } else {
+        byBookId.set(bookId, [name]);
+      }
+    }
+
+    for (const book of books) {
+      book.genres = byBookId.get(book.sourceBookId) ?? [];
+    }
+  }
+
+  private async attachTagsToBooks(conn: mysql.Connection, books: SourceBook[], tagTable: string | null, mappingTable: string | null): Promise<void> {
+    if (!tagTable || !mappingTable) return;
+
+    const mappingCols = await this.connector.listColumns(conn, mappingTable);
+    const mapBookIdCol = firstColumn(mappingCols, ['book_id', 'bookid']);
+    const mapTagIdCol = firstColumn(mappingCols, ['tag_id']);
+    if (!mapBookIdCol || !mapTagIdCol) return;
+
+    const tagCols = await this.connector.listColumns(conn, tagTable);
+    const tagIdCol = firstColumn(tagCols, ['id']);
+    const tagNameCol = firstColumn(tagCols, ['name']);
+    if (!tagIdCol || !tagNameCol) return;
+
+    const rows = await this.connector.queryRows(
+      conn,
+      `SELECT CAST(m.\`${mapBookIdCol}\` AS CHAR) AS bookId, CAST(t.\`${tagNameCol}\` AS CHAR) AS name
+       FROM \`${mappingTable}\` m
+       JOIN \`${tagTable}\` t ON t.\`${tagIdCol}\` = m.\`${mapTagIdCol}\``,
+    );
+
+    const byBookId = new Map<string, string[]>();
+    for (const row of rows) {
+      const bookId = asString(row.bookId);
+      const name = asString(row.name);
+      if (!bookId || !name) continue;
+      const existing = byBookId.get(bookId);
+      if (existing) {
+        existing.push(name);
+      } else {
+        byBookId.set(bookId, [name]);
+      }
+    }
+
+    for (const book of books) {
+      book.tags = byBookId.get(book.sourceBookId) ?? [];
+    }
+  }
+}
+
+function resolveTables(tables: Set<string>): TableResolution {
+  return {
+    users: resolveTable(tables, TABLE_CANDIDATES.users),
+    book: resolveTable(tables, TABLE_CANDIDATES.book),
+    bookFile: resolveTable(tables, TABLE_CANDIDATES.bookFile),
+    bookMetadata: resolveTable(tables, TABLE_CANDIDATES.bookMetadata),
+    libraryPath: resolveTable(tables, TABLE_CANDIDATES.libraryPath),
+    authors: resolveTable(tables, TABLE_CANDIDATES.authors),
+    authorMapping: resolveTable(tables, TABLE_CANDIDATES.authorMapping),
+    userBookProgress: resolveTable(tables, TABLE_CANDIDATES.userBookProgress),
+    userBookFileProgress: resolveTable(tables, TABLE_CANDIDATES.userBookFileProgress),
+    bookmarks: resolveTable(tables, TABLE_CANDIDATES.bookmarks),
+    annotations: resolveTable(tables, TABLE_CANDIDATES.annotations),
+    pdfAnnotations: resolveTable(tables, TABLE_CANDIDATES.pdfAnnotations),
+    shelves: resolveTable(tables, TABLE_CANDIDATES.shelves),
+    shelfBooks: resolveTable(tables, TABLE_CANDIDATES.shelfBooks),
+    categories: resolveTable(tables, TABLE_CANDIDATES.categories),
+    categoryMapping: resolveTable(tables, TABLE_CANDIDATES.categoryMapping),
+    tags: resolveTable(tables, TABLE_CANDIDATES.tags),
+    tagMapping: resolveTable(tables, TABLE_CANDIDATES.tagMapping),
+    bookNotes: resolveTable(tables, TABLE_CANDIDATES.bookNotes),
+    bookNotesV2: resolveTable(tables, TABLE_CANDIDATES.bookNotesV2),
+    epubViewerPreference: resolveTable(tables, TABLE_CANDIDATES.epubViewerPreference),
+    pdfViewerPreference: resolveTable(tables, TABLE_CANDIDATES.pdfViewerPreference),
+    cbxViewerPreference: resolveTable(tables, TABLE_CANDIDATES.cbxViewerPreference),
+    newPdfViewerPreference: resolveTable(tables, TABLE_CANDIDATES.newPdfViewerPreference),
+    koboUserSettings: resolveTable(tables, TABLE_CANDIDATES.koboUserSettings),
+    koboReadingState: resolveTable(tables, TABLE_CANDIDATES.koboReadingState),
+    comicMetadata: resolveTable(tables, TABLE_CANDIDATES.comicMetadata),
+  };
+}
+
+function resolveTable(tables: Set<string>, candidates: readonly string[]): string | null {
+  for (const candidate of candidates) {
+    if (tables.has(candidate.toLowerCase())) return candidate;
+  }
+  return null;
+}
+
+function requiredColumn(columns: Set<string>, candidates: string[]): string {
+  const found = firstColumn(columns, candidates);
+  if (!found) {
+    throw new Error(`Missing required column, expected one of: ${candidates.join(', ')}`);
+  }
+  return found;
+}
+
+function firstColumn(columns: Set<string>, candidates: string[]): string | null {
+  for (const candidate of candidates) {
+    if (columns.has(candidate.toLowerCase())) return candidate;
+  }
+  return null;
+}
+
+function sqlString(alias: string, column: string | null, outName: string): string {
+  if (!column) return `NULL AS ${outName}`;
+  return `CAST(${alias}.\`${column}\` AS CHAR) AS ${outName}`;
+}
+
+function sqlNumber(alias: string, column: string | null, outName: string): string {
+  if (!column) return `NULL AS ${outName}`;
+  return `${alias}.\`${column}\` AS ${outName}`;
+}
+
+function sqlDate(alias: string, column: string | null, outName: string): string {
+  if (!column) return `NULL AS ${outName}`;
+  return `${alias}.\`${column}\` AS ${outName}`;
+}
+
+function buildSourceFilePath(input: {
+  directPath: string | null;
+  libraryRootPath: string | null;
+  fileSubPath: string | null;
+  fileName: string | null;
+}): string | null {
+  if (input.directPath) return normalizeJoinedPath(input.directPath);
+  if (!input.libraryRootPath || !input.fileName) return null;
+  return normalizeJoinedPath([input.libraryRootPath, input.fileSubPath, input.fileName].filter((part): part is string => !!part).join('/'));
+}
+
+function normalizeJoinedPath(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return trimmed;
+  return trimmed.replace(/\/{2,}/g, '/');
+}
+
+function parseContributorNames(value: string | null): SourceContributor[] {
+  if (!value) return [];
+  const parsed = parseJsonStringArray(value);
+  const rawNames = parsed ?? value.split(/\s*(?:;|\|)\s*/);
+  const seen = new Set<string>();
+  const contributors: SourceContributor[] = [];
+  for (const rawName of rawNames) {
+    const name = rawName.trim();
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    contributors.push({
+      sourceContributorId: null,
+      name,
+      sortName: null,
+      description: null,
+      displayOrder: contributors.length,
+    });
+  }
+  return contributors;
+}
+
+function parseJsonStringArray(value: string): string[] | null {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!Array.isArray(parsed)) return null;
+    const strings = parsed.filter((item): item is string => typeof item === 'string');
+    return strings.length > 0 ? strings : null;
+  } catch {
+    return null;
+  }
+}
+
+function parsePublishedYear(value: unknown): number | null {
+  const direct = asInteger(value);
+  if (direct != null && direct > 999 && direct < 10_000) return direct;
+  const text = asString(value);
+  if (!text) return null;
+  const match = /\b(\d{4})\b/.exec(text);
+  if (!match) return null;
+  const year = Number(match[1]);
+  return Number.isFinite(year) ? year : null;
+}
+
+function asString(value: unknown): string | null {
+  if (value == null) return null;
+  const str =
+    typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' ? String(value) : null;
+  if (str == null) return null;
+  const trimmed = str.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asNumber(value: unknown): number | null {
+  if (value == null) return null;
+  const num = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(num) ? num : null;
+}
+
+function asInteger(value: unknown): number | null {
+  const num = asNumber(value);
+  if (num == null) return null;
+  return Math.round(num);
+}
+
+function asBoolean(value: unknown): boolean | null {
+  if (value == null) return null;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  if (typeof value === 'bigint') return value !== 0n;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) return null;
+    if (['1', 'true', 'yes', 'y'].includes(normalized)) return true;
+    if (['0', 'false', 'no', 'n'].includes(normalized)) return false;
+  }
+  return null;
+}
+
+function millisecondsToSeconds(value: number | null): number | null {
+  return value == null ? null : value / 1000;
+}
+
+function toIso(value: unknown): string | null {
+  if (!value) return null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint') {
+    const date = new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+  }
+  return null;
+}
diff --git a/server/src/modules/migration/adapters/source-adapter.registry.ts b/server/src/modules/migration/adapters/source-adapter.registry.ts
new file mode 100644
index 000000000..d6ed8a68e
--- /dev/null
+++ b/server/src/modules/migration/adapters/source-adapter.registry.ts
@@ -0,0 +1,27 @@
+import { BadRequestException, Injectable } from '@nestjs/common';
+
+import type { SourceAdapter } from './source-adapter.types';
+import { BookloreSourceAdapter } from './booklore/booklore-source.adapter';
+
+@Injectable()
+export class SourceAdapterRegistry {
+  private readonly adaptersByType: Map<string, SourceAdapter<any>>;
+
+  constructor(bookloreAdapter: BookloreSourceAdapter) {
+    const adapters: SourceAdapter<any>[] = [bookloreAdapter];
+    this.adaptersByType = new Map(adapters.map((adapter) => [adapter.type, adapter]));
+  }
+
+  listTypes(): string[] {
+    return [...this.adaptersByType.keys()].sort();
+  }
+
+  get(type: string): SourceAdapter<any> {
+    const key = type.trim().toLowerCase();
+    const found = this.adaptersByType.get(key);
+    if (!found) {
+      throw new BadRequestException(`Unsupported migration source type: ${type}`);
+    }
+    return found;
+  }
+}
diff --git a/server/src/modules/migration/adapters/source-adapter.types.ts b/server/src/modules/migration/adapters/source-adapter.types.ts
new file mode 100644
index 000000000..1395e107a
--- /dev/null
+++ b/server/src/modules/migration/adapters/source-adapter.types.ts
@@ -0,0 +1,158 @@
+export interface SourceValidationResult {
+  ok: boolean;
+  sourceType: string;
+  sourceVersion: string | null;
+  missingTables: string[];
+  warnings: string[];
+  counts: Record<string, number>;
+}
+
+export interface SourceSnapshot {
+  generatedAt: string;
+  sourceType: string;
+  sourceVersion: string | null;
+  counts: Record<string, number>;
+}
+
+export interface SourceUser {
+  sourceUserId: string;
+  username: string;
+  name: string | null;
+  email: string | null;
+}
+
+export interface SourceContributor {
+  sourceContributorId: string | null;
+  name: string;
+  sortName: string | null;
+  description: string | null;
+  displayOrder: number;
+}
+
+export interface SourceBookFile {
+  sourceFileId: string;
+  sourceBookId: string;
+  filePath: string | null;
+  fileHash: string | null;
+  fileName: string | null;
+  fileSubPath: string | null;
+  durationSeconds: number | null;
+}
+
+export interface SourceBook {
+  sourceBookId: string;
+  title: string | null;
+  /**
+   * Legacy display value retained for existing matching/report code. New code
+   * should prefer the structured authors array.
+   */
+  author: string | null;
+  subtitle: string | null;
+  isbn10: string | null;
+  isbn13: string | null;
+  description: string | null;
+  publisher: string | null;
+  publishedYear: number | null;
+  language: string | null;
+  pageCount?: number | null;
+  seriesName?: string | null;
+  seriesIndex?: number | null;
+  rating?: number | null;
+  googleBooksId?: string | null;
+  goodreadsId?: string | null;
+  amazonId?: string | null;
+  hardcoverId?: string | null;
+  audibleId?: string | null;
+  comicvineId?: string | null;
+  durationSeconds?: number | null;
+  abridged?: boolean | null;
+  authors?: SourceContributor[];
+  narrators?: SourceContributor[];
+  filePath: string | null;
+  fileHash: string | null;
+  files?: SourceBookFile[];
+  genres: string[];
+  tags: string[];
+  presentFields?: string[];
+}
+
+export interface SourceUserBookStatus {
+  sourceUserId: string;
+  sourceBookId: string;
+  status: string | null;
+  percentage: number | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  updatedAt: string | null;
+}
+
+export interface SourceUserFileProgress {
+  sourceUserId: string;
+  sourceBookId: string;
+  sourceFileId?: string | null;
+  percentage: number | null;
+  cfi: string | null;
+  href?: string | null;
+  pageNumber: number | null;
+  positionSeconds: number | null;
+  updatedAt: string | null;
+}
+
+export interface SourceBookmark {
+  sourceUserId: string;
+  sourceBookId: string;
+  sourceFileId?: string | null;
+  title: string | null;
+  cfi: string | null;
+  positionSeconds: number | null;
+  trackIndex?: number | null;
+  createdAt: string | null;
+}
+
+export interface SourceAnnotation {
+  sourceUserId: string;
+  sourceBookId: string;
+  cfi: string;
+  text: string;
+  color: string | null;
+  style: string | null;
+  note: string | null;
+  chapterTitle: string | null;
+  createdAt: string | null;
+  updatedAt: string | null;
+}
+
+export interface SourceShelf {
+  sourceShelfId: string;
+  sourceUserId: string;
+  name: string;
+}
+
+export interface SourceShelfBook {
+  sourceShelfId: string;
+  sourceUserId: string;
+  sourceBookId: string;
+}
+
+export interface SourceExportData {
+  users: SourceUser[];
+  books: SourceBook[];
+  userBookStatuses: SourceUserBookStatus[];
+  userFileProgress: SourceUserFileProgress[];
+  bookmarks: SourceBookmark[];
+  annotations: SourceAnnotation[];
+  shelves: SourceShelf[];
+  shelfBooks: SourceShelfBook[];
+}
+
+export interface SourceAdapter<TConnectionConfig = unknown> {
+  readonly type: string;
+
+  validate(config: TConnectionConfig): Promise<SourceValidationResult>;
+
+  snapshot(config: TConnectionConfig): Promise<SourceSnapshot>;
+
+  exportData(config: TConnectionConfig): Promise<SourceExportData>;
+
+  fetchPathPrefixes?(config: TConnectionConfig): Promise<string[]>;
+}
diff --git a/server/src/modules/migration/core/hash.test.ts b/server/src/modules/migration/core/hash.test.ts
new file mode 100644
index 000000000..7a642768f
--- /dev/null
+++ b/server/src/modules/migration/core/hash.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { sha256Hex, stableJsonStringify } from './hash';
+
+describe('migration hash helpers', () => {
+  it('stableJsonStringify sorts object keys recursively', () => {
+    const left = stableJsonStringify({ b: 1, a: { d: 2, c: 3 } });
+    const right = stableJsonStringify({ a: { c: 3, d: 2 }, b: 1 });
+    expect(left).toBe(right);
+  });
+
+  it('sha256Hex returns the same hash for semantically identical objects', () => {
+    const left = sha256Hex({ z: [2, 1], a: { y: true, x: false } });
+    const right = sha256Hex({ a: { x: false, y: true }, z: [2, 1] });
+    expect(left).toBe(right);
+  });
+});
diff --git a/server/src/modules/migration/core/hash.ts b/server/src/modules/migration/core/hash.ts
new file mode 100644
index 000000000..5bbf814b1
--- /dev/null
+++ b/server/src/modules/migration/core/hash.ts
@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+
+function normalizeJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(normalizeJson);
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return Object.fromEntries(entries.map(([key, val]) => [key, normalizeJson(val)]));
+  }
+  return value;
+}
+
+export function stableJsonStringify(value: unknown): string {
+  return JSON.stringify(normalizeJson(value));
+}
+
+export function sha256Hex(value: unknown): string {
+  return createHash('sha256').update(stableJsonStringify(value)).digest('hex');
+}
diff --git a/server/src/modules/migration/core/plan-hash.test.ts b/server/src/modules/migration/core/plan-hash.test.ts
new file mode 100644
index 000000000..ee29f5ed9
--- /dev/null
+++ b/server/src/modules/migration/core/plan-hash.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildPlanHash, buildSourceSnapshotHash } from './plan-hash';
+
+describe('buildPlanHash', () => {
+  it('ignores volatile generatedAt fields in plan hashing', () => {
+    const sourceSnapshotHash = 'snapshot-hash';
+    const profileHash = 'profile-hash';
+
+    const left = buildPlanHash({
+      sourceSnapshotHash,
+      profileHash,
+      plan: {
+        generatedAt: '2026-01-01T00:00:00.000Z',
+        snapshot: {
+          generatedAt: '2026-01-01T00:00:00.000Z',
+          counts: { books: 1 },
+        },
+        matchedBooks: [{ sourceBookId: 's1', targetBookId: 10, strategy: 'isbn' }],
+      },
+    });
+
+    const right = buildPlanHash({
+      sourceSnapshotHash,
+      profileHash,
+      plan: {
+        generatedAt: '2030-01-01T00:00:00.000Z',
+        snapshot: {
+          generatedAt: '2030-01-01T00:00:00.000Z',
+          counts: { books: 1 },
+        },
+        matchedBooks: [{ sourceBookId: 's1', targetBookId: 10, strategy: 'isbn' }],
+      },
+    });
+
+    expect(left).toBe(right);
+  });
+});
+
+describe('buildSourceSnapshotHash', () => {
+  it('ignores generatedAt in source snapshot hashing', () => {
+    const left = buildSourceSnapshotHash({
+      generatedAt: '2026-01-01T00:00:00.000Z',
+      sourceType: 'booklore',
+      counts: { books: 10 },
+    });
+
+    const right = buildSourceSnapshotHash({
+      generatedAt: '2030-01-01T00:00:00.000Z',
+      sourceType: 'booklore',
+      counts: { books: 10 },
+    });
+
+    expect(left).toBe(right);
+  });
+});
diff --git a/server/src/modules/migration/core/plan-hash.ts b/server/src/modules/migration/core/plan-hash.ts
new file mode 100644
index 000000000..6ed0ac956
--- /dev/null
+++ b/server/src/modules/migration/core/plan-hash.ts
@@ -0,0 +1,46 @@
+import type { MigrationProfile } from '../../../db/schema';
+import { sha256Hex } from './hash';
+
+export function buildProfileHash(profile: MigrationProfile): string {
+  return sha256Hex({
+    sourceId: profile.sourceId,
+    version: profile.version,
+    userMappings: profile.userMappings,
+    pathMappings: profile.pathMappings,
+    scope: profile.scope,
+  });
+}
+
+export function buildPlanHash(args: { sourceSnapshotHash: string; profileHash: string; plan: unknown }): string {
+  return sha256Hex({
+    sourceSnapshotHash: args.sourceSnapshotHash,
+    profileHash: args.profileHash,
+    plan: sanitizePlanForHash(args.plan),
+  });
+}
+
+export function buildSourceSnapshotHash(snapshot: unknown): string {
+  if (!isRecord(snapshot)) return sha256Hex(snapshot);
+  const sanitized = { ...snapshot };
+  delete sanitized.generatedAt;
+  return sha256Hex(sanitized);
+}
+
+function sanitizePlanForHash(plan: unknown): unknown {
+  if (!isRecord(plan)) return plan;
+
+  const sanitized: Record<string, unknown> = { ...plan };
+  delete sanitized.generatedAt;
+
+  if (isRecord(sanitized.snapshot)) {
+    const snapshot = { ...sanitized.snapshot };
+    delete snapshot.generatedAt;
+    sanitized.snapshot = snapshot;
+  }
+
+  return sanitized;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
diff --git a/server/src/modules/migration/dto/create-dry-run-plan.dto.ts b/server/src/modules/migration/dto/create-dry-run-plan.dto.ts
new file mode 100644
index 000000000..b2030cecf
--- /dev/null
+++ b/server/src/modules/migration/dto/create-dry-run-plan.dto.ts
@@ -0,0 +1,13 @@
+import { Type } from 'class-transformer';
+import { IsInt, IsObject, IsOptional, Min } from 'class-validator';
+
+export class CreateDryRunPlanDto {
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  profileId!: number;
+
+  @IsOptional()
+  @IsObject()
+  scopeOverride?: Record<string, unknown>;
+}
diff --git a/server/src/modules/migration/dto/create-migration-profile.dto.ts b/server/src/modules/migration/dto/create-migration-profile.dto.ts
new file mode 100644
index 000000000..2dcb4b666
--- /dev/null
+++ b/server/src/modules/migration/dto/create-migration-profile.dto.ts
@@ -0,0 +1,53 @@
+import { Type } from 'class-transformer';
+import { IsArray, IsInt, IsNotEmpty, IsObject, IsOptional, IsString, MaxLength, Min, ValidateNested } from 'class-validator';
+
+class UserMappingDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  sourceUserId!: string;
+
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  targetUserId!: number;
+}
+
+class PathMappingDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(1024)
+  sourcePrefix!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(1024)
+  targetPrefix!: string;
+}
+
+export class CreateMigrationProfileDto {
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  sourceId!: number;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  name!: string;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => UserMappingDto)
+  userMappings!: UserMappingDto[];
+
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => PathMappingDto)
+  pathMappings?: PathMappingDto[];
+
+  @IsOptional()
+  @IsObject()
+  scope?: Record<string, unknown>;
+}
diff --git a/server/src/modules/migration/dto/create-migration-source.dto.ts b/server/src/modules/migration/dto/create-migration-source.dto.ts
new file mode 100644
index 000000000..b91cfc3b8
--- /dev/null
+++ b/server/src/modules/migration/dto/create-migration-source.dto.ts
@@ -0,0 +1,16 @@
+import { IsNotEmpty, IsObject, IsString, MaxLength } from 'class-validator';
+
+export class CreateMigrationSourceDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(50)
+  type!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  name!: string;
+
+  @IsObject()
+  connectionConfig!: Record<string, unknown>;
+}
diff --git a/server/src/modules/migration/dto/start-live-run.dto.ts b/server/src/modules/migration/dto/start-live-run.dto.ts
new file mode 100644
index 000000000..05d77d840
--- /dev/null
+++ b/server/src/modules/migration/dto/start-live-run.dto.ts
@@ -0,0 +1,14 @@
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, IsString, MaxLength, Min } from 'class-validator';
+
+export class StartLiveRunDto {
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  planArtifactId!: number;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  targetKey?: string;
+}
diff --git a/server/src/modules/migration/dto/test-migration-source.dto.ts b/server/src/modules/migration/dto/test-migration-source.dto.ts
new file mode 100644
index 000000000..f852662af
--- /dev/null
+++ b/server/src/modules/migration/dto/test-migration-source.dto.ts
@@ -0,0 +1,11 @@
+import { IsNotEmpty, IsObject, IsString, MaxLength } from 'class-validator';
+
+export class TestMigrationSourceDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(50)
+  type!: string;
+
+  @IsObject()
+  connectionConfig!: Record<string, unknown>;
+}
diff --git a/server/src/modules/migration/dto/validate-path-mappings.dto.ts b/server/src/modules/migration/dto/validate-path-mappings.dto.ts
new file mode 100644
index 000000000..1d40c3e0e
--- /dev/null
+++ b/server/src/modules/migration/dto/validate-path-mappings.dto.ts
@@ -0,0 +1,28 @@
+import { Type } from 'class-transformer';
+import { IsArray, IsInt, IsNotEmpty, IsOptional, IsString, Max, MaxLength, Min, ValidateNested } from 'class-validator';
+
+class PathMappingInputDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(1024)
+  sourcePrefix!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(1024)
+  targetPrefix!: string;
+}
+
+export class ValidatePathMappingsDto {
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => PathMappingInputDto)
+  pathMappings!: PathMappingInputDto[];
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  sampleLimit?: number;
+}
diff --git a/server/src/modules/migration/executor/migration-executor.service.test.ts b/server/src/modules/migration/executor/migration-executor.service.test.ts
new file mode 100644
index 000000000..98c57c20e
--- /dev/null
+++ b/server/src/modules/migration/executor/migration-executor.service.test.ts
@@ -0,0 +1,381 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import sharp from 'sharp';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MigrationExecutorService } from './migration-executor.service';
+
+async function createSampleImageBytes(): Promise<Buffer> {
+  return sharp({
+    create: {
+      width: 8,
+      height: 12,
+      channels: 3,
+      background: { r: 40, g: 120, b: 200 },
+    },
+  })
+    .jpeg({ quality: 90 })
+    .toBuffer();
+}
+
+function createDbMock(existingRows: unknown[][] = [[]]) {
+  const limit = vi.fn(() => Promise.resolve(existingRows.shift() ?? []));
+  const where = vi.fn(() => ({ limit }));
+  const from = vi.fn(() => ({ where }));
+  const select = vi.fn(() => ({ from }));
+
+  const onConflictDoUpdate = vi.fn(() => Promise.resolve(undefined));
+  const values = vi.fn(() => ({ onConflictDoUpdate }));
+  const insert = vi.fn(() => ({ values }));
+  const deleteWhere = vi.fn(() => Promise.resolve(undefined));
+  const deleteMock = vi.fn(() => ({ where: deleteWhere }));
+
+  return {
+    db: { select, insert, delete: deleteMock },
+    mocks: { limit, where, from, select, onConflictDoUpdate, values, insert, deleteWhere, deleteMock },
+  };
+}
+
+function createRepoMock() {
+  return {
+    incrementRunMetric: vi.fn(() => Promise.resolve(undefined)),
+  };
+}
+
+describe('MigrationExecutorService audiobook progress import', () => {
+  it('imports only rows mapped to target audio books', async () => {
+    const repo = createRepoMock();
+    const { db, mocks } = createDbMock([[]]);
+    const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue('/tmp/books') } as never);
+
+    const planned = {
+      execution: {
+        sourceData: {
+          userFileProgress: [
+            {
+              sourceUserId: 'u1',
+              sourceBookId: 'source-audio',
+              percentage: 42,
+              cfi: null,
+              pageNumber: null,
+              positionSeconds: 120.5,
+              updatedAt: '2025-01-01T10:00:00.000Z',
+            },
+            {
+              sourceUserId: 'u1',
+              sourceBookId: 'source-ebook',
+              percentage: 65,
+              cfi: 'epubcfi(/6/2)',
+              pageNumber: 23,
+              positionSeconds: 500,
+              updatedAt: '2025-01-01T10:00:00.000Z',
+            },
+          ],
+        },
+      },
+    };
+
+    await (service as any).importAudiobookProgress(
+      77,
+      planned,
+      new Map([['u1', 10]]),
+      new Map([
+        ['source-audio', 101],
+        ['source-ebook', 102],
+      ]),
+      new Map([[101, 1001]]),
+      new Map(),
+      async () => {},
+    );
+
+    expect(mocks.insert).toHaveBeenCalledTimes(1);
+    expect(mocks.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 10,
+        bookId: 101,
+        currentFileId: 1001,
+        percentage: 42,
+        positionSeconds: 120.5,
+      }),
+    );
+    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      77,
+      'user_state',
+      'audiobook_progress',
+      expect.objectContaining({
+        processed: 1,
+        imported: 1,
+        skipped: 0,
+        unresolved: 0,
+        failed: 0,
+      }),
+    );
+  });
+
+  it('overwrites target audiobook progress even when the target is newer', async () => {
+    const repo = createRepoMock();
+    const { db, mocks } = createDbMock([[{ updatedAt: new Date('2025-01-02T00:00:00.000Z') }]]);
+    const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue('/tmp/books') } as never);
+
+    const planned = {
+      execution: {
+        sourceData: {
+          userFileProgress: [
+            {
+              sourceUserId: 'u1',
+              sourceBookId: 'source-audio',
+              percentage: 10,
+              cfi: null,
+              pageNumber: null,
+              positionSeconds: 33,
+              updatedAt: '2025-01-01T00:00:00.000Z',
+            },
+          ],
+        },
+      },
+    };
+
+    await (service as any).importAudiobookProgress(
+      88,
+      planned,
+      new Map([['u1', 10]]),
+      new Map([['source-audio', 101]]),
+      new Map([[101, 1001]]),
+      new Map(),
+      async () => {},
+    );
+
+    expect(mocks.insert).toHaveBeenCalledTimes(1);
+    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      88,
+      'user_state',
+      'audiobook_progress',
+      expect.objectContaining({
+        processed: 1,
+        imported: 1,
+        skipped: 0,
+        unresolved: 0,
+      }),
+    );
+  });
+});
+
+describe('MigrationExecutorService author import', () => {
+  it('replaces target book authors from source author names', async () => {
+    const repo = createRepoMock();
+    const deleteWhere = vi.fn(() => Promise.resolve(undefined));
+    const deleteFrom = vi.fn(() => ({ where: deleteWhere }));
+    const deleteMock = vi.fn(() => ({ where: deleteWhere }));
+
+    const onConflictDoNothing = vi.fn(() => Promise.resolve(undefined));
+    const bookAuthorValues = vi.fn(() => ({ onConflictDoNothing }));
+    const authorReturning = vi
+      .fn()
+      .mockResolvedValueOnce([{ id: 101 }])
+      .mockResolvedValueOnce([{ id: 102 }]);
+    const authorOnConflictDoUpdate = vi.fn(() => ({ returning: authorReturning }));
+    const authorValues = vi.fn(() => ({ onConflictDoUpdate: authorOnConflictDoUpdate }));
+    const insert = vi
+      .fn()
+      .mockReturnValueOnce({ values: authorValues })
+      .mockReturnValueOnce({ values: bookAuthorValues })
+      .mockReturnValueOnce({ values: authorValues })
+      .mockReturnValueOnce({ values: bookAuthorValues });
+
+    const db = { delete: deleteMock, insert };
+    const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue('/tmp/books') } as never);
+
+    const planned = {
+      execution: {
+        matchedBooks: [{ sourceBookId: 'source-1', targetBookId: 901 }],
+        sourceData: {
+          books: [{ sourceBookId: 'source-1', author: 'Ada Lovelace; Grace Hopper' }],
+        },
+      },
+    };
+
+    await (service as any).importAuthors(91, planned);
+
+    expect(deleteMock).toHaveBeenCalledTimes(1);
+    expect(authorValues).toHaveBeenNthCalledWith(1, { name: 'Ada Lovelace', sortName: 'Ada Lovelace' });
+    expect(authorValues).toHaveBeenNthCalledWith(2, { name: 'Grace Hopper', sortName: 'Grace Hopper' });
+    expect(bookAuthorValues).toHaveBeenNthCalledWith(1, { bookId: 901, authorId: 101, displayOrder: 0 });
+    expect(bookAuthorValues).toHaveBeenNthCalledWith(2, { bookId: 901, authorId: 102, displayOrder: 1 });
+    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      91,
+      'shared_overlays',
+      'book_authors',
+      expect.objectContaining({ processed: 1, imported: 2, skipped: 0, unresolved: 0 }),
+    );
+
+    expect(deleteFrom).not.toHaveBeenCalled();
+  });
+});
+
+describe('MigrationExecutorService book cover import', () => {
+  it('copies source cover and thumbnail into target cover directory and marks cover source custom', async () => {
+    const sourceRoot = await mkdtemp(join(tmpdir(), 'migration-source-media-'));
+    const booksPath = await mkdtemp(join(tmpdir(), 'migration-target-books-'));
+    try {
+      const sourceDir = join(sourceRoot, 'images', 'source-1');
+      await mkdir(sourceDir, { recursive: true });
+      const sourceCoverBytes = await createSampleImageBytes();
+      const sourceThumbnailBytes = await createSampleImageBytes();
+      await writeFile(join(sourceDir, 'cover.jpg'), sourceCoverBytes);
+      await writeFile(join(sourceDir, 'thumbnail.jpg'), sourceThumbnailBytes);
+
+      const repo = createRepoMock();
+      const { db, mocks } = createDbMock();
+      const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue(booksPath) } as never);
+
+      const planned = {
+        execution: {
+          matchedBooks: [{ sourceBookId: 'source-1', targetBookId: 901 }],
+        },
+      };
+
+      await (service as any).importBookCovers(52, planned, sourceRoot, async () => {});
+
+      const targetDir = join(booksPath, 'covers', '901');
+      const targetFiles = await readdir(targetDir);
+      const copiedCoverName = targetFiles.find((entry) => entry.startsWith('cover_custom.'));
+      expect(copiedCoverName).toBeTruthy();
+      expect(targetFiles).toContain('thumbnail.jpg');
+
+      const copiedCoverBytes = await readFile(join(targetDir, copiedCoverName!));
+      const copiedThumbnailBytes = await readFile(join(targetDir, 'thumbnail.jpg'));
+      expect(copiedCoverBytes.equals(sourceCoverBytes)).toBe(true);
+      expect(copiedThumbnailBytes.equals(sourceThumbnailBytes)).toBe(true);
+
+      expect(mocks.values).toHaveBeenCalledWith(expect.objectContaining({ bookId: 901, coverSource: 'custom' }));
+      expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+        52,
+        'shared_overlays',
+        'book_covers',
+        expect.objectContaining({ processed: 1, imported: 1, unresolved: 0, failed: 0 }),
+      );
+    } finally {
+      await rm(sourceRoot, { recursive: true, force: true });
+      await rm(booksPath, { recursive: true, force: true });
+    }
+  });
+
+  it('generates target thumbnail when source thumbnail is missing', async () => {
+    const sourceRoot = await mkdtemp(join(tmpdir(), 'migration-source-media-'));
+    const booksPath = await mkdtemp(join(tmpdir(), 'migration-target-books-'));
+    try {
+      const sourceDir = join(sourceRoot, 'images', 'source-2');
+      await mkdir(sourceDir, { recursive: true });
+      await writeFile(join(sourceDir, 'cover.jpg'), await createSampleImageBytes());
+
+      const repo = createRepoMock();
+      const { db } = createDbMock();
+      const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue(booksPath) } as never);
+
+      const planned = {
+        execution: {
+          matchedBooks: [{ sourceBookId: 'source-2', targetBookId: 902 }],
+        },
+      };
+
+      await (service as any).importBookCovers(53, planned, sourceRoot, async () => {});
+
+      const generatedThumbnail = await readFile(join(booksPath, 'covers', '902', 'thumbnail.jpg'));
+      expect(generatedThumbnail.length).toBeGreaterThan(0);
+      expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+        53,
+        'shared_overlays',
+        'book_covers',
+        expect.objectContaining({ processed: 1, imported: 1, unresolved: 0, failed: 0 }),
+      );
+    } finally {
+      await rm(sourceRoot, { recursive: true, force: true });
+      await rm(booksPath, { recursive: true, force: true });
+    }
+  });
+
+  it('skips book cover stage when source media root is not configured', async () => {
+    const repo = createRepoMock();
+    const { db, mocks } = createDbMock();
+    const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue('/tmp/books') } as never);
+
+    const planned = {
+      execution: {
+        matchedBooks: [{ sourceBookId: 'source-3', targetBookId: 903 }],
+      },
+    };
+
+    await (service as any).importBookCovers(54, planned, null, async () => {});
+
+    expect(mocks.insert).not.toHaveBeenCalled();
+    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      54,
+      'shared_overlays',
+      'book_covers',
+      expect.objectContaining({ processed: 1, skipped: 1, imported: 0 }),
+    );
+  });
+});
+
+describe('MigrationExecutorService collection import', () => {
+  it('skips shelf-book rows that do not belong to the shelf owner', async () => {
+    const repo = createRepoMock();
+    const selectWhere = vi.fn(() => Promise.resolve([]));
+    const selectFrom = vi.fn(() => ({ where: selectWhere }));
+    const select = vi.fn(() => ({ from: selectFrom }));
+
+    const collectionReturning = vi.fn().mockResolvedValue([{ id: 701 }]);
+    const collectionValues = vi.fn(() => ({ returning: collectionReturning }));
+
+    const collectionBookReturning = vi.fn().mockResolvedValue([{ collectionId: 701 }]);
+    const onConflictDoNothing = vi.fn(() => ({ returning: collectionBookReturning }));
+    const collectionBookValues = vi.fn(() => ({ onConflictDoNothing }));
+
+    const insert = vi.fn().mockReturnValueOnce({ values: collectionValues }).mockReturnValue({ values: collectionBookValues });
+    const deleteWhere = vi.fn(() => Promise.resolve(undefined));
+    const deleteMock = vi.fn(() => ({ where: deleteWhere }));
+
+    const db = { select, insert, delete: deleteMock };
+    const service = new MigrationExecutorService(repo as never, {} as never, db as never, { get: vi.fn().mockReturnValue('/tmp/books') } as never);
+
+    const planned = {
+      execution: {
+        sourceData: {
+          shelves: [{ sourceShelfId: 's1', sourceUserId: 'u1', name: 'Favorites' }],
+          shelfBooks: [
+            { sourceShelfId: 's1', sourceUserId: 'u1', sourceBookId: 'source-1' },
+            { sourceShelfId: 's1', sourceUserId: 'u2', sourceBookId: 'source-2' },
+          ],
+        },
+      },
+    };
+
+    await (service as any).importCollections(
+      78,
+      planned,
+      new Map([['u1', 10]]),
+      new Map([
+        ['source-1', 101],
+        ['source-2', 102],
+      ]),
+      async () => {},
+    );
+
+    expect(insert).toHaveBeenCalledTimes(2);
+    expect(collectionBookValues).toHaveBeenCalledTimes(1);
+    expect(collectionBookValues).toHaveBeenCalledWith({ collectionId: 701, bookId: 101 });
+    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      78,
+      'user_state',
+      'collections',
+      expect.objectContaining({
+        processed: 2,
+        imported: 1,
+        skipped: 0,
+        unresolved: 1,
+        failed: 0,
+      }),
+    );
+  });
+});
diff --git a/server/src/modules/migration/executor/migration-executor.service.ts b/server/src/modules/migration/executor/migration-executor.service.ts
new file mode 100644
index 000000000..a6b4587f3
--- /dev/null
+++ b/server/src/modules/migration/executor/migration-executor.service.ts
@@ -0,0 +1,1146 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { constants as fsConstants } from 'fs';
+import { access, mkdir, readdir, readFile, unlink, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { isAudioFormat } from '@projectx/types';
+
+import { DB } from '../../../db';
+import * as schema from '../../../db/schema';
+import { coverDirPath, generateThumbnail, imageExt } from '../../metadata/lib/cover';
+import { parseBookloreConnectionConfig } from '../adapters/booklore/booklore-connection-config';
+import { buildProfileHash, buildSourceSnapshotHash } from '../core/plan-hash';
+import { MigrationPlannerService } from '../planner/planner.service';
+import { applyPathMappings } from '../planner/matching.service';
+import type { PlannedMigration, PlannerResult } from '../planner/planner.types';
+import { MigrationRepository } from '../migration.repository';
+
+type Db = NodePgDatabase<typeof schema>;
+
+interface StageCounters {
+  processed: number;
+  imported: number;
+  skipped: number;
+  unresolved: number;
+  failed: number;
+}
+
+type RunStateCheck = (force?: boolean) => Promise<void>;
+
+class RunInterruptedError extends Error {
+  constructor(
+    readonly runId: number,
+    readonly state: string,
+  ) {
+    super(`Migration run ${runId} is no longer running (state=${state})`);
+  }
+}
+
+@Injectable()
+export class MigrationExecutorService {
+  private readonly logger = new Logger(MigrationExecutorService.name);
+  private readonly running = new Set<number>();
+  private readonly booksPath: string;
+
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly planner: MigrationPlannerService,
+    @Inject(DB) private readonly db: Db,
+    private readonly config: ConfigService,
+  ) {
+    this.booksPath = this.config.get<string>('storage.booksPath')!;
+  }
+
+  start(runId: number): void {
+    if (this.running.has(runId)) return;
+    this.running.add(runId);
+
+    void this.execute(runId).finally(() => {
+      this.running.delete(runId);
+    });
+  }
+
+  private async execute(runId: number): Promise<void> {
+    const run = await this.repo.findRunById(runId);
+    if (!run) return;
+    if (run.state !== 'running') return;
+    if (!run.planArtifactId) {
+      await this.failRun(runId, 'Migration run is missing a dry-run plan artifact');
+      return;
+    }
+
+    const artifact = await this.repo.findPlanArtifactById(run.planArtifactId);
+    const profile = await this.repo.findProfileById(run.profileId);
+    const source = await this.repo.findSourceById(run.sourceId);
+
+    if (!artifact || !profile || !source) {
+      await this.failRun(runId, 'Migration run references missing source/profile/plan artifact');
+      return;
+    }
+
+    try {
+      const artifactPlan = asRecord(artifact.plan);
+      const planned = await this.planner.buildPlan({
+        source,
+        profile,
+        scopeOverride: asRecord(artifactPlan.scope),
+      });
+
+      this.assertDeterministicPlan(artifact, profile, planned.plan);
+
+      const sourceMediaRootPath = this.resolveSourceMediaRootPath(source.type, source.connectionConfig);
+
+      await this.executeStage(runId, 'shared_overlays', async (ensureRunning) => this.importSharedOverlays(runId, planned, ensureRunning));
+      await this.executeStage(runId, 'book_covers', async (ensureRunning) =>
+        this.importBookCovers(runId, planned, sourceMediaRootPath, ensureRunning),
+      );
+      await this.executeStage(runId, 'user_state', async (ensureRunning) => this.importUserState(runId, planned, ensureRunning));
+      await this.assertRunIsRunning(runId);
+
+      await this.repo.updateRunState(runId, 'completed', {
+        currentStage: 'completed',
+        endedAt: new Date(),
+        errorMessage: null,
+      });
+    } catch (error) {
+      if (error instanceof RunInterruptedError) {
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`[migration.execute] runId=${runId} error="${message}"`);
+      await this.failRun(runId, message);
+    }
+  }
+
+  private assertDeterministicPlan(
+    artifact: typeof schema.migrationPlanArtifacts.$inferSelect,
+    profile: typeof schema.migrationProfiles.$inferSelect,
+    generatedPlan: PlannedMigration,
+  ): void {
+    const sourceSnapshotHash = buildSourceSnapshotHash(generatedPlan.snapshot);
+    const profileHash = buildProfileHash(profile);
+
+    if (artifact.sourceSnapshotHash !== sourceSnapshotHash || artifact.profileHash !== profileHash) {
+      throw new Error('Source or profile changed since dry-run. Re-run dry-run before starting migration.');
+    }
+  }
+
+  private async executeStage(runId: number, stage: string, handler: (ensureRunning: RunStateCheck) => Promise<void>): Promise<void> {
+    await this.repo.updateRunState(runId, 'running', {
+      currentStage: stage,
+      errorMessage: null,
+    });
+
+    const ensureRunning = this.createRunStateChecker(runId);
+    await ensureRunning(true);
+    await handler(ensureRunning);
+    await ensureRunning(true);
+  }
+
+  private createRunStateChecker(runId: number, checkEvery = 25): RunStateCheck {
+    let sinceLastCheck = 0;
+    return async (force = false) => {
+      sinceLastCheck += 1;
+      if (!force && sinceLastCheck % checkEvery !== 0) return;
+      await this.assertRunIsRunning(runId);
+    };
+  }
+
+  private async assertRunIsRunning(runId: number): Promise<void> {
+    const run = await this.repo.findRunById(runId);
+    const state = run?.state ?? 'missing';
+    if (!run || state !== 'running') {
+      throw new RunInterruptedError(runId, state);
+    }
+  }
+
+  private async importSharedOverlays(runId: number, planned: PlannerResult, ensureRunning: RunStateCheck): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((row) => [row.sourceBookId, row]));
+
+    const counters: StageCounters = {
+      processed: 0,
+      imported: 0,
+      skipped: 0,
+      unresolved: 0,
+      failed: 0,
+    };
+
+    for (const match of planned.execution.matchedBooks) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const values = buildMetadataPatch(sourceBook);
+
+      await this.db
+        .insert(schema.bookMetadata)
+        .values({ bookId: match.targetBookId, ...values })
+        .onConflictDoUpdate({
+          target: schema.bookMetadata.bookId,
+          set: values,
+        });
+
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_metadata', counters);
+
+    await this.importAuthors(runId, planned);
+    await this.importNarrators(runId, planned);
+    await this.importGenres(runId, planned);
+    await this.importTags(runId, planned);
+  }
+
+  private async importAuthors(runId: number, planned: PlannerResult): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((b) => [b.sourceBookId, b]));
+    const counters = emptyCounters();
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.delete(schema.bookAuthors).where(eq(schema.bookAuthors.bookId, match.targetBookId));
+
+      const authors = getSourceContributors(sourceBook.authors, sourceBook.author);
+      if (authors.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const [index, contributor] of authors.entries()) {
+        const [author] = await this.db
+          .insert(schema.authors)
+          .values(buildContributorValues(contributor))
+          .onConflictDoUpdate({ target: schema.authors.name, set: buildContributorValues(contributor) })
+          .returning({ id: schema.authors.id });
+        if (!author) continue;
+
+        await this.db
+          .insert(schema.bookAuthors)
+          .values({ bookId: match.targetBookId, authorId: author.id, displayOrder: index })
+          .onConflictDoNothing();
+      }
+
+      counters.imported += authors.length;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_authors', counters);
+  }
+
+  private async importNarrators(runId: number, planned: PlannerResult): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((b) => [b.sourceBookId, b]));
+    const counters = emptyCounters();
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.delete(schema.bookNarrators).where(eq(schema.bookNarrators.bookId, match.targetBookId));
+
+      const narrators = getSourceContributors(sourceBook.narrators, null);
+      if (narrators.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const [index, contributor] of narrators.entries()) {
+        const [narrator] = await this.db
+          .insert(schema.narrators)
+          .values({ name: contributor.name, sortName: contributor.sortName ?? contributor.name })
+          .onConflictDoUpdate({
+            target: schema.narrators.name,
+            set: { name: contributor.name, sortName: contributor.sortName ?? contributor.name },
+          })
+          .returning({ id: schema.narrators.id });
+        if (!narrator) continue;
+
+        await this.db
+          .insert(schema.bookNarrators)
+          .values({ bookId: match.targetBookId, narratorId: narrator.id, displayOrder: index })
+          .onConflictDoNothing();
+      }
+
+      counters.imported += narrators.length;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_narrators', counters);
+  }
+
+  private async importGenres(runId: number, planned: PlannerResult): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((b) => [b.sourceBookId, b]));
+    const counters = emptyCounters();
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.delete(schema.bookGenres).where(eq(schema.bookGenres.bookId, match.targetBookId));
+
+      if (sourceBook.genres.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const name of sourceBook.genres) {
+        const [genre] = await this.db
+          .insert(schema.genres)
+          .values({ name })
+          .onConflictDoUpdate({ target: schema.genres.name, set: { name: sql`excluded.name` } })
+          .returning({ id: schema.genres.id });
+        if (genre) {
+          await this.db.insert(schema.bookGenres).values({ bookId: match.targetBookId, genreId: genre.id }).onConflictDoNothing();
+          counters.imported += 1;
+        }
+      }
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_genres', counters);
+  }
+
+  private async importTags(runId: number, planned: PlannerResult): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((b) => [b.sourceBookId, b]));
+    const counters = emptyCounters();
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.delete(schema.bookTags).where(eq(schema.bookTags.bookId, match.targetBookId));
+
+      if (sourceBook.tags.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const name of sourceBook.tags) {
+        const [tag] = await this.db
+          .insert(schema.tags)
+          .values({ name })
+          .onConflictDoUpdate({ target: schema.tags.name, set: { name: sql`excluded.name` } })
+          .returning({ id: schema.tags.id });
+        if (tag) {
+          await this.db.insert(schema.bookTags).values({ bookId: match.targetBookId, tagId: tag.id }).onConflictDoNothing();
+          counters.imported += 1;
+        }
+      }
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_tags', counters);
+  }
+
+  private resolveSourceMediaRootPath(sourceType: string, connectionConfig: unknown): string | null {
+    if (sourceType !== 'booklore') return null;
+    const config = parseBookloreConnectionConfig(connectionConfig);
+    return config.mediaRootPath ?? null;
+  }
+
+  private async importBookCovers(
+    runId: number,
+    planned: PlannerResult,
+    sourceMediaRootPath: string | null,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    const matches = planned.execution.matchedBooks;
+
+    if (!sourceMediaRootPath) {
+      counters.processed = matches.length;
+      counters.skipped = matches.length;
+      await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_covers', counters);
+      return;
+    }
+
+    for (const match of matches) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const sourceImageDir = join(sourceMediaRootPath, 'images', match.sourceBookId);
+      const sourceCoverPath = join(sourceImageDir, 'cover.jpg');
+      const sourceThumbnailPath = join(sourceImageDir, 'thumbnail.jpg');
+      const coverBytes = await this.readOptionalFile(sourceCoverPath);
+      if (!coverBytes) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      try {
+        const targetCoverDir = coverDirPath(this.booksPath, match.targetBookId);
+        await mkdir(targetCoverDir, { recursive: true });
+        await this.deleteFilesByPrefix(targetCoverDir, 'cover_custom.');
+
+        const coverExt = imageExt(coverBytes);
+        await writeFile(join(targetCoverDir, `cover_custom.${coverExt}`), coverBytes);
+
+        const sourceThumbnailBytes = await this.readOptionalFile(sourceThumbnailPath);
+        const thumbnailBytes = sourceThumbnailBytes ?? (await generateThumbnail(coverBytes));
+        await writeFile(join(targetCoverDir, 'thumbnail.jpg'), thumbnailBytes);
+
+        const now = new Date();
+        await this.db
+          .insert(schema.bookMetadata)
+          .values({ bookId: match.targetBookId, coverSource: 'custom', updatedAt: now })
+          .onConflictDoUpdate({
+            target: schema.bookMetadata.bookId,
+            set: { coverSource: 'custom', updatedAt: now },
+          });
+
+        counters.imported += 1;
+      } catch (error) {
+        counters.failed += 1;
+        const message = error instanceof Error ? error.message : String(error);
+        this.logger.warn(`[migration.cover] runId=${runId} sourceBookId=${match.sourceBookId} targetBookId=${match.targetBookId} error="${message}"`);
+      }
+    }
+
+    await this.repo.incrementRunMetric(runId, 'shared_overlays', 'book_covers', counters);
+  }
+
+  private async importUserState(runId: number, planned: PlannerResult, ensureRunning: RunStateCheck): Promise<void> {
+    const sourceToTargetUser = new Map(planned.plan.userMappings.map((mapping) => [mapping.sourceUserId, mapping.targetUserId]));
+    const sourceToTargetBook = new Map(planned.execution.matchedBooks.map((mapping) => [mapping.sourceBookId, mapping.targetBookId]));
+
+    const targetBookIds = [...new Set(planned.execution.matchedBooks.map((entry) => entry.targetBookId))];
+    const primaryFilesByBookId = new Map<number, number>();
+    const audiobookPrimaryFilesByBookId = new Map<number, number>();
+    const targetFilesByBookId = new Map<number, Array<{ id: number; hash: string | null; absolutePath: string }>>();
+    if (targetBookIds.length > 0) {
+      const primaryRows = await this.db
+        .select({
+          bookId: schema.books.id,
+          primaryFileId: schema.books.primaryFileId,
+          primaryFileFormat: schema.bookFiles.format,
+        })
+        .from(schema.books)
+        .leftJoin(schema.bookFiles, eq(schema.bookFiles.id, schema.books.primaryFileId))
+        .where(inArray(schema.books.id, targetBookIds));
+      for (const row of primaryRows) {
+        if (!row.primaryFileId) continue;
+        primaryFilesByBookId.set(row.bookId, row.primaryFileId);
+        if (row.primaryFileFormat && isAudioFormat(row.primaryFileFormat)) {
+          audiobookPrimaryFilesByBookId.set(row.bookId, row.primaryFileId);
+        }
+      }
+
+      const fileRows = await this.db
+        .select({
+          id: schema.bookFiles.id,
+          bookId: schema.bookFiles.bookId,
+          hash: schema.bookFiles.hash,
+          absolutePath: schema.bookFiles.absolutePath,
+          format: schema.bookFiles.format,
+        })
+        .from(schema.bookFiles)
+        .where(inArray(schema.bookFiles.bookId, targetBookIds));
+      for (const row of fileRows) {
+        const files = targetFilesByBookId.get(row.bookId) ?? [];
+        files.push({ id: row.id, hash: row.hash, absolutePath: row.absolutePath });
+        targetFilesByBookId.set(row.bookId, files);
+      }
+    }
+    const sourceFileToTargetFile = buildSourceFileTargetMap(planned, targetFilesByBookId);
+
+    await this.importUserBookStatuses(runId, planned, sourceToTargetUser, sourceToTargetBook, ensureRunning);
+    await this.importReadingProgress(
+      runId,
+      planned,
+      sourceToTargetUser,
+      sourceToTargetBook,
+      primaryFilesByBookId,
+      sourceFileToTargetFile,
+      ensureRunning,
+    );
+    await this.importAudiobookProgress(
+      runId,
+      planned,
+      sourceToTargetUser,
+      sourceToTargetBook,
+      audiobookPrimaryFilesByBookId,
+      sourceFileToTargetFile,
+      ensureRunning,
+    );
+    await this.importBookmarks(runId, planned, sourceToTargetUser, sourceToTargetBook, ensureRunning);
+    await this.importAnnotations(runId, planned, sourceToTargetUser, sourceToTargetBook, ensureRunning);
+    await this.importCollections(runId, planned, sourceToTargetUser, sourceToTargetBook, ensureRunning);
+  }
+
+  private async importUserBookStatuses(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    await this.clearUserBookStatusesForMappedScope(userMap, bookMap);
+
+    for (const row of planned.execution.sourceData.userBookStatuses) {
+      await ensureRunning();
+      counters.processed += 1;
+      const targetUserId = userMap.get(row.sourceUserId);
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetUserId || !targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const status = normalizeReadStatus(row.status, row.percentage);
+      const sourceUpdatedAt = toDate(row.updatedAt) ?? new Date();
+
+      await this.db
+        .insert(schema.userBookStatus)
+        .values({
+          userId: targetUserId,
+          bookId: targetBookId,
+          status,
+          source: 'manual',
+          startedAt: toDate(row.startedAt),
+          finishedAt: toDate(row.finishedAt),
+          updatedAt: sourceUpdatedAt,
+        })
+        .onConflictDoUpdate({
+          target: [schema.userBookStatus.userId, schema.userBookStatus.bookId],
+          set: {
+            status,
+            source: 'manual',
+            startedAt: toDate(row.startedAt),
+            finishedAt: toDate(row.finishedAt),
+            updatedAt: sourceUpdatedAt,
+          },
+        });
+
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'user_book_status', counters);
+  }
+
+  private async importReadingProgress(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    primaryFilesByBookId: Map<number, number>,
+    sourceFileToTargetFile: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    await this.clearReadingProgressForMappedScope(userMap, primaryFilesByBookId, sourceFileToTargetFile);
+
+    for (const row of planned.execution.sourceData.userFileProgress) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const targetUserId = userMap.get(row.sourceUserId);
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetUserId || !targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const targetFileId = (row.sourceFileId ? sourceFileToTargetFile.get(row.sourceFileId) : null) ?? primaryFilesByBookId.get(targetBookId);
+      if (!targetFileId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const sourceUpdatedAt = toDate(row.updatedAt) ?? new Date();
+
+      await this.db
+        .insert(schema.readingProgress)
+        .values({
+          bookFileId: targetFileId,
+          userId: targetUserId,
+          percentage: clampPercent(row.percentage),
+          cfi: row.cfi,
+          pageNumber: row.pageNumber,
+          positionSeconds: row.positionSeconds,
+          updatedAt: sourceUpdatedAt,
+        })
+        .onConflictDoUpdate({
+          target: [schema.readingProgress.bookFileId, schema.readingProgress.userId],
+          set: {
+            percentage: clampPercent(row.percentage),
+            cfi: row.cfi,
+            pageNumber: row.pageNumber,
+            positionSeconds: row.positionSeconds,
+            updatedAt: sourceUpdatedAt,
+          },
+        });
+
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'reading_progress', counters);
+  }
+
+  private async importBookmarks(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    await this.clearBookmarksForMappedScope(userMap, bookMap);
+
+    for (const row of planned.execution.sourceData.bookmarks) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const targetUserId = userMap.get(row.sourceUserId);
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetUserId || !targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.insert(schema.bookmarks).values({
+        userId: targetUserId,
+        bookId: targetBookId,
+        title: row.title ?? 'Imported bookmark',
+        cfi: row.cfi,
+        positionSeconds: row.positionSeconds,
+        createdAt: toDate(row.createdAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'bookmarks', counters);
+  }
+
+  private async importAudiobookProgress(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    audiobookPrimaryFilesByBookId: Map<number, number>,
+    sourceFileToTargetFile: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    const sourceAudioRows = planned.execution.sourceData.userFileProgress.filter((row) => {
+      const targetBookId = bookMap.get(row.sourceBookId);
+      return targetBookId ? audiobookPrimaryFilesByBookId.has(targetBookId) : false;
+    });
+    await this.clearAudiobookProgressForMappedScope(userMap, audiobookPrimaryFilesByBookId);
+
+    for (const row of sourceAudioRows) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const targetUserId = userMap.get(row.sourceUserId);
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetUserId || !targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const targetFileId =
+        (row.sourceFileId ? sourceFileToTargetFile.get(row.sourceFileId) : null) ?? audiobookPrimaryFilesByBookId.get(targetBookId);
+      if (!targetFileId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const sourceUpdatedAt = toDate(row.updatedAt) ?? new Date();
+
+      await this.db
+        .insert(schema.audiobookProgress)
+        .values({
+          userId: targetUserId,
+          bookId: targetBookId,
+          percentage: clampPercent(row.percentage),
+          currentFileId: targetFileId,
+          positionSeconds: clampNonNegative(row.positionSeconds),
+          updatedAt: sourceUpdatedAt,
+        })
+        .onConflictDoUpdate({
+          target: [schema.audiobookProgress.userId, schema.audiobookProgress.bookId],
+          set: {
+            percentage: clampPercent(row.percentage),
+            currentFileId: targetFileId,
+            positionSeconds: clampNonNegative(row.positionSeconds),
+            updatedAt: sourceUpdatedAt,
+          },
+        });
+
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'audiobook_progress', counters);
+  }
+
+  private async importAnnotations(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    await this.clearAnnotationsForMappedScope(userMap, bookMap);
+
+    for (const row of planned.execution.sourceData.annotations) {
+      await ensureRunning();
+      counters.processed += 1;
+
+      const targetUserId = userMap.get(row.sourceUserId);
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetUserId || !targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      await this.db.insert(schema.annotations).values({
+        userId: targetUserId,
+        bookId: targetBookId,
+        cfi: row.cfi,
+        text: row.text,
+        color: row.color ?? 'yellow',
+        style: row.style ?? 'highlight',
+        note: row.note,
+        chapterTitle: row.chapterTitle,
+        createdAt: toDate(row.createdAt) ?? new Date(),
+        updatedAt: toDate(row.updatedAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'annotations', counters);
+  }
+
+  private async clearUserBookStatusesForMappedScope(userMap: Map<string, number>, bookMap: Map<string, number>): Promise<void> {
+    const targetUserIds = uniqueNumbers([...userMap.values()]);
+    const targetBookIds = uniqueNumbers([...bookMap.values()]);
+    if (targetUserIds.length === 0 || targetBookIds.length === 0) return;
+    await this.db
+      .delete(schema.userBookStatus)
+      .where(and(inArray(schema.userBookStatus.userId, targetUserIds), inArray(schema.userBookStatus.bookId, targetBookIds)));
+  }
+
+  private async clearReadingProgressForMappedScope(
+    userMap: Map<string, number>,
+    primaryFilesByBookId: Map<number, number>,
+    sourceFileToTargetFile: Map<string, number>,
+  ): Promise<void> {
+    const targetUserIds = uniqueNumbers([...userMap.values()]);
+    const targetFileIds = uniqueNumbers([...primaryFilesByBookId.values(), ...sourceFileToTargetFile.values()]);
+    if (targetUserIds.length === 0 || targetFileIds.length === 0) return;
+    await this.db
+      .delete(schema.readingProgress)
+      .where(and(inArray(schema.readingProgress.userId, targetUserIds), inArray(schema.readingProgress.bookFileId, targetFileIds)));
+  }
+
+  private async clearAudiobookProgressForMappedScope(
+    userMap: Map<string, number>,
+    audiobookPrimaryFilesByBookId: Map<number, number>,
+  ): Promise<void> {
+    const targetUserIds = uniqueNumbers([...userMap.values()]);
+    const targetBookIds = uniqueNumbers([...audiobookPrimaryFilesByBookId.keys()]);
+    if (targetUserIds.length === 0 || targetBookIds.length === 0) return;
+    await this.db
+      .delete(schema.audiobookProgress)
+      .where(and(inArray(schema.audiobookProgress.userId, targetUserIds), inArray(schema.audiobookProgress.bookId, targetBookIds)));
+  }
+
+  private async clearBookmarksForMappedScope(userMap: Map<string, number>, bookMap: Map<string, number>): Promise<void> {
+    const targetUserIds = uniqueNumbers([...userMap.values()]);
+    const targetBookIds = uniqueNumbers([...bookMap.values()]);
+    if (targetUserIds.length === 0 || targetBookIds.length === 0) return;
+    await this.db
+      .delete(schema.bookmarks)
+      .where(and(inArray(schema.bookmarks.userId, targetUserIds), inArray(schema.bookmarks.bookId, targetBookIds)));
+  }
+
+  private async clearAnnotationsForMappedScope(userMap: Map<string, number>, bookMap: Map<string, number>): Promise<void> {
+    const targetUserIds = uniqueNumbers([...userMap.values()]);
+    const targetBookIds = uniqueNumbers([...bookMap.values()]);
+    if (targetUserIds.length === 0 || targetBookIds.length === 0) return;
+    await this.db
+      .delete(schema.annotations)
+      .where(and(inArray(schema.annotations.userId, targetUserIds), inArray(schema.annotations.bookId, targetBookIds)));
+  }
+
+  private async importCollections(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    const shelvesById = new Map(planned.execution.sourceData.shelves.map((row) => [row.sourceShelfId, row]));
+
+    const targetUserIds = [...new Set([...userMap.values()])];
+    const existingCollections =
+      targetUserIds.length > 0 ? await this.db.select().from(schema.collections).where(inArray(schema.collections.userId, targetUserIds)) : [];
+
+    const collectionKeyToId = new Map(existingCollections.map((row) => [`${row.userId}:${row.name.toLowerCase()}`, row.id]));
+    const preparedCollectionIds = new Set<number>();
+
+    const ensureCollectionForShelf = async (shelf: { sourceUserId: string; name: string }): Promise<number | null> => {
+      const targetUserId = userMap.get(shelf.sourceUserId);
+      if (!targetUserId) return null;
+
+      const key = `${targetUserId}:${shelf.name.toLowerCase()}`;
+      let collectionId = collectionKeyToId.get(key);
+      if (!collectionId) {
+        const [inserted] = await this.db
+          .insert(schema.collections)
+          .values({ userId: targetUserId, name: shelf.name, syncToKobo: false, displayOrder: 0 })
+          .returning();
+        collectionId = inserted.id;
+        collectionKeyToId.set(key, collectionId);
+      }
+
+      if (!preparedCollectionIds.has(collectionId)) {
+        await this.db.delete(schema.collectionBooks).where(eq(schema.collectionBooks.collectionId, collectionId));
+        preparedCollectionIds.add(collectionId);
+      }
+
+      return collectionId;
+    };
+
+    for (const shelf of planned.execution.sourceData.shelves) {
+      await ensureRunning();
+      await ensureCollectionForShelf(shelf);
+    }
+
+    for (const row of planned.execution.sourceData.shelfBooks) {
+      await ensureRunning();
+      counters.processed += 1;
+      const shelf = shelvesById.get(row.sourceShelfId);
+      if (!shelf) {
+        counters.unresolved += 1;
+        continue;
+      }
+      if (row.sourceUserId !== shelf.sourceUserId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const targetBookId = bookMap.get(row.sourceBookId);
+      if (!targetBookId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const collectionId = await ensureCollectionForShelf(shelf);
+      if (!collectionId) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      const inserted = await this.db
+        .insert(schema.collectionBooks)
+        .values({ collectionId, bookId: targetBookId })
+        .onConflictDoNothing()
+        .returning({ collectionId: schema.collectionBooks.collectionId });
+      if (inserted.length > 0) {
+        counters.imported += 1;
+      } else {
+        counters.skipped += 1;
+      }
+    }
+
+    await this.repo.incrementRunMetric(runId, 'user_state', 'collections', counters);
+  }
+
+  private async readOptionalFile(path: string): Promise<Buffer | null> {
+    try {
+      return await readFile(path);
+    } catch (error) {
+      if (hasErrorCode(error, 'ENOENT')) return null;
+      throw error;
+    }
+  }
+
+  private async deleteFilesByPrefix(path: string, prefix: string): Promise<void> {
+    const files = await this.readDirIfExists(path);
+    for (const fileName of files) {
+      if (!fileName.startsWith(prefix)) continue;
+      await this.removeFileIfPresent(join(path, fileName));
+    }
+  }
+
+  private async readDirIfExists(path: string): Promise<string[]> {
+    try {
+      await access(path, fsConstants.R_OK);
+      return await readdir(path);
+    } catch (error) {
+      if (hasErrorCode(error, 'ENOENT')) return [];
+      throw error;
+    }
+  }
+
+  private async removeFileIfPresent(path: string): Promise<void> {
+    try {
+      await unlink(path);
+    } catch (error) {
+      if (hasErrorCode(error, 'ENOENT')) return;
+      throw error;
+    }
+  }
+
+  private async failRun(runId: number, message: string): Promise<void> {
+    await this.repo.updateRunState(runId, 'failed', {
+      currentStage: 'failed',
+      endedAt: new Date(),
+      errorMessage: message,
+    });
+  }
+}
+
+function emptyCounters(): StageCounters {
+  return {
+    processed: 0,
+    imported: 0,
+    skipped: 0,
+    unresolved: 0,
+    failed: 0,
+  };
+}
+
+function uniqueNumbers(values: number[]): number[] {
+  return [...new Set(values.filter((value) => Number.isFinite(value)))];
+}
+
+function buildSourceFileTargetMap(
+  planned: PlannerResult,
+  targetFilesByBookId: Map<number, Array<{ id: number; hash: string | null; absolutePath: string }>>,
+): Map<string, number> {
+  const sourceBooksById = new Map(planned.execution.sourceData.books.map((book) => [book.sourceBookId, book]));
+  const out = new Map<string, number>();
+
+  for (const match of planned.execution.matchedBooks) {
+    const sourceBook = sourceBooksById.get(match.sourceBookId);
+    const sourceFiles = sourceBook?.files ?? [];
+    const targetFiles = targetFilesByBookId.get(match.targetBookId) ?? [];
+    if (sourceFiles.length === 0 || targetFiles.length === 0) continue;
+
+    for (const sourceFile of sourceFiles) {
+      if (out.has(sourceFile.sourceFileId)) continue;
+
+      if (sourceFile.fileHash) {
+        const byHash = targetFiles.filter((targetFile) => targetFile.hash === sourceFile.fileHash);
+        if (byHash.length === 1) {
+          out.set(sourceFile.sourceFileId, byHash[0].id);
+          continue;
+        }
+      }
+
+      const mappedPath = applyPathMappings(sourceFile.filePath, planned.plan.pathMappings);
+      if (mappedPath) {
+        const byPath = targetFiles.filter((targetFile) => targetFile.absolutePath === mappedPath);
+        if (byPath.length === 1) {
+          out.set(sourceFile.sourceFileId, byPath[0].id);
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function buildMetadataPatch(sourceBook: {
+  title: string | null;
+  subtitle: string | null;
+  isbn10: string | null;
+  isbn13: string | null;
+  description: string | null;
+  publisher: string | null;
+  publishedYear: number | null;
+  language: string | null;
+  pageCount?: number | null;
+  seriesName?: string | null;
+  seriesIndex?: number | null;
+  rating?: number | null;
+  googleBooksId?: string | null;
+  goodreadsId?: string | null;
+  amazonId?: string | null;
+  hardcoverId?: string | null;
+  audibleId?: string | null;
+  comicvineId?: string | null;
+  durationSeconds?: number | null;
+  abridged?: boolean | null;
+  presentFields?: string[];
+}): Partial<typeof schema.bookMetadata.$inferInsert> {
+  const field = <T>(name: string, value: T | undefined): T | undefined =>
+    !sourceBook.presentFields || sourceBook.presentFields.includes(name) ? value : undefined;
+
+  return pruneUndefined({
+    title: field('title', sourceBook.title),
+    subtitle: field('subtitle', sourceBook.subtitle),
+    isbn10: field('isbn10', sourceBook.isbn10),
+    isbn13: field('isbn13', sourceBook.isbn13),
+    description: field('description', sourceBook.description),
+    publisher: field('publisher', sourceBook.publisher),
+    publishedYear: field('publishedYear', sourceBook.publishedYear),
+    language: field('language', sourceBook.language),
+    pageCount: field('pageCount', sourceBook.pageCount),
+    seriesName: field('seriesName', sourceBook.seriesName),
+    seriesIndex: field('seriesIndex', sourceBook.seriesIndex),
+    rating: field('rating', sourceBook.rating),
+    googleBooksId: field('googleBooksId', sourceBook.googleBooksId),
+    goodreadsId: field('goodreadsId', sourceBook.goodreadsId),
+    amazonId: field('amazonId', sourceBook.amazonId),
+    hardcoverId: field('hardcoverId', sourceBook.hardcoverId),
+    audibleId: field('audibleId', sourceBook.audibleId),
+    comicvineId: field('comicvineId', sourceBook.comicvineId),
+    durationSeconds: field('durationSeconds', sourceBook.durationSeconds),
+    abridged: field('abridged', sourceBook.abridged === undefined ? undefined : (sourceBook.abridged ?? false)),
+  });
+}
+
+function buildContributorValues(contributor: {
+  name: string;
+  sortName?: string | null;
+  description?: string | null;
+}): typeof schema.authors.$inferInsert {
+  return pruneUndefined({
+    name: contributor.name,
+    sortName: contributor.sortName ?? contributor.name,
+    description: contributor.description ?? undefined,
+  });
+}
+
+function getSourceContributors(
+  contributors: Array<{ name: string; sortName?: string | null; description?: string | null; displayOrder?: number | null }> | undefined,
+  legacyValue: string | null,
+): Array<{ name: string; sortName: string | null; description: string | null }> {
+  const structured =
+    contributors
+      ?.filter((contributor) => contributor.name.trim().length > 0)
+      .sort((a, b) => (a.displayOrder ?? 0) - (b.displayOrder ?? 0))
+      .map((contributor) => ({
+        name: contributor.name.trim(),
+        sortName: contributor.sortName ?? null,
+        description: contributor.description ?? null,
+      })) ?? [];
+  if (structured.length > 0) return dedupeContributors(structured);
+  return parseAuthorNames(legacyValue).map((name) => ({ name, sortName: name, description: null }));
+}
+
+function dedupeContributors<T extends { name: string }>(contributors: T[]): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const contributor of contributors) {
+    const key = contributor.name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(contributor);
+  }
+  return out;
+}
+
+function parseAuthorNames(value: string | null): string[] {
+  if (!value) return [];
+  const trimmed = value.trim();
+  if (!trimmed) return [];
+
+  const parsed = parseJsonStringArray(trimmed);
+  const rawNames = parsed ?? trimmed.split(/\s*(?:;|\||\s+&\s+|\s+and\s+)\s*/i);
+
+  const seen = new Set<string>();
+  const names: string[] = [];
+  for (const rawName of rawNames) {
+    const name = rawName.trim();
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    names.push(name);
+  }
+  return names;
+}
+
+function parseJsonStringArray(value: string): string[] | null {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!Array.isArray(parsed)) return null;
+    const strings = parsed.filter((item): item is string => typeof item === 'string');
+    return strings.length > 0 ? strings : null;
+  } catch {
+    return null;
+  }
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(input: T): T {
+  const out = {} as T;
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      (out as Record<string, unknown>)[key] = value;
+    }
+  }
+  return out;
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return Boolean(error && typeof error === 'object' && 'code' in error && (error as { code?: string }).code === code);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function toDate(value: string | null): Date | null {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function clampPercent(value: number | null): number {
+  if (value == null || !Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(100, value));
+}
+
+function clampNonNegative(value: number | null): number {
+  if (value == null || !Number.isFinite(value)) return 0;
+  return Math.max(0, value);
+}
+
+function normalizeReadStatus(
+  rawStatus: string | null,
+  percentage: number | null,
+): 'unread' | 'reading' | 'read' | 'abandoned' | 'on_hold' | 'want_to_read' | 'rereading' | 'skimmed' {
+  const normalized = rawStatus?.trim().toLowerCase();
+
+  if (normalized === 'read' || normalized === 'completed') return 'read';
+  if (normalized === 'reading' || normalized === 'in_progress') return 'reading';
+  if (normalized === 'on_hold' || normalized === 'paused') return 'on_hold';
+  if (normalized === 'abandoned' || normalized === 'dropped') return 'abandoned';
+  if (normalized === 'want_to_read' || normalized === 'wishlist') return 'want_to_read';
+  if (normalized === 'rereading') return 'rereading';
+  if (normalized === 'skimmed') return 'skimmed';
+
+  if (percentage != null) {
+    if (percentage >= 98) return 'read';
+    if (percentage > 0) return 'reading';
+  }
+
+  return 'unread';
+}
diff --git a/server/src/modules/migration/migration.controller.ts b/server/src/modules/migration/migration.controller.ts
new file mode 100644
index 000000000..ebc4caa22
--- /dev/null
+++ b/server/src/modules/migration/migration.controller.ts
@@ -0,0 +1,95 @@
+import { Body, Controller, Get, HttpCode, HttpStatus, Param, ParseIntPipe, Post, Query } from '@nestjs/common';
+import { Permission } from '@projectx/types';
+
+import { CurrentUser } from '../../common/decorators/current-user.decorator';
+import { RequirePermission } from '../../common/decorators/require-permission.decorator';
+import type { RequestUser } from '../../common/types/request-user';
+import { CreateDryRunPlanDto } from './dto/create-dry-run-plan.dto';
+import { CreateMigrationProfileDto } from './dto/create-migration-profile.dto';
+import { CreateMigrationSourceDto } from './dto/create-migration-source.dto';
+import { StartLiveRunDto } from './dto/start-live-run.dto';
+import { TestMigrationSourceDto } from './dto/test-migration-source.dto';
+import { ValidatePathMappingsDto } from './dto/validate-path-mappings.dto';
+import { MigrationService } from './migration.service';
+
+@Controller('migration')
+@RequirePermission(Permission.ManageAppSettings)
+export class MigrationController {
+  constructor(private readonly service: MigrationService) {}
+
+  @Get('supported-types')
+  listSupportedTypes() {
+    return this.service.listSupportedSourceTypes();
+  }
+
+  @Post('sources/test')
+  testSource(@Body() dto: TestMigrationSourceDto) {
+    return this.service.testSource(dto);
+  }
+
+  @Get('state')
+  getWorkflowState() {
+    return this.service.getWorkflowState();
+  }
+
+  @Get('target-users')
+  listTargetUsers() {
+    return this.service.listTargetUsers();
+  }
+
+  @Post('sources')
+  createSource(@Body() dto: CreateMigrationSourceDto, @CurrentUser() user: RequestUser) {
+    return this.service.createSource(dto, user.id);
+  }
+
+  @Post('sources/:id/validate')
+  @HttpCode(HttpStatus.OK)
+  validateSourceById(@Param('id', ParseIntPipe) sourceId: number) {
+    return this.service.validateSourceById(sourceId);
+  }
+
+  @Get('sources/:id/path-prefixes')
+  getSourcePathPrefixes(@Param('id', ParseIntPipe) sourceId: number) {
+    return this.service.getSourcePathPrefixes(sourceId);
+  }
+
+  @Get('sources/:id/user-mapping-suggestions')
+  suggestUserMappings(@Param('id', ParseIntPipe) sourceId: number) {
+    return this.service.suggestUserMappings(sourceId);
+  }
+
+  @Post('sources/:id/path-mappings/validate')
+  validatePathMappings(@Param('id', ParseIntPipe) sourceId: number, @Body() dto: ValidatePathMappingsDto) {
+    return this.service.validatePathMappings(sourceId, dto);
+  }
+
+  @Post('profiles')
+  createProfile(@Body() dto: CreateMigrationProfileDto, @CurrentUser() user: RequestUser) {
+    return this.service.createProfile(dto, user.id);
+  }
+
+  @Post('plans/dry-run')
+  createDryRunPlan(@Body() dto: CreateDryRunPlanDto, @CurrentUser() user: RequestUser) {
+    return this.service.createDryRunPlan(dto, user.id);
+  }
+
+  @Post('runs/live')
+  startLiveRun(@Body() dto: StartLiveRunDto, @CurrentUser() user: RequestUser) {
+    return this.service.startLiveRun(dto, user.id);
+  }
+
+  @Get('runs/:id/progress')
+  getRunProgress(@Param('id', ParseIntPipe) runId: number) {
+    return this.service.getRunProgress(runId);
+  }
+
+  @Get('runs/:id/report')
+  getRunReport(@Param('id', ParseIntPipe) runId: number) {
+    return this.service.getRunReport(runId);
+  }
+
+  @Get('runs/:id/report/export')
+  exportRunReport(@Param('id', ParseIntPipe) runId: number, @Query('format') format?: string) {
+    return this.service.exportRunReport(runId, format);
+  }
+}
diff --git a/server/src/modules/migration/migration.module.test.ts b/server/src/modules/migration/migration.module.test.ts
new file mode 100644
index 000000000..2c75cb565
--- /dev/null
+++ b/server/src/modules/migration/migration.module.test.ts
@@ -0,0 +1,33 @@
+import { MODULE_METADATA } from '@nestjs/common/constants';
+
+import { MigrationController } from './migration.controller';
+import { MigrationModule } from './migration.module';
+import { MigrationRepository } from './migration.repository';
+import { MigrationService } from './migration.service';
+import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
+import { MigrationPlannerService } from './planner/planner.service';
+import { PathMappingValidationService } from './planner/path-mapping-validation.service';
+import { MigrationExecutorService } from './executor/migration-executor.service';
+import { MigrationReportingService } from './reporting/migration-reporting.service';
+
+describe('MigrationModule', () => {
+  it('registers expected controllers and providers', () => {
+    const controllers = Reflect.getMetadata(MODULE_METADATA.CONTROLLERS, MigrationModule);
+    const providers = Reflect.getMetadata(MODULE_METADATA.PROVIDERS, MigrationModule);
+    const exports = Reflect.getMetadata(MODULE_METADATA.EXPORTS, MigrationModule);
+
+    expect(controllers).toEqual(expect.arrayContaining([MigrationController]));
+    expect(providers).toEqual(
+      expect.arrayContaining([
+        MigrationRepository,
+        SourceAdapterRegistry,
+        MigrationPlannerService,
+        PathMappingValidationService,
+        MigrationExecutorService,
+        MigrationReportingService,
+        MigrationService,
+      ]),
+    );
+    expect(exports).toEqual(expect.arrayContaining([MigrationRepository, MigrationService]));
+  });
+});
diff --git a/server/src/modules/migration/migration.module.ts b/server/src/modules/migration/migration.module.ts
new file mode 100644
index 000000000..077a0ce6e
--- /dev/null
+++ b/server/src/modules/migration/migration.module.ts
@@ -0,0 +1,31 @@
+import { Module } from '@nestjs/common';
+
+import { MigrationController } from './migration.controller';
+import { MigrationRepository } from './migration.repository';
+import { MigrationService } from './migration.service';
+import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
+import { BookloreSourceAdapter } from './adapters/booklore/booklore-source.adapter';
+import { BookloreConnector } from './adapters/booklore/booklore-connector';
+import { MatchingService } from './planner/matching.service';
+import { MigrationPlannerService } from './planner/planner.service';
+import { PathMappingValidationService } from './planner/path-mapping-validation.service';
+import { MigrationExecutorService } from './executor/migration-executor.service';
+import { MigrationReportingService } from './reporting/migration-reporting.service';
+
+@Module({
+  controllers: [MigrationController],
+  providers: [
+    MigrationRepository,
+    BookloreConnector,
+    BookloreSourceAdapter,
+    SourceAdapterRegistry,
+    MatchingService,
+    MigrationPlannerService,
+    PathMappingValidationService,
+    MigrationExecutorService,
+    MigrationReportingService,
+    MigrationService,
+  ],
+  exports: [MigrationRepository, MigrationService],
+})
+export class MigrationModule {}
diff --git a/server/src/modules/migration/migration.repository.ts b/server/src/modules/migration/migration.repository.ts
new file mode 100644
index 000000000..61c24210b
--- /dev/null
+++ b/server/src/modules/migration/migration.repository.ts
@@ -0,0 +1,266 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../db';
+import * as schema from '../../db/schema';
+
+type Db = NodePgDatabase<typeof schema>;
+type MigrationRunState = 'draft' | 'preflight_failed' | 'dry_run_ready' | 'running' | 'failed' | 'completed';
+const ACTIVE_RUN_STATES: MigrationRunState[] = ['running'];
+
+@Injectable()
+export class MigrationRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  listSources() {
+    return this.db.select().from(schema.migrationSources).orderBy(desc(schema.migrationSources.id));
+  }
+
+  async createSource(values: Pick<schema.NewMigrationSource, 'type' | 'name' | 'connectionConfig' | 'capabilities' | 'createdByUserId'>) {
+    const [row] = await this.db.insert(schema.migrationSources).values(values).returning();
+    return row;
+  }
+
+  async updateSource(id: number, values: Pick<schema.NewMigrationSource, 'type' | 'name' | 'connectionConfig' | 'capabilities' | 'createdByUserId'>) {
+    const [row] = await this.db
+      .update(schema.migrationSources)
+      .set({
+        type: values.type,
+        name: values.name,
+        connectionConfig: values.connectionConfig,
+        capabilities: values.capabilities,
+        createdByUserId: values.createdByUserId,
+      })
+      .where(eq(schema.migrationSources.id, id))
+      .returning();
+    return row ?? null;
+  }
+
+  async updateSourceValidation(id: number, patch: Pick<schema.NewMigrationSource, 'capabilities' | 'lastValidatedAt'>) {
+    const [row] = await this.db
+      .update(schema.migrationSources)
+      .set({ capabilities: patch.capabilities, lastValidatedAt: patch.lastValidatedAt })
+      .where(eq(schema.migrationSources.id, id))
+      .returning();
+    return row ?? null;
+  }
+
+  findSourceById(id: number) {
+    return this.db.query.migrationSources.findFirst({ where: eq(schema.migrationSources.id, id) });
+  }
+
+  listTargetUsersForMapping() {
+    return this.db
+      .select({
+        id: schema.users.id,
+        username: schema.users.username,
+        name: schema.users.name,
+        email: schema.users.email,
+      })
+      .from(schema.users)
+      .where(eq(schema.users.active, true))
+      .orderBy(asc(schema.users.username));
+  }
+
+  async findExistingBookFilePaths(paths: string[]): Promise<Set<string>> {
+    const uniquePaths = [...new Set(paths.filter((value) => value.trim().length > 0))];
+    if (uniquePaths.length === 0) return new Set();
+
+    const out = new Set<string>();
+    const chunkSize = 500;
+
+    for (let index = 0; index < uniquePaths.length; index += chunkSize) {
+      const chunk = uniquePaths.slice(index, index + chunkSize);
+      const rows = await this.db
+        .select({ absolutePath: schema.bookFiles.absolutePath })
+        .from(schema.bookFiles)
+        .where(inArray(schema.bookFiles.absolutePath, chunk));
+      for (const row of rows) out.add(row.absolutePath);
+    }
+
+    return out;
+  }
+
+  listProfiles(sourceId?: number) {
+    if (sourceId === undefined) {
+      return this.db.select().from(schema.migrationProfiles).orderBy(desc(schema.migrationProfiles.id));
+    }
+    return this.db
+      .select()
+      .from(schema.migrationProfiles)
+      .where(eq(schema.migrationProfiles.sourceId, sourceId))
+      .orderBy(desc(schema.migrationProfiles.id));
+  }
+
+  async createProfile(
+    values: Pick<schema.NewMigrationProfile, 'sourceId' | 'name' | 'version' | 'userMappings' | 'pathMappings' | 'scope' | 'createdByUserId'>,
+  ) {
+    const [row] = await this.db.insert(schema.migrationProfiles).values(values).returning();
+    return row;
+  }
+
+  findProfileById(id: number) {
+    return this.db.query.migrationProfiles.findFirst({ where: eq(schema.migrationProfiles.id, id) });
+  }
+
+  async createPlanArtifact(
+    values: Pick<
+      schema.NewMigrationPlanArtifact,
+      'sourceId' | 'profileId' | 'sourceSnapshotHash' | 'profileHash' | 'planHash' | 'plan' | 'summary' | 'createdByUserId'
+    >,
+  ) {
+    const [row] = await this.db.insert(schema.migrationPlanArtifacts).values(values).returning();
+    return row;
+  }
+
+  listPlanArtifacts(sourceId?: number) {
+    if (sourceId === undefined) {
+      return this.db.select().from(schema.migrationPlanArtifacts).orderBy(desc(schema.migrationPlanArtifacts.id));
+    }
+    return this.db
+      .select()
+      .from(schema.migrationPlanArtifacts)
+      .where(eq(schema.migrationPlanArtifacts.sourceId, sourceId))
+      .orderBy(desc(schema.migrationPlanArtifacts.id));
+  }
+
+  findPlanArtifactById(id: number) {
+    return this.db.query.migrationPlanArtifacts.findFirst({ where: eq(schema.migrationPlanArtifacts.id, id) });
+  }
+
+  async purgeRunState(sourceId: number): Promise<void> {
+    await this.db.delete(schema.migrationRuns).where(eq(schema.migrationRuns.sourceId, sourceId));
+    await this.db.delete(schema.migrationPlanArtifacts).where(eq(schema.migrationPlanArtifacts.sourceId, sourceId));
+  }
+
+  async findBookTitlesByIds(ids: number[]): Promise<Map<number, string | null>> {
+    if (ids.length === 0) return new Map();
+    const rows = await this.db
+      .select({ bookId: schema.bookMetadata.bookId, title: schema.bookMetadata.title })
+      .from(schema.bookMetadata)
+      .where(inArray(schema.bookMetadata.bookId, ids));
+    return new Map(rows.map((row) => [row.bookId, row.title ?? null]));
+  }
+
+  async createRunWithLock(
+    values: Pick<
+      schema.NewMigrationRun,
+      'sourceId' | 'profileId' | 'planArtifactId' | 'targetKey' | 'state' | 'currentStage' | 'triggeredByUserId' | 'startedAt'
+    >,
+  ): Promise<{ run: typeof schema.migrationRuns.$inferSelect | null; activeRun: typeof schema.migrationRuns.$inferSelect | null }> {
+    const targetKey = values.targetKey ?? 'projectx';
+    return this.db.transaction(async (tx) => {
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${buildRunLockKey(values.sourceId, targetKey)}))`);
+
+      const [activeRun] = await tx
+        .select()
+        .from(schema.migrationRuns)
+        .where(
+          and(
+            eq(schema.migrationRuns.sourceId, values.sourceId),
+            eq(schema.migrationRuns.targetKey, targetKey),
+            inArray(schema.migrationRuns.state, ACTIVE_RUN_STATES),
+          ),
+        )
+        .orderBy(desc(schema.migrationRuns.id))
+        .limit(1);
+
+      if (activeRun) return { run: null, activeRun };
+
+      await tx.delete(schema.migrationRuns).where(eq(schema.migrationRuns.sourceId, values.sourceId));
+
+      const [run] = await tx
+        .insert(schema.migrationRuns)
+        .values({ ...values, targetKey })
+        .returning();
+      return { run, activeRun: null };
+    });
+  }
+
+  listRuns(sourceId?: number) {
+    if (sourceId === undefined) {
+      return this.db.select().from(schema.migrationRuns).orderBy(desc(schema.migrationRuns.id));
+    }
+    return this.db.select().from(schema.migrationRuns).where(eq(schema.migrationRuns.sourceId, sourceId)).orderBy(desc(schema.migrationRuns.id));
+  }
+
+  findRunById(id: number) {
+    return this.db.query.migrationRuns.findFirst({ where: eq(schema.migrationRuns.id, id) });
+  }
+
+  async updateRunState(
+    runId: number,
+    state: MigrationRunState,
+    patch: Partial<Pick<schema.NewMigrationRun, 'currentStage' | 'startedAt' | 'endedAt' | 'errorMessage'>>,
+  ) {
+    const [row] = await this.db
+      .update(schema.migrationRuns)
+      .set({ ...patch, state })
+      .where(eq(schema.migrationRuns.id, runId))
+      .returning();
+    return row ?? null;
+  }
+
+  async incrementRunMetric(
+    runId: number,
+    stage: string,
+    entityType: string,
+    delta: Partial<Pick<typeof schema.migrationRunMetrics.$inferInsert, 'processed' | 'imported' | 'skipped' | 'unresolved' | 'failed'>>,
+  ) {
+    const [existing] = await this.db
+      .select()
+      .from(schema.migrationRunMetrics)
+      .where(
+        and(
+          eq(schema.migrationRunMetrics.runId, runId),
+          eq(schema.migrationRunMetrics.stage, stage),
+          eq(schema.migrationRunMetrics.entityType, entityType),
+        ),
+      )
+      .limit(1);
+
+    if (!existing) {
+      const [inserted] = await this.db
+        .insert(schema.migrationRunMetrics)
+        .values({
+          runId,
+          stage,
+          entityType,
+          processed: delta.processed ?? 0,
+          imported: delta.imported ?? 0,
+          skipped: delta.skipped ?? 0,
+          unresolved: delta.unresolved ?? 0,
+          failed: delta.failed ?? 0,
+        })
+        .returning();
+      return inserted;
+    }
+
+    const [updated] = await this.db
+      .update(schema.migrationRunMetrics)
+      .set({
+        processed: existing.processed + (delta.processed ?? 0),
+        imported: existing.imported + (delta.imported ?? 0),
+        skipped: existing.skipped + (delta.skipped ?? 0),
+        unresolved: existing.unresolved + (delta.unresolved ?? 0),
+        failed: existing.failed + (delta.failed ?? 0),
+        updatedAt: sql`now()`,
+      })
+      .where(eq(schema.migrationRunMetrics.id, existing.id))
+      .returning();
+    return updated;
+  }
+
+  listRunMetrics(runId: number) {
+    return this.db
+      .select()
+      .from(schema.migrationRunMetrics)
+      .where(eq(schema.migrationRunMetrics.runId, runId))
+      .orderBy(asc(schema.migrationRunMetrics.stage), asc(schema.migrationRunMetrics.entityType));
+  }
+}
+
+function buildRunLockKey(sourceId: number, targetKey: string): string {
+  return `migration-run-lock:${sourceId}:${targetKey}`;
+}
diff --git a/server/src/modules/migration/migration.service.test.ts b/server/src/modules/migration/migration.service.test.ts
new file mode 100644
index 000000000..936f80be1
--- /dev/null
+++ b/server/src/modules/migration/migration.service.test.ts
@@ -0,0 +1,251 @@
+import { BadRequestException, ConflictException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MigrationService } from './migration.service';
+
+function createService(overrides: Partial<Record<string, unknown>> = {}): MigrationService {
+  const repo = {
+    findSourceById: vi.fn(() =>
+      Promise.resolve({
+        id: 1,
+        type: 'booklore',
+        name: 'Booklore',
+        connectionConfig: {},
+        capabilities: null,
+        lastValidatedAt: new Date(),
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    ),
+    listTargetUsersForMapping: vi.fn(() =>
+      Promise.resolve([
+        {
+          id: 10,
+          username: 'target-user',
+          name: 'Target User',
+          email: 'target@example.com',
+        },
+      ]),
+    ),
+    listProfiles: vi.fn(() => Promise.resolve([])),
+    createProfile: vi.fn(),
+    findProfileById: vi.fn(() =>
+      Promise.resolve({
+        id: 2,
+        sourceId: 1,
+        name: 'Booklore Migration',
+        version: 1,
+        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+        pathMappings: [],
+        scope: { preflight: { pathValidatedAt: new Date().toISOString() } },
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    ),
+    listRuns: vi.fn(() => Promise.resolve([])),
+    findPlanArtifactById: vi.fn(() =>
+      Promise.resolve({
+        id: 100,
+        sourceId: 1,
+        profileId: 2,
+        sourceSnapshotHash: 'a',
+        profileHash: 'b',
+        planHash: 'd',
+        plan: {},
+        summary: {},
+        createdByUserId: 1,
+        createdAt: new Date(Date.now() + 1000),
+        updatedAt: new Date(),
+      }),
+    ),
+    createRunWithLock: vi.fn(() =>
+      Promise.resolve({
+        run: null,
+        activeRun: {
+          id: 77,
+          sourceId: 1,
+          profileId: 2,
+          planArtifactId: 100,
+          targetKey: 'projectx',
+          state: 'running',
+          currentStage: 'init',
+          triggeredByUserId: 1,
+          startedAt: new Date(),
+          endedAt: null,
+          errorMessage: null,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      }),
+    ),
+    purgeRunState: vi.fn(() => Promise.resolve()),
+    ...overrides,
+  };
+
+  return new MigrationService(
+    repo as never,
+    { listTypes: vi.fn(), get: vi.fn() } as never,
+    { buildPlan: vi.fn() } as never,
+    { start: vi.fn() } as never,
+    { getRunProgress: vi.fn(), getRunReport: vi.fn(), exportRunReport: vi.fn() } as never,
+    { validate: vi.fn() } as never,
+  );
+}
+
+describe('MigrationService', () => {
+  it('rejects profile creation when target user mapping IDs are invalid', async () => {
+    const service = createService();
+
+    await expect(
+      service.createProfile(
+        {
+          sourceId: 1,
+          name: 'Profile',
+          userMappings: [{ sourceUserId: 'src-user', targetUserId: 999 }],
+          pathMappings: [],
+        },
+        1,
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects live run start when another active run exists for the same source and target', async () => {
+    const service = createService();
+
+    await expect(
+      service.startLiveRun(
+        {
+          planArtifactId: 100,
+          targetKey: 'projectx',
+        },
+        1,
+      ),
+    ).rejects.toBeInstanceOf(ConflictException);
+  });
+
+  it('allows live run start without path validation when no path mappings are configured', async () => {
+    const run = {
+      id: 78,
+      sourceId: 1,
+      profileId: 2,
+      planArtifactId: 100,
+      targetKey: 'projectx',
+      state: 'running',
+      currentStage: 'init',
+      triggeredByUserId: 1,
+      startedAt: new Date(),
+      endedAt: null,
+      errorMessage: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    const service = createService({
+      findProfileById: vi.fn(() =>
+        Promise.resolve({
+          id: 2,
+          sourceId: 1,
+          name: 'Booklore Migration',
+          version: 1,
+          userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+          pathMappings: [],
+          scope: {},
+          createdByUserId: 1,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        }),
+      ),
+      createRunWithLock: vi.fn(() => Promise.resolve({ run, activeRun: null })),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).resolves.toEqual({
+      id: 78,
+      sourceId: 1,
+      profileId: 2,
+      planArtifactId: 100,
+      state: 'running',
+      currentStage: 'init',
+      startedAt: run.startedAt,
+      endedAt: null,
+      errorMessage: null,
+      createdAt: run.createdAt,
+      updatedAt: run.updatedAt,
+    });
+  });
+
+  it('rejects live run start when configured path mappings have not been validated', async () => {
+    const service = createService({
+      findProfileById: vi.fn(() =>
+        Promise.resolve({
+          id: 2,
+          sourceId: 1,
+          name: 'Booklore Migration',
+          version: 1,
+          userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+          pathMappings: [{ sourcePrefix: '/source', targetPrefix: '/target' }],
+          scope: {},
+          createdByUserId: 1,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        }),
+      ),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('creates a new profile version instead of overwriting the current one', async () => {
+    const createProfile = vi.fn(() =>
+      Promise.resolve({
+        id: 3,
+        sourceId: 1,
+        name: 'Booklore Migration',
+        version: 4,
+        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+        pathMappings: [],
+        scope: {},
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    );
+    const service = createService({
+      listProfiles: vi.fn(() =>
+        Promise.resolve([
+          {
+            id: 2,
+            sourceId: 1,
+            name: 'Booklore Migration',
+            version: 3,
+            userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+            pathMappings: [],
+            scope: {},
+            createdByUserId: 1,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          },
+        ]),
+      ),
+      createProfile,
+    });
+
+    await service.createProfile(
+      {
+        sourceId: 1,
+        name: 'Booklore Migration',
+        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+        pathMappings: [],
+      },
+      1,
+    );
+
+    expect(createProfile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sourceId: 1,
+        name: 'Booklore Migration',
+        version: 4,
+      }),
+    );
+  });
+});
diff --git a/server/src/modules/migration/migration.service.ts b/server/src/modules/migration/migration.service.ts
new file mode 100644
index 000000000..23d66a83a
--- /dev/null
+++ b/server/src/modules/migration/migration.service.ts
@@ -0,0 +1,576 @@
+import { BadRequestException, ConflictException, Injectable, InternalServerErrorException, NotFoundException } from '@nestjs/common';
+
+import { CreateDryRunPlanDto } from './dto/create-dry-run-plan.dto';
+import { CreateMigrationProfileDto } from './dto/create-migration-profile.dto';
+import { CreateMigrationSourceDto } from './dto/create-migration-source.dto';
+import { StartLiveRunDto } from './dto/start-live-run.dto';
+import { TestMigrationSourceDto } from './dto/test-migration-source.dto';
+import { ValidatePathMappingsDto } from './dto/validate-path-mappings.dto';
+import { buildPlanHash, buildProfileHash, buildSourceSnapshotHash } from './core/plan-hash';
+import { MigrationRepository } from './migration.repository';
+import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
+import { MigrationPlannerService } from './planner/planner.service';
+import { MigrationExecutorService } from './executor/migration-executor.service';
+import { MigrationReportingService } from './reporting/migration-reporting.service';
+import { parseBookloreConnectionConfig } from './adapters/booklore/booklore-connection-config';
+import { PathMappingValidationService } from './planner/path-mapping-validation.service';
+
+const ACTIVE_LIVE_STATES = new Set(['running']);
+
+type MigrationSourceRow = Awaited<ReturnType<MigrationRepository['listSources']>>[number];
+type MigrationProfileRow = Awaited<ReturnType<MigrationRepository['listProfiles']>>[number];
+type MigrationPlanArtifactRow = Awaited<ReturnType<MigrationRepository['listPlanArtifacts']>>[number];
+type MigrationRunRow = Awaited<ReturnType<MigrationRepository['listRuns']>>[number];
+
+export interface ApiMigrationSource {
+  id: number;
+  type: string;
+  name: string;
+  connectionConfig: unknown;
+  capabilities: MigrationSourceRow['capabilities'];
+  lastValidatedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationProfile {
+  id: number;
+  sourceId: number;
+  name: string;
+  userMappings: MigrationProfileRow['userMappings'];
+  pathMappings: MigrationProfileRow['pathMappings'];
+  scope: MigrationProfileRow['scope'];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationPlanArtifact {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  plan: MigrationPlanArtifactRow['plan'];
+  summary: MigrationPlanArtifactRow['summary'];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationRun {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  planArtifactId: number | null;
+  state: MigrationRunRow['state'];
+  currentStage: string | null;
+  startedAt: Date | null;
+  endedAt: Date | null;
+  errorMessage: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface WorkflowStateBundle {
+  source: MigrationSourceRow;
+  profile: MigrationProfileRow | null;
+  plan: MigrationPlanArtifactRow | null;
+  run: MigrationRunRow | null;
+}
+
+@Injectable()
+export class MigrationService {
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly adapterRegistry: SourceAdapterRegistry,
+    private readonly planner: MigrationPlannerService,
+    private readonly executor: MigrationExecutorService,
+    private readonly reporting: MigrationReportingService,
+    private readonly pathValidator: PathMappingValidationService,
+  ) {}
+
+  listSupportedSourceTypes() {
+    return this.adapterRegistry.listTypes();
+  }
+
+  async testSource(dto: TestMigrationSourceDto) {
+    const adapter = this.adapterRegistry.get(dto.type);
+    return adapter.validate(parseConnectionConfig(dto.type, dto.connectionConfig));
+  }
+
+  async validateSourceById(sourceId: number) {
+    const source = await this.repo.findSourceById(sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${sourceId}`);
+
+    const adapter = this.adapterRegistry.get(source.type);
+    const result = await adapter.validate(parseConnectionConfig(source.type, source.connectionConfig));
+
+    await this.repo.updateSourceValidation(source.id, {
+      capabilities: {
+        sourceType: result.sourceType,
+        sourceVersion: result.sourceVersion,
+        warnings: result.warnings,
+        counts: result.counts,
+        missingTables: result.missingTables,
+      },
+      lastValidatedAt: new Date(),
+    });
+    await this.repo.purgeRunState(source.id);
+
+    return result;
+  }
+
+  async createSource(dto: CreateMigrationSourceDto, userId: number) {
+    await this.assertNoGlobalActiveRun();
+
+    const adapter = this.adapterRegistry.get(dto.type);
+    const validation = await adapter.validate(parseConnectionConfig(dto.type, dto.connectionConfig));
+    const payload = {
+      type: dto.type.trim().toLowerCase(),
+      name: dto.name.trim(),
+      connectionConfig: dto.connectionConfig,
+      capabilities: {
+        sourceType: validation.sourceType,
+        sourceVersion: validation.sourceVersion,
+        warnings: validation.warnings,
+        counts: validation.counts,
+        missingTables: validation.missingTables,
+      },
+      createdByUserId: userId,
+    } as const;
+
+    const state = await this.getWorkflowState();
+    const sources = await this.repo.listSources();
+
+    const source = state.active?.source
+      ? await this.repo.updateSource(state.active.source.id, {
+          ...payload,
+          name: buildUniqueSourceName(payload.name, payload.type, sources, state.active.source.id),
+        })
+      : await this.repo.createSource({
+          ...payload,
+          name: buildUniqueSourceName(payload.name, payload.type, sources),
+        });
+
+    if (!source) throw new InternalServerErrorException('Failed to save migration source');
+    await this.repo.purgeRunState(source.id);
+    return sanitizeSourceForApi(source);
+  }
+
+  listTargetUsers() {
+    return this.repo.listTargetUsersForMapping();
+  }
+
+  async createProfile(dto: CreateMigrationProfileDto, userId: number) {
+    await this.assertNoGlobalActiveRun();
+
+    const source = await this.repo.findSourceById(dto.sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${dto.sourceId}`);
+
+    const targetUsers = await this.repo.listTargetUsersForMapping();
+    const knownTargetUserIds = new Set(targetUsers.map((row) => row.id));
+    const requestedTargetUserIds = [...new Set(dto.userMappings.map((row) => row.targetUserId))];
+    const unknownTargetUserIds = requestedTargetUserIds.filter((targetUserId) => !knownTargetUserIds.has(targetUserId));
+    if (unknownTargetUserIds.length > 0) {
+      throw new BadRequestException(`Invalid target user IDs in mapping: ${unknownTargetUserIds.join(', ')}`);
+    }
+
+    const payload = {
+      sourceId: dto.sourceId,
+      name: dto.name.trim(),
+      userMappings: dto.userMappings,
+      pathMappings: dto.pathMappings ?? [],
+      scope: dto.scope ?? {},
+      createdByUserId: userId,
+    } as const;
+
+    const existingProfiles = await this.repo.listProfiles(dto.sourceId);
+    const profile = await this.repo.createProfile({
+      ...payload,
+      version: (existingProfiles[0]?.version ?? 0) + 1,
+    });
+    if (!profile) throw new InternalServerErrorException('Failed to save migration profile');
+    await this.repo.purgeRunState(dto.sourceId);
+    return sanitizeProfileForApi(profile);
+  }
+
+  async suggestUserMappings(sourceId: number) {
+    const source = await this.repo.findSourceById(sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${sourceId}`);
+
+    const adapter = this.adapterRegistry.get(source.type);
+    const sourceData = await adapter.exportData(parseConnectionConfig(source.type, source.connectionConfig));
+    const targetUsers = await this.repo.listTargetUsersForMapping();
+
+    const suggestions = sourceData.users.map((sourceUser) => {
+      const candidates = targetUsers
+        .map((targetUser) => {
+          const score = scoreUserMapping(sourceUser, targetUser);
+          return {
+            targetUserId: targetUser.id,
+            username: targetUser.username,
+            name: targetUser.name,
+            email: targetUser.email,
+            score,
+            confidence: confidenceLabel(score),
+          };
+        })
+        .filter((candidate) => candidate.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3);
+
+      return {
+        sourceUserId: sourceUser.sourceUserId,
+        username: sourceUser.username,
+        name: sourceUser.name,
+        email: sourceUser.email,
+        suggestedTargetUserId: candidates[0]?.targetUserId ?? null,
+        confidence: candidates[0]?.confidence ?? null,
+        candidates,
+      };
+    });
+
+    return {
+      sourceId,
+      generatedAt: new Date().toISOString(),
+      suggestions,
+    };
+  }
+
+  async getSourcePathPrefixes(sourceId: number): Promise<{ prefixes: string[] }> {
+    const source = await this.repo.findSourceById(sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${sourceId}`);
+    const adapter = this.adapterRegistry.get(source.type);
+    if (!adapter.fetchPathPrefixes) return { prefixes: [] };
+    const prefixes = await adapter.fetchPathPrefixes(parseConnectionConfig(source.type, source.connectionConfig));
+    return { prefixes };
+  }
+
+  async validatePathMappings(sourceId: number, dto: ValidatePathMappingsDto) {
+    const source = await this.repo.findSourceById(sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${sourceId}`);
+
+    const adapter = this.adapterRegistry.get(source.type);
+    const sourceData = await adapter.exportData(parseConnectionConfig(source.type, source.connectionConfig));
+
+    const validation = await this.pathValidator.validate({
+      sourceBooks: sourceData.books,
+      pathMappings: dto.pathMappings,
+      sampleLimit: dto.sampleLimit,
+    });
+
+    return {
+      sourceId,
+      validatedAt: new Date().toISOString(),
+      ...validation,
+    };
+  }
+
+  async createDryRunPlan(dto: CreateDryRunPlanDto, userId: number) {
+    await this.assertNoGlobalActiveRun();
+
+    const profile = await this.repo.findProfileById(dto.profileId);
+    if (!profile) throw new NotFoundException(`Migration profile not found: ${dto.profileId}`);
+
+    const source = await this.repo.findSourceById(profile.sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${profile.sourceId}`);
+
+    await this.repo.purgeRunState(source.id);
+
+    const planned = await this.planner.buildPlan({
+      source,
+      profile,
+      scopeOverride: dto.scopeOverride,
+    });
+
+    const sourceSnapshotHash = buildSourceSnapshotHash(planned.plan.snapshot);
+    const profileHash = buildProfileHash(profile);
+    const planHash = buildPlanHash({ sourceSnapshotHash, profileHash, plan: planned.plan });
+
+    const summary = {
+      generatedAt: planned.plan.generatedAt,
+      status: planned.plan.duplicateBookMatches.length > 0 ? 'blocked' : 'ready_for_live_run',
+      matchedBooks: planned.plan.matchedBooks.length,
+      unresolvedBooks: planned.plan.unresolvedBooks.length,
+      duplicateBookMatches: planned.plan.duplicateBookMatches.length,
+      unresolvedByReason: planned.plan.unresolvedBooks.reduce<Record<string, number>>((acc, row) => {
+        acc[row.reason] = (acc[row.reason] ?? 0) + 1;
+        return acc;
+      }, {}),
+      mappedUsers: planned.plan.userPreview.length,
+      perUserPreview: planned.plan.userPreview,
+    };
+
+    const artifact = await this.repo.createPlanArtifact({
+      sourceId: source.id,
+      profileId: profile.id,
+      sourceSnapshotHash,
+      profileHash,
+      planHash,
+      plan: planned.plan,
+      summary,
+      createdByUserId: userId,
+    });
+    return sanitizePlanArtifactForApi(artifact);
+  }
+
+  async startLiveRun(dto: StartLiveRunDto, userId: number) {
+    await this.assertNoGlobalActiveRun();
+
+    const artifact = await this.repo.findPlanArtifactById(dto.planArtifactId);
+    if (!artifact) throw new NotFoundException(`Migration plan artifact not found: ${dto.planArtifactId}`);
+    const artifactPlan = asRecord(artifact.plan);
+    const duplicateBookMatches = Array.isArray(artifactPlan.duplicateBookMatches) ? artifactPlan.duplicateBookMatches : [];
+    if (duplicateBookMatches.length > 0) {
+      throw new BadRequestException('Cannot start migration: dry-run has duplicate target book matches. Resolve matching before running migration.');
+    }
+
+    const source = await this.repo.findSourceById(artifact.sourceId);
+    if (!source) throw new NotFoundException(`Migration source not found: ${artifact.sourceId}`);
+    if (!source.lastValidatedAt) {
+      throw new BadRequestException('Validate source before starting migration.');
+    }
+
+    const profile = await this.repo.findProfileById(artifact.profileId);
+    if (!profile) throw new NotFoundException(`Migration profile not found: ${artifact.profileId}`);
+    if (profile.sourceId !== source.id) {
+      throw new BadRequestException('Plan artifact profile does not match source.');
+    }
+    const profileMappings = Array.isArray(profile.userMappings) ? profile.userMappings : [];
+    if (profileMappings.length === 0) {
+      throw new BadRequestException('Save user mappings before starting migration.');
+    }
+
+    const scope = asRecord(profile.scope);
+    const preflightScope = asRecord(scope.preflight);
+    const pathValidatedAt = asString(preflightScope.pathValidatedAt);
+    const pathMappings = Array.isArray(profile.pathMappings) ? profile.pathMappings : [];
+    if (pathMappings.length > 0 && !pathValidatedAt) {
+      throw new BadRequestException('Validate path mappings before starting migration.');
+    }
+
+    const freshnessAnchor = latestDate(source.lastValidatedAt, source.updatedAt, profile.updatedAt);
+    if (artifact.createdAt < freshnessAnchor) {
+      throw new BadRequestException('Dry-run plan is stale. Re-run dry-run after latest source/profile updates.');
+    }
+
+    const targetKey = normalizeTargetKey(dto.targetKey);
+    const { run, activeRun } = await this.repo.createRunWithLock({
+      sourceId: artifact.sourceId,
+      profileId: artifact.profileId,
+      planArtifactId: artifact.id,
+      targetKey,
+      state: 'running',
+      currentStage: 'init',
+      triggeredByUserId: userId,
+      startedAt: new Date(),
+    });
+    if (!run && activeRun) {
+      throw new ConflictException(
+        `Another migration run is active for source=${artifact.sourceId} target=${targetKey} (runId=${activeRun.id}, state=${activeRun.state})`,
+      );
+    }
+    if (!run) {
+      throw new InternalServerErrorException('Failed to create migration run');
+    }
+
+    this.executor.start(run.id);
+    return sanitizeRunForApi(run);
+  }
+
+  getRunProgress(runId: number) {
+    return this.reporting.getRunProgress(runId);
+  }
+
+  getRunReport(runId: number) {
+    return this.reporting.getRunReport(runId);
+  }
+
+  exportRunReport(runId: number, format?: string) {
+    return this.reporting.exportRunReport(runId, format);
+  }
+
+  async getWorkflowState() {
+    const [sources, profiles, plans, runs] = await Promise.all([
+      this.repo.listSources(),
+      this.repo.listProfiles(),
+      this.repo.listPlanArtifacts(),
+      this.repo.listRuns(),
+    ]);
+
+    const activeRun = runs.find((row) => ACTIVE_LIVE_STATES.has(row.state)) ?? null;
+    const sourceById = new Map(sources.map((row) => [row.id, row]));
+    const activeSource = activeRun ? (sourceById.get(activeRun.sourceId) ?? null) : (sources[0] ?? null);
+    const activeBundle = this.resolveActiveBundle(activeSource, profiles, plans, runs);
+
+    return {
+      active: activeBundle
+        ? {
+            source: sanitizeSourceForApi(activeBundle.source),
+            profile: activeBundle.profile ? sanitizeProfileForApi(activeBundle.profile) : null,
+            plan: activeBundle.plan ? sanitizePlanArtifactForApi(activeBundle.plan) : null,
+            run: activeBundle.run ? sanitizeRunForApi(activeBundle.run) : null,
+          }
+        : null,
+      hasActiveRun: activeRun != null,
+    };
+  }
+
+  private resolveActiveBundle(
+    source: MigrationSourceRow | null,
+    profiles: Awaited<ReturnType<MigrationRepository['listProfiles']>>,
+    plans: Awaited<ReturnType<MigrationRepository['listPlanArtifacts']>>,
+    runs: Awaited<ReturnType<MigrationRepository['listRuns']>>,
+  ): WorkflowStateBundle | null {
+    if (!source) return null;
+    const profile = profiles.find((row) => row.sourceId === source.id) ?? null;
+    const plan = profile
+      ? (plans.find((row) => row.profileId === profile.id) ?? plans.find((row) => row.sourceId === source.id) ?? null)
+      : (plans.find((row) => row.sourceId === source.id) ?? null);
+    const run = runs.find((row) => row.sourceId === source.id) ?? null;
+    return { source, profile, plan, run };
+  }
+
+  private async assertNoGlobalActiveRun() {
+    const runs = await this.repo.listRuns();
+    const active = runs.find((row) => ACTIVE_LIVE_STATES.has(row.state));
+    if (!active) return;
+    throw new ConflictException(`Another migration run is active (runId=${active.id}, state=${active.state}).`);
+  }
+}
+
+function parseConnectionConfig(type: string, raw: unknown): unknown {
+  if (type === 'booklore') {
+    return parseBookloreConnectionConfig(raw);
+  }
+  return asRecord(raw);
+}
+
+function normalizeTargetKey(value: string | undefined): string {
+  const normalized = value?.trim();
+  return normalized ? normalized : 'projectx';
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function scoreUserMapping(
+  sourceUser: { username: string; email: string | null; name: string | null },
+  targetUser: { username: string; email: string | null; name: string },
+): number {
+  const sUsername = sourceUser.username.trim().toLowerCase();
+  const tUsername = targetUser.username.trim().toLowerCase();
+  const sEmail = sourceUser.email?.trim().toLowerCase() ?? null;
+  const tEmail = targetUser.email?.trim().toLowerCase() ?? null;
+  const sName = sourceUser.name?.trim().toLowerCase() ?? null;
+  const tName = targetUser.name.trim().toLowerCase();
+
+  if (sEmail && tEmail && sEmail === tEmail) return 100;
+  if (sUsername && tUsername && sUsername === tUsername) return 95;
+  if (sName && tName && sName === tName) return 85;
+  if (sUsername && tUsername && (sUsername.includes(tUsername) || tUsername.includes(sUsername))) return 70;
+  if (sName && tName && (sName.includes(tName) || tName.includes(sName))) return 60;
+  return 0;
+}
+
+function confidenceLabel(score: number): 'high' | 'medium' | 'low' {
+  if (score >= 90) return 'high';
+  if (score >= 70) return 'medium';
+  return 'low';
+}
+
+function sanitizeSourceForApi(source: MigrationSourceRow): ApiMigrationSource {
+  return {
+    id: source.id,
+    type: source.type,
+    name: source.name,
+    connectionConfig: redactConnectionConfig(source.type, source.connectionConfig),
+    capabilities: source.capabilities,
+    lastValidatedAt: source.lastValidatedAt,
+    createdAt: source.createdAt,
+    updatedAt: source.updatedAt,
+  };
+}
+
+function sanitizeProfileForApi(profile: MigrationProfileRow): ApiMigrationProfile {
+  return {
+    id: profile.id,
+    sourceId: profile.sourceId,
+    name: profile.name,
+    userMappings: profile.userMappings,
+    pathMappings: profile.pathMappings,
+    scope: profile.scope,
+    createdAt: profile.createdAt,
+    updatedAt: profile.updatedAt,
+  };
+}
+
+function sanitizePlanArtifactForApi(artifact: MigrationPlanArtifactRow): ApiMigrationPlanArtifact {
+  return {
+    id: artifact.id,
+    sourceId: artifact.sourceId,
+    profileId: artifact.profileId,
+    plan: artifact.plan,
+    summary: artifact.summary,
+    createdAt: artifact.createdAt,
+    updatedAt: artifact.updatedAt,
+  };
+}
+
+function sanitizeRunForApi(run: MigrationRunRow): ApiMigrationRun {
+  return {
+    id: run.id,
+    sourceId: run.sourceId,
+    profileId: run.profileId,
+    planArtifactId: run.planArtifactId,
+    state: run.state,
+    currentStage: run.currentStage,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    errorMessage: run.errorMessage,
+    createdAt: run.createdAt,
+    updatedAt: run.updatedAt,
+  };
+}
+
+function redactConnectionConfig(type: string, raw: unknown): unknown {
+  const config = asRecord(raw);
+  if (type !== 'booklore') return config;
+
+  return {
+    ...config,
+    password: typeof config.password === 'string' && config.password.length > 0 ? '********' : '',
+  };
+}
+
+function buildUniqueSourceName(
+  desiredName: string,
+  sourceType: string,
+  sources: Array<{ id: number; type: string; name: string }>,
+  ignoreId?: number,
+): string {
+  const trimmed = desiredName.trim();
+  const safeBase = trimmed.length > 0 ? trimmed : 'Booklore Import';
+  const names = new Set(sources.filter((row) => row.type === sourceType && row.id !== ignoreId).map((row) => row.name.toLowerCase()));
+
+  if (!names.has(safeBase.toLowerCase())) return safeBase;
+
+  let counter = 2;
+  while (counter < 10_000) {
+    const candidate = `${safeBase} ${counter}`;
+    if (!names.has(candidate.toLowerCase())) return candidate;
+    counter += 1;
+  }
+
+  return `${safeBase} ${Date.now()}`;
+}
+
+function latestDate(...dates: Date[]): Date {
+  const [first, ...rest] = dates;
+  return rest.reduce((max, current) => (current > max ? current : max), first);
+}
diff --git a/server/src/modules/migration/planner/matching.service.test.ts b/server/src/modules/migration/planner/matching.service.test.ts
new file mode 100644
index 000000000..1178d3cb0
--- /dev/null
+++ b/server/src/modules/migration/planner/matching.service.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { applyPathMappings, deriveUnresolvedReason } from './matching.service';
+
+describe('applyPathMappings', () => {
+  it('uses the most specific source prefix when multiple mappings match', () => {
+    const mapped = applyPathMappings('/mnt/books/fiction/Dune.epub', [
+      { sourcePrefix: '/mnt/books', targetPrefix: '/library' },
+      { sourcePrefix: '/mnt/books/fiction', targetPrefix: '/library/fiction' },
+    ]);
+
+    expect(mapped).toBe('/library/fiction/Dune.epub');
+  });
+
+  it('returns the original path when no prefix matches', () => {
+    const mapped = applyPathMappings('/other/path/file.epub', [{ sourcePrefix: '/mnt/books', targetPrefix: '/library' }]);
+    expect(mapped).toBe('/other/path/file.epub');
+  });
+});
+
+describe('deriveUnresolvedReason', () => {
+  it('returns the highest-signal reason based on attempted strategies', () => {
+    expect(deriveUnresolvedReason(['isbn'])).toBe('no_isbn_match');
+    expect(deriveUnresolvedReason(['isbn', 'file_hash'])).toBe('no_file_hash_match');
+    expect(deriveUnresolvedReason(['isbn', 'file_hash', 'file_path'])).toBe('no_file_path_match');
+    expect(deriveUnresolvedReason(['isbn', 'file_hash', 'file_path', 'title_author'])).toBe('no_title_author_match');
+  });
+
+  it('returns insufficient_source_data when no strategy could be attempted', () => {
+    expect(deriveUnresolvedReason([])).toBe('insufficient_source_data');
+  });
+});
diff --git a/server/src/modules/migration/planner/matching.service.ts b/server/src/modules/migration/planner/matching.service.ts
new file mode 100644
index 000000000..07364b223
--- /dev/null
+++ b/server/src/modules/migration/planner/matching.service.ts
@@ -0,0 +1,217 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, eq, ilike, or } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../../db';
+import * as schema from '../../../db/schema';
+import type { SourceBook } from '../adapters/source-adapter.types';
+import type { PathMapping, PlannedBookMatch, PlannedUnresolvedBook, UnresolvedReasonCode } from './planner.types';
+
+type Db = NodePgDatabase<typeof schema>;
+type MatchAttempt = 'isbn' | 'file_hash' | 'file_path' | 'title_author';
+
+@Injectable()
+export class MatchingService {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async matchBooks(
+    sourceBooks: SourceBook[],
+    pathMappings: PathMapping[],
+  ): Promise<{ matches: PlannedBookMatch[]; unresolved: PlannedUnresolvedBook[] }> {
+    const matches: PlannedBookMatch[] = [];
+    const unresolved: PlannedUnresolvedBook[] = [];
+
+    const isbnCache = new Map<string, number | null>();
+    const fileHashCache = new Map<string, number | null>();
+    const filePathCache = new Map<string, number | null>();
+    const titleAuthorCache = new Map<string, number | null>();
+
+    for (const sourceBook of sourceBooks) {
+      const attempts: MatchAttempt[] = [];
+      const isbn = sourceBook.isbn13 ?? sourceBook.isbn10;
+      if (isbn) {
+        attempts.push('isbn');
+        const cached = isbnCache.get(isbn);
+        const bookId = cached !== undefined ? cached : await this.findByIsbn(sourceBook.isbn13, sourceBook.isbn10);
+        if (cached === undefined) isbnCache.set(isbn, bookId);
+        if (bookId) {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: bookId, strategy: 'isbn' });
+          continue;
+        }
+      }
+
+      if (sourceBook.fileHash) {
+        attempts.push('file_hash');
+        const hash = sourceBook.fileHash;
+        const cached = fileHashCache.get(hash);
+        const bookId = cached !== undefined ? cached : await this.findByFileHash(hash);
+        if (cached === undefined) fileHashCache.set(hash, bookId);
+        if (bookId) {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: bookId, strategy: 'file_hash' });
+          continue;
+        }
+      }
+
+      const mappedPath = applyPathMappings(sourceBook.filePath, pathMappings);
+      if (mappedPath) {
+        attempts.push('file_path');
+        const cached = filePathCache.get(mappedPath);
+        const bookId = cached !== undefined ? cached : await this.findByFilePath(mappedPath);
+        if (cached === undefined) filePathCache.set(mappedPath, bookId);
+        if (bookId) {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: bookId, strategy: 'path_mapping' });
+          continue;
+        }
+      }
+
+      const titleKey = normalizeTitle(sourceBook.title);
+      if (titleKey) {
+        attempts.push('title_author');
+        const authorNames = getSourceAuthorNames(sourceBook);
+        const cacheKey = buildTitleAuthorCacheKey(sourceBook.title, authorNames);
+        const cached = titleAuthorCache.get(cacheKey);
+        const bookId = cached !== undefined ? cached : await this.findByTitleAuthor(sourceBook.title ?? '', authorNames);
+        if (cached === undefined) titleAuthorCache.set(cacheKey, bookId);
+        if (bookId) {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: bookId, strategy: 'title_author' });
+          continue;
+        }
+      }
+
+      unresolved.push({
+        sourceBookId: sourceBook.sourceBookId,
+        title: sourceBook.title,
+        reason: deriveUnresolvedReason(attempts),
+      });
+    }
+
+    return { matches, unresolved };
+  }
+
+  private async findByIsbn(isbn13: string | null, isbn10: string | null): Promise<number | null> {
+    if (!isbn13 && !isbn10) return null;
+
+    const where =
+      isbn13 && isbn10
+        ? or(eq(schema.bookMetadata.isbn13, isbn13), eq(schema.bookMetadata.isbn10, isbn10))
+        : isbn13
+          ? eq(schema.bookMetadata.isbn13, isbn13)
+          : eq(schema.bookMetadata.isbn10, isbn10 as string);
+
+    const rows = await this.db.select({ bookId: schema.bookMetadata.bookId }).from(schema.bookMetadata).where(where).limit(2);
+
+    return singleBookId(rows);
+  }
+
+  private async findByFileHash(fileHash: string): Promise<number | null> {
+    const rows = await this.db.select({ bookId: schema.bookFiles.bookId }).from(schema.bookFiles).where(eq(schema.bookFiles.hash, fileHash)).limit(2);
+
+    return singleBookId(rows);
+  }
+
+  private async findByFilePath(filePath: string): Promise<number | null> {
+    const rows = await this.db
+      .select({ bookId: schema.bookFiles.bookId })
+      .from(schema.bookFiles)
+      .where(eq(schema.bookFiles.absolutePath, filePath))
+      .limit(2);
+
+    return singleBookId(rows);
+  }
+
+  private async findByTitleAuthor(title: string, authors: string[]): Promise<number | null> {
+    const normalizedTitle = title.trim();
+    if (!normalizedTitle) return null;
+
+    const normalizedAuthors = authors.map((author) => normalizeAuthor(author)).filter((author): author is string => !!author);
+    if (normalizedAuthors.length === 0) return null;
+
+    for (const normalizedAuthor of normalizedAuthors) {
+      const exactRows = await this.db
+        .select({ bookId: schema.bookMetadata.bookId })
+        .from(schema.bookMetadata)
+        .innerJoin(schema.bookAuthors, eq(schema.bookAuthors.bookId, schema.bookMetadata.bookId))
+        .innerJoin(schema.authors, eq(schema.authors.id, schema.bookAuthors.authorId))
+        .where(and(eq(schema.bookMetadata.title, normalizedTitle), eq(schema.authors.name, normalizedAuthor)))
+        .limit(2);
+      const exactBookId = singleBookId(exactRows);
+      if (exactBookId) return exactBookId;
+    }
+
+    for (const normalizedAuthor of normalizedAuthors) {
+      const approxRows = await this.db
+        .select({ bookId: schema.bookMetadata.bookId })
+        .from(schema.bookMetadata)
+        .innerJoin(schema.bookAuthors, eq(schema.bookAuthors.bookId, schema.bookMetadata.bookId))
+        .innerJoin(schema.authors, eq(schema.authors.id, schema.bookAuthors.authorId))
+        .where(and(eq(schema.bookMetadata.title, normalizedTitle), ilike(schema.authors.name, `%${escapeLike(normalizedAuthor)}%`)))
+        .limit(2);
+      const approxBookId = singleBookId(approxRows);
+      if (approxBookId) return approxBookId;
+    }
+
+    return null;
+  }
+}
+
+export function deriveUnresolvedReason(attempts: MatchAttempt[]): UnresolvedReasonCode {
+  if (attempts.includes('title_author')) return 'no_title_author_match';
+  if (attempts.includes('file_path')) return 'no_file_path_match';
+  if (attempts.includes('file_hash')) return 'no_file_hash_match';
+  if (attempts.includes('isbn')) return 'no_isbn_match';
+  return 'insufficient_source_data';
+}
+
+function normalizeTitle(value: string | null): string | null {
+  if (!value) return null;
+  const normalized = value.trim().toLowerCase();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeAuthor(value: string | null): string | null {
+  if (!value) return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function getSourceAuthorNames(sourceBook: SourceBook): string[] {
+  const structured = sourceBook.authors?.map((author) => author.name).filter((name) => name.trim().length > 0) ?? [];
+  if (structured.length > 0) return structured;
+  const legacy = normalizeAuthor(sourceBook.author);
+  return legacy ? [legacy] : [];
+}
+
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, '\\$&');
+}
+
+function buildTitleAuthorCacheKey(title: string | null, authors: string[]): string {
+  return `${normalizeTitle(title) ?? ''}|${authors.map((author) => normalizeAuthor(author)?.toLowerCase() ?? '').join(';')}`;
+}
+
+function singleBookId(rows: Array<{ bookId: number }>): number | null {
+  return rows.length === 1 ? rows[0].bookId : null;
+}
+
+export function applyPathMappings(filePath: string | null, mappings: PathMapping[]): string | null {
+  if (!filePath) return null;
+
+  const sorted = [...mappings].sort((a, b) => b.sourcePrefix.length - a.sourcePrefix.length);
+  for (const mapping of sorted) {
+    const sourcePrefix = normalizePathPrefix(mapping.sourcePrefix);
+    const targetPrefix = normalizePathPrefix(mapping.targetPrefix);
+    if (!sourcePrefix || !targetPrefix) continue;
+
+    if (filePath.startsWith(sourcePrefix)) {
+      return `${targetPrefix}${filePath.slice(sourcePrefix.length)}`;
+    }
+  }
+
+  return filePath;
+}
+
+function normalizePathPrefix(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
diff --git a/server/src/modules/migration/planner/path-mapping-validation.service.test.ts b/server/src/modules/migration/planner/path-mapping-validation.service.test.ts
new file mode 100644
index 000000000..c351617a9
--- /dev/null
+++ b/server/src/modules/migration/planner/path-mapping-validation.service.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MigrationRepository } from '../migration.repository';
+import { PathMappingValidationService } from './path-mapping-validation.service';
+
+function createRepoMock(existingPaths: string[]) {
+  return {
+    findExistingBookFilePaths: vi.fn(() => Promise.resolve(new Set(existingPaths))),
+  } as unknown as MigrationRepository;
+}
+
+describe('PathMappingValidationService', () => {
+  it('computes summary and mapping stats against target file paths', async () => {
+    const repo = createRepoMock(['/target/library/book-1.epub']);
+    const service = new PathMappingValidationService(repo);
+
+    const result = await service.validate({
+      sourceBooks: [
+        {
+          sourceBookId: '1',
+          title: null,
+          author: null,
+          subtitle: null,
+          isbn10: null,
+          isbn13: null,
+          description: null,
+          publisher: null,
+          publishedYear: null,
+          language: null,
+          filePath: '/source/library/book-1.epub',
+          fileHash: null,
+          genres: [],
+          tags: [],
+        },
+        {
+          sourceBookId: '2',
+          title: null,
+          author: null,
+          subtitle: null,
+          isbn10: null,
+          isbn13: null,
+          description: null,
+          publisher: null,
+          publishedYear: null,
+          language: null,
+          filePath: '/source/library/book-2.epub',
+          fileHash: null,
+          genres: [],
+          tags: [],
+        },
+        {
+          sourceBookId: '3',
+          title: null,
+          author: null,
+          subtitle: null,
+          isbn10: null,
+          isbn13: null,
+          description: null,
+          publisher: null,
+          publishedYear: null,
+          language: null,
+          filePath: '/other/no-map.epub',
+          fileHash: null,
+          genres: [],
+          tags: [],
+        },
+      ],
+      pathMappings: [{ sourcePrefix: '/source/library', targetPrefix: '/target/library' }],
+      sampleLimit: 5,
+    });
+
+    expect(result.summary.booksWithFilePath).toBe(3);
+    expect(result.summary.mappedByPrefix).toBe(2);
+    expect(result.summary.matchedTargetPaths).toBe(1);
+    expect(result.summary.unmatchedTargetPaths).toBe(2);
+
+    expect(result.mappings).toEqual([
+      {
+        sourcePrefix: '/source/library',
+        targetPrefix: '/target/library',
+        affectedBooks: 2,
+        matchedTargetPaths: 1,
+        unmatchedTargetPaths: 1,
+        unmatchedSamples: ['/target/library/book-2.epub'],
+      },
+    ]);
+  });
+});
diff --git a/server/src/modules/migration/planner/path-mapping-validation.service.ts b/server/src/modules/migration/planner/path-mapping-validation.service.ts
new file mode 100644
index 000000000..b115b22c9
--- /dev/null
+++ b/server/src/modules/migration/planner/path-mapping-validation.service.ts
@@ -0,0 +1,155 @@
+import { Injectable } from '@nestjs/common';
+
+import type { SourceBook } from '../adapters/source-adapter.types';
+import { MigrationRepository } from '../migration.repository';
+import type { PathMapping } from './planner.types';
+
+interface MappedPathRow {
+  sourcePath: string;
+  mappedPath: string;
+  mappingIndex: number | null;
+}
+
+export interface MappingStats {
+  sourcePrefix: string;
+  targetPrefix: string;
+  affectedBooks: number;
+  matchedTargetPaths: number;
+  unmatchedTargetPaths: number;
+  unmatchedSamples: string[];
+}
+
+@Injectable()
+export class PathMappingValidationService {
+  constructor(private readonly repo: MigrationRepository) {}
+
+  async validate(params: { sourceBooks: SourceBook[]; pathMappings: PathMapping[]; sampleLimit?: number }): Promise<{
+    summary: {
+      totalSourceBooks: number;
+      booksWithFilePath: number;
+      mappedByPrefix: number;
+      matchedTargetPaths: number;
+      unmatchedTargetPaths: number;
+      unchangedPaths: number;
+    };
+    mappings: MappingStats[];
+  }> {
+    const sampleLimit = Math.min(Math.max(params.sampleLimit ?? 10, 1), 100);
+    const mappings = normalizeMappings(params.pathMappings);
+
+    const filePathRows: string[] = [];
+    for (const book of params.sourceBooks) {
+      const path = normalizePath(book.filePath);
+      if (path) filePathRows.push(path);
+    }
+
+    const mappedRows: MappedPathRow[] = filePathRows.map((sourcePath) => {
+      const matched = findMatchingMapping(sourcePath, mappings);
+      if (matched) {
+        return {
+          sourcePath,
+          mappedPath: `${matched.mapping.targetPrefix}${sourcePath.slice(matched.mapping.sourcePrefix.length)}`,
+          mappingIndex: matched.index,
+        };
+      }
+      return {
+        sourcePath,
+        mappedPath: sourcePath,
+        mappingIndex: null,
+      };
+    });
+
+    const existingTargetPaths = await this.repo.findExistingBookFilePaths(mappedRows.map((row) => row.mappedPath));
+
+    const mappingStats: MappingStats[] = mappings.map((mapping) => ({
+      sourcePrefix: mapping.sourcePrefix,
+      targetPrefix: mapping.targetPrefix,
+      affectedBooks: 0,
+      matchedTargetPaths: 0,
+      unmatchedTargetPaths: 0,
+      unmatchedSamples: [],
+    }));
+
+    let mappedByPrefix = 0;
+    let matchedTargetPaths = 0;
+    let unmatchedTargetPaths = 0;
+    let unchangedPaths = 0;
+
+    for (const row of mappedRows) {
+      if (row.mappingIndex == null) {
+        unchangedPaths += 1;
+      } else {
+        mappedByPrefix += 1;
+        const stats = mappingStats[row.mappingIndex];
+        stats.affectedBooks += 1;
+      }
+
+      const isMatched = existingTargetPaths.has(row.mappedPath);
+      if (isMatched) {
+        matchedTargetPaths += 1;
+        if (row.mappingIndex != null) {
+          mappingStats[row.mappingIndex].matchedTargetPaths += 1;
+        }
+      } else {
+        unmatchedTargetPaths += 1;
+        if (row.mappingIndex != null) {
+          const stats = mappingStats[row.mappingIndex];
+          stats.unmatchedTargetPaths += 1;
+          if (stats.unmatchedSamples.length < sampleLimit) {
+            stats.unmatchedSamples.push(row.mappedPath);
+          }
+        }
+      }
+    }
+
+    return {
+      summary: {
+        totalSourceBooks: params.sourceBooks.length,
+        booksWithFilePath: filePathRows.length,
+        mappedByPrefix,
+        matchedTargetPaths,
+        unmatchedTargetPaths,
+        unchangedPaths,
+      },
+      mappings: mappingStats,
+    };
+  }
+}
+
+function findMatchingMapping(sourcePath: string, mappings: PathMapping[]): { index: number; mapping: PathMapping } | null {
+  for (const [index, mapping] of mappings.entries()) {
+    if (sourcePath.startsWith(mapping.sourcePrefix)) {
+      return { index, mapping };
+    }
+  }
+  return null;
+}
+
+function normalizeMappings(pathMappings: PathMapping[]): PathMapping[] {
+  const normalized = pathMappings
+    .map((row) => ({
+      sourcePrefix: normalizePath(row.sourcePrefix),
+      targetPrefix: normalizePath(row.targetPrefix),
+    }))
+    .filter((row): row is PathMapping => !!row.sourcePrefix && !!row.targetPrefix)
+    .sort((a, b) => b.sourcePrefix.length - a.sourcePrefix.length);
+
+  const deduped: PathMapping[] = [];
+  const seen = new Set<string>();
+
+  for (const mapping of normalized) {
+    const key = `${mapping.sourcePrefix}|${mapping.targetPrefix}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(mapping);
+  }
+
+  return deduped;
+}
+
+function normalizePath(value: string | null): string | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
diff --git a/server/src/modules/migration/planner/planner.service.ts b/server/src/modules/migration/planner/planner.service.ts
new file mode 100644
index 000000000..bdb3ddd7b
--- /dev/null
+++ b/server/src/modules/migration/planner/planner.service.ts
@@ -0,0 +1,207 @@
+import { Injectable } from '@nestjs/common';
+
+import type { MigrationProfile, MigrationSource } from '../../../db/schema';
+import { SourceAdapterRegistry } from '../adapters/source-adapter.registry';
+import type { SourceExportData } from '../adapters/source-adapter.types';
+import { parseBookloreConnectionConfig } from '../adapters/booklore/booklore-connection-config';
+import { MatchingService } from './matching.service';
+import type {
+  PathMapping,
+  PlannedBookMatch,
+  PlannedDuplicateBookMatch,
+  PlannerResult,
+  PlannedMigration,
+  PlannedUserPreview,
+  UserMapping,
+} from './planner.types';
+
+const MATCHING_PRIORITY = ['isbn', 'file_hash', 'path_mapping', 'title_author'] as const;
+
+@Injectable()
+export class MigrationPlannerService {
+  constructor(
+    private readonly adapterRegistry: SourceAdapterRegistry,
+    private readonly matchingService: MatchingService,
+  ) {}
+
+  async buildPlan(params: { source: MigrationSource; profile: MigrationProfile; scopeOverride?: Record<string, unknown> }): Promise<PlannerResult> {
+    const { source, profile, scopeOverride } = params;
+    const adapter = this.adapterRegistry.get(source.type);
+
+    const connectionConfig = parseConnectionConfig(source.type, source.connectionConfig);
+    const snapshot = await adapter.snapshot(connectionConfig);
+    const sourceData = await adapter.exportData(connectionConfig);
+
+    const userMappings = parseUserMappings(profile.userMappings);
+    const pathMappings = parsePathMappings(profile.pathMappings);
+
+    const scope = { ...asRecord(profile.scope), ...(scopeOverride ?? {}) };
+
+    const { matches, unresolved } = await this.matchingService.matchBooks(sourceData.books, pathMappings);
+    const { executableMatches, duplicateBookMatches } = splitDuplicateMatches(matches);
+
+    const matchedBookIds = new Set(executableMatches.map((entry) => entry.sourceBookId));
+    const mappedUsers = new Map(userMappings.map((entry) => [entry.sourceUserId, entry.targetUserId]));
+
+    const userPreview = buildUserPreview(sourceData, mappedUsers, matchedBookIds);
+
+    const plan: PlannedMigration = {
+      generatedAt: new Date().toISOString(),
+      snapshot,
+      matchingPriority: [...MATCHING_PRIORITY],
+      userMappings,
+      pathMappings,
+      scope,
+      matchedBooks: executableMatches,
+      unresolvedBooks: unresolved,
+      duplicateBookMatches,
+      userPreview,
+    };
+
+    return {
+      plan,
+      execution: {
+        sourceData,
+        matchedBooks: executableMatches,
+        unresolvedBooks: unresolved,
+        duplicateBookMatches,
+      },
+    };
+  }
+}
+
+function splitDuplicateMatches(matches: PlannedBookMatch[]): {
+  executableMatches: PlannedBookMatch[];
+  duplicateBookMatches: PlannedDuplicateBookMatch[];
+} {
+  const byTarget = new Map<number, PlannedBookMatch[]>();
+  for (const match of matches) {
+    const rows = byTarget.get(match.targetBookId) ?? [];
+    rows.push(match);
+    byTarget.set(match.targetBookId, rows);
+  }
+
+  const duplicateTargetIds = new Set<number>();
+  const duplicateBookMatches: PlannedDuplicateBookMatch[] = [];
+  for (const [targetBookId, rows] of byTarget) {
+    if (rows.length < 2) continue;
+    duplicateTargetIds.add(targetBookId);
+    duplicateBookMatches.push({
+      targetBookId,
+      sourceBookIds: rows.map((row) => row.sourceBookId),
+      strategies: [...new Set(rows.map((row) => row.strategy))],
+      reason: 'duplicate_target_match',
+    });
+  }
+
+  return {
+    executableMatches: matches.filter((match) => !duplicateTargetIds.has(match.targetBookId)),
+    duplicateBookMatches,
+  };
+}
+
+function parseConnectionConfig(type: string, raw: unknown): unknown {
+  if (type === 'booklore') {
+    return parseBookloreConnectionConfig(raw);
+  }
+  return asRecord(raw);
+}
+
+function parseUserMappings(raw: unknown): UserMapping[] {
+  if (!Array.isArray(raw)) return [];
+
+  const out: UserMapping[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+
+    const sourceUserId = toString((item as Record<string, unknown>).sourceUserId ?? (item as Record<string, unknown>).source_user_id);
+    const targetUserId = toNumber((item as Record<string, unknown>).targetUserId ?? (item as Record<string, unknown>).target_user_id);
+    if (!sourceUserId || !targetUserId) continue;
+
+    out.push({ sourceUserId, targetUserId });
+  }
+
+  return out;
+}
+
+function parsePathMappings(raw: unknown): PathMapping[] {
+  if (!Array.isArray(raw)) return [];
+
+  const out: PathMapping[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+
+    const sourcePrefix = toString((item as Record<string, unknown>).sourcePrefix ?? (item as Record<string, unknown>).source_prefix);
+    const targetPrefix = toString((item as Record<string, unknown>).targetPrefix ?? (item as Record<string, unknown>).target_prefix);
+    if (!sourcePrefix || !targetPrefix) continue;
+
+    out.push({ sourcePrefix, targetPrefix });
+  }
+
+  return out;
+}
+
+function buildUserPreview(sourceData: SourceExportData, mappedUsers: Map<string, number>, matchedBookIds: Set<string>): PlannedUserPreview[] {
+  const usersById = new Map(sourceData.users.map((user) => [user.sourceUserId, user]));
+  const countsBySourceUser = new Map<string, { statuses: number; fileProgress: number; bookmarks: number; annotations: number; shelves: number }>();
+
+  const increment = (sourceUserId: string, key: 'statuses' | 'fileProgress' | 'bookmarks' | 'annotations' | 'shelves') => {
+    const current = countsBySourceUser.get(sourceUserId) ?? { statuses: 0, fileProgress: 0, bookmarks: 0, annotations: 0, shelves: 0 };
+    current[key] += 1;
+    countsBySourceUser.set(sourceUserId, current);
+  };
+
+  for (const row of sourceData.userBookStatuses) {
+    if (mappedUsers.has(row.sourceUserId) && matchedBookIds.has(row.sourceBookId)) increment(row.sourceUserId, 'statuses');
+  }
+  for (const row of sourceData.userFileProgress) {
+    if (mappedUsers.has(row.sourceUserId) && matchedBookIds.has(row.sourceBookId)) increment(row.sourceUserId, 'fileProgress');
+  }
+  for (const row of sourceData.bookmarks) {
+    if (mappedUsers.has(row.sourceUserId) && matchedBookIds.has(row.sourceBookId)) increment(row.sourceUserId, 'bookmarks');
+  }
+  for (const row of sourceData.annotations) {
+    if (mappedUsers.has(row.sourceUserId) && matchedBookIds.has(row.sourceBookId)) increment(row.sourceUserId, 'annotations');
+  }
+
+  const shelfById = new Map(sourceData.shelves.map((row) => [row.sourceShelfId, row]));
+  for (const row of sourceData.shelfBooks) {
+    if (!matchedBookIds.has(row.sourceBookId)) continue;
+    const shelf = shelfById.get(row.sourceShelfId);
+    const sourceUserId = row.sourceUserId || shelf?.sourceUserId;
+    if (!sourceUserId) continue;
+    if (!mappedUsers.has(sourceUserId)) continue;
+    increment(sourceUserId, 'shelves');
+  }
+
+  return [...mappedUsers.entries()].map(([sourceUserId, targetUserId]) => {
+    const sourceUser = usersById.get(sourceUserId);
+    const counts = countsBySourceUser.get(sourceUserId) ?? { statuses: 0, fileProgress: 0, bookmarks: 0, annotations: 0, shelves: 0 };
+    return {
+      sourceUserId,
+      targetUserId,
+      username: sourceUser?.username ?? sourceUserId,
+      counts,
+    };
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function toString(value: unknown): string | null {
+  if (value == null) return null;
+  const str =
+    typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' ? String(value) : null;
+  if (str == null) return null;
+  const trimmed = str.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toNumber(value: unknown): number | null {
+  if (value == null) return null;
+  const num = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(num) ? num : null;
+}
diff --git a/server/src/modules/migration/planner/planner.types.ts b/server/src/modules/migration/planner/planner.types.ts
new file mode 100644
index 000000000..06b072df5
--- /dev/null
+++ b/server/src/modules/migration/planner/planner.types.ts
@@ -0,0 +1,79 @@
+import type { SourceExportData, SourceSnapshot } from '../adapters/source-adapter.types';
+
+export interface PathMapping {
+  sourcePrefix: string;
+  targetPrefix: string;
+}
+
+export interface UserMapping {
+  sourceUserId: string;
+  targetUserId: number;
+}
+
+export type MatchStrategy = 'isbn' | 'file_hash' | 'path_mapping' | 'title_author';
+
+export type UnresolvedReasonCode =
+  | 'insufficient_source_data'
+  | 'no_isbn_match'
+  | 'no_file_hash_match'
+  | 'no_file_path_match'
+  | 'no_title_author_match';
+
+export interface PlannedBookMatch {
+  sourceBookId: string;
+  targetBookId: number;
+  strategy: MatchStrategy;
+}
+
+export interface PlannedDuplicateBookMatch {
+  targetBookId: number;
+  sourceBookIds: string[];
+  strategies: MatchStrategy[];
+  reason: 'duplicate_target_match';
+}
+
+export interface PlannedUnresolvedBook {
+  sourceBookId: string;
+  title: string | null;
+  reason: UnresolvedReasonCode;
+}
+
+export interface UserPreviewCounts {
+  statuses: number;
+  fileProgress: number;
+  bookmarks: number;
+  annotations: number;
+  shelves: number;
+}
+
+export interface PlannedUserPreview {
+  sourceUserId: string;
+  targetUserId: number;
+  username: string;
+  counts: UserPreviewCounts;
+}
+
+export interface PlannedMigration {
+  generatedAt: string;
+  snapshot: SourceSnapshot;
+  matchingPriority: MatchStrategy[];
+  userMappings: UserMapping[];
+  pathMappings: PathMapping[];
+  scope: Record<string, unknown>;
+  matchedBooks: PlannedBookMatch[];
+  unresolvedBooks: PlannedUnresolvedBook[];
+  duplicateBookMatches: PlannedDuplicateBookMatch[];
+  userPreview: PlannedUserPreview[];
+}
+
+export interface PlannedExecutionContext {
+  sourceData: SourceExportData;
+  matchedBooks: PlannedBookMatch[];
+  unresolvedBooks: PlannedUnresolvedBook[];
+  duplicateBookMatches: PlannedDuplicateBookMatch[];
+}
+
+export interface PlannerResult {
+  plan: PlannedMigration;
+  execution: PlannedExecutionContext;
+}
diff --git a/server/src/modules/migration/reporting/migration-reporting.service.ts b/server/src/modules/migration/reporting/migration-reporting.service.ts
new file mode 100644
index 000000000..be7b87760
--- /dev/null
+++ b/server/src/modules/migration/reporting/migration-reporting.service.ts
@@ -0,0 +1,140 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+
+import { MigrationRepository } from '../migration.repository';
+
+@Injectable()
+export class MigrationReportingService {
+  constructor(private readonly repo: MigrationRepository) {}
+
+  async getRunReport(runId: number) {
+    const run = await this.repo.findRunById(runId);
+    if (!run) throw new NotFoundException(`Migration run not found: ${runId}`);
+
+    const [metrics, artifact] = await Promise.all([
+      this.repo.listRunMetrics(runId),
+      run.planArtifactId ? this.repo.findPlanArtifactById(run.planArtifactId) : Promise.resolve(null),
+    ]);
+
+    return {
+      run: sanitizeRunForApi(run),
+      metrics,
+      plan: artifact?.plan ?? null,
+      summary: artifact?.summary ?? null,
+    };
+  }
+
+  async getRunProgress(runId: number) {
+    const run = await this.repo.findRunById(runId);
+    if (!run) throw new NotFoundException(`Migration run not found: ${runId}`);
+
+    const metrics = await this.repo.listRunMetrics(runId);
+    const totals = metrics.reduce(
+      (acc, row) => ({
+        processed: acc.processed + row.processed,
+        imported: acc.imported + row.imported,
+        skipped: acc.skipped + row.skipped,
+        unresolved: acc.unresolved + row.unresolved,
+        failed: acc.failed + row.failed,
+      }),
+      {
+        processed: 0,
+        imported: 0,
+        skipped: 0,
+        unresolved: 0,
+        failed: 0,
+      },
+    );
+
+    return {
+      run: sanitizeRunForApi(run),
+      totals,
+      metrics,
+    };
+  }
+
+  async exportRunReport(runId: number, requestedFormat?: string) {
+    const report = await this.getRunReport(runId);
+    const format = requestedFormat?.toLowerCase() === 'csv' ? 'csv' : 'json';
+
+    if (format === 'json') {
+      return {
+        format,
+        fileName: `migration-run-${runId}-report.json`,
+        contentType: 'application/json',
+        content: JSON.stringify(report, null, 2),
+      };
+    }
+
+    const rows: Record<string, string | number | null>[] = [
+      {
+        section: 'summary',
+        stage: null,
+        entityType: null,
+        processed: report.metrics.reduce((sum, row) => sum + row.processed, 0),
+        imported: report.metrics.reduce((sum, row) => sum + row.imported, 0),
+        skipped: report.metrics.reduce((sum, row) => sum + row.skipped, 0),
+        unresolved: report.metrics.reduce((sum, row) => sum + row.unresolved, 0),
+        failed: report.metrics.reduce((sum, row) => sum + row.failed, 0),
+        code: 'summary',
+        message: `Run state: ${report.run.state}`,
+        createdAt: report.run.updatedAt?.toISOString() ?? report.run.createdAt.toISOString(),
+      },
+      ...report.metrics.map((row) => ({
+        section: 'metrics',
+        stage: row.stage,
+        entityType: row.entityType,
+        processed: row.processed,
+        imported: row.imported,
+        skipped: row.skipped,
+        unresolved: row.unresolved,
+        failed: row.failed,
+        code: null,
+        message: null,
+        createdAt: row.updatedAt.toISOString(),
+      })),
+    ];
+
+    return {
+      format,
+      fileName: `migration-run-${runId}-report.csv`,
+      contentType: 'text/csv; charset=utf-8',
+      content: toCsv(rows),
+    };
+  }
+}
+
+function sanitizeRunForApi(run: Awaited<ReturnType<MigrationRepository['listRuns']>>[number]) {
+  return {
+    id: run.id,
+    sourceId: run.sourceId,
+    profileId: run.profileId,
+    planArtifactId: run.planArtifactId,
+    state: run.state,
+    currentStage: run.currentStage,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    errorMessage: run.errorMessage,
+    createdAt: run.createdAt,
+    updatedAt: run.updatedAt,
+  };
+}
+
+function toCsv(rows: Record<string, string | number | null>[]): string {
+  if (rows.length === 0) return '';
+  const headers = Object.keys(rows[0]);
+  const lines = [headers.join(',')];
+
+  for (const row of rows) {
+    const values = headers.map((header) => csvCell(row[header]));
+    lines.push(values.join(','));
+  }
+
+  return lines.join('\n');
+}
+
+function csvCell(value: string | number | null | undefined): string {
+  if (value === null || value === undefined) return '';
+  const text = String(value);
+  if (!/[",\n]/.test(text)) return text;
+  return `"${text.replace(/"/g, '""')}"`;
+}