From 9fd4e162aaba4955e0d70beeb1e40d55dde0e6d4 Mon Sep 17 00:00:00 2001
From: neon <18559658+neonsolstice@users.noreply.github.com>
Date: Sun, 5 Apr 2026 16:01:04 -0600
Subject: [PATCH] feat(server): harden booklore migration with adapters and E2E
 tests

---
 .github/workflows/ci.yml                      |    8 +
 .../migration/components/MigrationModal.vue   | 1559 +++++++++++++++++
 .../migration/components/MigrationStepper.vue |   63 +
 .../components/SearchableUserSelect.vue       |   97 +
 .../composables/useMigrationPolling.ts        |   51 +
 .../composables/useMigrationProgress.ts       |   57 +
 .../features/migration/lib/migration-api.ts   |  128 +-
 .../features/settings/MaintenanceSettings.vue |  181 +-
 .../features/settings/MigrationSettings.vue   | 1335 ++++++++------
 .../src/features/settings/SettingsHeader.vue  |    3 -
 client/src/router/index.ts                    |    6 -
 packages/types/src/index.ts                   |    1 +
 packages/types/src/migration.ts               |  106 ++
 scripts/test/e2e-suites.mjs                   |   10 +
 server/.env.example                           |    5 +
 server/src/app.module.ts                      |    4 +-
 server/src/config/config.ts                   |    4 +
 .../{0000_baseline.sql => 0000_initial.sql}   |    5 +-
 .../src/db/migrations/meta/0000_snapshot.json |   30 +-
 server/src/db/migrations/meta/_journal.json   |    4 +-
 server/src/db/schema/migration.ts             |   14 +-
 .../architecture-boundaries.test.ts           |    1 -
 .../booklore/booklore-connector.test.ts       |   25 +
 .../adapters/booklore/booklore-connector.ts   |    7 +
 .../booklore/booklore-source.adapter.test.ts  |   57 +
 .../booklore/booklore-source.adapter.ts       |  137 +-
 .../adapters/booklore/booklore-tables.ts      |   36 +
 .../adapters/source-adapter.types.ts          |   15 +
 .../migration/core/api-sanitizers.test.ts     |  161 ++
 .../modules/migration/core/api-sanitizers.ts  |  116 ++
 .../src/modules/migration/core/coerce.test.ts |  137 ++
 server/src/modules/migration/core/coerce.ts   |   25 +
 .../migration/core/connection-config.test.ts  |   44 +
 .../migration/core/connection-config.ts       |   11 +
 .../core/migration-encryption.service.test.ts |  116 ++
 .../core/migration-encryption.service.ts      |   75 +
 .../src/modules/migration/core/plan-hash.ts   |    4 +
 .../dto/resolve-duplicate-matches.dto.ts      |   19 +
 .../migration/executor/cover.importer.ts      |  131 ++
 .../migration/executor/executor-utils.ts      |  247 +++
 .../migration-executor.service.test.ts        |  236 +--
 .../executor/migration-executor.service.ts    | 1168 ++----------
 .../executor/migration-import.repository.ts   |  549 ++++++
 .../executor/shared-overlays.importer.ts      |  261 +++
 .../migration/executor/user-state.importer.ts |  522 ++++++
 .../migration-profile.service.test.ts         |  172 ++
 .../migration/migration-profile.service.ts    |  178 ++
 .../migration/migration-progress.gateway.ts   |   95 +
 .../migration-source.service.test.ts          |  193 ++
 .../migration/migration-source.service.ts     |  161 ++
 .../modules/migration/migration.controller.ts |   66 +-
 .../migration/migration.module.test.ts        |    8 +
 .../src/modules/migration/migration.module.ts |   30 +
 .../modules/migration/migration.repository.ts |  161 +-
 .../migration/migration.service.test.ts       |  521 +++++-
 .../modules/migration/migration.service.ts    |  611 +++----
 .../planner/matching.service.test.ts          |   25 +
 .../migration/planner/matching.service.ts     |  305 +++-
 .../path-mapping-validation.service.ts        |    3 +-
 .../migration/planner/planner.service.ts      |   43 +-
 .../migration/planner/planner.types.ts        |    8 +-
 .../reporting/migration-reporting.service.ts  |   17 +-
 server/test/e2e/app-harness.ts                |   10 +
 .../migration-booklore-fixture-builder.ts     | 1030 +++++++++++
 .../migration-booklore-harness.ts             |  521 ++++++
 server/test/migration-booklore.e2e-spec.ts    | 1060 +++++++++++
 66 files changed, 10540 insertions(+), 2449 deletions(-)
 create mode 100644 client/src/features/migration/components/MigrationModal.vue
 create mode 100644 client/src/features/migration/components/MigrationStepper.vue
 create mode 100644 client/src/features/migration/components/SearchableUserSelect.vue
 create mode 100644 client/src/features/migration/composables/useMigrationPolling.ts
 create mode 100644 client/src/features/migration/composables/useMigrationProgress.ts
 create mode 100644 packages/types/src/migration.ts
 rename server/src/db/migrations/{0000_baseline.sql => 0000_initial.sql} (99%)
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-connector.test.ts
 create mode 100644 server/src/modules/migration/adapters/booklore/booklore-tables.ts
 create mode 100644 server/src/modules/migration/core/api-sanitizers.test.ts
 create mode 100644 server/src/modules/migration/core/api-sanitizers.ts
 create mode 100644 server/src/modules/migration/core/coerce.test.ts
 create mode 100644 server/src/modules/migration/core/coerce.ts
 create mode 100644 server/src/modules/migration/core/connection-config.test.ts
 create mode 100644 server/src/modules/migration/core/connection-config.ts
 create mode 100644 server/src/modules/migration/core/migration-encryption.service.test.ts
 create mode 100644 server/src/modules/migration/core/migration-encryption.service.ts
 create mode 100644 server/src/modules/migration/dto/resolve-duplicate-matches.dto.ts
 create mode 100644 server/src/modules/migration/executor/cover.importer.ts
 create mode 100644 server/src/modules/migration/executor/executor-utils.ts
 create mode 100644 server/src/modules/migration/executor/migration-import.repository.ts
 create mode 100644 server/src/modules/migration/executor/shared-overlays.importer.ts
 create mode 100644 server/src/modules/migration/executor/user-state.importer.ts
 create mode 100644 server/src/modules/migration/migration-profile.service.test.ts
 create mode 100644 server/src/modules/migration/migration-profile.service.ts
 create mode 100644 server/src/modules/migration/migration-progress.gateway.ts
 create mode 100644 server/src/modules/migration/migration-source.service.test.ts
 create mode 100644 server/src/modules/migration/migration-source.service.ts
 create mode 100644 server/test/e2e/migration-booklore/migration-booklore-fixture-builder.ts
 create mode 100644 server/test/e2e/migration-booklore/migration-booklore-harness.ts
 create mode 100644 server/test/migration-booklore.e2e-spec.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 354aeeebe..538106c6e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -340,6 +340,14 @@ jobs:
               - 'scripts/test/**'
               - 'scripts/db/**'
               - '.github/workflows/e2e-runner.yml'
+            migration-booklore:
+              - 'server/src/modules/migration/**'
+              - 'server/test/migration-booklore.e2e-spec.ts'
+              - 'server/test/e2e/migration-booklore/**'
+              - 'server/src/db/schema/**'
+              - 'scripts/test/**'
+              - 'scripts/db/**'
+              - '.github/workflows/e2e-runner.yml'
             opds-auth-catalog:
               - 'server/src/modules/opds/**'
               - 'server/src/modules/book/**'
diff --git a/client/src/features/migration/components/MigrationModal.vue b/client/src/features/migration/components/MigrationModal.vue
new file mode 100644
index 000000000..643d4fbc2
--- /dev/null
+++ b/client/src/features/migration/components/MigrationModal.vue
@@ -0,0 +1,1559 @@
+<script setup lang="ts">
+import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+import { Eye, EyeOff, Loader2, X, ChevronLeft, ChevronRight, Check, AlertCircle } from 'lucide-vue-next'
+import { toast } from 'vue-sonner'
+import SearchableUserSelect from './SearchableUserSelect.vue'
+import {
+  cancelRun,
+  createDryRunPlan,
+  createProfile,
+  createSource,
+  exportRunReport,
+  getRunProgress,
+  getRunReport,
+  getWorkflowState,
+  listSourcePathPrefixes,
+  listSupportedSourceTypes,
+  listTargetLibraryFolders,
+  listTargetUsers,
+  resolveDuplicateMatches,
+  retryRun,
+  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'
+import { useMigrationPolling } from '@/features/migration/composables/useMigrationPolling'
+import { useMigrationProgress } from '@/features/migration/composables/useMigrationProgress'
+
+interface StepDefinition {
+  label: string
+  status: 'pending' | 'done' | 'active' | 'running' | 'failed' | 'saved'
+}
+
+const emit = defineEmits<{ close: [] }>()
+
+const { subscribeRun, unsubscribeRun, getProgress: getSocketProgress, progressMap: socketProgressMap } = useMigrationProgress()
+
+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,
+  cancellingRun: false,
+  retryingRun: false,
+  loadingProgress: false,
+  loadingReport: false,
+  exporting: false,
+  resolvingDuplicates: 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 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 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 stepperSteps = computed<StepDefinition[]>(() => {
+  const s = stepStatus.value
+  return [
+    { label: 'Source Connection', status: s.source === 'done' ? 'done' : s.source === 'saved' ? 'saved' : 'pending' },
+    { label: 'User & Path Mapping', status: s.mappings },
+    { label: 'Dry Run', status: s.dryRun },
+    { label: 'Run Migration', status: s.migration },
+    { label: 'Report', status: run.value ? 'done' : 'pending' },
+  ]
+})
+
+const activeStepIndex = computed(() => {
+  const s = stepStatus.value
+  if (s.migration === 'running' || s.migration === 'failed') return 3
+  if (run.value) return 4
+  if (s.dryRun === 'done') return 3
+  if (s.mappings === 'done') return 2
+  if (s.source === 'done' || s.source === 'saved') return 1
+  return 0
+})
+
+const currentStep = ref(0)
+
+watch(activeStepIndex, (newVal) => {
+  if (newVal > currentStep.value) currentStep.value = newVal
+})
+
+function onStepClick(index: number) {
+  currentStep.value = index
+}
+
+function goNext() {
+  if (currentStep.value < 4) currentStep.value++
+}
+
+function goPrev() {
+  if (currentStep.value > 0) currentStep.value--
+}
+
+function goToSetup() {
+  currentStep.value = 0
+}
+
+function onBackOrCancel() {
+  if (currentStep.value > 0) goPrev()
+  else handleClose()
+}
+
+const stepTitles = ['Source Connection', 'User & Path Mapping', 'Dry Run', 'Run Migration', 'Migration Report']
+const stepSubtitles = [
+  'Configure the database connection to your source Booklore instance.',
+  'Map source users to target users and translate file paths.',
+  'Preview what will be imported before running the live migration.',
+  'Start the live import and monitor its progress.',
+  'Review what was imported and export a detailed report.',
+]
+const continueLabels = ['Continue to Mappings', 'Continue to Dry Run', 'Continue to Migration', 'View Report', '']
+
+const currentStepTitle = computed(() => stepTitles[currentStep.value] ?? '')
+const currentStepSubtitle = computed(() => stepSubtitles[currentStep.value] ?? '')
+const continueLabel = computed(() => continueLabels[currentStep.value] ?? '')
+
+const currentStepBadge = computed((): { label: string; cls: string } | null => {
+  const s = stepStatus.value
+  const n = currentStep.value
+  if (n === 0) {
+    if (s.source === 'done') return { label: 'Validated', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+    if (s.source === 'saved') return { label: 'Saved', cls: 'text-amber-700 bg-amber-500/10 border-amber-500/20' }
+  }
+  if (n === 1 && s.mappings === 'done') return { label: 'Saved', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+  if (n === 2 && s.dryRun === 'done') return { label: 'Up to date', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+  if (n === 3) {
+    if (s.migration === 'done') return { label: 'Completed', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+    if (s.migration === 'running') return { label: 'Running', cls: 'text-sky-700 bg-sky-500/10 border-sky-500/20' }
+    if (s.migration === 'failed') return { label: 'Failed', cls: 'text-red-700 bg-red-500/10 border-red-500/20' }
+  }
+  return null
+})
+
+function stepIndicatorClass(index: number): string {
+  const step = stepperSteps.value[index]
+  if (!step) return 'bg-muted-foreground/15 text-muted-foreground/60'
+  if (step.status === 'done') return 'bg-primary text-primary-foreground'
+  if (step.status === 'failed') return 'bg-red-500 text-white'
+  if (step.status === 'running') return 'bg-sky-500 text-white'
+  if (index === currentStep.value) return 'bg-primary/15 text-primary ring-1 ring-primary'
+  if (step.status === 'saved') return 'bg-amber-500/15 text-amber-600'
+  return 'bg-muted-foreground/15 text-muted-foreground/60'
+}
+
+const unresolvedSummary = computed(() => Object.entries(plan.value?.summary?.unresolvedByReason ?? {}))
+
+interface DuplicateBookMatch {
+  targetBookId: number
+  sourceBookIds: string[]
+  strategies: string[]
+  reason: string
+}
+
+const duplicateMatches = computed<DuplicateBookMatch[]>(() => {
+  const raw = plan.value?.plan
+  if (!raw || typeof raw !== 'object') return []
+  const planData = raw as Record<string, unknown>
+  return Array.isArray(planData.duplicateBookMatches) ? planData.duplicateBookMatches : []
+})
+
+const duplicateResolutions = ref<Map<number, string>>(new Map())
+
+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('book_covers', '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,
+  }
+})
+
+const STAGE_NAMES = ['shared_overlays', 'book_covers', 'user_state'] as const
+
+const migrationProgress = computed(() => {
+  const currentRun = run.value
+  if (!currentRun || currentRun.state !== 'running') return null
+
+  const currentStage = currentRun.currentStage ?? 'init'
+  if (currentStage === 'completed') return { percent: 100, label: 'Completed' }
+
+  const stageIdx = STAGE_NAMES.indexOf(currentStage as (typeof STAGE_NAMES)[number])
+  const completedStages = stageIdx >= 0 ? stageIdx : 0
+  const stageWeight = 100 / STAGE_NAMES.length
+  const percent = Math.min(Math.round(completedStages * stageWeight + stageWeight * 0.5), 99)
+
+  const stageLabels: Record<string, string> = {
+    init: 'Initializing',
+    shared_overlays: 'Importing metadata',
+    book_covers: 'Importing covers',
+    user_state: 'Importing user data',
+  }
+
+  return { percent, label: stageLabels[currentStage] ?? currentStage }
+})
+
+watch(socketProgressMap, () => {
+  const currentRun = run.value
+  if (!currentRun) return
+  const socketData = getSocketProgress(currentRun.id)
+  if (!socketData) return
+
+  runProgress.value = {
+    run: { ...currentRun, state: socketData.state, currentStage: socketData.currentStage },
+    totals: socketData.totals,
+    metrics: socketData.metrics as MigrationRunProgress['metrics'],
+  }
+  if (socketData.state !== 'running') {
+    unsubscribeRun(currentRun.id)
+    void refreshWorkflowState()
+  }
+})
+
+const { pollingError, retry: onRetryPolling } = useMigrationPolling({
+  runState: computed(() => run.value?.state),
+  pollFn: async () => {
+    const currentRun = run.value
+    if (!currentRun) return
+    const socketData = getSocketProgress(currentRun.id)
+    if (socketData) {
+      runProgress.value = {
+        run: { ...run.value!, state: socketData.state, currentStage: socketData.currentStage },
+        totals: socketData.totals,
+        metrics: socketData.metrics as MigrationRunProgress['metrics'],
+      }
+      if (socketData.state !== 'running') {
+        unsubscribeRun(currentRun.id)
+        await refreshWorkflowState()
+      }
+      return
+    }
+    busy.loadingProgress = true
+    try {
+      runProgress.value = await getRunProgress(currentRun.id)
+      if (runProgress.value.run.state !== 'running') await refreshWorkflowState()
+    } finally {
+      busy.loadingProgress = false
+    }
+  },
+  intervalMs: 5000,
+})
+
+function handleClose() {
+  emit('close')
+}
+
+function onKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape') emit('close')
+}
+
+onMounted(async () => {
+  document.addEventListener('keydown', onKeydown)
+  await initialize()
+})
+
+onUnmounted(() => {
+  document.removeEventListener('keydown', onKeydown)
+})
+
+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') {
+    subscribeRun(run.value.id)
+    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.password = asString(cfg.password) ?? ''
+  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 */
+  }
+}
+
+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 (pathError) {
+        toast.warning(getErrorMessage(pathError, 'Path validation failed, but profile will still be saved'))
+      }
+    }
+    await createProfile({
+      sourceId: currentSource.id,
+      name: 'Booklore Migration',
+      userMappings: mappings,
+      pathMappings: cleanedPaths,
+      scope: {
+        preflight: {
+          pathValidatedAt: pathValidation.value?.validatedAt ?? getPersistedPathValidatedAt(profile.value),
+          pathMappingsHash: pathValidation.value?.pathMappingsHash ?? getPersistedPathMappingsHash(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
+  }
+}
+
+function handleDuplicateSelection(targetBookId: number, sourceBookId: string) {
+  duplicateResolutions.value.set(targetBookId, sourceBookId)
+}
+
+async function onResolveDuplicates() {
+  const currentPlan = plan.value
+  if (!currentPlan) return
+  const matches = duplicateMatches.value
+  if (matches.length === 0) return
+  const unresolved = matches.filter((m) => !duplicateResolutions.value.has(m.targetBookId))
+  if (unresolved.length > 0) {
+    toast.error(`Select a source book for all ${unresolved.length} duplicate groups`)
+    return
+  }
+
+  busy.resolvingDuplicates = true
+  try {
+    const resolutions = matches.map((m) => ({ targetBookId: m.targetBookId, selectedSourceBookId: duplicateResolutions.value.get(m.targetBookId)! }))
+    await resolveDuplicateMatches(currentPlan.id, resolutions)
+    duplicateResolutions.value = new Map()
+    await refreshWorkflowState()
+    toast.success('Duplicate matches resolved')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to resolve duplicates'))
+  } finally {
+    busy.resolvingDuplicates = false
+  }
+}
+
+const confirmingMigrationStart = ref(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
+  }
+  if (!confirmingMigrationStart.value) {
+    confirmingMigrationStart.value = true
+    return
+  }
+
+  confirmingMigrationStart.value = false
+  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
+  }
+}
+
+function onCancelMigrationStart() {
+  confirmingMigrationStart.value = false
+}
+
+async function onCancelRun() {
+  const currentRun = run.value
+  if (!currentRun) return
+  busy.cancellingRun = true
+  try {
+    await cancelRun(currentRun.id)
+    await refreshWorkflowState()
+    toast.success('Migration run cancelled')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to cancel migration'))
+  } finally {
+    busy.cancellingRun = false
+  }
+}
+
+async function onRetryRun() {
+  const currentRun = run.value
+  if (!currentRun) return
+  busy.retryingRun = true
+  try {
+    await retryRun(currentRun.id)
+    await refreshWorkflowState()
+    toast.success('Migration run retried - resuming from last completed stage')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to retry migration'))
+  } finally {
+    busy.retryingRun = 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') await refreshWorkflowState()
+  } catch (error) {
+    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 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'
+  if (reason === 'ambiguous_isbn_match') return 'Multiple books matched the same ISBN'
+  if (reason === 'ambiguous_file_hash_match') return 'Multiple books matched the same file hash'
+  if (reason === 'ambiguous_file_path_match') return 'Multiple books matched the same file path'
+  if (reason === 'ambiguous_title_author_match') return 'Multiple books matched the same title and author'
+  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 getPersistedPathMappingsHash(currentProfile: MigrationProfile | null): string | null {
+  if (!currentProfile) return null
+  const scope = asRecord(currentProfile.scope)
+  const preflightScope = asRecord(scope.preflight)
+  return asString(preflightScope.pathMappingsHash)
+}
+
+function hasValidatedPathMappings(currentProfile: MigrationProfile | null): boolean {
+  if (!currentProfile) return false
+  if (currentProfile.pathMappings.length === 0) return true
+  return getPersistedPathValidatedAt(currentProfile) != null && getPersistedPathMappingsHash(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>
+  <Teleport to="body">
+    <div class="fixed inset-0 z-[70] flex items-center justify-center p-4">
+      <div class="absolute inset-0 bg-black/50 backdrop-blur-[2px]" @click="handleClose" />
+
+      <div
+        class="relative flex flex-col w-full max-w-5xl bg-background rounded-xl shadow-2xl overflow-hidden border border-border"
+        style="height: min(90vh, 700px)"
+      >
+        <!-- Mobile top bar -->
+        <div class="md:hidden flex items-center px-4 h-14 border-b border-border shrink-0">
+          <span class="flex-1 text-sm font-semibold text-foreground font-serif text-center">{{ currentStepTitle }}</span>
+          <button
+            class="flex items-center justify-center w-8 h-8 rounded-lg text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+            @click="handleClose"
+          >
+            <X :size="16" />
+          </button>
+        </div>
+
+        <!-- Body: sidebar + content -->
+        <div class="flex flex-1 min-h-0">
+          <!-- Sidebar (desktop only) -->
+          <nav class="hidden md:flex flex-col w-52 shrink-0 bg-muted/40 border-r border-border">
+            <div class="px-4 pt-5 pb-4 border-b border-border flex items-center justify-between shrink-0">
+              <span class="text-sm font-semibold text-foreground font-serif truncate">Booklore Import</span>
+              <button
+                class="flex items-center justify-center w-6 h-6 rounded text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0 ml-1"
+                @click="handleClose"
+              >
+                <X :size="14" />
+              </button>
+            </div>
+
+            <div class="flex-1 overflow-y-auto py-3 px-2">
+              <button
+                v-for="(step, i) in stepperSteps"
+                :key="i"
+                class="w-full flex items-center gap-2.5 px-2.5 py-2 rounded-lg text-sm transition-colors relative"
+                :class="[
+                  currentStep === i
+                    ? 'bg-background text-foreground font-medium shadow-sm'
+                    : 'text-muted-foreground hover:text-foreground hover:bg-muted/60 cursor-pointer',
+                ]"
+                @click="onStepClick(i)"
+              >
+                <span
+                  class="flex items-center justify-center w-5 h-5 rounded-full text-[10px] font-bold shrink-0 transition-colors"
+                  :class="stepIndicatorClass(i)"
+                >
+                  <Check v-if="step.status === 'done'" :size="10" />
+                  <AlertCircle v-else-if="step.status === 'failed'" :size="9" />
+                  <Loader2 v-else-if="step.status === 'running'" :size="9" class="animate-spin" />
+                  <template v-else>{{ i + 1 }}</template>
+                </span>
+                <span class="flex-1 text-left text-xs leading-snug">{{ step.label }}</span>
+                <div v-if="currentStep === i" class="absolute left-0 top-1/2 -translate-y-1/2 w-0.5 h-5 rounded-r bg-primary" />
+              </button>
+            </div>
+          </nav>
+
+          <!-- Right panel -->
+          <div class="flex flex-col flex-1 min-w-0">
+            <!-- Step header (desktop only) -->
+            <div class="hidden md:flex items-start justify-between gap-3 px-6 pt-5 pb-4 border-b border-border shrink-0">
+              <div>
+                <h2 class="font-serif font-semibold text-foreground text-base tracking-tight">{{ currentStepTitle }}</h2>
+                <p class="text-xs text-muted-foreground mt-0.5">{{ currentStepSubtitle }}</p>
+              </div>
+              <span
+                v-if="currentStepBadge"
+                class="shrink-0 inline-flex items-center rounded-full border px-2 py-0.5 text-[10px] font-medium"
+                :class="currentStepBadge.cls"
+                >{{ currentStepBadge.label }}</span
+              >
+            </div>
+
+            <!-- Step content -->
+            <div class="flex-1 overflow-y-auto px-5 md:px-6 py-5">
+              <div v-if="loading" class="flex items-center justify-center py-16">
+                <Loader2 class="size-5 animate-spin text-muted-foreground" />
+              </div>
+
+              <template v-else>
+                <!-- Step 0: Source Connection -->
+                <div v-if="currentStep === 0" class="space-y-5">
+                  <div class="grid gap-3 md:grid-cols-2">
+                    <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"
+                          :type="showPassword ? 'text' : 'password'"
+                          :placeholder="source ? 'Saved - leave unchanged' : '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">
+                      <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">
+                      <p v-for="[key, count] in sourceRowCounts" :key="key">{{ formatSourceCountLabel(key) }}: {{ count }}</p>
+                    </div>
+                  </div>
+                </div>
+
+                <!-- Step 1: User & Path Mapping -->
+                <div v-else-if="currentStep === 1" class="space-y-5">
+                  <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">
+                            <SearchableUserSelect v-model="row.targetUserId" :users="targetUsers" :disabled="hasActiveRun" />
+                          </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. Books are also matched by
+                      ISBN, file hash, and title/author regardless of path mappings.
+                    </p>
+                    <div v-for="(row, index) in pathMappings" :key="index" class="grid gap-2 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
+                    </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>
+
+                <!-- Step 2: Dry Run -->
+                <div v-else-if="currentStep === 2" class="space-y-5">
+                  <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> · Duplicates:
+                      <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">{{ friendlyUnresolvedReason(reason) }}: {{ count }}</p>
+                    </div>
+
+                    <div v-if="duplicateMatches.length > 0" class="space-y-3 border-t border-border pt-3">
+                      <div>
+                        <p class="font-medium text-red-600">Duplicate target matches</p>
+                        <p class="text-xs text-muted-foreground">Multiple source books matched the same target book. Select which to use for each.</p>
+                      </div>
+                      <div class="space-y-2">
+                        <div
+                          v-for="dup in duplicateMatches"
+                          :key="dup.targetBookId"
+                          class="rounded border border-border bg-background p-3 space-y-1.5"
+                        >
+                          <p class="text-xs font-medium">Target book #{{ dup.targetBookId }}</p>
+                          <label
+                            v-for="sourceId in dup.sourceBookIds"
+                            :key="sourceId"
+                            class="flex items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50 cursor-pointer"
+                          >
+                            <input
+                              type="radio"
+                              :name="`dup-${dup.targetBookId}`"
+                              :value="sourceId"
+                              :checked="duplicateResolutions.get(dup.targetBookId) === sourceId"
+                              class="accent-primary"
+                              @change="() => handleDuplicateSelection(dup.targetBookId, sourceId)"
+                            />
+                            <span>{{ sourceId }}</span>
+                            <span class="text-muted-foreground">({{ dup.strategies[dup.sourceBookIds.indexOf(sourceId)] ?? 'unknown' }})</span>
+                          </label>
+                        </div>
+                      </div>
+                      <button
+                        class="settings-btn-primary"
+                        :disabled="busy.resolvingDuplicates || duplicateResolutions.size < duplicateMatches.length"
+                        @click="onResolveDuplicates"
+                      >
+                        <Loader2 v-if="busy.resolvingDuplicates" class="size-3.5 animate-spin" />
+                        Resolve {{ duplicateMatches.length }} duplicate{{ duplicateMatches.length === 1 ? '' : 's' }}
+                      </button>
+                    </div>
+                  </div>
+                </div>
+
+                <!-- Step 3: Run Migration -->
+                <div v-else-if="currentStep === 3" class="space-y-5">
+                  <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">
+                    <template v-if="confirmingMigrationStart">
+                      <span class="text-xs text-amber-600 self-center">This will start the live migration. Are you sure?</span>
+                      <button class="settings-btn-primary" :disabled="busy.startingRun" @click="onStartMigration">
+                        <Loader2 v-if="busy.startingRun" class="size-3.5 animate-spin" />
+                        Confirm Start
+                      </button>
+                      <button class="settings-btn-outline" @click="onCancelMigrationStart">Cancel</button>
+                    </template>
+                    <template v-else>
+                      <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>
+                    </template>
+                    <button
+                      v-if="run?.state === 'running'"
+                      class="settings-btn-outline text-red-600"
+                      :disabled="busy.cancellingRun"
+                      @click="onCancelRun"
+                    >
+                      <Loader2 v-if="busy.cancellingRun" class="size-3.5 animate-spin" />
+                      Cancel Run
+                    </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="pollingError"
+                    class="rounded border border-amber-500/20 bg-amber-500/10 px-3 py-2 flex items-center gap-2 text-xs text-amber-700"
+                  >
+                    <span>Status polling stopped due to an error.</span>
+                    <button class="underline font-medium" @click="onRetryPolling">Retry</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>
+                    <button v-if="run.state !== 'running'" class="text-xs text-primary underline-offset-2 hover:underline ml-auto" @click="goNext">
+                      View Report
+                    </button>
+                  </div>
+
+                  <div v-if="migrationProgress" class="space-y-1.5">
+                    <div class="flex items-center justify-between text-xs text-muted-foreground">
+                      <span>{{ migrationProgress.label }}</span>
+                      <span>{{ migrationProgress.percent }}%</span>
+                    </div>
+                    <div class="h-2 w-full rounded-full bg-muted overflow-hidden">
+                      <div
+                        class="h-full rounded-full bg-primary transition-all duration-500 ease-out"
+                        :style="{ width: `${migrationProgress.percent}%` }"
+                      />
+                    </div>
+                  </div>
+                </div>
+
+                <!-- Step 4: Migration Report -->
+                <div v-else-if="currentStep === 4" class="space-y-5">
+                  <p v-if="!run" class="text-sm text-muted-foreground">No migration run yet. Complete the steps above to start.</p>
+
+                  <template v-else>
+                    <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>
+
+                    <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-2">
+                      <div class="space-y-0.5">
+                        <p class="font-medium">Migration failed</p>
+                        <p>{{ run.errorMessage }}</p>
+                      </div>
+                      <button v-if="run.state === 'failed'" class="settings-btn-outline text-xs" :disabled="busy.retryingRun" @click="onRetryRun">
+                        <Loader2 v-if="busy.retryingRun" class="size-3.5 animate-spin" />
+                        Retry from last completed stage
+                      </button>
+                    </div>
+
+                    <template v-if="runReport || runProgress">
+                      <div class="grid gap-3 sm:grid-cols-2">
+                        <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 skipped - media root path not configured
+                            </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>
+                        <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>
+
+                    <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-48 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>
+                  </template>
+                </div>
+              </template>
+            </div>
+
+            <!-- Footer -->
+            <div class="shrink-0 border-t border-border px-5 md:px-6 py-4">
+              <div class="flex items-center justify-between">
+                <button
+                  class="flex items-center gap-1.5 px-4 py-2 rounded-md border border-border text-sm font-medium text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+                  @click="onBackOrCancel"
+                >
+                  <X v-if="currentStep === 0" :size="14" />
+                  <ChevronLeft v-else :size="14" />
+                  {{ currentStep === 0 ? 'Cancel' : 'Back' }}
+                </button>
+
+                <span class="text-xs text-muted-foreground hidden md:block">Step {{ currentStep + 1 }} of 5</span>
+
+                <button
+                  v-if="currentStep < 4"
+                  class="flex items-center gap-1.5 px-5 py-2 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:opacity-90 transition-opacity"
+                  @click="goNext"
+                >
+                  {{ continueLabel }}
+                  <ChevronRight :size="14" />
+                </button>
+                <button
+                  v-else
+                  class="flex items-center gap-1.5 px-4 py-2 rounded-md border border-border text-sm font-medium text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+                  @click="goToSetup"
+                >
+                  Back to Setup
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
diff --git a/client/src/features/migration/components/MigrationStepper.vue b/client/src/features/migration/components/MigrationStepper.vue
new file mode 100644
index 000000000..cb79ac4e7
--- /dev/null
+++ b/client/src/features/migration/components/MigrationStepper.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import { Check, AlertCircle, Loader2 } from 'lucide-vue-next'
+
+export interface StepDefinition {
+  label: string
+  status: 'pending' | 'done' | 'active' | 'running' | 'failed' | 'saved'
+}
+
+defineProps<{
+  steps: StepDefinition[]
+  activeIndex: number
+}>()
+
+const emit = defineEmits<{
+  stepClick: [index: number]
+}>()
+
+function handleStepClick(index: number) {
+  emit('stepClick', index)
+}
+</script>
+
+<template>
+  <nav class="flex flex-col">
+    <template v-for="(step, i) in steps" :key="i">
+      <button
+        class="flex items-start gap-3 rounded-lg px-2.5 py-2.5 text-left w-full transition-colors"
+        :class="i === activeIndex ? 'bg-primary/10' : 'hover:bg-muted'"
+        @click="handleStepClick(i)"
+      >
+        <span
+          class="mt-0.5 size-6 shrink-0 rounded-full flex items-center justify-center text-[10px] font-bold transition-colors"
+          :class="
+            step.status === 'done'
+              ? 'bg-emerald-500 text-white'
+              : step.status === 'failed'
+                ? 'bg-red-500 text-white'
+                : step.status === 'running'
+                  ? 'bg-sky-500 text-white'
+                  : i === activeIndex
+                    ? 'bg-primary text-primary-foreground'
+                    : 'border-2 border-muted-foreground/25 text-muted-foreground'
+          "
+        >
+          <Check v-if="step.status === 'done'" class="size-3" />
+          <AlertCircle v-else-if="step.status === 'failed'" class="size-3" />
+          <Loader2 v-else-if="step.status === 'running'" class="size-3 animate-spin" />
+          <span v-else>{{ i + 1 }}</span>
+        </span>
+        <span class="flex flex-col min-w-0 pt-0.5">
+          <span class="text-xs font-medium leading-snug" :class="i === activeIndex ? 'text-primary' : 'text-foreground/80'">
+            {{ step.label }}
+          </span>
+          <span v-if="step.status === 'done' && i !== activeIndex" class="text-[10px] text-emerald-600 mt-0.5 leading-none">Done</span>
+          <span v-else-if="step.status === 'saved' && i !== activeIndex" class="text-[10px] text-amber-600 mt-0.5 leading-none">Saved</span>
+          <span v-else-if="step.status === 'running'" class="text-[10px] text-sky-600 mt-0.5 leading-none">Running</span>
+          <span v-else-if="step.status === 'failed'" class="text-[10px] text-red-600 mt-0.5 leading-none">Failed</span>
+        </span>
+      </button>
+      <div v-if="i < steps.length - 1" class="ml-[1.375rem] w-px h-3 bg-border shrink-0" />
+    </template>
+  </nav>
+</template>
diff --git a/client/src/features/migration/components/SearchableUserSelect.vue b/client/src/features/migration/components/SearchableUserSelect.vue
new file mode 100644
index 000000000..ea56c32fe
--- /dev/null
+++ b/client/src/features/migration/components/SearchableUserSelect.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import {
+  ComboboxAnchor,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxItemIndicator,
+  ComboboxPortal,
+  ComboboxRoot,
+  ComboboxTrigger,
+  ComboboxViewport,
+} from 'reka-ui'
+import { Check, ChevronsUpDown } from 'lucide-vue-next'
+
+interface User {
+  id: number
+  username: string
+  name: string
+}
+
+const props = defineProps<{
+  users: User[]
+  modelValue: number | null
+  disabled?: boolean
+  placeholder?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: number | null]
+}>()
+
+const searchTerm = ref('')
+
+const selectedUser = computed(() => props.users.find((u) => u.id === props.modelValue) ?? null)
+
+const filteredUsers = computed(() => {
+  const q = searchTerm.value.toLowerCase().trim()
+  if (!q) return props.users
+  return props.users.filter((u) => u.username.toLowerCase().includes(q) || u.name.toLowerCase().includes(q))
+})
+
+function handleSelect(user: User | null) {
+  emit('update:modelValue', user?.id ?? null)
+}
+
+function displayValue(user: unknown): string {
+  if (!user || typeof user !== 'object') return ''
+  const u = user as User
+  return `${u.username} · ${u.name}`
+}
+</script>
+
+<template>
+  <ComboboxRoot :model-value="selectedUser" :ignore-filter="true" :disabled="disabled" @update:model-value="handleSelect">
+    <ComboboxAnchor
+      class="inline-flex w-full min-w-48 items-center justify-between rounded-md border border-input bg-background text-sm text-foreground transition-colors focus-within:ring-2 focus-within:ring-primary/50 focus-within:border-primary disabled:opacity-50"
+    >
+      <ComboboxInput
+        v-model="searchTerm"
+        :display-value="displayValue"
+        :placeholder="placeholder ?? 'Select user'"
+        class="h-9 w-full bg-transparent px-3 text-sm outline-none placeholder:text-muted-foreground/70 disabled:opacity-50"
+      />
+      <ComboboxTrigger class="shrink-0 px-2 text-muted-foreground">
+        <ChevronsUpDown class="size-3.5" />
+      </ComboboxTrigger>
+    </ComboboxAnchor>
+
+    <ComboboxPortal>
+      <ComboboxContent
+        position="popper"
+        :side-offset="4"
+        class="z-50 max-h-60 w-[var(--reka-combobox-trigger-width)] overflow-hidden rounded-md border border-border bg-popover shadow-md"
+      >
+        <ComboboxViewport class="p-1">
+          <ComboboxEmpty class="px-3 py-2 text-sm text-muted-foreground"> No users found </ComboboxEmpty>
+          <ComboboxItem
+            v-for="user in filteredUsers"
+            :key="user.id"
+            :value="user"
+            class="relative flex cursor-pointer items-center rounded-sm px-3 py-1.5 text-sm outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50"
+          >
+            <ComboboxItemIndicator class="absolute right-2">
+              <Check class="size-3.5" />
+            </ComboboxItemIndicator>
+            <div>
+              <span class="font-medium">{{ user.username }}</span>
+              <span class="ml-1.5 text-muted-foreground">{{ user.name }}</span>
+            </div>
+          </ComboboxItem>
+        </ComboboxViewport>
+      </ComboboxContent>
+    </ComboboxPortal>
+  </ComboboxRoot>
+</template>
diff --git a/client/src/features/migration/composables/useMigrationPolling.ts b/client/src/features/migration/composables/useMigrationPolling.ts
new file mode 100644
index 000000000..6931bb798
--- /dev/null
+++ b/client/src/features/migration/composables/useMigrationPolling.ts
@@ -0,0 +1,51 @@
+import { onBeforeUnmount, ref, watch, type Ref } from 'vue'
+
+interface UseMigrationPollingOptions {
+  runState: Ref<string | undefined>
+  pollFn: () => Promise<void>
+  intervalMs?: number
+}
+
+export function useMigrationPolling({ runState, pollFn, intervalMs = 3000 }: UseMigrationPollingOptions) {
+  let timer: ReturnType<typeof setInterval> | null = null
+  const pollingError = ref(false)
+
+  function start() {
+    stop()
+    timer = setInterval(() => void doPoll(), intervalMs)
+  }
+
+  function stop() {
+    if (timer == null) return
+    clearInterval(timer)
+    timer = null
+  }
+
+  async function doPoll() {
+    try {
+      await pollFn()
+      pollingError.value = false
+    } catch {
+      stop()
+      pollingError.value = true
+    }
+  }
+
+  function retry() {
+    pollingError.value = false
+    start()
+    void doPoll()
+  }
+
+  watch(runState, (state) => {
+    if (state === 'running') {
+      start()
+    } else {
+      stop()
+    }
+  })
+
+  onBeforeUnmount(stop)
+
+  return { pollingError, start, stop, retry }
+}
diff --git a/client/src/features/migration/composables/useMigrationProgress.ts b/client/src/features/migration/composables/useMigrationProgress.ts
new file mode 100644
index 000000000..ab49b7a45
--- /dev/null
+++ b/client/src/features/migration/composables/useMigrationProgress.ts
@@ -0,0 +1,57 @@
+import { ref } from 'vue'
+import { io, Socket } from 'socket.io-client'
+import type { MigrationProgressEvent } from '@projectx/types'
+import { getAccessToken } from '@/lib/api'
+
+let socket: Socket | null = null
+const progressMap = ref<Map<number, MigrationProgressEvent>>(new Map())
+const subscribedRuns = new Set<number>()
+
+function getSocket(): Socket {
+  if (!socket) {
+    socket = io('/migration', {
+      auth: (cb: (data: object) => void) => cb({ token: getAccessToken() }),
+      transports: ['websocket'],
+      autoConnect: true,
+    })
+
+    socket.on('migration:progress', (event: MigrationProgressEvent) => {
+      progressMap.value.set(event.runId, event)
+      progressMap.value = new Map(progressMap.value)
+    })
+
+    socket.on('disconnect', () => {
+      progressMap.value = new Map()
+    })
+
+    socket.on('connect', () => {
+      for (const runId of subscribedRuns) {
+        socket!.emit('subscribe:run', runId)
+      }
+    })
+  }
+  return socket
+}
+
+export function useMigrationProgress() {
+  function subscribeRun(runId: number): void {
+    subscribedRuns.add(runId)
+    getSocket().emit('subscribe:run', runId)
+  }
+
+  function unsubscribeRun(runId: number): void {
+    subscribedRuns.delete(runId)
+    progressMap.value.delete(runId)
+    progressMap.value = new Map(progressMap.value)
+  }
+
+  function getProgress(runId: number): MigrationProgressEvent | undefined {
+    return progressMap.value.get(runId)
+  }
+
+  function isRunning(runId: number): boolean {
+    return progressMap.value.get(runId)?.state === 'running'
+  }
+
+  return { subscribeRun, unsubscribeRun, getProgress, isRunning, progressMap }
+}
diff --git a/client/src/features/migration/lib/migration-api.ts b/client/src/features/migration/lib/migration-api.ts
index 961856938..7fb72e767 100644
--- a/client/src/features/migration/lib/migration-api.ts
+++ b/client/src/features/migration/lib/migration-api.ts
@@ -1,82 +1,26 @@
 import { api } from '@/lib/api'
+import type {
+  MigrationRunState as SharedMigrationRunState,
+  MigrationSourceApi,
+  MigrationSourceCapabilities as SharedMigrationSourceCapabilities,
+  MigrationProfileApi,
+  MigrationPlanArtifactApi,
+  MigrationPlanSummary,
+  MigrationRunApi,
+  MigrationRunMetricApi,
+} from '@projectx/types'
 
-export type MigrationRunState = 'draft' | 'preflight_failed' | 'dry_run_ready' | 'running' | 'failed' | 'completed'
+export type MigrationRunState = SharedMigrationRunState
+export type MigrationSourceCapabilities = SharedMigrationSourceCapabilities
+export type MigrationSource = MigrationSourceApi
+export type MigrationProfile = MigrationProfileApi
+export type MigrationPlanArtifact = MigrationPlanArtifactApi & { summary: MigrationPlanSummary }
+export type MigrationRun = MigrationRunApi
 
-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 {
+export interface MigrationRunMetric extends MigrationRunMetricApi {
   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 {
@@ -95,7 +39,7 @@ export interface MigrationRunReport {
   run: MigrationRun
   metrics: MigrationRunMetric[]
   plan: Record<string, unknown> | null
-  summary: MigrationPlanArtifact['summary'] | null
+  summary: MigrationPlanSummary | null
 }
 
 export interface MigrationWorkflowState {
@@ -111,6 +55,8 @@ export interface MigrationWorkflowState {
 export interface PathMappingValidation {
   sourceId: number
   validatedAt: string
+  pathMappingsHash: string
+  persistedProfileId: number | null
   summary: {
     totalSourceBooks: number
     booksWithFilePath: number
@@ -243,6 +189,14 @@ export function createDryRunPlan(payload: { profileId: number; scopeOverride?: R
   }).then((res) => expectJson<MigrationPlanArtifact>(res, 'Failed to run dry-run plan'))
 }
 
+export function resolveDuplicateMatches(artifactId: number, resolutions: Array<{ targetBookId: number; selectedSourceBookId: string }>) {
+  return api(`/api/v1/migration/plans/${artifactId}/resolve-duplicates`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ resolutions }),
+  }).then((res) => expectJson<MigrationPlanArtifact>(res, 'Failed to resolve duplicate matches'))
+}
+
 export function startLiveRun(payload: { planArtifactId: number; targetKey?: string }) {
   return api('/api/v1/migration/runs/live', {
     method: 'POST',
@@ -259,8 +213,28 @@ 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'),
+export async function exportRunReport(runId: number, format: 'json' | 'csv') {
+  const res = await api(`/api/v1/migration/runs/${runId}/report/export?format=${format}`)
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(body || 'Failed to export migration report')
+  }
+  const disposition = res.headers.get('Content-Disposition') ?? ''
+  const fileNameMatch = disposition.match(/filename="?([^"]+)"?/)
+  const fileName = fileNameMatch?.[1] ?? `migration-run-${runId}-report.${format}`
+  const contentType = res.headers.get('Content-Type') ?? (format === 'csv' ? 'text/csv' : 'application/json')
+  const content = await res.text()
+  return { format, fileName, contentType, content }
+}
+
+export function cancelRun(runId: number) {
+  return api(`/api/v1/migration/runs/${runId}/cancel`, { method: 'POST' }).then((res) =>
+    expectJson<MigrationRun>(res, 'Failed to cancel migration run'),
+  )
+}
+
+export function retryRun(runId: number) {
+  return api(`/api/v1/migration/runs/${runId}/retry`, { method: 'POST' }).then((res) =>
+    expectJson<MigrationRun>(res, 'Failed to retry migration run'),
   )
 }
diff --git a/client/src/features/settings/MaintenanceSettings.vue b/client/src/features/settings/MaintenanceSettings.vue
index 69e4bf634..6bcbe8b2c 100644
--- a/client/src/features/settings/MaintenanceSettings.vue
+++ b/client/src/features/settings/MaintenanceSettings.vue
@@ -1,18 +1,58 @@
 <script setup lang="ts">
-import { ref, onMounted } from 'vue'
-import { Check, RefreshCw, Sparkles } from 'lucide-vue-next'
+import { ref, computed, onMounted } from 'vue'
+import { Check, RefreshCw, Sparkles, ArrowUpFromLine, CheckCircle2, AlertCircle, Loader2 } from 'lucide-vue-next'
 import { toast } from 'vue-sonner'
 import SettingsPageHeader from './SettingsPageHeader.vue'
+import MigrationModal from '@/features/migration/components/MigrationModal.vue'
 import { api } from '@/lib/api'
+import { getWorkflowState, type MigrationWorkflowState } from '@/features/migration/lib/migration-api'
+
+const showMigrationModal = ref(false)
 
 const running = ref(false)
 const queued = ref<number | null>(null)
-const error = ref<string | null>(null)
+const embeddingError = ref<string | null>(null)
+
+const migrationState = ref<MigrationWorkflowState | null>(null)
+const migrationLoading = ref(true)
+
+const migrationSource = computed(() => migrationState.value?.active?.source ?? null)
+const migrationRun = computed(() => migrationState.value?.active?.run ?? null)
+
+const migrationCardState = computed(() => {
+  if (migrationLoading.value) return 'loading'
+  if (!migrationSource.value) return 'none'
+  if (!migrationRun.value) return 'configured'
+  return migrationRun.value.state
+})
+
+onMounted(async () => {
+  try {
+    migrationState.value = await getWorkflowState()
+  } catch {
+    // non-fatal
+  } finally {
+    migrationLoading.value = false
+  }
+})
+
+async function onMigrationModalClose() {
+  showMigrationModal.value = false
+  try {
+    migrationState.value = await getWorkflowState()
+  } catch {
+    // non-fatal
+  }
+}
+
+function goToMigration() {
+  showMigrationModal.value = true
+}
 
 async function rebuildEmbeddings() {
   running.value = true
   queued.value = null
-  error.value = null
+  embeddingError.value = null
   try {
     const res = await api('/api/v1/books/embed-all', { method: 'POST' })
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
@@ -20,43 +60,126 @@ async function rebuildEmbeddings() {
     queued.value = data.queued
     toast.success(`${data.queued} books queued for embedding`)
   } catch (e) {
-    error.value = e instanceof Error ? e.message : 'Failed'
-    toast.error(`Failed to rebuild embeddings: ${error.value ?? 'Unknown error'}`)
+    embeddingError.value = e instanceof Error ? e.message : 'Failed'
+    toast.error(`Failed to rebuild embeddings: ${embeddingError.value ?? 'Unknown error'}`)
   } finally {
     running.value = false
   }
 }
 
-onMounted(() => {})
+function formatDate(iso: string | null | undefined): string {
+  if (!iso) return ''
+  return new Date(iso).toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' })
+}
 </script>
 
 <template>
+  <MigrationModal v-if="showMigrationModal" @close="onMigrationModalClose" />
   <SettingsPageHeader title="Maintenance" subtitle="Manage background tasks, system indices, and maintenance operations." />
 
-  <div>
-    <p class="settings-group-label">Recommendations</p>
-    <div class="border border-border rounded-lg bg-card px-5 py-5">
-      <div class="flex items-start justify-between gap-6">
-        <div class="flex items-start gap-3">
-          <div class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary/10">
-            <Sparkles :size="16" class="text-primary" />
-          </div>
-          <div>
-            <p class="settings-label">Refresh recommendation index</p>
-            <p class="settings-hint leading-relaxed max-w-sm">
-              Update the recommendations engine with your latest library changes. This process runs in the background.
-            </p>
-            <p v-if="queued !== null" class="flex items-center gap-1.5 text-xs text-green-600 dark:text-green-400 mt-2">
-              <Check :size="12" />
-              {{ queued }} books queued for processing
-            </p>
-            <p v-if="error" class="text-xs text-destructive mt-2">{{ error }}</p>
+  <div class="space-y-6">
+    <!-- Booklore Import -->
+    <div>
+      <p class="settings-group-label">Import</p>
+      <div class="border border-border rounded-lg bg-card px-5 py-5">
+        <div class="flex items-start justify-between gap-6">
+          <div class="flex items-start gap-3">
+            <div
+              class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg"
+              :class="
+                migrationCardState === 'completed'
+                  ? 'bg-emerald-500/10'
+                  : migrationCardState === 'failed'
+                    ? 'bg-red-500/10'
+                    : migrationCardState === 'running'
+                      ? 'bg-sky-500/10'
+                      : 'bg-primary/10'
+              "
+            >
+              <Loader2
+                v-if="migrationCardState === 'loading' || migrationCardState === 'running'"
+                :size="16"
+                class="animate-spin"
+                :class="migrationCardState === 'running' ? 'text-sky-600' : 'text-muted-foreground'"
+              />
+              <CheckCircle2 v-else-if="migrationCardState === 'completed'" :size="16" class="text-emerald-600" />
+              <AlertCircle v-else-if="migrationCardState === 'failed'" :size="16" class="text-red-600" />
+              <ArrowUpFromLine v-else :size="16" class="text-primary" />
+            </div>
+
+            <div>
+              <p class="settings-label">
+                <template v-if="migrationCardState === 'none' || migrationCardState === 'loading'">Import from Booklore</template>
+                <template v-else-if="migrationCardState === 'configured'">Booklore import configured</template>
+                <template v-else-if="migrationCardState === 'running'">Migration running</template>
+                <template v-else-if="migrationCardState === 'completed'">Migration completed</template>
+                <template v-else-if="migrationCardState === 'failed'">Migration failed</template>
+              </p>
+
+              <p class="settings-hint leading-relaxed max-w-sm mt-0.5">
+                <template v-if="migrationCardState === 'none' || migrationCardState === 'loading'">
+                  One-time import of books, metadata, and reading progress from a previous Booklore installation.
+                </template>
+                <template v-else-if="migrationCardState === 'configured'">
+                  Source: {{ migrationSource!.name }}. No migration run yet - continue setup to run the import.
+                </template>
+                <template v-else-if="migrationCardState === 'running'">
+                  Stage: {{ migrationRun!.currentStage ?? 'initializing' }} - started
+                  {{ migrationRun!.startedAt ? formatDate(migrationRun!.startedAt) : 'recently' }}
+                </template>
+                <template v-else-if="migrationCardState === 'completed'">
+                  From {{ migrationSource!.name }} - completed {{ formatDate(migrationRun!.endedAt) }}
+                </template>
+                <template v-else-if="migrationCardState === 'failed'">
+                  {{ migrationRun!.errorMessage ?? 'An error occurred during migration.' }}
+                </template>
+              </p>
+            </div>
           </div>
+
+          <button
+            v-if="migrationCardState !== 'loading'"
+            class="shrink-0"
+            :class="migrationCardState === 'none' ? 'settings-btn-primary' : 'settings-btn-outline'"
+            @click="goToMigration"
+          >
+            <template v-if="migrationCardState === 'none'">
+              <ArrowUpFromLine :size="13" />
+              Get Started
+            </template>
+            <template v-else-if="migrationCardState === 'configured'">Continue Setup</template>
+            <template v-else>View Details</template>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <!-- Recommendations -->
+    <div>
+      <p class="settings-group-label">Recommendations</p>
+      <div class="border border-border rounded-lg bg-card px-5 py-5">
+        <div class="flex items-start justify-between gap-6">
+          <div class="flex items-start gap-3">
+            <div class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary/10">
+              <Sparkles :size="16" class="text-primary" />
+            </div>
+            <div>
+              <p class="settings-label">Refresh recommendation index</p>
+              <p class="settings-hint leading-relaxed max-w-sm">
+                Update the recommendations engine with your latest library changes. This process runs in the background.
+              </p>
+              <p v-if="queued !== null" class="flex items-center gap-1.5 text-xs text-green-600 dark:text-green-400 mt-2">
+                <Check :size="12" />
+                {{ queued }} books queued for processing
+              </p>
+              <p v-if="embeddingError" class="text-xs text-destructive mt-2">{{ embeddingError }}</p>
+            </div>
+          </div>
+          <button class="settings-btn-outline shrink-0" :disabled="running" @click="rebuildEmbeddings">
+            <RefreshCw :size="13" :class="running ? 'animate-spin' : ''" />
+            {{ running ? 'Running...' : 'Run' }}
+          </button>
         </div>
-        <button class="settings-btn-outline" :disabled="running" @click="rebuildEmbeddings">
-          <RefreshCw :size="13" :class="running ? 'animate-spin' : ''" />
-          {{ running ? 'Running...' : 'Run' }}
-        </button>
       </div>
     </div>
   </div>
diff --git a/client/src/features/settings/MigrationSettings.vue b/client/src/features/settings/MigrationSettings.vue
index d670d8697..c8969f31c 100644
--- a/client/src/features/settings/MigrationSettings.vue
+++ b/client/src/features/settings/MigrationSettings.vue
@@ -1,9 +1,13 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { computed, 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 MigrationStepper from '@/features/migration/components/MigrationStepper.vue'
+import SearchableUserSelect from '@/features/migration/components/SearchableUserSelect.vue'
+import type { StepDefinition } from '@/features/migration/components/MigrationStepper.vue'
 import {
+  cancelRun,
   createDryRunPlan,
   createProfile,
   createSource,
@@ -15,6 +19,8 @@ import {
   listSupportedSourceTypes,
   listTargetLibraryFolders,
   listTargetUsers,
+  resolveDuplicateMatches,
+  retryRun,
   startLiveRun,
   suggestUserMappings,
   testSource,
@@ -30,6 +36,10 @@ import {
   type MigrationWorkflowState,
   type PathMappingValidation,
 } from '@/features/migration/lib/migration-api'
+import { useMigrationPolling } from '@/features/migration/composables/useMigrationPolling'
+import { useMigrationProgress } from '@/features/migration/composables/useMigrationProgress'
+
+const { subscribeRun, unsubscribeRun, getProgress: getSocketProgress, progressMap: socketProgressMap } = useMigrationProgress()
 
 interface TargetUser {
   id: number
@@ -89,9 +99,12 @@ const busy = reactive({
   savingProfile: false,
   dryRun: false,
   startingRun: false,
+  cancellingRun: false,
+  retryingRun: false,
   loadingProgress: false,
   loadingReport: false,
   exporting: false,
+  resolvingDuplicates: false,
 })
 
 const showPassword = ref(false)
@@ -106,24 +119,6 @@ const sourceCapabilities = computed<MigrationSourceCapabilities | null>(() => so
 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
@@ -153,10 +148,120 @@ const preflight = computed(() => {
   return { sourceValidated, pathMappingsValidated, dryRunFresh, ready: issues.length === 0, issues }
 })
 
+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 stepperSteps = computed<StepDefinition[]>(() => {
+  const s = stepStatus.value
+  return [
+    { label: 'Source Connection', status: s.source === 'done' ? 'done' : s.source === 'saved' ? 'saved' : 'pending' },
+    { label: 'User & Path Mapping', status: s.mappings },
+    { label: 'Dry-Run', status: s.dryRun },
+    { label: 'Run Migration', status: s.migration },
+    { label: 'Report', status: run.value ? 'done' : 'pending' },
+  ]
+})
+
+const activeStepIndex = computed(() => {
+  const s = stepStatus.value
+  if (s.migration === 'running' || s.migration === 'failed') return 3
+  if (run.value) return 4
+  if (s.dryRun === 'done') return 3
+  if (s.mappings === 'done') return 2
+  if (s.source === 'done' || s.source === 'saved') return 1
+  return 0
+})
+
+const currentStep = ref(0)
+
+watch(activeStepIndex, (newVal) => {
+  if (newVal > currentStep.value) {
+    currentStep.value = newVal
+  }
+})
+
+function onStepClick(index: number) {
+  currentStep.value = index
+}
+
+function goNext() {
+  if (currentStep.value < 4) currentStep.value++
+}
+
+function goPrev() {
+  if (currentStep.value > 0) currentStep.value--
+}
+
+function goToSetup() {
+  currentStep.value = 0
+}
+
+const stepTitles = ['Source Connection', 'User & Path Mapping', 'Dry Run', 'Run Migration', 'Migration Report']
+const stepSubtitles = [
+  'Configure the database connection to your source Booklore instance.',
+  'Map source users to target users and translate file paths.',
+  'Preview what will be imported before running the live migration.',
+  'Start the live import and monitor its progress.',
+  'Review what was imported and export a detailed report.',
+]
+const continueLabels = ['Continue to Mappings', 'Continue to Dry Run', 'Continue to Migration', 'View Report', '']
+
+const currentStepTitle = computed(() => stepTitles[currentStep.value] ?? '')
+const currentStepSubtitle = computed(() => stepSubtitles[currentStep.value] ?? '')
+const continueLabel = computed(() => continueLabels[currentStep.value] ?? '')
+
+const currentStepBadge = computed((): { label: string; cls: string } | null => {
+  const s = stepStatus.value
+  const n = currentStep.value
+  if (n === 0) {
+    if (s.source === 'done') return { label: 'Validated', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+    if (s.source === 'saved') return { label: 'Saved', cls: 'text-amber-700 bg-amber-500/10 border-amber-500/20' }
+  }
+  if (n === 1 && s.mappings === 'done') return { label: 'Saved', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+  if (n === 2 && s.dryRun === 'done') return { label: 'Up to date', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+  if (n === 3) {
+    if (s.migration === 'done') return { label: 'Completed', cls: 'text-emerald-700 bg-emerald-500/10 border-emerald-500/20' }
+    if (s.migration === 'running') return { label: 'Running', cls: 'text-sky-700 bg-sky-500/10 border-sky-500/20' }
+    if (s.migration === 'failed') return { label: 'Failed', cls: 'text-red-700 bg-red-500/10 border-red-500/20' }
+  }
+  return null
+})
+
+const unresolvedSummary = computed(() => Object.entries(plan.value?.summary?.unresolvedByReason ?? {}))
+
+interface DuplicateBookMatch {
+  targetBookId: number
+  sourceBookIds: string[]
+  strategies: string[]
+  reason: string
+}
+
+const duplicateMatches = computed<DuplicateBookMatch[]>(() => {
+  const raw = plan.value?.plan
+  if (!raw || typeof raw !== 'object') return []
+  const planData = raw as Record<string, unknown>
+  return Array.isArray(planData.duplicateBookMatches) ? planData.duplicateBookMatches : []
+})
+
+const duplicateResolutions = ref<Map<number, string>>(new Map())
+
 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 bookCovers = m('book_covers', '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)
@@ -182,27 +287,83 @@ const reportData = computed(() => {
   }
 })
 
-let runPollTimer: ReturnType<typeof setInterval> | null = null
+const STAGE_NAMES = ['shared_overlays', 'book_covers', 'user_state'] as const
+
+const migrationProgress = computed(() => {
+  const currentRun = run.value
+  if (!currentRun || currentRun.state !== 'running') return null
+
+  const currentStage = currentRun.currentStage ?? 'init'
+  if (currentStage === 'completed') return { percent: 100, label: 'Completed' }
+
+  const stageIdx = STAGE_NAMES.indexOf(currentStage as (typeof STAGE_NAMES)[number])
+  const completedStages = stageIdx >= 0 ? stageIdx : 0
+  const stageWeight = 100 / STAGE_NAMES.length
+  const percent = Math.min(Math.round(completedStages * stageWeight + stageWeight * 0.5), 99)
+
+  const stageLabels: Record<string, string> = {
+    init: 'Initializing',
+    shared_overlays: 'Importing metadata',
+    book_covers: 'Importing covers',
+    user_state: 'Importing user data',
+  }
+
+  return { percent, label: stageLabels[currentStage] ?? currentStage }
+})
+
+watch(socketProgressMap, () => {
+  const currentRun = run.value
+  if (!currentRun) return
+  const socketData = getSocketProgress(currentRun.id)
+  if (!socketData) return
+
+  runProgress.value = {
+    run: { ...currentRun, state: socketData.state, currentStage: socketData.currentStage },
+    totals: socketData.totals,
+    metrics: socketData.metrics as MigrationRunProgress['metrics'],
+  }
+  if (socketData.state !== 'running') {
+    unsubscribeRun(currentRun.id)
+    void refreshWorkflowState()
+  }
+})
+
+const { pollingError, retry: onRetryPolling } = useMigrationPolling({
+  runState: computed(() => run.value?.state),
+  pollFn: async () => {
+    const currentRun = run.value
+    if (!currentRun) return
+    // Only poll if no fresh socket data is available
+    const socketData = getSocketProgress(currentRun.id)
+    if (socketData) {
+      runProgress.value = {
+        run: { ...run.value!, state: socketData.state, currentStage: socketData.currentStage },
+        totals: socketData.totals,
+        metrics: socketData.metrics as MigrationRunProgress['metrics'],
+      }
+      if (socketData.state !== 'running') {
+        unsubscribeRun(currentRun.id)
+        await refreshWorkflowState()
+      }
+      return
+    }
+    busy.loadingProgress = true
+    try {
+      runProgress.value = await getRunProgress(currentRun.id)
+      if (runProgress.value.run.state !== 'running') {
+        await refreshWorkflowState()
+      }
+    } finally {
+      busy.loadingProgress = false
+    }
+  },
+  intervalMs: 5000,
+})
 
 onMounted(async () => {
   await initialize()
 })
 
-onBeforeUnmount(() => {
-  stopRunPolling()
-})
-
-watch(
-  () => run.value?.state,
-  (state) => {
-    if (state === 'running') {
-      startRunPolling()
-      return
-    }
-    stopRunPolling()
-  },
-)
-
 async function initialize() {
   loading.value = true
   try {
@@ -228,6 +389,7 @@ async function refreshWorkflowState() {
     await autoLoadPathPrefixes()
   }
   if (run.value?.state === 'running') {
+    subscribeRun(run.value.id)
     await refreshRunProgress()
   }
 }
@@ -241,6 +403,7 @@ function hydrateSourceDraft() {
   sourceDraft.host = asString(cfg.host) ?? sourceDraft.host
   sourceDraft.port = asNumber(cfg.port) ?? sourceDraft.port
   sourceDraft.user = asString(cfg.user) ?? sourceDraft.user
+  sourceDraft.password = asString(cfg.password) ?? ''
   sourceDraft.database = asString(cfg.database) ?? sourceDraft.database
   sourceDraft.ssl = asBoolean(cfg.ssl) ?? sourceDraft.ssl
   sourceDraft.mediaRootPath = asString(cfg.mediaRootPath) ?? ''
@@ -436,8 +599,8 @@ async function onSaveMappings() {
     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
+      } catch (pathError) {
+        toast.warning(getErrorMessage(pathError, 'Path validation failed, but profile will still be saved'))
       }
     }
 
@@ -449,6 +612,7 @@ async function onSaveMappings() {
       scope: {
         preflight: {
           pathValidatedAt: pathValidation.value?.validatedAt ?? getPersistedPathValidatedAt(profile.value),
+          pathMappingsHash: pathValidation.value?.pathMappingsHash ?? getPersistedPathMappingsHash(profile.value),
           suggestionsLoadedAt: suggestionsLoadedAt.value,
         },
       },
@@ -487,6 +651,42 @@ async function onRunDryRun() {
   }
 }
 
+function handleDuplicateSelection(targetBookId: number, sourceBookId: string) {
+  duplicateResolutions.value.set(targetBookId, sourceBookId)
+}
+
+async function onResolveDuplicates() {
+  const currentPlan = plan.value
+  if (!currentPlan) return
+
+  const matches = duplicateMatches.value
+  if (matches.length === 0) return
+
+  const unresolved = matches.filter((m) => !duplicateResolutions.value.has(m.targetBookId))
+  if (unresolved.length > 0) {
+    toast.error(`Select a source book for all ${unresolved.length} duplicate groups`)
+    return
+  }
+
+  busy.resolvingDuplicates = true
+  try {
+    const resolutions = matches.map((m) => ({
+      targetBookId: m.targetBookId,
+      selectedSourceBookId: duplicateResolutions.value.get(m.targetBookId)!,
+    }))
+    await resolveDuplicateMatches(currentPlan.id, resolutions)
+    duplicateResolutions.value = new Map()
+    await refreshWorkflowState()
+    toast.success('Duplicate matches resolved')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to resolve duplicates'))
+  } finally {
+    busy.resolvingDuplicates = false
+  }
+}
+
+const confirmingMigrationStart = ref(false)
+
 async function onStartMigration() {
   if (!preflight.value.ready) {
     toast.error(preflight.value.issues[0] ?? 'Migration preflight not ready')
@@ -498,9 +698,12 @@ async function onStartMigration() {
     return
   }
 
-  const confirmed = window.confirm('Start migration now?')
-  if (!confirmed) return
+  if (!confirmingMigrationStart.value) {
+    confirmingMigrationStart.value = true
+    return
+  }
 
+  confirmingMigrationStart.value = false
   busy.startingRun = true
   try {
     await startLiveRun({ planArtifactId: currentPlan.id })
@@ -514,6 +717,40 @@ async function onStartMigration() {
   }
 }
 
+function onCancelMigrationStart() {
+  confirmingMigrationStart.value = false
+}
+
+async function onCancelRun() {
+  const currentRun = run.value
+  if (!currentRun) return
+  busy.cancellingRun = true
+  try {
+    await cancelRun(currentRun.id)
+    await refreshWorkflowState()
+    toast.success('Migration run cancelled')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to cancel migration'))
+  } finally {
+    busy.cancellingRun = false
+  }
+}
+
+async function onRetryRun() {
+  const currentRun = run.value
+  if (!currentRun) return
+  busy.retryingRun = true
+  try {
+    await retryRun(currentRun.id)
+    await refreshWorkflowState()
+    toast.success('Migration run retried - resuming from last completed stage')
+  } catch (error) {
+    toast.error(getErrorMessage(error, 'Failed to retry migration'))
+  } finally {
+    busy.retryingRun = false
+  }
+}
+
 async function refreshRunProgress() {
   const currentRun = run.value
   if (!currentRun) return
@@ -522,11 +759,9 @@ async function refreshRunProgress() {
   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
@@ -582,19 +817,6 @@ async function exportReport(format: 'json' | 'csv') {
   }
 }
 
-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)
@@ -625,6 +847,10 @@ function friendlyUnresolvedReason(reason: string | null): string {
   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'
+  if (reason === 'ambiguous_isbn_match') return 'Multiple books matched the same ISBN'
+  if (reason === 'ambiguous_file_hash_match') return 'Multiple books matched the same file hash'
+  if (reason === 'ambiguous_file_path_match') return 'Multiple books matched the same file path'
+  if (reason === 'ambiguous_title_author_match') return 'Multiple books matched the same title and author'
   return reason ?? 'Could not determine reason'
 }
 
@@ -669,10 +895,17 @@ function getPersistedPathValidatedAt(currentProfile: MigrationProfile | null): s
   return asString(preflightScope.pathValidatedAt)
 }
 
+function getPersistedPathMappingsHash(currentProfile: MigrationProfile | null): string | null {
+  if (!currentProfile) return null
+  const scope = asRecord(currentProfile.scope)
+  const preflightScope = asRecord(scope.preflight)
+  return asString(preflightScope.pathMappingsHash)
+}
+
 function hasValidatedPathMappings(currentProfile: MigrationProfile | null): boolean {
   if (!currentProfile) return false
   if (currentProfile.pathMappings.length === 0) return true
-  return getPersistedPathValidatedAt(currentProfile) != null
+  return getPersistedPathValidatedAt(currentProfile) != null && getPersistedPathMappingsHash(currentProfile) != null
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -717,477 +950,571 @@ function formatSourceCountLabel(key: string) {
     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">
+  <div v-if="loading" class="flex items-center justify-center py-16">
     <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>
+  <div v-else class="flex gap-10 items-start">
+    <!-- Sidebar stepper (desktop) -->
+    <aside class="hidden lg:block w-44 shrink-0 pt-1">
+      <p class="settings-group-label mb-2">Progress</p>
+      <MigrationStepper :steps="stepperSteps" :active-index="currentStep" @step-click="onStepClick" />
+    </aside>
 
-    <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>
+    <!-- Content area -->
+    <div class="flex-1 min-w-0">
+      <!-- Mobile progress -->
+      <div class="lg:hidden mb-4 flex items-center gap-3">
+        <div class="flex-1 h-1 rounded-full bg-muted overflow-hidden">
+          <div class="h-full rounded-full bg-primary transition-all duration-300" :style="{ width: `${(currentStep / 4) * 100}%` }" />
+        </div>
+        <span class="text-xs text-muted-foreground shrink-0">{{ currentStep + 1 }} / 5</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" />
+
+      <!-- Unified step card -->
+      <div class="rounded-xl border border-border bg-card shadow-sm overflow-hidden">
+        <!-- Card header -->
+        <div class="px-6 pt-6 pb-5 border-b border-border">
+          <div class="flex items-start justify-between gap-4">
+            <div>
+              <h2 class="font-serif font-semibold text-foreground text-lg tracking-tight">{{ currentStepTitle }}</h2>
+              <p class="text-xs text-muted-foreground mt-1">{{ currentStepSubtitle }}</p>
+            </div>
+            <span
+              v-if="currentStepBadge"
+              class="shrink-0 mt-0.5 inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium"
+              :class="currentStepBadge.cls"
+              >{{ currentStepBadge.label }}</span
+            >
+          </div>
+        </div>
+
+        <!-- Card body -->
+        <div class="px-6 py-6">
+          <!-- Step 0: Source Connection -->
+          <div v-if="currentStep === 0" class="space-y-5">
+            <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"
+                    :type="showPassword ? 'text' : 'password'"
+                    :placeholder="source ? 'Saved - leave unchanged' : '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>
-          </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
+              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>
 
-            <!-- 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 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>
 
-          <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>
+          <!-- Step 1: User & Path Mapping -->
+          <div v-else-if="currentStep === 1" class="space-y-5">
+            <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>
 
-        <!-- 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 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">
+                      <SearchableUserSelect v-model="row.targetUserId" :users="targetUsers" :disabled="hasActiveRun" />
+                    </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 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.
+            <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>
-            <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>
+
+            <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>
+
+          <!-- Step 2: Dry Run -->
+          <div v-else-if="currentStep === 2" class="space-y-5">
+            <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">{{ friendlyUnresolvedReason(reason) }}: {{ count }}</p>
+              </div>
+
+              <div v-if="duplicateMatches.length > 0" class="space-y-3 border-t border-border pt-3">
+                <div>
+                  <p class="font-medium text-red-600">Duplicate target matches</p>
+                  <p class="text-xs text-muted-foreground">
+                    Multiple source books matched the same target book. Select which source book to use for each target.
+                  </p>
+                </div>
+                <div class="space-y-3">
+                  <div v-for="dup in duplicateMatches" :key="dup.targetBookId" class="rounded border border-border bg-background p-3 space-y-2">
+                    <p class="text-xs font-medium">Target book #{{ dup.targetBookId }}</p>
+                    <div class="space-y-1">
+                      <label
+                        v-for="sourceId in dup.sourceBookIds"
+                        :key="sourceId"
+                        class="flex items-center gap-2 rounded px-2 py-1 text-xs hover:bg-muted/50 cursor-pointer"
+                      >
+                        <input
+                          type="radio"
+                          :name="`dup-${dup.targetBookId}`"
+                          :value="sourceId"
+                          :checked="duplicateResolutions.get(dup.targetBookId) === sourceId"
+                          class="accent-primary"
+                          @change="() => handleDuplicateSelection(dup.targetBookId, sourceId)"
+                        />
+                        <span>{{ sourceId }}</span>
+                        <span class="text-muted-foreground"> ({{ dup.strategies[dup.sourceBookIds.indexOf(sourceId)] ?? 'unknown' }}) </span>
+                      </label>
+                    </div>
+                  </div>
+                </div>
+                <button
+                  class="settings-btn-primary"
+                  :disabled="busy.resolvingDuplicates || duplicateResolutions.size < duplicateMatches.length"
+                  @click="onResolveDuplicates"
+                >
+                  <Loader2 v-if="busy.resolvingDuplicates" class="size-3.5 animate-spin" />
+                  Resolve {{ duplicateMatches.length }} duplicate{{ duplicateMatches.length === 1 ? '' : 's' }}
+                </button>
               </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.
+          <!-- Step 3: Run Migration -->
+          <div v-else-if="currentStep === 3" class="space-y-5">
+            <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">
+              <template v-if="confirmingMigrationStart">
+                <span class="text-xs text-amber-600 self-center">This will start the live migration. Are you sure?</span>
+                <button class="settings-btn-primary" :disabled="busy.startingRun" @click="onStartMigration">
+                  <Loader2 v-if="busy.startingRun" class="size-3.5 animate-spin" />
+                  Confirm Start
+                </button>
+                <button class="settings-btn-outline" @click="onCancelMigrationStart">Cancel</button>
+              </template>
+              <template v-else>
+                <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>
+              </template>
+              <button v-if="run?.state === 'running'" class="settings-btn-outline text-red-600" :disabled="busy.cancellingRun" @click="onCancelRun">
+                <Loader2 v-if="busy.cancellingRun" class="size-3.5 animate-spin" />
+                Cancel Run
+              </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="pollingError"
+              class="rounded border border-amber-500/20 bg-amber-500/10 px-3 py-2 flex items-center gap-2 text-xs text-amber-700"
+            >
+              <span>Status polling stopped due to an error.</span>
+              <button class="underline font-medium" @click="onRetryPolling">Retry</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>
+              <button v-if="run.state !== 'running'" class="text-xs text-primary underline-offset-2 hover:underline ml-auto" @click="goNext">
+                View Report
+              </button>
+            </div>
+
+            <div v-if="migrationProgress" class="space-y-1.5">
+              <div class="flex items-center justify-between text-xs text-muted-foreground">
+                <span>{{ migrationProgress.label }}</span>
+                <span>{{ migrationProgress.percent }}%</span>
+              </div>
+              <div class="h-2 w-full rounded-full bg-muted overflow-hidden">
+                <div
+                  class="h-full rounded-full bg-primary transition-all duration-500 ease-out"
+                  :style="{ width: `${migrationProgress.percent}%` }"
+                />
+              </div>
+            </div>
           </div>
-        </template>
+
+          <!-- Step 4: Migration Report -->
+          <div v-else-if="currentStep === 4" class="space-y-5">
+            <p v-if="!run" class="text-sm text-muted-foreground">No migration run yet. Complete the steps above to start.</p>
+
+            <template v-else>
+              <!-- 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-2">
+                <div class="space-y-0.5">
+                  <p class="font-medium">Migration failed</p>
+                  <p>{{ run.errorMessage }}</p>
+                </div>
+                <button v-if="run.state === 'failed'" class="settings-btn-outline text-xs" :disabled="busy.retryingRun" @click="onRetryRun">
+                  <Loader2 v-if="busy.retryingRun" class="size-3.5 animate-spin" />
+                  Retry from last completed stage
+                </button>
+              </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>
+            </template>
+          </div>
+        </div>
+
+        <!-- Card footer -->
+        <div class="px-6 py-4 border-t border-border bg-muted/30 flex items-center justify-between">
+          <button v-if="currentStep > 0" class="settings-btn-outline" @click="goPrev">Back</button>
+          <div v-else />
+          <button v-if="currentStep < 4" class="settings-btn-primary" @click="goNext">{{ continueLabel }}</button>
+          <button v-else class="settings-btn-outline" @click="goToSetup">Back to Setup</button>
+        </div>
       </div>
-    </section>
+    </div>
   </div>
 </template>
diff --git a/client/src/features/settings/SettingsHeader.vue b/client/src/features/settings/SettingsHeader.vue
index 5af8aa1b9..e9a891bf3 100644
--- a/client/src/features/settings/SettingsHeader.vue
+++ b/client/src/features/settings/SettingsHeader.vue
@@ -52,9 +52,6 @@ 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 dad17fc98..906f8411b 100644
--- a/client/src/router/index.ts
+++ b/client/src/router/index.ts
@@ -152,12 +152,6 @@ 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/packages/types/src/index.ts b/packages/types/src/index.ts
index 848f2e9ae..788d94444 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -25,3 +25,4 @@ export * from "./metadata-score";
 export * from "./book-metadata-fetch";
 export * from "./statistics";
 export * from "./user-statistics";
+export * from "./migration";
diff --git a/packages/types/src/migration.ts b/packages/types/src/migration.ts
new file mode 100644
index 000000000..2c8c31ba0
--- /dev/null
+++ b/packages/types/src/migration.ts
@@ -0,0 +1,106 @@
+export type MigrationRunState = "draft" | "preflight_failed" | "dry_run_ready" | "running" | "failed" | "completed";
+
+export type UnresolvedReasonCode =
+  | "no_isbn_match"
+  | "no_file_hash_match"
+  | "no_file_path_match"
+  | "no_title_author_match"
+  | "insufficient_source_data"
+  | "ambiguous_isbn_match"
+  | "ambiguous_file_hash_match"
+  | "ambiguous_file_path_match"
+  | "ambiguous_title_author_match"
+  | "duplicate_target_match";
+
+export interface MigrationSourceCapabilities {
+  ok?: boolean;
+  sourceType: string;
+  sourceVersion: string | null;
+  missingTables: string[];
+  warnings: string[];
+  counts: Record<string, number>;
+}
+
+export interface MigrationSourceApi {
+  id: number;
+  type: string;
+  name: string;
+  connectionConfig: Record<string, unknown>;
+  capabilities: MigrationSourceCapabilities | null;
+  lastValidatedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MigrationProfileApi {
+  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 MigrationPlanSummary {
+  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> }>;
+  artifactSizeBytes?: { plan: number; sourceData: number; total: number };
+}
+
+export interface MigrationPlanArtifactApi {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  plan: Record<string, unknown>;
+  summary: MigrationPlanSummary;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MigrationRunApi {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  planArtifactId: number | null;
+  state: MigrationRunState;
+  currentStage: string | null;
+  targetKey: string;
+  errorMessage: string | null;
+  startedAt: string | null;
+  endedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MigrationRunMetricApi {
+  stage: string;
+  entityType: string;
+  processed: number;
+  imported: number;
+  skipped: number;
+  unresolved: number;
+  failed: number;
+  updatedAt: string;
+}
+
+export interface MigrationProgressEvent {
+  runId: number;
+  state: MigrationRunState;
+  currentStage: string | null;
+  totals: {
+    processed: number;
+    imported: number;
+    skipped: number;
+    unresolved: number;
+    failed: number;
+  };
+  metrics: MigrationRunMetricApi[];
+}
diff --git a/scripts/test/e2e-suites.mjs b/scripts/test/e2e-suites.mjs
index 8607c3062..258b4c2c9 100644
--- a/scripts/test/e2e-suites.mjs
+++ b/scripts/test/e2e-suites.mjs
@@ -81,6 +81,16 @@ export const E2E_SUITES = Object.freeze({
     prepareDedicatedDatabase: true,
     useDedicatedDatabase: true,
   },
+  "migration-booklore": {
+    id: "migration-booklore",
+    name: "Migration Booklore",
+    timeout: 70,
+    description: "Booklore migration end-to-end suite",
+    vitestTarget: "test/migration-booklore.e2e-spec.ts",
+    junitOutput: `${TEST_RESULTS_DIR}/migration-booklore-e2e-junit.xml`,
+    prepareDedicatedDatabase: true,
+    useDedicatedDatabase: true,
+  },
   "authorization-matrix": {
     id: "authorization-matrix",
     name: "Authorization Matrix",
diff --git a/server/.env.example b/server/.env.example
index 3be3d4697..a6ee1ae82 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -36,5 +36,10 @@ APP_URL=http://localhost:5173
 # Generate with: openssl rand -hex 32
 # EMAIL_ENCRYPTION_KEY=
 
+# Migration encryption key (optional but recommended — 64-char hex string for AES-256)
+# Encrypts source connection config (database passwords) at rest.
+# Generate with: openssl rand -hex 32
+# MIGRATION_ENCRYPTION_KEY=
+
 # SMTP for system emails (password reset) is configured via the admin UI,
 # not via environment variables.
diff --git a/server/src/app.module.ts b/server/src/app.module.ts
index 2cfe5308d..6a8775e0d 100644
--- a/server/src/app.module.ts
+++ b/server/src/app.module.ts
@@ -4,7 +4,7 @@ import { APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
 import { ScheduleModule } from '@nestjs/schedule';
 import { LoggerModule } from 'nestjs-pino';
 
-import { appConfig, authConfig, dbConfig, emailConfig, fileWriteConfig, storageConfig } from './config/config';
+import { appConfig, authConfig, dbConfig, emailConfig, fileWriteConfig, migrationConfig, storageConfig } from './config/config';
 import { validateEnv } from './config/env.validation';
 import { loggerConfig } from './common/logger.config';
 import { CommonModule } from './common/common.module';
@@ -58,7 +58,7 @@ import { MigrationModule } from './modules/migration/migration.module';
     ConfigModule.forRoot({
       isGlobal: true,
       validate: validateEnv,
-      load: [appConfig, dbConfig, authConfig, storageConfig, fileWriteConfig, emailConfig],
+      load: [appConfig, dbConfig, authConfig, storageConfig, fileWriteConfig, emailConfig, migrationConfig],
     }),
     ScheduleModule.forRoot(),
     DbModule,
diff --git a/server/src/config/config.ts b/server/src/config/config.ts
index fcfd0613c..5b5bfe00e 100644
--- a/server/src/config/config.ts
+++ b/server/src/config/config.ts
@@ -30,6 +30,10 @@ export const emailConfig = registerAs('email', () => ({
   encryptionKey: process.env.EMAIL_ENCRYPTION_KEY ?? '',
 }));
 
+export const migrationConfig = registerAs('migration', () => ({
+  encryptionKey: process.env.MIGRATION_ENCRYPTION_KEY ?? '',
+}));
+
 function parsePositiveInteger(value: string | undefined, fallback: number): number {
   const parsed = Number(value);
   if (!Number.isFinite(parsed) || parsed < 1) {
diff --git a/server/src/db/migrations/0000_baseline.sql b/server/src/db/migrations/0000_initial.sql
similarity index 99%
rename from server/src/db/migrations/0000_baseline.sql
rename to server/src/db/migrations/0000_initial.sql
index 119c1b4b5..b5c467184 100644
--- a/server/src/db/migrations/0000_baseline.sql
+++ b/server/src/db/migrations/0000_initial.sql
@@ -105,6 +105,7 @@ CREATE TABLE "migration_plan_artifacts" (
 	"profile_hash" varchar(128) NOT NULL,
 	"plan_hash" varchar(128) NOT NULL,
 	"plan" jsonb NOT NULL,
+	"source_data" jsonb,
 	"summary" jsonb NOT NULL,
 	"created_by_user_id" integer,
 	"created_at" timestamp DEFAULT now() NOT NULL,
@@ -151,7 +152,8 @@ CREATE TABLE "migration_runs" (
 	"ended_at" timestamp,
 	"error_message" text,
 	"created_at" timestamp DEFAULT now() NOT NULL,
-	"updated_at" timestamp DEFAULT now() NOT NULL
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "migration_runs_state_chk" CHECK ("state" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed'))
 );
 --> statement-breakpoint
 CREATE TABLE "migration_sources" (
@@ -811,6 +813,7 @@ CREATE INDEX "migration_run_metrics_run_id_idx" ON "migration_run_metrics" USING
 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 INDEX "migration_sources_created_by_user_id_idx" ON "migration_sources" USING btree ("created_by_user_id");--> 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 ea7fa2fd6..bcf0950b7 100644
--- a/server/src/db/migrations/meta/0000_snapshot.json
+++ b/server/src/db/migrations/meta/0000_snapshot.json
@@ -1,5 +1,5 @@
 {
-  "id": "72e849a9-b27e-4b5f-877b-08d05168e0bb",
+  "id": "d56006ae-b874-42cc-be23-62c2537e2dd8",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -785,6 +785,12 @@
           "primaryKey": false,
           "notNull": true
         },
+        "source_data": {
+          "name": "source_data",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
         "summary": {
           "name": "summary",
           "type": "jsonb",
@@ -1345,7 +1351,12 @@
       "compositePrimaryKeys": {},
       "uniqueConstraints": {},
       "policies": {},
-      "checkConstraints": {},
+      "checkConstraints": {
+        "migration_runs_state_chk": {
+          "name": "migration_runs_state_chk",
+          "value": "\"state\" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')"
+        }
+      },
       "isRLSEnabled": false
     },
     "public.migration_sources": {
@@ -1430,6 +1441,21 @@
           "concurrently": false,
           "method": "btree",
           "with": {}
+        },
+        "migration_sources_created_by_user_id_idx": {
+          "name": "migration_sources_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
         }
       },
       "foreignKeys": {
diff --git a/server/src/db/migrations/meta/_journal.json b/server/src/db/migrations/meta/_journal.json
index 6511110a6..f1b61dec0 100644
--- a/server/src/db/migrations/meta/_journal.json
+++ b/server/src/db/migrations/meta/_journal.json
@@ -5,8 +5,8 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1775305491228,
-      "tag": "0000_baseline",
+      "when": 1775440071752,
+      "tag": "0000_initial",
       "breakpoints": true
     }
   ]
diff --git a/server/src/db/schema/migration.ts b/server/src/db/schema/migration.ts
index 9a7430a58..28762a37e 100644
--- a/server/src/db/schema/migration.ts
+++ b/server/src/db/schema/migration.ts
@@ -1,4 +1,4 @@
-import { index, integer, jsonb, pgTable, serial, text, timestamp, uniqueIndex, varchar } from 'drizzle-orm/pg-core';
+import { check, index, integer, jsonb, pgTable, serial, text, timestamp, uniqueIndex, varchar } from 'drizzle-orm/pg-core';
 import { sql } from 'drizzle-orm';
 
 import { users } from './auth';
@@ -19,7 +19,10 @@ export const migrationSources = pgTable(
       .notNull()
       .$onUpdateFn(() => new Date()),
   },
-  (t) => [uniqueIndex('migration_sources_type_name_uidx').on(t.type, t.name)],
+  (t) => [
+    uniqueIndex('migration_sources_type_name_uidx').on(t.type, t.name),
+    index('migration_sources_created_by_user_id_idx').on(t.createdByUserId),
+  ],
 );
 
 export const migrationProfiles = pgTable(
@@ -65,6 +68,7 @@ export const migrationPlanArtifacts = pgTable(
     profileHash: varchar('profile_hash', { length: 128 }).notNull(),
     planHash: varchar('plan_hash', { length: 128 }).notNull(),
     plan: jsonb('plan').notNull(),
+    sourceData: jsonb('source_data'),
     summary: jsonb('summary').notNull(),
     createdByUserId: integer('created_by_user_id').references(() => users.id, { onDelete: 'set null' }),
     createdAt: timestamp('created_at').defaultNow().notNull(),
@@ -104,7 +108,11 @@ export const migrationRuns = pgTable(
       .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)],
+  (t) => [
+    index('migration_runs_source_target_state_idx').on(t.sourceId, t.targetKey, t.state),
+    index('migration_runs_state_idx').on(t.state),
+    check('migration_runs_state_chk', sql`"state" IN ('draft', 'preflight_failed', 'dry_run_ready', 'running', 'failed', 'completed')`),
+  ],
 );
 
 export const migrationRunMetrics = pgTable(
diff --git a/server/src/modules/architecture/architecture-boundaries.test.ts b/server/src/modules/architecture/architecture-boundaries.test.ts
index bec8edb4b..f65bf4b50 100644
--- a/server/src/modules/architecture/architecture-boundaries.test.ts
+++ b/server/src/modules/architecture/architecture-boundaries.test.ts
@@ -57,7 +57,6 @@ 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',
diff --git a/server/src/modules/migration/adapters/booklore/booklore-connector.test.ts b/server/src/modules/migration/adapters/booklore/booklore-connector.test.ts
new file mode 100644
index 000000000..55b0d805d
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-connector.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { BookloreConnector } from './booklore-connector';
+
+describe('BookloreConnector', () => {
+  it('counts live Booklore migration tables', async () => {
+    const connector = new BookloreConnector();
+    const conn = {
+      query: vi.fn().mockResolvedValue([[{ count: 12 }]]),
+    };
+
+    await expect(connector.countRows(conn as never, 'book_file')).resolves.toBe(12);
+    expect(conn.query).toHaveBeenCalledWith('SELECT COUNT(*) AS count FROM `book_file`');
+  });
+
+  it('rejects guessed plural table names that are not in the live Booklore schema', async () => {
+    const connector = new BookloreConnector();
+    const conn = {
+      query: vi.fn(),
+    };
+
+    await expect(connector.countRows(conn as never, 'book_files')).rejects.toThrow('allowed migration table list');
+    expect(conn.query).not.toHaveBeenCalled();
+  });
+});
diff --git a/server/src/modules/migration/adapters/booklore/booklore-connector.ts b/server/src/modules/migration/adapters/booklore/booklore-connector.ts
index 9551c1162..ada848a21 100644
--- a/server/src/modules/migration/adapters/booklore/booklore-connector.ts
+++ b/server/src/modules/migration/adapters/booklore/booklore-connector.ts
@@ -3,9 +3,12 @@ import mysql from 'mysql2/promise';
 import type { RowDataPacket } from 'mysql2';
 
 import type { BookloreConnectionConfig } from './booklore-connection-config';
+import { isBookloreMigrationTableName } from './booklore-tables';
 
 type Row = RowDataPacket & Record<string, unknown>;
 
+const CONNECT_TIMEOUT_MS = 10_000;
+
 @Injectable()
 export class BookloreConnector {
   async withConnection<T>(config: BookloreConnectionConfig, fn: (conn: mysql.Connection) => Promise<T>): Promise<T> {
@@ -17,6 +20,7 @@ export class BookloreConnector {
       database: config.database,
       ssl: config.ssl ? {} : undefined,
       supportBigNumbers: true,
+      connectTimeout: CONNECT_TIMEOUT_MS,
     });
 
     try {
@@ -52,6 +56,9 @@ export class BookloreConnector {
   }
 
   async countRows(conn: mysql.Connection, tableName: string): Promise<number> {
+    if (!isBookloreMigrationTableName(tableName)) {
+      throw new Error(`Table "${tableName}" is not in the allowed migration table list`);
+    }
     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);
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
index 75e6305fa..f1242265a 100644
--- a/server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts
+++ b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.test.ts
@@ -27,3 +27,60 @@ describe('BookloreSourceAdapter shelf export', () => {
     expect(connector.queryRows).toHaveBeenNthCalledWith(2, expect.anything(), expect.stringContaining('JOIN `shelf` s ON s.`id` = m.`shelf_id`'));
   });
 });
+
+describe('BookloreSourceAdapter table resolution', () => {
+  it('uses the resolved library path table when fetching path prefixes', async () => {
+    const connector = {
+      withConnection: vi.fn().mockImplementation((_config, fn) => fn({})),
+      listTables: vi.fn().mockResolvedValue(new Set(['library_path'])),
+      queryRows: vi.fn().mockResolvedValue([{ path: '/books' }]),
+    };
+
+    const adapter = new BookloreSourceAdapter(connector as never);
+
+    const result = await adapter.fetchPathPrefixes({} as never);
+
+    expect(result).toEqual(['/books']);
+    expect(connector.queryRows).toHaveBeenCalledWith(expect.anything(), expect.stringContaining('FROM `library_path`'));
+  });
+
+  it('does not resolve guessed plural table names that are absent from Booklore', async () => {
+    const connector = {
+      withConnection: vi.fn().mockImplementation((_config, fn) => fn({})),
+      listTables: vi.fn().mockResolvedValue(new Set(['library_paths'])),
+      queryRows: vi.fn(),
+    };
+
+    const adapter = new BookloreSourceAdapter(connector as never);
+
+    const result = await adapter.fetchPathPrefixes({} as never);
+
+    expect(result).toEqual([]);
+    expect(connector.queryRows).not.toHaveBeenCalled();
+  });
+
+  it('detects ebook viewer preferences from the live Booklore table name', async () => {
+    const connector = {
+      withConnection: vi.fn().mockImplementation((_config, fn) => fn({})),
+      listTables: vi.fn().mockResolvedValue(new Set(['users', 'book', 'book_file', 'epub_viewer_preference', 'ebook_viewer_preference'])),
+      countRows: vi.fn().mockResolvedValue(1),
+      queryRows: vi.fn().mockResolvedValue([{ version: '11.4.5' }]),
+    };
+
+    const adapter = new BookloreSourceAdapter(connector as never);
+
+    const result = await adapter.validate({
+      host: 'localhost',
+      port: 3306,
+      user: 'booklore',
+      password: 'secret',
+      database: 'booklore',
+      mediaRootPath: '/books',
+      ssl: false,
+    });
+
+    expect(result.warnings).toContain('Booklore viewer preference tables detected; reader preference migration is deferred');
+    expect(connector.countRows).toHaveBeenCalledWith(expect.anything(), 'epub_viewer_preference');
+    expect(connector.countRows).toHaveBeenCalledWith(expect.anything(), 'ebook_viewer_preference');
+  });
+});
diff --git a/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
index 5155a0f26..5c923fa69 100644
--- a/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
+++ b/server/src/modules/migration/adapters/booklore/booklore-source.adapter.ts
@@ -7,6 +7,7 @@ import type {
   SourceBook,
   SourceBookmark,
   SourceContributor,
+  SourceExportDomains,
   SourceExportData,
   SourceShelf,
   SourceShelfBook,
@@ -18,35 +19,37 @@ import type {
 } from '../source-adapter.types';
 import type { BookloreConnectionConfig } from './booklore-connection-config';
 import { BookloreConnector } from './booklore-connector';
+import { BOOKLORE_TABLES } from './booklore-tables';
 
 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'],
+  users: [BOOKLORE_TABLES.users],
+  book: [BOOKLORE_TABLES.book],
+  bookFile: [BOOKLORE_TABLES.bookFile],
+  bookMetadata: [BOOKLORE_TABLES.bookMetadata],
+  libraryPath: [BOOKLORE_TABLES.libraryPath],
+  authors: [BOOKLORE_TABLES.author],
+  authorMapping: [BOOKLORE_TABLES.bookMetadataAuthorMapping],
+  userBookProgress: [BOOKLORE_TABLES.userBookProgress],
+  userBookFileProgress: [BOOKLORE_TABLES.userBookFileProgress],
+  bookmarks: [BOOKLORE_TABLES.bookMarks],
+  annotations: [BOOKLORE_TABLES.annotations],
+  pdfAnnotations: [BOOKLORE_TABLES.pdfAnnotations],
+  shelves: [BOOKLORE_TABLES.shelf],
+  shelfBooks: [BOOKLORE_TABLES.bookShelfMapping],
+  categories: [BOOKLORE_TABLES.category],
+  categoryMapping: [BOOKLORE_TABLES.bookMetadataCategoryMapping],
+  tags: [BOOKLORE_TABLES.tag],
+  tagMapping: [BOOKLORE_TABLES.bookMetadataTagMapping],
+  bookNotes: [BOOKLORE_TABLES.bookNotes],
+  bookNotesV2: [BOOKLORE_TABLES.bookNotesV2],
+  epubViewerPreference: [BOOKLORE_TABLES.epubViewerPreference],
+  ebookViewerPreference: [BOOKLORE_TABLES.ebookViewerPreference],
+  pdfViewerPreference: [BOOKLORE_TABLES.pdfViewerPreference],
+  cbxViewerPreference: [BOOKLORE_TABLES.cbxViewerPreference],
+  newPdfViewerPreference: [BOOKLORE_TABLES.newPdfViewerPreference],
+  koboUserSettings: [BOOKLORE_TABLES.koboUserSettings],
+  koboReadingState: [BOOKLORE_TABLES.koboReadingState],
+  comicMetadata: [BOOKLORE_TABLES.comicMetadata],
 } as const;
 
 interface TableResolution {
@@ -71,6 +74,7 @@ interface TableResolution {
   bookNotes: string | null;
   bookNotesV2: string | null;
   epubViewerPreference: string | null;
+  ebookViewerPreference: string | null;
   pdfViewerPreference: string | null;
   cbxViewerPreference: string | null;
   newPdfViewerPreference: string | null;
@@ -141,6 +145,7 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
       await this.attachTagsToBooks(conn, books, resolved.tags, resolved.tagMapping);
 
       return {
+        availableDomains: this.buildAvailableDomains(resolved, config),
         users,
         books,
         userBookStatuses,
@@ -153,14 +158,31 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
     });
   }
 
+  private buildAvailableDomains(resolved: TableResolution, config: BookloreConnectionConfig): SourceExportDomains {
+    return {
+      metadata: !!resolved.bookMetadata,
+      authors: !!resolved.authors && !!resolved.authorMapping,
+      narrators: !!resolved.bookMetadata,
+      genres: !!resolved.categories && !!resolved.categoryMapping,
+      tags: !!resolved.tags && !!resolved.tagMapping,
+      userBookStatuses: !!resolved.userBookProgress,
+      readingProgress: !!resolved.userBookFileProgress,
+      bookmarks: !!resolved.bookmarks,
+      annotations: !!resolved.annotations,
+      shelves: !!resolved.shelves && !!resolved.shelfBooks,
+      covers: !!config.mediaRootPath,
+    };
+  }
+
   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 libraryPathTable = resolveTables(tables).libraryPath;
+      if (!libraryPathTable) 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`',
+        `SELECT DISTINCT CAST(\`path\` AS CHAR) AS path FROM \`${libraryPathTable}\` WHERE \`path\` IS NOT NULL ORDER BY \`path\``,
       );
 
       return rows.map((row) => asString(row.path)).filter((p): p is string => p !== null);
@@ -193,19 +215,26 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
     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.bookmarks) warnings.push('book_marks 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.categories || !resolved.categoryMapping) warnings.push('category mapping 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) {
+    if (
+      resolved.epubViewerPreference ||
+      resolved.ebookViewerPreference ||
+      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');
+    if (!config.password) warnings.push('No password set; connection may fail if the database requires authentication');
 
     return warnings;
   }
@@ -248,6 +277,7 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
     const bookColumns = await this.connector.listColumns(conn, bookTable);
     const bookIdCol = requiredColumn(bookColumns, ['id', 'book_id']);
     const bookLibraryPathIdCol = firstColumn(bookColumns, ['library_path_id', 'librarypath_id']);
+    const bookDeletedCol = firstColumn(bookColumns, ['deleted']);
 
     let metadataColumns: Set<string> | null = null;
     let metadataJoinCol: string | null = null;
@@ -302,6 +332,7 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
     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 fileIsBookCol = fileColumns ? firstColumn(fileColumns, ['is_book']) : null;
 
     const presentFields: string[] = (
       [
@@ -323,7 +354,7 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
         ['hardcoverId', hardcoverIdCol],
         ['audibleId', audibleIdCol],
         ['comicvineId', comicvineIdCol],
-        ['durationSeconds', durationSecondsCol],
+        ['durationSeconds', durationSecondsCol ?? fileDurationSecondsCol],
         ['abridged', abridgedCol],
       ] as Array<[string, string | null]>
     )
@@ -370,17 +401,27 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
       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}\``);
+      const contentFilter = fileIsBookCol ? ` AND f.\`${fileIsBookCol}\` = 1` : '';
+      joins.push(`LEFT JOIN \`${bookFileTable}\` f ON f.\`${fileJoinCol}\` = b.\`${bookIdCol}\`${contentFilter}`);
     }
     if (resolved.libraryPath && bookLibraryPathIdCol && libraryPathIdCol && libraryPathValueCol) {
       joins.push(`LEFT JOIN \`${resolved.libraryPath}\` lp ON lp.\`${libraryPathIdCol}\` = b.\`${bookLibraryPathIdCol}\``);
     }
 
+    const whereParts: string[] = [];
+    if (bookDeletedCol) {
+      whereParts.push(`(b.\`${bookDeletedCol}\` = 0 OR b.\`${bookDeletedCol}\` IS NULL)`);
+    }
+    const whereSql = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
+    const orderParts = [`b.\`${bookIdCol}\``];
+    if (fileIdCol) orderParts.push(`f.\`${fileIdCol}\``);
+
     const sqlText = `
       SELECT ${selectParts.join(',\n')}
       FROM \`${bookTable}\` b
       ${joins.join('\n')}
-      ORDER BY b.\`${bookIdCol}\`
+      ${whereSql}
+      ORDER BY ${orderParts.join(', ')}
     `;
 
     const rows = await this.connector.queryRows(conn, sqlText);
@@ -534,15 +575,16 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
     if (!userCol || !bookCol) return [];
 
     const statusCol = firstColumn(cols, ['status', 'read_status']);
-    const pctCol = firstColumn(cols, [
+    const pctCols = columnsInOrder(cols, [
       'percentage',
       'progress_percent',
-      'progress',
       'percent_complete',
-      'epub_progress',
-      'pdf_progress',
-      'cbx_progress',
-      'koreader_progress',
+      'epub_progress_percent',
+      'pdf_progress_percent',
+      'cbx_progress_percent',
+      'koreader_progress_percent',
+      'kobo_progress_percent',
+      'progress',
     ]);
     const startedAtCol = firstColumn(cols, ['started_at', 'start_date', 'date_started']);
     const finishedAtCol = firstColumn(cols, ['finished_at', 'finish_date', 'completed_at', 'date_finished']);
@@ -553,7 +595,7 @@ export class BookloreSourceAdapter implements SourceAdapter<BookloreConnectionCo
         CAST(p.\`${userCol}\` AS CHAR) AS sourceUserId,
         CAST(p.\`${bookCol}\` AS CHAR) AS sourceBookId,
         ${sqlString('p', statusCol, 'status')},
-        ${sqlNumber('p', pctCol, 'percentage')},
+        ${sqlCoalesceNumber('p', pctCols, 'percentage')},
         ${sqlDate('p', startedAtCol, 'startedAt')},
         ${sqlDate('p', finishedAtCol, 'finishedAt')},
         ${sqlDate('p', updatedAtCol, 'updatedAt')}
@@ -918,6 +960,7 @@ function resolveTables(tables: Set<string>): TableResolution {
     bookNotes: resolveTable(tables, TABLE_CANDIDATES.bookNotes),
     bookNotesV2: resolveTable(tables, TABLE_CANDIDATES.bookNotesV2),
     epubViewerPreference: resolveTable(tables, TABLE_CANDIDATES.epubViewerPreference),
+    ebookViewerPreference: resolveTable(tables, TABLE_CANDIDATES.ebookViewerPreference),
     pdfViewerPreference: resolveTable(tables, TABLE_CANDIDATES.pdfViewerPreference),
     cbxViewerPreference: resolveTable(tables, TABLE_CANDIDATES.cbxViewerPreference),
     newPdfViewerPreference: resolveTable(tables, TABLE_CANDIDATES.newPdfViewerPreference),
@@ -949,6 +992,10 @@ function firstColumn(columns: Set<string>, candidates: string[]): string | null
   return null;
 }
 
+function columnsInOrder(columns: Set<string>, candidates: string[]): string[] {
+  return candidates.filter((candidate) => columns.has(candidate.toLowerCase()));
+}
+
 function sqlString(alias: string, column: string | null, outName: string): string {
   if (!column) return `NULL AS ${outName}`;
   return `CAST(${alias}.\`${column}\` AS CHAR) AS ${outName}`;
@@ -959,6 +1006,12 @@ function sqlNumber(alias: string, column: string | null, outName: string): strin
   return `${alias}.\`${column}\` AS ${outName}`;
 }
 
+function sqlCoalesceNumber(alias: string, columns: string[], outName: string): string {
+  if (columns.length === 0) return `NULL AS ${outName}`;
+  if (columns.length === 1) return sqlNumber(alias, columns[0], outName);
+  return `COALESCE(${columns.map((column) => `${alias}.\`${column}\``).join(', ')}) AS ${outName}`;
+}
+
 function sqlDate(alias: string, column: string | null, outName: string): string {
   if (!column) return `NULL AS ${outName}`;
   return `${alias}.\`${column}\` AS ${outName}`;
diff --git a/server/src/modules/migration/adapters/booklore/booklore-tables.ts b/server/src/modules/migration/adapters/booklore/booklore-tables.ts
new file mode 100644
index 000000000..66f5ce37f
--- /dev/null
+++ b/server/src/modules/migration/adapters/booklore/booklore-tables.ts
@@ -0,0 +1,36 @@
+export const BOOKLORE_TABLES = {
+  annotations: 'annotations',
+  author: 'author',
+  book: 'book',
+  bookFile: 'book_file',
+  bookMarks: 'book_marks',
+  bookMetadata: 'book_metadata',
+  bookMetadataAuthorMapping: 'book_metadata_author_mapping',
+  bookMetadataCategoryMapping: 'book_metadata_category_mapping',
+  bookMetadataTagMapping: 'book_metadata_tag_mapping',
+  bookNotes: 'book_notes',
+  bookNotesV2: 'book_notes_v2',
+  bookShelfMapping: 'book_shelf_mapping',
+  category: 'category',
+  cbxViewerPreference: 'cbx_viewer_preference',
+  comicMetadata: 'comic_metadata',
+  ebookViewerPreference: 'ebook_viewer_preference',
+  epubViewerPreference: 'epub_viewer_preference',
+  koboReadingState: 'kobo_reading_state',
+  koboUserSettings: 'kobo_user_settings',
+  libraryPath: 'library_path',
+  newPdfViewerPreference: 'new_pdf_viewer_preference',
+  pdfAnnotations: 'pdf_annotations',
+  pdfViewerPreference: 'pdf_viewer_preference',
+  shelf: 'shelf',
+  tag: 'tag',
+  userBookFileProgress: 'user_book_file_progress',
+  userBookProgress: 'user_book_progress',
+  users: 'users',
+} as const;
+
+const BOOKLORE_MIGRATION_TABLE_NAME_SET = new Set<string>(Object.values(BOOKLORE_TABLES));
+
+export function isBookloreMigrationTableName(tableName: string): boolean {
+  return BOOKLORE_MIGRATION_TABLE_NAME_SET.has(tableName.toLowerCase());
+}
diff --git a/server/src/modules/migration/adapters/source-adapter.types.ts b/server/src/modules/migration/adapters/source-adapter.types.ts
index 1395e107a..a50992ac4 100644
--- a/server/src/modules/migration/adapters/source-adapter.types.ts
+++ b/server/src/modules/migration/adapters/source-adapter.types.ts
@@ -134,6 +134,20 @@ export interface SourceShelfBook {
   sourceBookId: string;
 }
 
+export interface SourceExportDomains {
+  metadata: boolean;
+  authors: boolean;
+  narrators: boolean;
+  genres: boolean;
+  tags: boolean;
+  userBookStatuses: boolean;
+  readingProgress: boolean;
+  bookmarks: boolean;
+  annotations: boolean;
+  shelves: boolean;
+  covers: boolean;
+}
+
 export interface SourceExportData {
   users: SourceUser[];
   books: SourceBook[];
@@ -143,6 +157,7 @@ export interface SourceExportData {
   annotations: SourceAnnotation[];
   shelves: SourceShelf[];
   shelfBooks: SourceShelfBook[];
+  availableDomains?: SourceExportDomains;
 }
 
 export interface SourceAdapter<TConnectionConfig = unknown> {
diff --git a/server/src/modules/migration/core/api-sanitizers.test.ts b/server/src/modules/migration/core/api-sanitizers.test.ts
new file mode 100644
index 000000000..f6c807a26
--- /dev/null
+++ b/server/src/modules/migration/core/api-sanitizers.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest';
+
+import { sanitizeSourceForApi, sanitizeProfileForApi, sanitizePlanArtifactForApi, sanitizeRunForApi } from './api-sanitizers';
+import type { MigrationSource, MigrationProfile, MigrationPlanArtifact, MigrationRun } from '../../../db/schema';
+
+function makeSource(overrides: Partial<MigrationSource> = {}): MigrationSource {
+  return {
+    id: 1,
+    type: 'booklore',
+    name: 'Test Source',
+    connectionConfig: { host: 'localhost', password: 'secret123' },
+    capabilities: null,
+    lastValidatedAt: null,
+    createdByUserId: 1,
+    createdAt: new Date('2024-01-01'),
+    updatedAt: new Date('2024-01-02'),
+    ...overrides,
+  };
+}
+
+function makeProfile(overrides: Partial<MigrationProfile> = {}): MigrationProfile {
+  return {
+    id: 2,
+    sourceId: 1,
+    name: 'Test Profile',
+    version: 1,
+    userMappings: [{ sourceUserId: 'u1', targetUserId: 10 }],
+    pathMappings: [],
+    scope: {},
+    createdByUserId: 1,
+    createdAt: new Date('2024-01-01'),
+    updatedAt: new Date('2024-01-02'),
+    ...overrides,
+  };
+}
+
+function makeArtifact(overrides: Partial<MigrationPlanArtifact> = {}): MigrationPlanArtifact {
+  return {
+    id: 3,
+    sourceId: 1,
+    profileId: 2,
+    sourceSnapshotHash: 'hash-a',
+    profileHash: 'hash-b',
+    planHash: 'hash-c',
+    plan: { matchedBooks: [] },
+    sourceData: null,
+    summary: { status: 'ready' },
+    createdByUserId: 1,
+    createdAt: new Date('2024-01-01'),
+    updatedAt: new Date('2024-01-02'),
+    ...overrides,
+  };
+}
+
+function makeRun(overrides: Partial<MigrationRun> = {}): MigrationRun {
+  return {
+    id: 4,
+    sourceId: 1,
+    profileId: 2,
+    planArtifactId: 3,
+    targetKey: 'projectx',
+    state: 'running',
+    currentStage: 'init',
+    triggeredByUserId: 1,
+    startedAt: new Date('2024-01-01'),
+    endedAt: null,
+    errorMessage: null,
+    createdAt: new Date('2024-01-01'),
+    updatedAt: new Date('2024-01-02'),
+    ...overrides,
+  };
+}
+
+describe('sanitizeSourceForApi', () => {
+  it('strips createdByUserId from the response', () => {
+    const result = sanitizeSourceForApi(makeSource());
+    expect(result).not.toHaveProperty('createdByUserId');
+  });
+
+  it('redacts booklore password to sentinel value', () => {
+    const result = sanitizeSourceForApi(makeSource({ connectionConfig: { host: 'db', password: 'my-secret' } }));
+    expect((result.connectionConfig as Record<string, unknown>).password).toBe('********');
+  });
+
+  it('sets password to empty string when no password is set', () => {
+    const result = sanitizeSourceForApi(makeSource({ connectionConfig: { host: 'db', password: '' } }));
+    expect((result.connectionConfig as Record<string, unknown>).password).toBe('');
+  });
+
+  it('does not redact password for non-booklore types', () => {
+    const result = sanitizeSourceForApi(makeSource({ type: 'calibre', connectionConfig: { token: 'abc123' } }));
+    expect((result.connectionConfig as Record<string, unknown>).token).toBe('abc123');
+  });
+
+  it('preserves non-sensitive fields', () => {
+    const source = makeSource();
+    const result = sanitizeSourceForApi(source);
+    expect(result.id).toBe(source.id);
+    expect(result.type).toBe(source.type);
+    expect(result.name).toBe(source.name);
+    expect(result.createdAt).toBe(source.createdAt);
+    expect(result.updatedAt).toBe(source.updatedAt);
+  });
+});
+
+describe('sanitizeProfileForApi', () => {
+  it('strips internal fields (version, createdByUserId)', () => {
+    const result = sanitizeProfileForApi(makeProfile());
+    expect(result).not.toHaveProperty('version');
+    expect(result).not.toHaveProperty('createdByUserId');
+  });
+
+  it('preserves user and path mappings', () => {
+    const profile = makeProfile({
+      userMappings: [{ sourceUserId: 'u1', targetUserId: 10 }],
+      pathMappings: [{ sourcePrefix: '/src', targetPrefix: '/dst' }],
+    });
+    const result = sanitizeProfileForApi(profile);
+    expect(result.userMappings).toEqual(profile.userMappings);
+    expect(result.pathMappings).toEqual(profile.pathMappings);
+  });
+});
+
+describe('sanitizePlanArtifactForApi', () => {
+  it('strips hash fields and createdByUserId', () => {
+    const result = sanitizePlanArtifactForApi(makeArtifact());
+    expect(result).not.toHaveProperty('sourceSnapshotHash');
+    expect(result).not.toHaveProperty('profileHash');
+    expect(result).not.toHaveProperty('planHash');
+    expect(result).not.toHaveProperty('createdByUserId');
+  });
+
+  it('includes plan and summary', () => {
+    const artifact = makeArtifact({ plan: { books: [] }, summary: { total: 5 } });
+    const result = sanitizePlanArtifactForApi(artifact);
+    expect(result.plan).toEqual({ books: [] });
+    expect(result.summary).toEqual({ total: 5 });
+  });
+});
+
+describe('sanitizeRunForApi', () => {
+  it('preserves targetKey and strips triggeredByUserId', () => {
+    const result = sanitizeRunForApi(makeRun());
+    expect(result.targetKey).toBe('projectx');
+    expect(result).not.toHaveProperty('triggeredByUserId');
+  });
+
+  it('includes error message and dates', () => {
+    const run = makeRun({ state: 'failed', errorMessage: 'timeout', endedAt: new Date('2024-01-03') });
+    const result = sanitizeRunForApi(run);
+    expect(result.state).toBe('failed');
+    expect(result.errorMessage).toBe('timeout');
+    expect(result.endedAt).toEqual(new Date('2024-01-03'));
+  });
+
+  it('preserves null fields', () => {
+    const result = sanitizeRunForApi(makeRun({ endedAt: null, errorMessage: null }));
+    expect(result.endedAt).toBeNull();
+    expect(result.errorMessage).toBeNull();
+  });
+});
diff --git a/server/src/modules/migration/core/api-sanitizers.ts b/server/src/modules/migration/core/api-sanitizers.ts
new file mode 100644
index 000000000..d2844fdf2
--- /dev/null
+++ b/server/src/modules/migration/core/api-sanitizers.ts
@@ -0,0 +1,116 @@
+import { asRecord } from './coerce';
+import { PASSWORD_REDACTED_SENTINEL } from './connection-config';
+
+import type { MigrationSource, MigrationProfile, MigrationPlanArtifact, MigrationRun } from '../../../db/schema';
+
+export interface ApiMigrationSource {
+  id: number;
+  type: string;
+  name: string;
+  connectionConfig: unknown;
+  capabilities: MigrationSource['capabilities'];
+  lastValidatedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationProfile {
+  id: number;
+  sourceId: number;
+  name: string;
+  userMappings: MigrationProfile['userMappings'];
+  pathMappings: MigrationProfile['pathMappings'];
+  scope: MigrationProfile['scope'];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationPlanArtifact {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  plan: MigrationPlanArtifact['plan'];
+  summary: MigrationPlanArtifact['summary'];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ApiMigrationRun {
+  id: number;
+  sourceId: number;
+  profileId: number;
+  planArtifactId: number | null;
+  state: MigrationRun['state'];
+  currentStage: string | null;
+  targetKey: string;
+  startedAt: Date | null;
+  endedAt: Date | null;
+  errorMessage: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export function sanitizeSourceForApi(source: MigrationSource): 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,
+  };
+}
+
+export function sanitizeProfileForApi(profile: MigrationProfile): 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,
+  };
+}
+
+export function sanitizePlanArtifactForApi(artifact: MigrationPlanArtifact): ApiMigrationPlanArtifact {
+  return {
+    id: artifact.id,
+    sourceId: artifact.sourceId,
+    profileId: artifact.profileId,
+    plan: artifact.plan,
+    summary: artifact.summary,
+    createdAt: artifact.createdAt,
+    updatedAt: artifact.updatedAt,
+  };
+}
+
+export function sanitizeRunForApi(run: MigrationRun): ApiMigrationRun {
+  return {
+    id: run.id,
+    sourceId: run.sourceId,
+    profileId: run.profileId,
+    planArtifactId: run.planArtifactId,
+    state: run.state,
+    currentStage: run.currentStage,
+    targetKey: run.targetKey,
+    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 ? PASSWORD_REDACTED_SENTINEL : '',
+  };
+}
diff --git a/server/src/modules/migration/core/coerce.test.ts b/server/src/modules/migration/core/coerce.test.ts
new file mode 100644
index 000000000..3016e7243
--- /dev/null
+++ b/server/src/modules/migration/core/coerce.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+
+import { asRecord, asString, asNumber, asInteger } from './coerce';
+
+describe('asRecord', () => {
+  it('returns empty object for null', () => {
+    expect(asRecord(null)).toEqual({});
+  });
+
+  it('returns empty object for undefined', () => {
+    expect(asRecord(undefined)).toEqual({});
+  });
+
+  it('returns empty object for primitives', () => {
+    expect(asRecord(42)).toEqual({});
+    expect(asRecord('hello')).toEqual({});
+    expect(asRecord(true)).toEqual({});
+  });
+
+  it('returns empty object for arrays', () => {
+    expect(asRecord([1, 2, 3])).toEqual({});
+  });
+
+  it('returns the object itself for plain objects', () => {
+    const obj = { host: 'localhost', port: 3306 };
+    expect(asRecord(obj)).toBe(obj);
+  });
+
+  it('returns empty object for empty input', () => {
+    expect(asRecord({})).toEqual({});
+  });
+});
+
+describe('asString', () => {
+  it('returns trimmed string for valid string', () => {
+    expect(asString('  hello  ')).toBe('hello');
+  });
+
+  it('returns null for empty string', () => {
+    expect(asString('')).toBeNull();
+  });
+
+  it('returns null for whitespace-only string', () => {
+    expect(asString('   ')).toBeNull();
+  });
+
+  it('converts numbers and booleans to strings', () => {
+    expect(asString(42)).toBe('42');
+    expect(asString(true)).toBe('true');
+  });
+
+  it('returns null for null, undefined, and objects', () => {
+    expect(asString(null)).toBeNull();
+    expect(asString(undefined)).toBeNull();
+    expect(asString({})).toBeNull();
+  });
+
+  it('preserves internal whitespace', () => {
+    expect(asString('hello world')).toBe('hello world');
+  });
+});
+
+describe('asNumber', () => {
+  it('returns number for valid number', () => {
+    expect(asNumber(42)).toBe(42);
+    expect(asNumber(3.14)).toBe(3.14);
+    expect(asNumber(0)).toBe(0);
+    expect(asNumber(-1)).toBe(-1);
+  });
+
+  it('parses numeric strings', () => {
+    expect(asNumber('42')).toBe(42);
+    expect(asNumber('3.14')).toBe(3.14);
+    expect(asNumber('0')).toBe(0);
+  });
+
+  it('returns null for NaN', () => {
+    expect(asNumber(NaN)).toBeNull();
+  });
+
+  it('returns null for Infinity', () => {
+    expect(asNumber(Infinity)).toBeNull();
+    expect(asNumber(-Infinity)).toBeNull();
+  });
+
+  it('coerces empty string to 0', () => {
+    expect(asNumber('')).toBe(0);
+  });
+
+  it('returns null for non-numeric strings', () => {
+    expect(asNumber('abc')).toBeNull();
+  });
+
+  it('returns null for null/undefined', () => {
+    expect(asNumber(null)).toBeNull();
+    expect(asNumber(undefined)).toBeNull();
+  });
+
+  it('coerces empty array to 0', () => {
+    expect(asNumber([])).toBe(0);
+  });
+
+  it('returns null for non-empty objects', () => {
+    expect(asNumber({})).toBeNull();
+  });
+});
+
+describe('asInteger', () => {
+  it('returns integer for whole numbers', () => {
+    expect(asInteger(42)).toBe(42);
+    expect(asInteger(0)).toBe(0);
+    expect(asInteger(-5)).toBe(-5);
+  });
+
+  it('rounds floating point numbers', () => {
+    expect(asInteger(3.14)).toBe(3);
+    expect(asInteger(1.5)).toBe(2);
+    expect(asInteger(2.9)).toBe(3);
+  });
+
+  it('parses integer strings', () => {
+    expect(asInteger('42')).toBe(42);
+    expect(asInteger('0')).toBe(0);
+  });
+
+  it('rounds float strings', () => {
+    expect(asInteger('3.14')).toBe(3);
+  });
+
+  it('returns null for non-numeric values', () => {
+    expect(asInteger('abc')).toBeNull();
+    expect(asInteger(null)).toBeNull();
+    expect(asInteger(undefined)).toBeNull();
+    expect(asInteger(NaN)).toBeNull();
+    expect(asInteger(Infinity)).toBeNull();
+  });
+});
diff --git a/server/src/modules/migration/core/coerce.ts b/server/src/modules/migration/core/coerce.ts
new file mode 100644
index 000000000..861ae319a
--- /dev/null
+++ b/server/src/modules/migration/core/coerce.ts
@@ -0,0 +1,25 @@
+export function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export function asInteger(value: unknown): number | null {
+  const num = asNumber(value);
+  if (num == null) return null;
+  return Math.round(num);
+}
diff --git a/server/src/modules/migration/core/connection-config.test.ts b/server/src/modules/migration/core/connection-config.test.ts
new file mode 100644
index 000000000..b3fd703ab
--- /dev/null
+++ b/server/src/modules/migration/core/connection-config.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseConnectionConfig, PASSWORD_REDACTED_SENTINEL } from './connection-config';
+
+describe('parseConnectionConfig', () => {
+  it('parses booklore config via parseBookloreConnectionConfig', () => {
+    const config = parseConnectionConfig('booklore', {
+      host: 'db.example.com',
+      port: 3306,
+      user: 'admin',
+      password: 'secret',
+      database: 'booklore',
+    });
+    expect(config).toMatchObject({
+      host: 'db.example.com',
+      port: 3306,
+      user: 'admin',
+      password: 'secret',
+      database: 'booklore',
+    });
+  });
+
+  it('returns asRecord for non-booklore types', () => {
+    const raw = { host: 'localhost', token: 'abc' };
+    const config = parseConnectionConfig('calibre', raw);
+    expect(config).toEqual(raw);
+  });
+
+  it('returns empty object for non-booklore type with null raw', () => {
+    const config = parseConnectionConfig('calibre', null);
+    expect(config).toEqual({});
+  });
+
+  it('returns empty object for non-booklore type with array raw', () => {
+    const config = parseConnectionConfig('calibre', [1, 2, 3]);
+    expect(config).toEqual({});
+  });
+});
+
+describe('PASSWORD_REDACTED_SENTINEL', () => {
+  it('is defined as redaction mask', () => {
+    expect(PASSWORD_REDACTED_SENTINEL).toBe('********');
+  });
+});
diff --git a/server/src/modules/migration/core/connection-config.ts b/server/src/modules/migration/core/connection-config.ts
new file mode 100644
index 000000000..9ab2e5e56
--- /dev/null
+++ b/server/src/modules/migration/core/connection-config.ts
@@ -0,0 +1,11 @@
+import { parseBookloreConnectionConfig } from '../adapters/booklore/booklore-connection-config';
+import { asRecord } from './coerce';
+
+export function parseConnectionConfig(type: string, raw: unknown): unknown {
+  if (type === 'booklore') {
+    return parseBookloreConnectionConfig(raw);
+  }
+  return asRecord(raw);
+}
+
+export const PASSWORD_REDACTED_SENTINEL = '********';
diff --git a/server/src/modules/migration/core/migration-encryption.service.test.ts b/server/src/modules/migration/core/migration-encryption.service.test.ts
new file mode 100644
index 000000000..1d8ab19fe
--- /dev/null
+++ b/server/src/modules/migration/core/migration-encryption.service.test.ts
@@ -0,0 +1,116 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { ConfigService } from '@nestjs/config';
+import { MigrationEncryptionService } from './migration-encryption.service';
+
+describe('MigrationEncryptionService', () => {
+  let config: ConfigService;
+
+  const MOCK_KEY = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+
+  function buildService(keyValue: string | null): MigrationEncryptionService {
+    (config.get as ReturnType<typeof vi.fn>).mockReturnValue(keyValue);
+    return new MigrationEncryptionService(config);
+  }
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        MigrationEncryptionService,
+        {
+          provide: ConfigService,
+          useValue: { get: vi.fn() },
+        },
+      ],
+    }).compile();
+
+    config = module.get<ConfigService>(ConfigService);
+  });
+
+  describe('isConfigured', () => {
+    it('returns true when key is valid 64-char hex', () => {
+      expect(buildService(MOCK_KEY).isConfigured()).toBe(true);
+    });
+
+    it('returns false when key is missing', () => {
+      expect(buildService(null).isConfigured()).toBe(false);
+    });
+
+    it('returns false when key is wrong length', () => {
+      expect(buildService('too-short').isConfigured()).toBe(false);
+    });
+  });
+
+  describe('encryptConfig / decryptConfig', () => {
+    it('encrypts and decrypts a config object round-trip', () => {
+      const service = buildService(MOCK_KEY);
+      const original = { host: 'localhost', port: 5432, password: 'secret' };
+
+      const encrypted = service.encryptConfig(original);
+      expect(encrypted).toHaveProperty('_encrypted');
+      expect(typeof encrypted._encrypted).toBe('string');
+      expect(encrypted).not.toHaveProperty('host');
+
+      const decrypted = service.decryptConfig(encrypted);
+      expect(decrypted).toEqual(original);
+    });
+
+    it('returns config as-is when key is not configured', () => {
+      const service = buildService(null);
+      const original = { host: 'localhost', password: 'secret' };
+
+      const encrypted = service.encryptConfig(original);
+      expect(encrypted).toEqual(original);
+      expect(encrypted).not.toHaveProperty('_encrypted');
+    });
+
+    it('decrypts plain (unencrypted) config objects for backward compatibility', () => {
+      const service = buildService(MOCK_KEY);
+      const plain = { host: 'localhost', password: 'secret' };
+
+      const decrypted = service.decryptConfig(plain);
+      expect(decrypted).toEqual(plain);
+    });
+
+    it('produces different ciphertext for the same config (random IV)', () => {
+      const service = buildService(MOCK_KEY);
+      const original = { key: 'value' };
+
+      const enc1 = service.encryptConfig(original);
+      const enc2 = service.encryptConfig(original);
+      expect(enc1._encrypted).not.toBe(enc2._encrypted);
+
+      expect(service.decryptConfig(enc1)).toEqual(original);
+      expect(service.decryptConfig(enc2)).toEqual(original);
+    });
+
+    it('throws on tampered ciphertext', () => {
+      const service = buildService(MOCK_KEY);
+      const encrypted = service.encryptConfig({ password: 'secret' });
+
+      const buf = Buffer.from(encrypted._encrypted as string, 'base64');
+      buf[buf.length - 1] ^= 1;
+      const tampered = { _encrypted: buf.toString('base64') };
+
+      expect(() => service.decryptConfig(tampered)).toThrow();
+    });
+
+    it('handles null/undefined stored values gracefully', () => {
+      const service = buildService(MOCK_KEY);
+      expect(service.decryptConfig(null)).toEqual({});
+      expect(service.decryptConfig(undefined)).toEqual({});
+    });
+
+    it('handles complex nested config objects', () => {
+      const service = buildService(MOCK_KEY);
+      const original = {
+        host: 'db.example.com',
+        port: 3306,
+        credentials: { user: 'admin', password: 's3cret!' },
+        tags: ['prod', 'primary'],
+      };
+
+      const decrypted = service.decryptConfig(service.encryptConfig(original));
+      expect(decrypted).toEqual(original);
+    });
+  });
+});
diff --git a/server/src/modules/migration/core/migration-encryption.service.ts b/server/src/modules/migration/core/migration-encryption.service.ts
new file mode 100644
index 000000000..34d3a298c
--- /dev/null
+++ b/server/src/modules/migration/core/migration-encryption.service.ts
@@ -0,0 +1,75 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const ENCRYPTED_MARKER = '_encrypted';
+
+@Injectable()
+export class MigrationEncryptionService {
+  private readonly logger = new Logger(MigrationEncryptionService.name);
+  private readonly key: Buffer | null;
+
+  constructor(private readonly config: ConfigService) {
+    const raw = this.config.get<string>('migration.encryptionKey') ?? '';
+    if (raw.length === 64) {
+      this.key = Buffer.from(raw, 'hex');
+    } else if (raw.length > 0) {
+      this.logger.warn('MIGRATION_ENCRYPTION_KEY must be a 64-char hex string (32 bytes). Connection configs will not be encrypted.');
+      this.key = null;
+    } else {
+      this.key = null;
+    }
+  }
+
+  isConfigured(): boolean {
+    return this.key !== null;
+  }
+
+  encryptConfig(config: Record<string, unknown>): Record<string, unknown> {
+    if (!this.key) return config;
+    const plaintext = JSON.stringify(config);
+    return { [ENCRYPTED_MARKER]: this.encrypt(plaintext) };
+  }
+
+  decryptConfig(stored: unknown): Record<string, unknown> {
+    if (!stored || typeof stored !== 'object') return {};
+    const obj = stored as Record<string, unknown>;
+
+    if (typeof obj[ENCRYPTED_MARKER] !== 'string') return obj;
+    if (!this.key) {
+      this.logger.warn('Encrypted config found but no encryption key configured. Cannot decrypt.');
+      return obj;
+    }
+
+    const decrypted = this.decrypt(obj[ENCRYPTED_MARKER] as string);
+    return JSON.parse(decrypted) as Record<string, unknown>;
+  }
+
+  private encrypt(plaintext: string): string {
+    if (!this.key) return plaintext;
+
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, this.key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+
+    return Buffer.concat([iv, tag, encrypted]).toString('base64');
+  }
+
+  private decrypt(ciphertext: string): string {
+    if (!this.key) return ciphertext;
+
+    const buf = Buffer.from(ciphertext, 'base64');
+    const iv = buf.subarray(0, IV_LENGTH);
+    const tag = buf.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+    const encrypted = buf.subarray(IV_LENGTH + TAG_LENGTH);
+
+    const decipher = createDecipheriv(ALGORITHM, this.key, iv);
+    decipher.setAuthTag(tag);
+
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+  }
+}
diff --git a/server/src/modules/migration/core/plan-hash.ts b/server/src/modules/migration/core/plan-hash.ts
index 6ed0ac956..eb1be0b51 100644
--- a/server/src/modules/migration/core/plan-hash.ts
+++ b/server/src/modules/migration/core/plan-hash.ts
@@ -26,6 +26,10 @@ export function buildSourceSnapshotHash(snapshot: unknown): string {
   return sha256Hex(sanitized);
 }
 
+export function buildPathMappingsHash(pathMappings: unknown): string {
+  return sha256Hex(pathMappings);
+}
+
 function sanitizePlanForHash(plan: unknown): unknown {
   if (!isRecord(plan)) return plan;
 
diff --git a/server/src/modules/migration/dto/resolve-duplicate-matches.dto.ts b/server/src/modules/migration/dto/resolve-duplicate-matches.dto.ts
new file mode 100644
index 000000000..d69af94d2
--- /dev/null
+++ b/server/src/modules/migration/dto/resolve-duplicate-matches.dto.ts
@@ -0,0 +1,19 @@
+import { Type } from 'class-transformer';
+import { ArrayMinSize, IsArray, IsInt, IsString, Min, ValidateNested } from 'class-validator';
+
+export class DuplicateResolutionItemDto {
+  @IsInt()
+  @Min(1)
+  targetBookId!: number;
+
+  @IsString()
+  selectedSourceBookId!: string;
+}
+
+export class ResolveDuplicateMatchesDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => DuplicateResolutionItemDto)
+  resolutions!: DuplicateResolutionItemDto[];
+}
diff --git a/server/src/modules/migration/executor/cover.importer.ts b/server/src/modules/migration/executor/cover.importer.ts
new file mode 100644
index 000000000..974aee991
--- /dev/null
+++ b/server/src/modules/migration/executor/cover.importer.ts
@@ -0,0 +1,131 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { constants as fsConstants } from 'fs';
+import { access, mkdir, readdir, readFile, unlink, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+import { coverDirPath, generateThumbnail, imageExt } from '../../metadata/lib/cover';
+import { MigrationRepository } from '../migration.repository';
+import { MigrationImportRepository } from './migration-import.repository';
+import type { PlannerResult } from '../planner/planner.types';
+import { type RunStateCheck, emptyCounters, hasErrorCode } from './executor-utils';
+
+const COVER_CONCURRENCY = 10;
+
+@Injectable()
+export class CoverImporter {
+  private readonly logger = new Logger(CoverImporter.name);
+
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly importRepo: MigrationImportRepository,
+  ) {}
+
+  async import(
+    runId: number,
+    planned: PlannerResult,
+    booksPath: string,
+    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.setRunMetric(runId, 'book_covers', 'book_covers', counters);
+      return;
+    }
+
+    for (let i = 0; i < matches.length; i += COVER_CONCURRENCY) {
+      await ensureRunning();
+      const batch = matches.slice(i, i + COVER_CONCURRENCY);
+
+      const results = await Promise.allSettled(batch.map((match) => this.processSingleMatch(runId, match, booksPath, sourceMediaRootPath)));
+
+      for (const result of results) {
+        counters.processed += 1;
+        if (result.status === 'fulfilled') {
+          counters[result.value] += 1;
+        } else {
+          counters.failed += 1;
+        }
+      }
+    }
+
+    await this.repo.setRunMetric(runId, 'book_covers', 'book_covers', counters);
+  }
+
+  private async processSingleMatch(
+    runId: number,
+    match: { sourceBookId: string; targetBookId: number },
+    booksPath: string,
+    sourceMediaRootPath: string,
+  ): Promise<'imported' | 'unresolved' | 'failed'> {
+    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) return 'unresolved';
+
+    try {
+      await this.importSingleCover(match.targetBookId, booksPath, coverBytes, sourceThumbnailPath);
+      return 'imported';
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`[migration.cover] runId=${runId} sourceBookId=${match.sourceBookId} targetBookId=${match.targetBookId} error="${message}"`);
+      return 'failed';
+    }
+  }
+
+  private async importSingleCover(targetBookId: number, booksPath: string, coverBytes: Buffer, sourceThumbnailPath: string): Promise<void> {
+    const targetCoverDir = coverDirPath(booksPath, 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);
+
+    await this.importRepo.markCoverAsCustom(targetBookId);
+  }
+
+  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(dirPath: string, prefix: string): Promise<void> {
+    const files = await this.readDirIfExists(dirPath);
+    for (const fileName of files) {
+      if (!fileName.startsWith(prefix)) continue;
+      await this.removeFileIfPresent(join(dirPath, fileName));
+    }
+  }
+
+  private async readDirIfExists(dirPath: string): Promise<string[]> {
+    try {
+      await access(dirPath, fsConstants.R_OK);
+      return await readdir(dirPath);
+    } catch (error) {
+      if (hasErrorCode(error, 'ENOENT')) return [];
+      throw error;
+    }
+  }
+
+  private async removeFileIfPresent(filePath: string): Promise<void> {
+    try {
+      await unlink(filePath);
+    } catch (error) {
+      if (hasErrorCode(error, 'ENOENT')) return;
+      throw error;
+    }
+  }
+}
diff --git a/server/src/modules/migration/executor/executor-utils.ts b/server/src/modules/migration/executor/executor-utils.ts
new file mode 100644
index 000000000..2eb38745d
--- /dev/null
+++ b/server/src/modules/migration/executor/executor-utils.ts
@@ -0,0 +1,247 @@
+import * as schema from '../../../db/schema';
+import { applyPathMappings } from '../planner/matching.service';
+import type { PlannerResult } from '../planner/planner.types';
+
+export interface StageCounters {
+  processed: number;
+  imported: number;
+  skipped: number;
+  unresolved: number;
+  failed: number;
+}
+
+export type RunStateCheck = (force?: boolean) => Promise<void>;
+
+export class RunInterruptedError extends Error {
+  constructor(
+    readonly runId: number,
+    readonly state: string,
+  ) {
+    super(`Migration run ${runId} is no longer running (state=${state})`);
+  }
+}
+
+export function emptyCounters(): StageCounters {
+  return { processed: 0, imported: 0, skipped: 0, unresolved: 0, failed: 0 };
+}
+
+export function uniqueNumbers(values: number[]): number[] {
+  return [...new Set(values.filter((value) => Number.isFinite(value)))];
+}
+
+export 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((tf) => tf.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((tf) => tf.absolutePath === mappedPath);
+        if (byPath.length === 1) {
+          out.set(sourceFile.sourceFileId, byPath[0].id);
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+export 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', truncateNullableText(sourceBook.title, 1000)),
+    subtitle: field('subtitle', truncateNullableText(sourceBook.subtitle, 1000)),
+    isbn10: field('isbn10', truncateNullableText(sourceBook.isbn10, 10)),
+    isbn13: field('isbn13', truncateNullableText(sourceBook.isbn13, 13)),
+    description: field('description', sourceBook.description),
+    publisher: field('publisher', truncateNullableText(sourceBook.publisher, 500)),
+    publishedYear: field('publishedYear', sourceBook.publishedYear),
+    language: field('language', truncateNullableText(sourceBook.language, 100)),
+    pageCount: field('pageCount', sourceBook.pageCount),
+    seriesName: field('seriesName', truncateNullableText(sourceBook.seriesName, 500)),
+    seriesIndex: field('seriesIndex', sourceBook.seriesIndex),
+    rating: field('rating', sourceBook.rating),
+    googleBooksId: field('googleBooksId', truncateNullableText(sourceBook.googleBooksId, 50)),
+    goodreadsId: field('goodreadsId', truncateNullableText(sourceBook.goodreadsId, 50)),
+    amazonId: field('amazonId', truncateNullableText(sourceBook.amazonId, 20)),
+    hardcoverId: field('hardcoverId', truncateNullableText(sourceBook.hardcoverId, 50)),
+    audibleId: field('audibleId', truncateNullableText(sourceBook.audibleId, 20)),
+    comicvineId: field('comicvineId', truncateNullableText(sourceBook.comicvineId, 50)),
+    durationSeconds: field('durationSeconds', sourceBook.durationSeconds),
+    abridged: field('abridged', sourceBook.abridged === undefined ? undefined : (sourceBook.abridged ?? false)),
+  });
+}
+
+export function buildContributorValues(contributor: {
+  name: string;
+  sortName?: string | null;
+  description?: string | null;
+}): typeof schema.authors.$inferInsert {
+  return pruneUndefined({
+    name: truncateText(contributor.name, 500),
+    sortName: truncateText(contributor.sortName ?? contributor.name, 500),
+    description: contributor.description ?? undefined,
+  });
+}
+
+export 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((c) => c.name.trim().length > 0)
+      .sort((a, b) => (a.displayOrder ?? 0) - (b.displayOrder ?? 0))
+      .map((c) => ({ name: c.name.trim(), sortName: c.sortName ?? null, description: c.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 c of contributors) {
+    const key = c.name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  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;
+  }
+}
+
+export 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;
+}
+
+export function hasErrorCode(error: unknown, code: string): boolean {
+  return Boolean(error && typeof error === 'object' && 'code' in error && (error as { code?: string }).code === code);
+}
+
+export function toDate(value: string | null): Date | null {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+export function clampPercent(value: number | null): number {
+  if (value == null || !Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(100, value));
+}
+
+export function clampNonNegative(value: number | null): number {
+  if (value == null || !Number.isFinite(value)) return 0;
+  return Math.max(0, value);
+}
+
+export function truncateText(value: string, maxLength: number): string {
+  return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+
+export function truncateNullableText(value: string | null | undefined, maxLength: number): string | null | undefined {
+  if (value == null) return value;
+  return truncateText(value, maxLength);
+}
+
+export 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/executor/migration-executor.service.test.ts b/server/src/modules/migration/executor/migration-executor.service.test.ts
index 98c57c20e..1005dc75d 100644
--- a/server/src/modules/migration/executor/migration-executor.service.test.ts
+++ b/server/src/modules/migration/executor/migration-executor.service.test.ts
@@ -4,7 +4,9 @@ import { join } from 'path';
 import sharp from 'sharp';
 import { describe, expect, it, vi } from 'vitest';
 
-import { MigrationExecutorService } from './migration-executor.service';
+import { SharedOverlaysImporter } from './shared-overlays.importer';
+import { CoverImporter } from './cover.importer';
+import { UserStateImporter } from './user-state.importer';
 
 async function createSampleImageBytes(): Promise<Buffer> {
   return sharp({
@@ -19,35 +21,84 @@ async function createSampleImageBytes(): Promise<Buffer> {
     .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)),
+    setRunMetric: vi.fn(() => Promise.resolve(undefined)),
   };
 }
 
-describe('MigrationExecutorService audiobook progress import', () => {
+function createImportRepoMock() {
+  const repo = {
+    // Single-row methods (kept for backward compat)
+    upsertBookMetadata: vi.fn(() => Promise.resolve()),
+    deleteBookAuthors: vi.fn(() => Promise.resolve()),
+    upsertAuthor: vi.fn(),
+    insertBookAuthor: vi.fn(() => Promise.resolve()),
+    deleteBookNarrators: vi.fn(() => Promise.resolve()),
+    upsertNarrator: vi.fn(),
+    insertBookNarrator: vi.fn(() => Promise.resolve()),
+    deleteBookGenres: vi.fn(() => Promise.resolve()),
+    upsertGenre: vi.fn(),
+    insertBookGenre: vi.fn(() => Promise.resolve()),
+    deleteBookTags: vi.fn(() => Promise.resolve()),
+    upsertTag: vi.fn(),
+    insertBookTag: vi.fn(() => Promise.resolve()),
+    markCoverAsCustom: vi.fn(() => Promise.resolve()),
+    clearUserBookStatuses: vi.fn(() => Promise.resolve()),
+    upsertUserBookStatus: vi.fn(() => Promise.resolve()),
+    clearReadingProgress: vi.fn(() => Promise.resolve()),
+    upsertReadingProgress: vi.fn(() => Promise.resolve()),
+    clearAudiobookProgress: vi.fn(() => Promise.resolve()),
+    upsertAudiobookProgress: vi.fn(() => Promise.resolve()),
+    clearBookmarks: vi.fn(() => Promise.resolve()),
+    insertBookmark: vi.fn(() => Promise.resolve()),
+    clearAnnotations: vi.fn(() => Promise.resolve()),
+    insertAnnotation: vi.fn(() => Promise.resolve()),
+    fetchExistingCollections: vi.fn(() => Promise.resolve([])),
+    insertCollection: vi.fn(),
+    clearCollectionBooks: vi.fn(() => Promise.resolve()),
+    upsertCollectionBook: vi.fn(),
+    fetchTargetBookPrimaryFiles: vi.fn(() =>
+      Promise.resolve({
+        primaryFilesByBookId: new Map<number, number>(),
+        audiobookPrimaryFilesByBookId: new Map<number, number>(),
+      }),
+    ),
+    fetchTargetBookFiles: vi.fn(() => Promise.resolve(new Map())),
+    // Batch methods
+    batchUpsertBookMetadata: vi.fn(() => Promise.resolve()),
+    batchDeleteBookAuthors: vi.fn(() => Promise.resolve()),
+    batchUpsertAuthors: vi.fn(() => Promise.resolve(new Map<string, number>())),
+    batchInsertBookAuthors: vi.fn(() => Promise.resolve()),
+    batchDeleteBookNarrators: vi.fn(() => Promise.resolve()),
+    batchUpsertNarrators: vi.fn(() => Promise.resolve(new Map<string, number>())),
+    batchInsertBookNarrators: vi.fn(() => Promise.resolve()),
+    batchDeleteBookGenres: vi.fn(() => Promise.resolve()),
+    batchUpsertGenres: vi.fn(() => Promise.resolve(new Map<string, number>())),
+    batchInsertBookGenres: vi.fn(() => Promise.resolve()),
+    batchDeleteBookTags: vi.fn(() => Promise.resolve()),
+    batchUpsertTags: vi.fn(() => Promise.resolve(new Map<string, number>())),
+    batchInsertBookTags: vi.fn(() => Promise.resolve()),
+    batchUpsertUserBookStatuses: vi.fn(() => Promise.resolve()),
+    batchUpsertReadingProgress: vi.fn(() => Promise.resolve()),
+    batchUpsertAudiobookProgress: vi.fn(() => Promise.resolve()),
+    batchInsertBookmarks: vi.fn(() => Promise.resolve()),
+    batchInsertAnnotations: vi.fn(() => Promise.resolve()),
+    batchInsertCollectionBooks: vi.fn(() => Promise.resolve()),
+  };
+  return {
+    ...repo,
+    withTransaction: vi.fn((handler: (repo: typeof repo) => Promise<unknown>) => handler(repo)),
+  };
+}
+
+describe('UserStateImporter 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 importRepo = createImportRepoMock();
+    importRepo.upsertAudiobookProgress.mockResolvedValue(undefined);
+
+    const importer = new UserStateImporter(repo as never, importRepo as never);
 
     const planned = {
       execution: {
@@ -76,7 +127,7 @@ describe('MigrationExecutorService audiobook progress import', () => {
       },
     };
 
-    await (service as any).importAudiobookProgress(
+    await (importer as any).importAudiobookProgress(
       77,
       planned,
       new Map([['u1', 10]]),
@@ -89,8 +140,10 @@ describe('MigrationExecutorService audiobook progress import', () => {
       async () => {},
     );
 
-    expect(mocks.insert).toHaveBeenCalledTimes(1);
-    expect(mocks.values).toHaveBeenCalledWith(
+    expect(importRepo.batchUpsertAudiobookProgress).toHaveBeenCalledTimes(1);
+    const batchArg = (importRepo.batchUpsertAudiobookProgress.mock.calls as unknown[][])[0][0] as Array<Record<string, unknown>>;
+    expect(batchArg).toHaveLength(1);
+    expect(batchArg[0]).toEqual(
       expect.objectContaining({
         userId: 10,
         bookId: 101,
@@ -99,7 +152,7 @@ describe('MigrationExecutorService audiobook progress import', () => {
         positionSeconds: 120.5,
       }),
     );
-    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+    expect(repo.setRunMetric).toHaveBeenCalledWith(
       77,
       'user_state',
       'audiobook_progress',
@@ -115,8 +168,10 @@ describe('MigrationExecutorService audiobook progress import', () => {
 
   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 importRepo = createImportRepoMock();
+    importRepo.upsertAudiobookProgress.mockResolvedValue(undefined);
+
+    const importer = new UserStateImporter(repo as never, importRepo as never);
 
     const planned = {
       execution: {
@@ -136,7 +191,7 @@ describe('MigrationExecutorService audiobook progress import', () => {
       },
     };
 
-    await (service as any).importAudiobookProgress(
+    await (importer as any).importAudiobookProgress(
       88,
       planned,
       new Map([['u1', 10]]),
@@ -146,8 +201,8 @@ describe('MigrationExecutorService audiobook progress import', () => {
       async () => {},
     );
 
-    expect(mocks.insert).toHaveBeenCalledTimes(1);
-    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+    expect(importRepo.batchUpsertAudiobookProgress).toHaveBeenCalledTimes(1);
+    expect(repo.setRunMetric).toHaveBeenCalledWith(
       88,
       'user_state',
       'audiobook_progress',
@@ -161,30 +216,18 @@ describe('MigrationExecutorService audiobook progress import', () => {
   });
 });
 
-describe('MigrationExecutorService author import', () => {
+describe('SharedOverlaysImporter 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 importRepo = createImportRepoMock();
+    importRepo.batchUpsertAuthors.mockResolvedValueOnce(
+      new Map([
+        ['Ada Lovelace', 101],
+        ['Grace Hopper', 102],
+      ]),
+    );
 
-    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 importer = new SharedOverlaysImporter(repo as never, importRepo as never);
 
     const planned = {
       execution: {
@@ -195,25 +238,27 @@ describe('MigrationExecutorService author import', () => {
       },
     };
 
-    await (service as any).importAuthors(91, planned);
+    await (importer 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(
+    expect(importRepo.batchDeleteBookAuthors).toHaveBeenCalledWith([901]);
+    expect(importRepo.batchUpsertAuthors).toHaveBeenCalledWith([
+      { name: 'Ada Lovelace', sortName: 'Ada Lovelace' },
+      { name: 'Grace Hopper', sortName: 'Grace Hopper' },
+    ]);
+    expect(importRepo.batchInsertBookAuthors).toHaveBeenCalledWith([
+      { bookId: 901, authorId: 101, displayOrder: 0 },
+      { bookId: 901, authorId: 102, displayOrder: 1 },
+    ]);
+    expect(repo.setRunMetric).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', () => {
+describe('CoverImporter 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-'));
@@ -226,8 +271,8 @@ describe('MigrationExecutorService book cover import', () => {
       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 importRepo = createImportRepoMock();
+      const importer = new CoverImporter(repo as never, importRepo as never);
 
       const planned = {
         execution: {
@@ -235,7 +280,7 @@ describe('MigrationExecutorService book cover import', () => {
         },
       };
 
-      await (service as any).importBookCovers(52, planned, sourceRoot, async () => {});
+      await importer.import(52, planned as never, booksPath, sourceRoot, async () => {});
 
       const targetDir = join(booksPath, 'covers', '901');
       const targetFiles = await readdir(targetDir);
@@ -248,10 +293,10 @@ describe('MigrationExecutorService book cover import', () => {
       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(
+      expect(importRepo.markCoverAsCustom).toHaveBeenCalledWith(901);
+      expect(repo.setRunMetric).toHaveBeenCalledWith(
         52,
-        'shared_overlays',
+        'book_covers',
         'book_covers',
         expect.objectContaining({ processed: 1, imported: 1, unresolved: 0, failed: 0 }),
       );
@@ -270,8 +315,8 @@ describe('MigrationExecutorService book cover import', () => {
       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 importRepo = createImportRepoMock();
+      const importer = new CoverImporter(repo as never, importRepo as never);
 
       const planned = {
         execution: {
@@ -279,13 +324,13 @@ describe('MigrationExecutorService book cover import', () => {
         },
       };
 
-      await (service as any).importBookCovers(53, planned, sourceRoot, async () => {});
+      await importer.import(53, planned as never, booksPath, sourceRoot, async () => {});
 
       const generatedThumbnail = await readFile(join(booksPath, 'covers', '902', 'thumbnail.jpg'));
       expect(generatedThumbnail.length).toBeGreaterThan(0);
-      expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+      expect(repo.setRunMetric).toHaveBeenCalledWith(
         53,
-        'shared_overlays',
+        'book_covers',
         'book_covers',
         expect.objectContaining({ processed: 1, imported: 1, unresolved: 0, failed: 0 }),
       );
@@ -297,8 +342,8 @@ describe('MigrationExecutorService book cover import', () => {
 
   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 importRepo = createImportRepoMock();
+    const importer = new CoverImporter(repo as never, importRepo as never);
 
     const planned = {
       execution: {
@@ -306,38 +351,26 @@ describe('MigrationExecutorService book cover import', () => {
       },
     };
 
-    await (service as any).importBookCovers(54, planned, null, async () => {});
+    await importer.import(54, planned as never, '/tmp/books', null, async () => {});
 
-    expect(mocks.insert).not.toHaveBeenCalled();
-    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+    expect(importRepo.markCoverAsCustom).not.toHaveBeenCalled();
+    expect(repo.setRunMetric).toHaveBeenCalledWith(
       54,
-      'shared_overlays',
+      'book_covers',
       'book_covers',
       expect.objectContaining({ processed: 1, skipped: 1, imported: 0 }),
     );
   });
 });
 
-describe('MigrationExecutorService collection import', () => {
+describe('UserStateImporter 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 importRepo = createImportRepoMock();
+    importRepo.insertCollection.mockResolvedValue({ id: 701 });
+    importRepo.upsertCollectionBook.mockResolvedValue(true);
 
-    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 importer = new UserStateImporter(repo as never, importRepo as never);
 
     const planned = {
       execution: {
@@ -351,7 +384,7 @@ describe('MigrationExecutorService collection import', () => {
       },
     };
 
-    await (service as any).importCollections(
+    await (importer as any).importCollections(
       78,
       planned,
       new Map([['u1', 10]]),
@@ -362,10 +395,9 @@ describe('MigrationExecutorService collection import', () => {
       async () => {},
     );
 
-    expect(insert).toHaveBeenCalledTimes(2);
-    expect(collectionBookValues).toHaveBeenCalledTimes(1);
-    expect(collectionBookValues).toHaveBeenCalledWith({ collectionId: 701, bookId: 101 });
-    expect(repo.incrementRunMetric).toHaveBeenCalledWith(
+    expect(importRepo.insertCollection).toHaveBeenCalledTimes(1);
+    expect(importRepo.batchInsertCollectionBooks).toHaveBeenCalledWith([{ collectionId: 701, bookId: 101 }]);
+    expect(repo.setRunMetric).toHaveBeenCalledWith(
       78,
       'user_state',
       'collections',
diff --git a/server/src/modules/migration/executor/migration-executor.service.ts b/server/src/modules/migration/executor/migration-executor.service.ts
index a6b4587f3..1b694770c 100644
--- a/server/src/modules/migration/executor/migration-executor.service.ts
+++ b/server/src/modules/migration/executor/migration-executor.service.ts
@@ -1,42 +1,20 @@
-import { Inject, Injectable, Logger } from '@nestjs/common';
+import { 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 type { MigrationProgressEvent } from '@projectx/types';
+import { asRecord } from '../core/coerce';
+import { parseConnectionConfig } from '../core/connection-config';
+import { MigrationEncryptionService } from '../core/migration-encryption.service';
+import type { SourceExportData } from '../adapters/source-adapter.types';
+import type { PlannedBookMatch, PlannedUnresolvedBook, PlannerResult, PlannedMigration } from '../planner/planner.types';
 import { MigrationRepository } from '../migration.repository';
+import { MigrationProgressGateway } from '../migration-progress.gateway';
+import { SharedOverlaysImporter } from './shared-overlays.importer';
+import { CoverImporter } from './cover.importer';
+import { UserStateImporter } from './user-state.importer';
+import { RunInterruptedError, type RunStateCheck } from './executor-utils';
 
-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})`);
-  }
-}
+const STAGE_ORDER = ['shared_overlays', 'book_covers', 'user_state'] as const;
 
 @Injectable()
 export class MigrationExecutorService {
@@ -46,9 +24,12 @@ export class MigrationExecutorService {
 
   constructor(
     private readonly repo: MigrationRepository,
-    private readonly planner: MigrationPlannerService,
-    @Inject(DB) private readonly db: Db,
+    private readonly sharedOverlays: SharedOverlaysImporter,
+    private readonly covers: CoverImporter,
+    private readonly userState: UserStateImporter,
     private readonly config: ConfigService,
+    private readonly encryption: MigrationEncryptionService,
+    private readonly progressGateway: MigrationProgressGateway,
   ) {
     this.booksPath = this.config.get<string>('storage.booksPath')!;
   }
@@ -63,6 +44,9 @@ export class MigrationExecutorService {
   }
 
   private async execute(runId: number): Promise<void> {
+    const startMs = Date.now();
+    this.logger.log(`[migration.execute] [start] runId=${runId} - migration execution started`);
+
     const run = await this.repo.findRunById(runId);
     if (!run) return;
     if (run.state !== 'running') return;
@@ -72,31 +56,49 @@ export class MigrationExecutorService {
     }
 
     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');
+    if (!artifact || !source) {
+      await this.failRun(runId, 'Migration run references missing source or plan artifact');
       return;
     }
 
     try {
-      const artifactPlan = asRecord(artifact.plan);
-      const planned = await this.planner.buildPlan({
-        source,
-        profile,
-        scopeOverride: asRecord(artifactPlan.scope),
-      });
+      const artifactPlan = asRecord(artifact.plan) as unknown as PlannedMigration;
+      const sourceData = artifact.sourceData as SourceExportData | null;
+      if (!sourceData) {
+        throw new Error('Plan artifact is missing cached source data. Re-run dry-run.');
+      }
 
-      this.assertDeterministicPlan(artifact, profile, planned.plan);
+      const matchedBooks = Array.isArray(artifactPlan.matchedBooks) ? (artifactPlan.matchedBooks as PlannedBookMatch[]) : [];
+      const unresolvedBooks = Array.isArray(artifactPlan.unresolvedBooks) ? (artifactPlan.unresolvedBooks as PlannedUnresolvedBook[]) : [];
 
-      const sourceMediaRootPath = this.resolveSourceMediaRootPath(source.type, source.connectionConfig);
+      const planned: PlannerResult = {
+        plan: artifactPlan,
+        execution: {
+          sourceData,
+          matchedBooks,
+          unresolvedBooks,
+          duplicateBookMatches: Array.isArray(artifactPlan.duplicateBookMatches) ? artifactPlan.duplicateBookMatches : [],
+        },
+      };
 
-      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),
+      const decryptedConfig = this.encryption.decryptConfig(source.connectionConfig);
+      const sourceMediaRootPath = this.resolveSourceMediaRootPath(source.type, decryptedConfig);
+
+      const completedStages = await this.resolveCompletedStages(runId, run.currentStage);
+
+      await this.executeStage(runId, 'shared_overlays', completedStages, async (ensureRunning) =>
+        this.sharedOverlays.import(runId, planned, ensureRunning),
       );
-      await this.executeStage(runId, 'user_state', async (ensureRunning) => this.importUserState(runId, planned, ensureRunning));
+      await this.emitRunProgress(runId, 'running', 'shared_overlays');
+
+      await this.executeStage(runId, 'book_covers', completedStages, async (ensureRunning) =>
+        this.covers.import(runId, planned, this.booksPath, sourceMediaRootPath, ensureRunning),
+      );
+      await this.emitRunProgress(runId, 'running', 'book_covers');
+
+      await this.executeStage(runId, 'user_state', completedStages, async (ensureRunning) => this.userState.import(runId, planned, ensureRunning));
       await this.assertRunIsRunning(runId);
 
       await this.repo.updateRunState(runId, 'completed', {
@@ -104,30 +106,57 @@ export class MigrationExecutorService {
         endedAt: new Date(),
         errorMessage: null,
       });
+      await this.emitRunProgress(runId, 'completed', 'completed');
+
+      const durationMs = Date.now() - startMs;
+      this.logger.log(
+        `[migration.execute] [end] runId=${runId} durationMs=${durationMs} matchedBooks=${planned.plan.matchedBooks.length} unresolvedBooks=${planned.plan.unresolvedBooks.length} - migration execution completed`,
+      );
     } catch (error) {
+      const durationMs = Date.now() - startMs;
       if (error instanceof RunInterruptedError) {
+        this.logger.warn(
+          `[migration.execute] [fail] runId=${runId} durationMs=${durationMs} errorClass=RunInterruptedError error="run interrupted (state=${error.state})" - migration interrupted`,
+        );
         return;
       }
       const message = error instanceof Error ? error.message : String(error);
-      this.logger.warn(`[migration.execute] runId=${runId} error="${message}"`);
-      await this.failRun(runId, message);
+      const errorClass = error instanceof Error ? error.constructor.name : 'UnknownError';
+      this.logger.warn(
+        `[migration.execute] [fail] runId=${runId} durationMs=${durationMs} errorClass=${errorClass} error="${message}" - migration execution failed`,
+      );
+      const failedStage = await this.failRun(runId, message);
+      await this.emitRunProgress(runId, 'failed', failedStage);
     }
   }
 
-  private assertDeterministicPlan(
-    artifact: typeof schema.migrationPlanArtifacts.$inferSelect,
-    profile: typeof schema.migrationProfiles.$inferSelect,
-    generatedPlan: PlannedMigration,
-  ): void {
-    const sourceSnapshotHash = buildSourceSnapshotHash(generatedPlan.snapshot);
-    const profileHash = buildProfileHash(profile);
+  private async resolveCompletedStages(runId: number, currentStage: string | null): Promise<Set<string>> {
+    const completed = new Set<string>();
+    if (!currentStage || currentStage === 'init') return completed;
 
-    if (artifact.sourceSnapshotHash !== sourceSnapshotHash || artifact.profileHash !== profileHash) {
-      throw new Error('Source or profile changed since dry-run. Re-run dry-run before starting migration.');
+    const currentIdx = STAGE_ORDER.indexOf(currentStage as (typeof STAGE_ORDER)[number]);
+    if (currentIdx <= 0) return completed;
+
+    for (let i = 0; i < currentIdx; i++) {
+      const stage = STAGE_ORDER[i];
+      const hasMetrics = await this.repo.hasStageMetrics(runId, stage);
+      if (hasMetrics) completed.add(stage);
     }
+    return completed;
   }
 
-  private async executeStage(runId: number, stage: string, handler: (ensureRunning: RunStateCheck) => Promise<void>): Promise<void> {
+  private async executeStage(
+    runId: number,
+    stage: string,
+    completedStages: Set<string>,
+    handler: (ensureRunning: RunStateCheck) => Promise<void>,
+  ): Promise<void> {
+    if (completedStages.has(stage)) {
+      this.logger.log(`[migration.execute] runId=${runId} stage=${stage} - skipping already completed stage`);
+      return;
+    }
+
+    await this.repo.clearStageMetrics(runId, stage);
     await this.repo.updateRunState(runId, 'running', {
       currentStage: stage,
       errorMessage: null,
@@ -156,991 +185,54 @@ export class MigrationExecutorService {
     }
   }
 
-  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;
+    const config = parseConnectionConfig(sourceType, connectionConfig) as Record<string, unknown>;
+    return typeof config.mediaRootPath === 'string' ? 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> {
+  private async failRun(runId: number, message: string): Promise<string | null> {
+    const current = await this.repo.findRunById(runId);
     await this.repo.updateRunState(runId, 'failed', {
-      currentStage: 'failed',
       endedAt: new Date(),
       errorMessage: message,
     });
+    return current?.currentStage ?? null;
   }
-}
 
-function emptyCounters(): StageCounters {
-  return {
-    processed: 0,
-    imported: 0,
-    skipped: 0,
-    unresolved: 0,
-    failed: 0,
-  };
-}
+  private async emitRunProgress(runId: number, state: string, currentStage: string | null): Promise<void> {
+    try {
+      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 },
+      );
 
-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);
-        }
-      }
+      const event: MigrationProgressEvent = {
+        runId,
+        state: state as MigrationProgressEvent['state'],
+        currentStage,
+        totals,
+        metrics: metrics.map((m) => ({
+          stage: m.stage,
+          entityType: m.entityType,
+          processed: m.processed,
+          imported: m.imported,
+          skipped: m.skipped,
+          unresolved: m.unresolved,
+          failed: m.failed,
+          updatedAt: m.updatedAt.toISOString(),
+        })),
+      };
+      this.progressGateway.emitProgress(event);
+    } catch {
+      // Non-critical: don't let progress emission failures break the migration
     }
   }
-
-  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/executor/migration-import.repository.ts b/server/src/modules/migration/executor/migration-import.repository.ts
new file mode 100644
index 000000000..97574aeef
--- /dev/null
+++ b/server/src/modules/migration/executor/migration-import.repository.ts
@@ -0,0 +1,549 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+import { DB } from '../../../db';
+import * as schema from '../../../db/schema';
+import { uniqueNumbers } from './executor-utils';
+
+type Db = NodePgDatabase<typeof schema>;
+
+const BATCH_CHUNK_SIZE = 500;
+
+function omitKeys<T extends Record<string, unknown>>(obj: T, ...keys: string[]): Partial<T> {
+  const keySet = new Set(keys);
+  const result = {} as Partial<T>;
+  for (const [key, value] of Object.entries(obj)) {
+    if (!keySet.has(key)) {
+      (result as Record<string, unknown>)[key] = value;
+    }
+  }
+  return result;
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}
+
+const BOOK_METADATA_COLUMN_BY_PROPERTY = {
+  title: 'title',
+  subtitle: 'subtitle',
+  description: 'description',
+  publisher: 'publisher',
+  publishedYear: 'published_year',
+  language: 'language',
+  pageCount: 'page_count',
+  isbn10: 'isbn10',
+  isbn13: 'isbn13',
+  seriesName: 'series_name',
+  seriesIndex: 'series_index',
+  rating: 'rating',
+  googleBooksId: 'google_books_id',
+  goodreadsId: 'goodreads_id',
+  amazonId: 'amazon_id',
+  hardcoverId: 'hardcover_id',
+  audibleId: 'audible_id',
+  comicvineId: 'comicvine_id',
+  durationSeconds: 'duration_seconds',
+  abridged: 'abridged',
+} as const;
+
+function bookMetadataConflictSet(item: Record<string, unknown>): Record<string, unknown> {
+  const set: Record<string, unknown> = {};
+  for (const [property, column] of Object.entries(BOOK_METADATA_COLUMN_BY_PROPERTY)) {
+    if (Object.prototype.hasOwnProperty.call(item, property)) {
+      set[property] = sql.raw(`excluded.${column}`);
+    }
+  }
+  set.updatedAt = sql`now()`;
+  return set;
+}
+
+@Injectable()
+export class MigrationImportRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async withTransaction<T>(handler: (repo: MigrationImportRepository) => Promise<T>): Promise<T> {
+    return this.db.transaction(async (tx) => handler(new MigrationImportRepository(tx as unknown as Db)));
+  }
+
+  // --- Metadata ---
+
+  async upsertBookMetadata(bookId: number, values: Partial<typeof schema.bookMetadata.$inferInsert>): Promise<void> {
+    await this.db
+      .insert(schema.bookMetadata)
+      .values({ bookId, ...values })
+      .onConflictDoUpdate({ target: schema.bookMetadata.bookId, set: values });
+  }
+
+  // --- Authors ---
+
+  async deleteBookAuthors(bookId: number): Promise<void> {
+    await this.db.delete(schema.bookAuthors).where(eq(schema.bookAuthors.bookId, bookId));
+  }
+
+  async upsertAuthor(values: typeof schema.authors.$inferInsert): Promise<{ id: number } | null> {
+    const [row] = await this.db
+      .insert(schema.authors)
+      .values(values)
+      .onConflictDoUpdate({ target: schema.authors.name, set: values })
+      .returning({ id: schema.authors.id });
+    return row ?? null;
+  }
+
+  async insertBookAuthor(bookId: number, authorId: number, displayOrder: number): Promise<void> {
+    await this.db.insert(schema.bookAuthors).values({ bookId, authorId, displayOrder }).onConflictDoNothing();
+  }
+
+  // --- Narrators ---
+
+  async deleteBookNarrators(bookId: number): Promise<void> {
+    await this.db.delete(schema.bookNarrators).where(eq(schema.bookNarrators.bookId, bookId));
+  }
+
+  async upsertNarrator(values: { name: string; sortName: string }): Promise<{ id: number } | null> {
+    const [row] = await this.db
+      .insert(schema.narrators)
+      .values(values)
+      .onConflictDoUpdate({ target: schema.narrators.name, set: values })
+      .returning({ id: schema.narrators.id });
+    return row ?? null;
+  }
+
+  async insertBookNarrator(bookId: number, narratorId: number, displayOrder: number): Promise<void> {
+    await this.db.insert(schema.bookNarrators).values({ bookId, narratorId, displayOrder }).onConflictDoNothing();
+  }
+
+  // --- Genres ---
+
+  async deleteBookGenres(bookId: number): Promise<void> {
+    await this.db.delete(schema.bookGenres).where(eq(schema.bookGenres.bookId, bookId));
+  }
+
+  async upsertGenre(name: string): Promise<{ id: number } | null> {
+    const [row] = await this.db
+      .insert(schema.genres)
+      .values({ name })
+      .onConflictDoUpdate({ target: schema.genres.name, set: { name: sql`excluded.name` } })
+      .returning({ id: schema.genres.id });
+    return row ?? null;
+  }
+
+  async insertBookGenre(bookId: number, genreId: number): Promise<void> {
+    await this.db.insert(schema.bookGenres).values({ bookId, genreId }).onConflictDoNothing();
+  }
+
+  // --- Tags ---
+
+  async deleteBookTags(bookId: number): Promise<void> {
+    await this.db.delete(schema.bookTags).where(eq(schema.bookTags.bookId, bookId));
+  }
+
+  async upsertTag(name: string): Promise<{ id: number } | null> {
+    const [row] = await this.db
+      .insert(schema.tags)
+      .values({ name })
+      .onConflictDoUpdate({ target: schema.tags.name, set: { name: sql`excluded.name` } })
+      .returning({ id: schema.tags.id });
+    return row ?? null;
+  }
+
+  async insertBookTag(bookId: number, tagId: number): Promise<void> {
+    await this.db.insert(schema.bookTags).values({ bookId, tagId }).onConflictDoNothing();
+  }
+
+  // --- Cover metadata ---
+
+  async markCoverAsCustom(bookId: number): Promise<void> {
+    const now = new Date();
+    await this.db
+      .insert(schema.bookMetadata)
+      .values({ bookId, coverSource: 'custom', updatedAt: now })
+      .onConflictDoUpdate({ target: schema.bookMetadata.bookId, set: { coverSource: 'custom', updatedAt: now } });
+  }
+
+  // --- User book statuses ---
+
+  async clearUserBookStatuses(userIds: number[], bookIds: number[]): Promise<void> {
+    const targetUserIds = uniqueNumbers(userIds);
+    const targetBookIds = uniqueNumbers(bookIds);
+    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)));
+  }
+
+  async upsertUserBookStatus(values: typeof schema.userBookStatus.$inferInsert): Promise<void> {
+    await this.db
+      .insert(schema.userBookStatus)
+      .values(values)
+      .onConflictDoUpdate({
+        target: [schema.userBookStatus.userId, schema.userBookStatus.bookId],
+        set: omitKeys(values, 'userId', 'bookId'),
+      });
+  }
+
+  // --- Reading progress ---
+
+  async clearReadingProgress(userIds: number[], fileIds: number[]): Promise<void> {
+    const targetUserIds = uniqueNumbers(userIds);
+    const targetFileIds = uniqueNumbers(fileIds);
+    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)));
+  }
+
+  async upsertReadingProgress(values: typeof schema.readingProgress.$inferInsert): Promise<void> {
+    await this.db
+      .insert(schema.readingProgress)
+      .values(values)
+      .onConflictDoUpdate({
+        target: [schema.readingProgress.bookFileId, schema.readingProgress.userId],
+        set: omitKeys(values, 'bookFileId', 'userId'),
+      });
+  }
+
+  // --- Audiobook progress ---
+
+  async clearAudiobookProgress(userIds: number[], bookIds: number[]): Promise<void> {
+    const targetUserIds = uniqueNumbers(userIds);
+    const targetBookIds = uniqueNumbers(bookIds);
+    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)));
+  }
+
+  async upsertAudiobookProgress(values: typeof schema.audiobookProgress.$inferInsert): Promise<void> {
+    await this.db
+      .insert(schema.audiobookProgress)
+      .values(values)
+      .onConflictDoUpdate({
+        target: [schema.audiobookProgress.userId, schema.audiobookProgress.bookId],
+        set: omitKeys(values, 'userId', 'bookId'),
+      });
+  }
+
+  // --- Bookmarks ---
+
+  async clearBookmarks(userIds: number[], bookIds: number[]): Promise<void> {
+    const targetUserIds = uniqueNumbers(userIds);
+    const targetBookIds = uniqueNumbers(bookIds);
+    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)));
+  }
+
+  async insertBookmark(values: typeof schema.bookmarks.$inferInsert): Promise<void> {
+    await this.db.insert(schema.bookmarks).values(values);
+  }
+
+  // --- Annotations ---
+
+  async clearAnnotations(userIds: number[], bookIds: number[]): Promise<void> {
+    const targetUserIds = uniqueNumbers(userIds);
+    const targetBookIds = uniqueNumbers(bookIds);
+    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)));
+  }
+
+  async insertAnnotation(values: typeof schema.annotations.$inferInsert): Promise<void> {
+    await this.db.insert(schema.annotations).values(values);
+  }
+
+  // --- Collections ---
+
+  async fetchExistingCollections(userIds: number[]): Promise<Array<typeof schema.collections.$inferSelect>> {
+    if (userIds.length === 0) return [];
+    return this.db.select().from(schema.collections).where(inArray(schema.collections.userId, userIds));
+  }
+
+  async insertCollection(values: typeof schema.collections.$inferInsert): Promise<{ id: number }> {
+    const [row] = await this.db.insert(schema.collections).values(values).returning({ id: schema.collections.id });
+    return row;
+  }
+
+  async clearCollectionBooks(collectionId: number): Promise<void> {
+    await this.db.delete(schema.collectionBooks).where(eq(schema.collectionBooks.collectionId, collectionId));
+  }
+
+  async upsertCollectionBook(collectionId: number, bookId: number): Promise<boolean> {
+    const inserted = await this.db
+      .insert(schema.collectionBooks)
+      .values({ collectionId, bookId })
+      .onConflictDoNothing()
+      .returning({ collectionId: schema.collectionBooks.collectionId });
+    return inserted.length > 0;
+  }
+
+  // --- Batch operations ---
+
+  async batchUpsertBookMetadata(items: Array<{ bookId: number } & Partial<typeof schema.bookMetadata.$inferInsert>>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      for (const item of batch) {
+        const set = bookMetadataConflictSet(item);
+        await this.db.insert(schema.bookMetadata).values(item).onConflictDoUpdate({
+          target: schema.bookMetadata.bookId,
+          set,
+        });
+      }
+    }
+  }
+
+  async batchDeleteBookAuthors(bookIds: number[]): Promise<void> {
+    if (bookIds.length === 0) return;
+    for (const batch of chunk(bookIds, BATCH_CHUNK_SIZE)) {
+      await this.db.delete(schema.bookAuthors).where(inArray(schema.bookAuthors.bookId, batch));
+    }
+  }
+
+  async batchUpsertAuthors(items: Array<typeof schema.authors.$inferInsert>): Promise<Map<string, number>> {
+    const nameToId = new Map<string, number>();
+    if (items.length === 0) return nameToId;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      const rows = await this.db
+        .insert(schema.authors)
+        .values(batch)
+        .onConflictDoUpdate({ target: schema.authors.name, set: { sortName: sql`excluded.sort_name` } })
+        .returning({ id: schema.authors.id, name: schema.authors.name });
+      for (const row of rows) nameToId.set(row.name, row.id);
+    }
+    return nameToId;
+  }
+
+  async batchInsertBookAuthors(items: Array<{ bookId: number; authorId: number; displayOrder: number }>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.bookAuthors).values(batch).onConflictDoNothing();
+    }
+  }
+
+  async batchDeleteBookNarrators(bookIds: number[]): Promise<void> {
+    if (bookIds.length === 0) return;
+    for (const batch of chunk(bookIds, BATCH_CHUNK_SIZE)) {
+      await this.db.delete(schema.bookNarrators).where(inArray(schema.bookNarrators.bookId, batch));
+    }
+  }
+
+  async batchUpsertNarrators(items: Array<{ name: string; sortName: string }>): Promise<Map<string, number>> {
+    const nameToId = new Map<string, number>();
+    if (items.length === 0) return nameToId;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      const rows = await this.db
+        .insert(schema.narrators)
+        .values(batch)
+        .onConflictDoUpdate({ target: schema.narrators.name, set: { sortName: sql`excluded.sort_name` } })
+        .returning({ id: schema.narrators.id, name: schema.narrators.name });
+      for (const row of rows) nameToId.set(row.name, row.id);
+    }
+    return nameToId;
+  }
+
+  async batchInsertBookNarrators(items: Array<{ bookId: number; narratorId: number; displayOrder: number }>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.bookNarrators).values(batch).onConflictDoNothing();
+    }
+  }
+
+  async batchDeleteBookGenres(bookIds: number[]): Promise<void> {
+    if (bookIds.length === 0) return;
+    for (const batch of chunk(bookIds, BATCH_CHUNK_SIZE)) {
+      await this.db.delete(schema.bookGenres).where(inArray(schema.bookGenres.bookId, batch));
+    }
+  }
+
+  async batchUpsertGenres(names: string[]): Promise<Map<string, number>> {
+    const nameToId = new Map<string, number>();
+    if (names.length === 0) return nameToId;
+    const items = names.map((name) => ({ name }));
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      const rows = await this.db
+        .insert(schema.genres)
+        .values(batch)
+        .onConflictDoUpdate({ target: schema.genres.name, set: { name: sql`excluded.name` } })
+        .returning({ id: schema.genres.id, name: schema.genres.name });
+      for (const row of rows) nameToId.set(row.name, row.id);
+    }
+    return nameToId;
+  }
+
+  async batchInsertBookGenres(items: Array<{ bookId: number; genreId: number }>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.bookGenres).values(batch).onConflictDoNothing();
+    }
+  }
+
+  async batchDeleteBookTags(bookIds: number[]): Promise<void> {
+    if (bookIds.length === 0) return;
+    for (const batch of chunk(bookIds, BATCH_CHUNK_SIZE)) {
+      await this.db.delete(schema.bookTags).where(inArray(schema.bookTags.bookId, batch));
+    }
+  }
+
+  async batchUpsertTags(names: string[]): Promise<Map<string, number>> {
+    const nameToId = new Map<string, number>();
+    if (names.length === 0) return nameToId;
+    const items = names.map((name) => ({ name }));
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      const rows = await this.db
+        .insert(schema.tags)
+        .values(batch)
+        .onConflictDoUpdate({ target: schema.tags.name, set: { name: sql`excluded.name` } })
+        .returning({ id: schema.tags.id, name: schema.tags.name });
+      for (const row of rows) nameToId.set(row.name, row.id);
+    }
+    return nameToId;
+  }
+
+  async batchInsertBookTags(items: Array<{ bookId: number; tagId: number }>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.bookTags).values(batch).onConflictDoNothing();
+    }
+  }
+
+  async batchUpsertUserBookStatuses(items: Array<typeof schema.userBookStatus.$inferInsert>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db
+        .insert(schema.userBookStatus)
+        .values(batch)
+        .onConflictDoUpdate({
+          target: [schema.userBookStatus.userId, schema.userBookStatus.bookId],
+          set: {
+            status: sql`excluded.status`,
+            source: sql`excluded.source`,
+            startedAt: sql`excluded.started_at`,
+            finishedAt: sql`excluded.finished_at`,
+            updatedAt: sql`excluded.updated_at`,
+          },
+        });
+    }
+  }
+
+  async batchUpsertReadingProgress(items: Array<typeof schema.readingProgress.$inferInsert>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db
+        .insert(schema.readingProgress)
+        .values(batch)
+        .onConflictDoUpdate({
+          target: [schema.readingProgress.bookFileId, schema.readingProgress.userId],
+          set: {
+            percentage: sql`excluded.percentage`,
+            cfi: sql`excluded.cfi`,
+            pageNumber: sql`excluded.page_number`,
+            positionSeconds: sql`excluded.position_seconds`,
+            updatedAt: sql`excluded.updated_at`,
+          },
+        });
+    }
+  }
+
+  async batchUpsertAudiobookProgress(items: Array<typeof schema.audiobookProgress.$inferInsert>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db
+        .insert(schema.audiobookProgress)
+        .values(batch)
+        .onConflictDoUpdate({
+          target: [schema.audiobookProgress.userId, schema.audiobookProgress.bookId],
+          set: {
+            percentage: sql`excluded.percentage`,
+            currentFileId: sql`excluded.current_file_id`,
+            positionSeconds: sql`excluded.position_seconds`,
+            updatedAt: sql`excluded.updated_at`,
+          },
+        });
+    }
+  }
+
+  async batchInsertBookmarks(items: Array<typeof schema.bookmarks.$inferInsert>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.bookmarks).values(batch);
+    }
+  }
+
+  async batchInsertAnnotations(items: Array<typeof schema.annotations.$inferInsert>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.annotations).values(batch);
+    }
+  }
+
+  async batchInsertCollectionBooks(items: Array<{ collectionId: number; bookId: number }>): Promise<void> {
+    if (items.length === 0) return;
+    for (const batch of chunk(items, BATCH_CHUNK_SIZE)) {
+      await this.db.insert(schema.collectionBooks).values(batch).onConflictDoNothing();
+    }
+  }
+
+  // --- File lookups for user state ---
+
+  async fetchTargetBookPrimaryFiles(bookIds: number[]): Promise<{
+    primaryFilesByBookId: Map<number, number>;
+    audiobookPrimaryFilesByBookId: Map<number, number>;
+  }> {
+    const primaryFilesByBookId = new Map<number, number>();
+    const audiobookPrimaryFilesByBookId = new Map<number, number>();
+
+    if (bookIds.length === 0) return { primaryFilesByBookId, audiobookPrimaryFilesByBookId };
+
+    const { isAudioFormat } = await import('@projectx/types');
+
+    const rows = 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, bookIds));
+
+    for (const row of rows) {
+      if (!row.primaryFileId) continue;
+      primaryFilesByBookId.set(row.bookId, row.primaryFileId);
+      if (row.primaryFileFormat && isAudioFormat(row.primaryFileFormat)) {
+        audiobookPrimaryFilesByBookId.set(row.bookId, row.primaryFileId);
+      }
+    }
+
+    return { primaryFilesByBookId, audiobookPrimaryFilesByBookId };
+  }
+
+  async fetchTargetBookFiles(bookIds: number[]): Promise<Map<number, Array<{ id: number; hash: string | null; absolutePath: string }>>> {
+    const result = new Map<number, Array<{ id: number; hash: string | null; absolutePath: string }>>();
+    if (bookIds.length === 0) return result;
+
+    const rows = await this.db
+      .select({
+        id: schema.bookFiles.id,
+        bookId: schema.bookFiles.bookId,
+        hash: schema.bookFiles.hash,
+        absolutePath: schema.bookFiles.absolutePath,
+      })
+      .from(schema.bookFiles)
+      .where(inArray(schema.bookFiles.bookId, bookIds));
+
+    for (const row of rows) {
+      const files = result.get(row.bookId) ?? [];
+      files.push({ id: row.id, hash: row.hash, absolutePath: row.absolutePath });
+      result.set(row.bookId, files);
+    }
+
+    return result;
+  }
+}
diff --git a/server/src/modules/migration/executor/shared-overlays.importer.ts b/server/src/modules/migration/executor/shared-overlays.importer.ts
new file mode 100644
index 000000000..a2691bc18
--- /dev/null
+++ b/server/src/modules/migration/executor/shared-overlays.importer.ts
@@ -0,0 +1,261 @@
+import { Injectable } from '@nestjs/common';
+
+import type * as schema from '../../../db/schema';
+import { MigrationRepository } from '../migration.repository';
+import { MigrationImportRepository } from './migration-import.repository';
+import type { PlannerResult } from '../planner/planner.types';
+import { type RunStateCheck, buildContributorValues, buildMetadataPatch, emptyCounters, getSourceContributors, truncateText } from './executor-utils';
+
+function isDomainAvailable(planned: PlannerResult, domain: keyof NonNullable<PlannerResult['execution']['sourceData']['availableDomains']>): boolean {
+  return planned.execution.sourceData.availableDomains?.[domain] ?? true;
+}
+
+@Injectable()
+export class SharedOverlaysImporter {
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly importRepo: MigrationImportRepository,
+  ) {}
+
+  async import(runId: number, planned: PlannerResult, ensureRunning: RunStateCheck): Promise<void> {
+    await this.importMetadata(runId, planned, ensureRunning);
+    await this.importAuthors(runId, planned);
+    await this.importNarrators(runId, planned);
+    await this.importGenres(runId, planned);
+    await this.importTags(runId, planned);
+  }
+
+  private async importMetadata(runId: number, planned: PlannerResult, ensureRunning: RunStateCheck): Promise<void> {
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((row) => [row.sourceBookId, row]));
+    const counters = emptyCounters();
+    const batch: Array<{ bookId: number } & Record<string, unknown>> = [];
+
+    if (!isDomainAvailable(planned, 'metadata')) {
+      counters.processed = planned.execution.matchedBooks.length;
+      counters.skipped = planned.execution.matchedBooks.length;
+      await this.repo.setRunMetric(runId, 'shared_overlays', 'book_metadata', counters);
+      return;
+    }
+
+    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 patch = buildMetadataPatch(sourceBook);
+      if (Object.keys(patch).length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      batch.push({ bookId: match.targetBookId, ...patch });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction((importRepo) => importRepo.batchUpsertBookMetadata(batch));
+    await this.repo.setRunMetric(runId, 'shared_overlays', 'book_metadata', counters);
+  }
+
+  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();
+
+    if (!isDomainAvailable(planned, 'authors')) {
+      counters.processed = planned.execution.matchedBooks.length;
+      counters.skipped = planned.execution.matchedBooks.length;
+      await this.repo.setRunMetric(runId, 'shared_overlays', 'book_authors', counters);
+      return;
+    }
+
+    // Collect all unique authors and per-book assignments in a single pass
+    const allAuthors = new Map<string, typeof schema.authors.$inferInsert>();
+    const bookAssignments: Array<{ bookId: number; authorName: string; displayOrder: number }> = [];
+    const affectedBookIds: number[] = [];
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      affectedBookIds.push(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 values = buildContributorValues(contributor);
+        allAuthors.set(values.name, values);
+        bookAssignments.push({ bookId: match.targetBookId, authorName: values.name, displayOrder: index });
+      }
+      counters.imported += authors.length;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.batchDeleteBookAuthors(affectedBookIds);
+      const nameToId = await importRepo.batchUpsertAuthors([...allAuthors.values()]);
+      const links = bookAssignments
+        .map((a) => ({ bookId: a.bookId, authorId: nameToId.get(a.authorName)!, displayOrder: a.displayOrder }))
+        .filter((a) => a.authorId != null);
+      await importRepo.batchInsertBookAuthors(links);
+    });
+
+    await this.repo.setRunMetric(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();
+
+    if (!isDomainAvailable(planned, 'narrators')) {
+      counters.processed = planned.execution.matchedBooks.length;
+      counters.skipped = planned.execution.matchedBooks.length;
+      await this.repo.setRunMetric(runId, 'shared_overlays', 'book_narrators', counters);
+      return;
+    }
+
+    const allNarrators = new Map<string, { name: string; sortName: string }>();
+    const bookAssignments: Array<{ bookId: number; narratorName: string; displayOrder: number }> = [];
+    const affectedBookIds: number[] = [];
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      affectedBookIds.push(match.targetBookId);
+      const narrators = getSourceContributors(sourceBook.narrators, null);
+      if (narrators.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const [index, contributor] of narrators.entries()) {
+        const values = {
+          name: truncateText(contributor.name, 500),
+          sortName: truncateText(contributor.sortName ?? contributor.name, 500),
+        };
+        allNarrators.set(values.name, values);
+        bookAssignments.push({ bookId: match.targetBookId, narratorName: values.name, displayOrder: index });
+      }
+      counters.imported += narrators.length;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.batchDeleteBookNarrators(affectedBookIds);
+      const nameToId = await importRepo.batchUpsertNarrators([...allNarrators.values()]);
+      const links = bookAssignments
+        .map((a) => ({ bookId: a.bookId, narratorId: nameToId.get(a.narratorName)!, displayOrder: a.displayOrder }))
+        .filter((a) => a.narratorId != null);
+      await importRepo.batchInsertBookNarrators(links);
+    });
+
+    await this.repo.setRunMetric(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();
+
+    if (!isDomainAvailable(planned, 'genres')) {
+      counters.processed = planned.execution.matchedBooks.length;
+      counters.skipped = planned.execution.matchedBooks.length;
+      await this.repo.setRunMetric(runId, 'shared_overlays', 'book_genres', counters);
+      return;
+    }
+
+    const allGenreNames = new Set<string>();
+    const bookAssignments: Array<{ bookId: number; genreName: string }> = [];
+    const affectedBookIds: number[] = [];
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      affectedBookIds.push(match.targetBookId);
+      if (sourceBook.genres.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const name of sourceBook.genres) {
+        const genreName = truncateText(name, 200);
+        allGenreNames.add(genreName);
+        bookAssignments.push({ bookId: match.targetBookId, genreName });
+      }
+      counters.imported += sourceBook.genres.length;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.batchDeleteBookGenres(affectedBookIds);
+      const nameToId = await importRepo.batchUpsertGenres([...allGenreNames]);
+      const links = bookAssignments.map((a) => ({ bookId: a.bookId, genreId: nameToId.get(a.genreName)! })).filter((a) => a.genreId != null);
+      await importRepo.batchInsertBookGenres(links);
+    });
+
+    await this.repo.setRunMetric(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();
+
+    if (!isDomainAvailable(planned, 'tags')) {
+      counters.processed = planned.execution.matchedBooks.length;
+      counters.skipped = planned.execution.matchedBooks.length;
+      await this.repo.setRunMetric(runId, 'shared_overlays', 'book_tags', counters);
+      return;
+    }
+
+    const allTagNames = new Set<string>();
+    const bookAssignments: Array<{ bookId: number; tagName: string }> = [];
+    const affectedBookIds: number[] = [];
+
+    for (const match of planned.execution.matchedBooks) {
+      counters.processed += 1;
+      const sourceBook = sourceBooksById.get(match.sourceBookId);
+      if (!sourceBook) {
+        counters.unresolved += 1;
+        continue;
+      }
+
+      affectedBookIds.push(match.targetBookId);
+      if (sourceBook.tags.length === 0) {
+        counters.skipped += 1;
+        continue;
+      }
+
+      for (const name of sourceBook.tags) {
+        const tagName = truncateText(name, 200);
+        allTagNames.add(tagName);
+        bookAssignments.push({ bookId: match.targetBookId, tagName });
+      }
+      counters.imported += sourceBook.tags.length;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.batchDeleteBookTags(affectedBookIds);
+      const nameToId = await importRepo.batchUpsertTags([...allTagNames]);
+      const links = bookAssignments.map((a) => ({ bookId: a.bookId, tagId: nameToId.get(a.tagName)! })).filter((a) => a.tagId != null);
+      await importRepo.batchInsertBookTags(links);
+    });
+
+    await this.repo.setRunMetric(runId, 'shared_overlays', 'book_tags', counters);
+  }
+}
diff --git a/server/src/modules/migration/executor/user-state.importer.ts b/server/src/modules/migration/executor/user-state.importer.ts
new file mode 100644
index 000000000..112ce7429
--- /dev/null
+++ b/server/src/modules/migration/executor/user-state.importer.ts
@@ -0,0 +1,522 @@
+import { Injectable } from '@nestjs/common';
+import type { ReadStatus, ReadStatusSource } from '@projectx/types';
+
+import type { SourceBook, SourceBookmark } from '../adapters/source-adapter.types';
+import { MigrationRepository } from '../migration.repository';
+import { MigrationImportRepository } from './migration-import.repository';
+import type { PlannerResult } from '../planner/planner.types';
+import {
+  type RunStateCheck,
+  buildSourceFileTargetMap,
+  clampNonNegative,
+  clampPercent,
+  emptyCounters,
+  normalizeReadStatus,
+  toDate,
+  truncateNullableText,
+  truncateText,
+  uniqueNumbers,
+} from './executor-utils';
+
+function isDomainAvailable(planned: PlannerResult, domain: keyof NonNullable<PlannerResult['execution']['sourceData']['availableDomains']>): boolean {
+  return planned.execution.sourceData.availableDomains?.[domain] ?? true;
+}
+
+@Injectable()
+export class UserStateImporter {
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly importRepo: MigrationImportRepository,
+  ) {}
+
+  async import(runId: number, planned: PlannerResult, ensureRunning: RunStateCheck): Promise<void> {
+    const sourceToTargetUser = new Map(planned.plan.userMappings.map((m) => [m.sourceUserId, m.targetUserId]));
+    const sourceToTargetBook = new Map(planned.execution.matchedBooks.map((m) => [m.sourceBookId, m.targetBookId]));
+    const targetBookIds = uniqueNumbers([...sourceToTargetBook.values()]);
+
+    const { primaryFilesByBookId, audiobookPrimaryFilesByBookId } = await this.importRepo.fetchTargetBookPrimaryFiles(targetBookIds);
+    const targetFilesByBookId = await this.importRepo.fetchTargetBookFiles(targetBookIds);
+    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();
+    if (!isDomainAvailable(planned, 'userBookStatuses')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'user_book_status', counters);
+      return;
+    }
+
+    const batch: Array<{
+      userId: number;
+      bookId: number;
+      status: ReadStatus;
+      source: ReadStatusSource;
+      startedAt: Date | null;
+      finishedAt: Date | null;
+      updatedAt: Date;
+    }> = [];
+
+    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;
+      }
+
+      batch.push({
+        userId: targetUserId,
+        bookId: targetBookId,
+        status: normalizeReadStatus(row.status, row.percentage),
+        source: 'manual',
+        startedAt: toDate(row.startedAt),
+        finishedAt: toDate(row.finishedAt),
+        updatedAt: toDate(row.updatedAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.clearUserBookStatuses([...userMap.values()], [...bookMap.values()]);
+      await importRepo.batchUpsertUserBookStatuses(batch);
+    });
+    await this.repo.setRunMetric(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();
+    if (!isDomainAvailable(planned, 'readingProgress')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'reading_progress', counters);
+      return;
+    }
+
+    const batch: Array<{
+      bookFileId: number;
+      userId: number;
+      percentage: number;
+      cfi: string | null;
+      pageNumber: number | null;
+      positionSeconds: number | null;
+      updatedAt: Date;
+    }> = [];
+
+    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;
+      }
+
+      batch.push({
+        bookFileId: targetFileId,
+        userId: targetUserId,
+        percentage: clampPercent(row.percentage),
+        cfi: row.cfi,
+        pageNumber: row.pageNumber,
+        positionSeconds: row.positionSeconds,
+        updatedAt: toDate(row.updatedAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.clearReadingProgress([...userMap.values()], [...primaryFilesByBookId.values(), ...sourceFileToTargetFile.values()]);
+      await importRepo.batchUpsertReadingProgress(batch);
+    });
+    await this.repo.setRunMetric(runId, 'user_state', 'reading_progress', 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();
+    if (!isDomainAvailable(planned, 'readingProgress')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'audiobook_progress', counters);
+      return;
+    }
+
+    const sourceAudioRows = planned.execution.sourceData.userFileProgress.filter((row) => {
+      const targetBookId = bookMap.get(row.sourceBookId);
+      return targetBookId ? audiobookPrimaryFilesByBookId.has(targetBookId) : false;
+    });
+
+    const batch: Array<{
+      userId: number;
+      bookId: number;
+      percentage: number;
+      currentFileId: number;
+      positionSeconds: number;
+      updatedAt: Date;
+    }> = [];
+
+    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;
+      }
+
+      batch.push({
+        userId: targetUserId,
+        bookId: targetBookId,
+        percentage: clampPercent(row.percentage),
+        currentFileId: targetFileId,
+        positionSeconds: clampNonNegative(row.positionSeconds) ?? 0,
+        updatedAt: toDate(row.updatedAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.clearAudiobookProgress([...userMap.values()], [...audiobookPrimaryFilesByBookId.keys()]);
+      await importRepo.batchUpsertAudiobookProgress(batch);
+    });
+    await this.repo.setRunMetric(runId, 'user_state', 'audiobook_progress', counters);
+  }
+
+  private async importBookmarks(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    if (!isDomainAvailable(planned, 'bookmarks')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'bookmarks', counters);
+      return;
+    }
+
+    const sourceBooksById = new Map(planned.execution.sourceData.books.map((book) => [book.sourceBookId, book]));
+
+    const batch: Array<{
+      userId: number;
+      bookId: number;
+      title: string;
+      cfi: string | null;
+      positionSeconds: number | null;
+      createdAt: Date;
+    }> = [];
+
+    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;
+      }
+
+      batch.push({
+        userId: targetUserId,
+        bookId: targetBookId,
+        title: truncateText(row.title ?? 'Imported bookmark', 500),
+        cfi: truncateNullableText(row.cfi, 2000) ?? null,
+        positionSeconds: resolveBookmarkPositionSeconds(row, sourceBooksById.get(row.sourceBookId)),
+        createdAt: toDate(row.createdAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.clearBookmarks([...userMap.values()], [...bookMap.values()]);
+      await importRepo.batchInsertBookmarks(batch);
+    });
+    await this.repo.setRunMetric(runId, 'user_state', 'bookmarks', counters);
+  }
+
+  private async importAnnotations(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    if (!isDomainAvailable(planned, 'annotations')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'annotations', counters);
+      return;
+    }
+
+    const batch: Array<{
+      userId: number;
+      bookId: number;
+      cfi: string;
+      text: string;
+      color: string;
+      style: string;
+      note: string | null;
+      chapterTitle: string | null;
+      createdAt: Date;
+      updatedAt: Date;
+    }> = [];
+
+    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;
+      }
+
+      batch.push({
+        userId: targetUserId,
+        bookId: targetBookId,
+        cfi: truncateText(row.cfi ?? '', 2000),
+        text: row.text ?? '',
+        color: truncateText(row.color ?? 'yellow', 20),
+        style: truncateText(row.style ?? 'highlight', 20),
+        note: row.note,
+        chapterTitle: truncateNullableText(row.chapterTitle, 500) ?? null,
+        createdAt: toDate(row.createdAt) ?? new Date(),
+        updatedAt: toDate(row.updatedAt) ?? new Date(),
+      });
+      counters.imported += 1;
+    }
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      await importRepo.clearAnnotations([...userMap.values()], [...bookMap.values()]);
+      await importRepo.batchInsertAnnotations(batch);
+    });
+    await this.repo.setRunMetric(runId, 'user_state', 'annotations', counters);
+  }
+
+  private async importCollections(
+    runId: number,
+    planned: PlannerResult,
+    userMap: Map<string, number>,
+    bookMap: Map<string, number>,
+    ensureRunning: RunStateCheck,
+  ): Promise<void> {
+    const counters = emptyCounters();
+    if (!isDomainAvailable(planned, 'shelves')) {
+      await this.repo.setRunMetric(runId, 'user_state', 'collections', counters);
+      return;
+    }
+
+    const shelvesById = new Map(planned.execution.sourceData.shelves.map((row) => [row.sourceShelfId, row]));
+
+    await this.importRepo.withTransaction(async (importRepo) => {
+      const targetUserIds = uniqueNumbers([...userMap.values()]);
+      const existingCollections = await importRepo.fetchExistingCollections(targetUserIds);
+      const importedCollectionKeyToId = new Map<string, number>(
+        existingCollections
+          .map((row) => {
+            const sourceShelfId = parseImportedCollectionSourceShelfId(row.description);
+            return sourceShelfId ? ([`${row.userId}:${sourceShelfId}`, row.id] as readonly [string, number]) : null;
+          })
+          .filter((row): row is readonly [string, number] => row !== null),
+      );
+      const usedCollectionNamesByUser = new Map<number, Set<string>>();
+      for (const row of existingCollections) {
+        const names = usedCollectionNamesByUser.get(row.userId) ?? new Set<string>();
+        names.add(row.name.toLowerCase());
+        usedCollectionNamesByUser.set(row.userId, names);
+      }
+      const preparedCollectionIds = new Set<number>();
+
+      const ensureCollection = async (shelf: { sourceShelfId: string; sourceUserId: string; name: string }): Promise<number | null> => {
+        const targetUserId = userMap.get(shelf.sourceUserId);
+        if (!targetUserId) return null;
+
+        const key = `${targetUserId}:${shelf.sourceShelfId}`;
+        let collectionId = importedCollectionKeyToId.get(key);
+        if (!collectionId) {
+          const usedNames = usedCollectionNamesByUser.get(targetUserId) ?? new Set<string>();
+          const name = nextImportedCollectionName(shelf.name, usedNames);
+          usedCollectionNamesByUser.set(targetUserId, usedNames);
+          const inserted = await importRepo.insertCollection({
+            userId: targetUserId,
+            name,
+            description: buildImportedCollectionDescription(shelf.sourceShelfId),
+            syncToKobo: false,
+            displayOrder: 0,
+          });
+          collectionId = inserted.id;
+          importedCollectionKeyToId.set(key, collectionId);
+        }
+
+        if (!preparedCollectionIds.has(collectionId)) {
+          await importRepo.clearCollectionBooks(collectionId);
+          preparedCollectionIds.add(collectionId);
+        }
+
+        return collectionId;
+      };
+
+      for (const shelf of planned.execution.sourceData.shelves) {
+        await ensureRunning();
+        await ensureCollection(shelf);
+      }
+
+      const collectionBookBatch: Array<{ collectionId: number; bookId: number }> = [];
+
+      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 ensureCollection(shelf);
+        if (!collectionId) {
+          counters.unresolved += 1;
+          continue;
+        }
+
+        collectionBookBatch.push({ collectionId, bookId: targetBookId });
+        counters.imported += 1;
+      }
+
+      await importRepo.batchInsertCollectionBooks(collectionBookBatch);
+    });
+    await this.repo.setRunMetric(runId, 'user_state', 'collections', counters);
+  }
+}
+
+const IMPORTED_COLLECTION_DESCRIPTION_PREFIX = 'Imported from Booklore migration shelf: ';
+
+function buildImportedCollectionDescription(sourceShelfId: string): string {
+  return `${IMPORTED_COLLECTION_DESCRIPTION_PREFIX}${sourceShelfId}`;
+}
+
+function parseImportedCollectionSourceShelfId(description: string | null): string | null {
+  if (!description?.startsWith(IMPORTED_COLLECTION_DESCRIPTION_PREFIX)) return null;
+  const sourceShelfId = description.slice(IMPORTED_COLLECTION_DESCRIPTION_PREFIX.length).trim();
+  return sourceShelfId.length > 0 ? sourceShelfId : null;
+}
+
+function nextImportedCollectionName(baseName: string, usedNames: Set<string>): string {
+  const base = baseName.trim() || 'Imported Shelf';
+  if (!usedNames.has(base.toLowerCase())) {
+    usedNames.add(base.toLowerCase());
+    return base;
+  }
+
+  const importedBase = `${base} (Booklore)`;
+  if (!usedNames.has(importedBase.toLowerCase())) {
+    usedNames.add(importedBase.toLowerCase());
+    return importedBase;
+  }
+
+  for (let i = 2; i < 10_000; i += 1) {
+    const candidate = `${base} (Booklore ${i})`;
+    if (!usedNames.has(candidate.toLowerCase())) {
+      usedNames.add(candidate.toLowerCase());
+      return candidate;
+    }
+  }
+
+  const fallback = `${base} (Booklore ${Date.now()})`;
+  usedNames.add(fallback.toLowerCase());
+  return fallback;
+}
+
+function resolveBookmarkPositionSeconds(row: SourceBookmark, sourceBook: SourceBook | undefined): number | null {
+  if (row.positionSeconds == null || !Number.isFinite(row.positionSeconds)) return null;
+  const positionSeconds = Math.max(0, row.positionSeconds);
+  if (row.sourceFileId || row.trackIndex == null || !sourceBook?.files?.length) return positionSeconds;
+
+  const trackIndex = resolveTrackIndex(row.trackIndex, sourceBook.files.length);
+  if (trackIndex == null || trackIndex === 0) return positionSeconds;
+
+  let offsetSeconds = 0;
+  for (const file of sourceBook.files.slice(0, trackIndex)) {
+    if (file.durationSeconds == null) return positionSeconds;
+    offsetSeconds += file.durationSeconds;
+  }
+
+  return offsetSeconds + positionSeconds;
+}
+
+function resolveTrackIndex(trackIndex: number, fileCount: number): number | null {
+  if (!Number.isFinite(trackIndex)) return null;
+  const rounded = Math.trunc(trackIndex);
+  if (rounded >= 0 && rounded < fileCount) return rounded;
+  const oneBased = rounded - 1;
+  if (oneBased >= 0 && oneBased < fileCount) return oneBased;
+  return null;
+}
diff --git a/server/src/modules/migration/migration-profile.service.test.ts b/server/src/modules/migration/migration-profile.service.test.ts
new file mode 100644
index 000000000..dabbcb5fa
--- /dev/null
+++ b/server/src/modules/migration/migration-profile.service.test.ts
@@ -0,0 +1,172 @@
+import { BadRequestException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MigrationProfileService } from './migration-profile.service';
+
+const noopEncryption = {
+  encryptConfig: (c: Record<string, unknown>) => c,
+  decryptConfig: (c: unknown) => c as Record<string, unknown>,
+  isConfigured: () => false,
+} as never;
+
+function createProfileService(overrides: Partial<Record<string, unknown>> = {}): MigrationProfileService {
+  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(),
+    listRuns: vi.fn(() => Promise.resolve([])),
+    purgeRunState: vi.fn(() => Promise.resolve()),
+    ...overrides,
+  };
+
+  return new MigrationProfileService(repo as never, { listTypes: vi.fn(), get: vi.fn() } as never, { validate: vi.fn() } as never, noopEncryption);
+}
+
+describe('MigrationProfileService', () => {
+  it('rejects profile creation when target user mapping IDs are invalid', async () => {
+    const service = createProfileService();
+
+    await expect(
+      service.createProfile(
+        {
+          sourceId: 1,
+          name: 'Profile',
+          userMappings: [{ sourceUserId: 'src-user', targetUserId: 999 }],
+          pathMappings: [],
+        },
+        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 = createProfileService({
+      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',
+      }),
+    );
+    expect(createProfile).toHaveBeenCalledWith(
+      expect.not.objectContaining({
+        version: expect.anything(),
+      }),
+    );
+  });
+
+  it('does not pass version to createProfile (repo handles it)', async () => {
+    const createProfileFn = vi.fn(() =>
+      Promise.resolve({
+        id: 5,
+        sourceId: 1,
+        name: 'Booklore Migration',
+        version: 1,
+        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+        pathMappings: [],
+        scope: {},
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+    );
+
+    const service = createProfileService({
+      listProfiles: vi.fn(() =>
+        Promise.resolve([
+          {
+            id: 3,
+            sourceId: 1,
+            name: 'Booklore Migration',
+            version: 3,
+            userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+            pathMappings: [],
+            scope: {},
+            createdByUserId: 1,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          },
+        ]),
+      ),
+      createProfile: createProfileFn,
+    });
+
+    await service.createProfile(
+      {
+        sourceId: 1,
+        name: 'Booklore Migration',
+        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
+        pathMappings: [],
+      },
+      1,
+    );
+
+    expect(createProfileFn).toHaveBeenCalledTimes(1);
+    const callArg = (createProfileFn.mock.calls as unknown[][])[0][0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty('version');
+  });
+});
diff --git a/server/src/modules/migration/migration-profile.service.ts b/server/src/modules/migration/migration-profile.service.ts
new file mode 100644
index 000000000..4220209d4
--- /dev/null
+++ b/server/src/modules/migration/migration-profile.service.ts
@@ -0,0 +1,178 @@
+import { BadRequestException, ConflictException, Injectable, InternalServerErrorException, NotFoundException } from '@nestjs/common';
+
+import { CreateMigrationProfileDto } from './dto/create-migration-profile.dto';
+import { ValidatePathMappingsDto } from './dto/validate-path-mappings.dto';
+import { parseConnectionConfig } from './core/connection-config';
+import { asRecord } from './core/coerce';
+import { buildPathMappingsHash } from './core/plan-hash';
+import { sanitizeProfileForApi } from './core/api-sanitizers';
+import { MigrationEncryptionService } from './core/migration-encryption.service';
+import { MigrationRepository } from './migration.repository';
+import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
+import { PathMappingValidationService } from './planner/path-mapping-validation.service';
+
+const ACTIVE_LIVE_STATES = new Set(['running']);
+
+@Injectable()
+export class MigrationProfileService {
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly adapterRegistry: SourceAdapterRegistry,
+    private readonly pathValidator: PathMappingValidationService,
+    private readonly encryption: MigrationEncryptionService,
+  ) {}
+
+  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 profile = await this.repo.createProfile({ ...payload });
+    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 decryptedConfig = this.encryption.decryptConfig(source.connectionConfig);
+    const sourceData = await adapter.exportData(parseConnectionConfig(source.type, decryptedConfig));
+    const targetUsers = await this.repo.listTargetUsersForMapping();
+
+    const suggestions = sourceData.users.map((sourceUser: { sourceUserId: string; username: string; email: string | null; name: string | null }) => {
+      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 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 decryptedConfig = this.encryption.decryptConfig(source.connectionConfig);
+    const sourceData = await adapter.exportData(parseConnectionConfig(source.type, decryptedConfig));
+
+    const validation = await this.pathValidator.validate({
+      sourceBooks: sourceData.books,
+      pathMappings: dto.pathMappings,
+      sampleLimit: dto.sampleLimit,
+    });
+
+    const validatedAt = new Date().toISOString();
+    const pathMappingsHash = buildPathMappingsHash(dto.pathMappings);
+    const persistedProfileId = await this.persistPathValidation(sourceId, pathMappingsHash, validatedAt);
+
+    return {
+      sourceId,
+      validatedAt,
+      pathMappingsHash,
+      persistedProfileId,
+      ...validation,
+    };
+  }
+
+  private async persistPathValidation(sourceId: number, pathMappingsHash: string, validatedAt: string): Promise<number | null> {
+    const profiles = await this.repo.listProfiles(sourceId);
+    const matchingProfile = profiles.find((profile) => buildPathMappingsHash(profile.pathMappings) === pathMappingsHash);
+    if (!matchingProfile) return null;
+
+    const scope = asRecord(matchingProfile.scope);
+    const preflight = asRecord(scope.preflight);
+    await this.repo.updateProfileScope(matchingProfile.id, {
+      ...scope,
+      preflight: {
+        ...preflight,
+        pathValidatedAt: validatedAt,
+        pathMappingsHash,
+      },
+    });
+    return matchingProfile.id;
+  }
+
+  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 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';
+}
diff --git a/server/src/modules/migration/migration-progress.gateway.ts b/server/src/modules/migration/migration-progress.gateway.ts
new file mode 100644
index 000000000..1668a330d
--- /dev/null
+++ b/server/src/modules/migration/migration-progress.gateway.ts
@@ -0,0 +1,95 @@
+import { Logger } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { OnGatewayConnection, OnGatewayDisconnect, SubscribeMessage, WebSocketGateway, WebSocketServer } from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+
+import { Permission, type MigrationProgressEvent, type MigrationRunState } from '@projectx/types';
+import type { RequestUser } from '../../common/types/request-user';
+import { AuthService } from '../auth/auth.service';
+import { MigrationRepository } from './migration.repository';
+import { sanitizeRunForApi } from './core/api-sanitizers';
+
+@WebSocketGateway({ namespace: '/migration', cors: { origin: '*', credentials: true } })
+export class MigrationProgressGateway implements OnGatewayConnection, OnGatewayDisconnect {
+  @WebSocketServer() server: Server;
+  private readonly logger = new Logger(MigrationProgressGateway.name);
+
+  constructor(
+    private readonly jwtService: JwtService,
+    private readonly authService: AuthService,
+    private readonly repo: MigrationRepository,
+  ) {}
+
+  async handleConnection(client: Socket): Promise<void> {
+    try {
+      const token = client.handshake.auth?.token as string | undefined;
+      if (!token) throw new Error('No token provided');
+      const payload = this.jwtService.verify<{ sub: number; ver: number }>(token);
+      const user = await this.authService.validateUser(payload.sub, payload.ver);
+      if (!user) throw new Error('User not found or token revoked');
+      this.assertCanViewMigrationProgress(user);
+      (client.data as Record<string, unknown>).user = user;
+      this.logger.debug(`[migration.ws_connection] [start] userId=${user.id} socketId=${client.id} - websocket connected`);
+    } catch (err) {
+      this.logger.warn(
+        `[migration.ws_connection] [fail] socketId=${client.id} errorClass=${err instanceof Error ? err.name : 'Error'} error="${(err instanceof Error ? err.message : String(err)).replace(/"/g, '\\"')}" - websocket rejected`,
+      );
+      client.disconnect();
+    }
+  }
+
+  handleDisconnect(client: Socket): void {
+    this.logger.debug(`[migration.ws_connection] [end] socketId=${client.id} - websocket disconnected`);
+  }
+
+  @SubscribeMessage('subscribe:run')
+  async handleSubscribeRun(client: Socket, runId: number): Promise<void> {
+    const user = (client.data as { user?: RequestUser }).user;
+    if (!user) return;
+    void client.join(`run:${runId}`);
+
+    const run = await this.repo.findRunById(runId);
+    if (!run) return;
+
+    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 },
+    );
+
+    const sanitized = sanitizeRunForApi(run);
+    const snapshot: MigrationProgressEvent = {
+      runId,
+      state: sanitized.state as MigrationRunState,
+      currentStage: sanitized.currentStage,
+      totals,
+      metrics: metrics.map((m) => ({
+        stage: m.stage,
+        entityType: m.entityType,
+        processed: m.processed,
+        imported: m.imported,
+        skipped: m.skipped,
+        unresolved: m.unresolved,
+        failed: m.failed,
+        updatedAt: m.updatedAt.toISOString(),
+      })),
+    };
+    client.emit('migration:progress', snapshot);
+  }
+
+  emitProgress(event: MigrationProgressEvent): void {
+    this.server?.to(`run:${event.runId}`).emit('migration:progress', event);
+  }
+
+  private assertCanViewMigrationProgress(user: RequestUser): void {
+    if (user.isSuperuser) return;
+    if (user.permissions.includes(Permission.ManageAppSettings)) return;
+    throw new Error('Missing permission: manage_app_settings');
+  }
+}
diff --git a/server/src/modules/migration/migration-source.service.test.ts b/server/src/modules/migration/migration-source.service.test.ts
new file mode 100644
index 000000000..bf011ef4e
--- /dev/null
+++ b/server/src/modules/migration/migration-source.service.test.ts
@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { MigrationSourceService, resolveConnectionConfig } from './migration-source.service';
+
+const noopEncryption = {
+  encryptConfig: (c: Record<string, unknown>) => c,
+  decryptConfig: (c: unknown) => c as Record<string, unknown>,
+  isConfigured: () => false,
+} as never;
+
+describe('MigrationSourceService', () => {
+  describe('createSource - password sentinel', () => {
+    it('preserves existing password when sentinel is sent back', async () => {
+      const existingSource = {
+        id: 1,
+        type: 'booklore',
+        name: 'Existing Source',
+        connectionConfig: { host: 'db.example.com', user: 'admin', password: 'real-secret-password', database: 'booklore' },
+        capabilities: null,
+        lastValidatedAt: new Date(),
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const updateSource = vi.fn((id: number, values: Record<string, unknown>) => {
+        return Promise.resolve({ ...existingSource, ...values, id });
+      });
+
+      const validate = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          sourceType: 'booklore',
+          sourceVersion: '1.0',
+          warnings: [],
+          counts: {},
+          missingTables: [],
+        }),
+      );
+
+      const repo = {
+        findSourceById: vi.fn(() => Promise.resolve(existingSource)),
+        listRuns: vi.fn(() => Promise.resolve([])),
+        listSources: vi.fn(() => Promise.resolve([existingSource])),
+        updateSource,
+        createSource: vi.fn(),
+        purgeRunState: vi.fn(() => Promise.resolve()),
+      };
+
+      const service = new MigrationSourceService(repo as never, { listTypes: vi.fn(), get: () => ({ validate }) } as never, noopEncryption);
+
+      await service.createSource(
+        {
+          type: 'booklore',
+          name: 'Existing Source',
+          connectionConfig: { host: 'db.example.com', user: 'admin', password: '********', database: 'booklore' },
+        },
+        1,
+      );
+
+      const calledConfig = updateSource.mock.calls[0][1].connectionConfig as Record<string, unknown>;
+      expect(calledConfig.password).toBe('real-secret-password');
+    });
+
+    it('uses new password when non-sentinel value is sent', async () => {
+      const existingSource = {
+        id: 1,
+        type: 'booklore',
+        name: 'Existing Source',
+        connectionConfig: { host: 'db.example.com', user: 'admin', password: 'old-password', database: 'booklore' },
+        capabilities: null,
+        lastValidatedAt: new Date(),
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const updateSource = vi.fn((id: number, values: Record<string, unknown>) => {
+        return Promise.resolve({ ...existingSource, ...values, id });
+      });
+
+      const validate = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          sourceType: 'booklore',
+          sourceVersion: '1.0',
+          warnings: [],
+          counts: {},
+          missingTables: [],
+        }),
+      );
+
+      const repo = {
+        findSourceById: vi.fn(() => Promise.resolve(existingSource)),
+        listRuns: vi.fn(() => Promise.resolve([])),
+        listSources: vi.fn(() => Promise.resolve([existingSource])),
+        updateSource,
+        createSource: vi.fn(),
+        purgeRunState: vi.fn(() => Promise.resolve()),
+      };
+
+      const service = new MigrationSourceService(repo as never, { listTypes: vi.fn(), get: () => ({ validate }) } as never, noopEncryption);
+
+      await service.createSource(
+        {
+          type: 'booklore',
+          name: 'Existing Source',
+          connectionConfig: { host: 'db.example.com', user: 'admin', password: 'new-password', database: 'booklore' },
+        },
+        1,
+      );
+
+      const calledConfig = updateSource.mock.calls[0][1].connectionConfig as Record<string, unknown>;
+      expect(calledConfig.password).toBe('new-password');
+    });
+  });
+
+  describe('resolveConnectionConfig - adapter-agnostic sentinel', () => {
+    it('resolves sentinel in any field named with password-like keys', async () => {
+      const existingSource = {
+        id: 1,
+        type: 'custom_source',
+        name: 'Custom Source',
+        connectionConfig: { host: 'db.example.com', user: 'admin', password: 'real-secret', apiKey: 'real-api-key', database: 'mydb' },
+        capabilities: null,
+        lastValidatedAt: new Date(),
+        createdByUserId: 1,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const updateSource = vi.fn((id: number, values: Record<string, unknown>) => {
+        return Promise.resolve({ ...existingSource, ...values, id });
+      });
+
+      const validate = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          sourceType: 'custom',
+          sourceVersion: '1.0',
+          warnings: [],
+          counts: {},
+          missingTables: [],
+        }),
+      );
+
+      const repo = {
+        findSourceById: vi.fn(() => Promise.resolve(existingSource)),
+        listRuns: vi.fn(() => Promise.resolve([])),
+        listSources: vi.fn(() => Promise.resolve([existingSource])),
+        updateSource,
+        createSource: vi.fn(),
+        purgeRunState: vi.fn(() => Promise.resolve()),
+      };
+
+      const service = new MigrationSourceService(repo as never, { listTypes: vi.fn(), get: () => ({ validate }) } as never, noopEncryption);
+
+      await service.createSource(
+        {
+          type: 'custom_source',
+          name: 'Custom Source',
+          connectionConfig: { host: 'db.example.com', user: 'admin', password: '********', apiKey: '********', database: 'mydb' },
+        },
+        1,
+      );
+
+      const calledConfig = updateSource.mock.calls[0][1].connectionConfig as Record<string, unknown>;
+      expect(calledConfig.password).toBe('real-secret');
+      expect(calledConfig.apiKey).toBe('real-api-key');
+      expect(calledConfig.host).toBe('db.example.com');
+    });
+  });
+
+  describe('resolveConnectionConfig (standalone)', () => {
+    it('returns incoming config when no existing source', () => {
+      const result = resolveConnectionConfig({ host: 'localhost', password: 'secret' }, null, noopEncryption);
+      expect(result).toEqual({ host: 'localhost', password: 'secret' });
+    });
+
+    it('replaces sentinel values from existing config', () => {
+      const existing = {
+        id: 1,
+        type: 'booklore',
+        name: 'test',
+        connectionConfig: { host: 'db.local', password: 'real-pw' },
+      } as never;
+
+      const result = resolveConnectionConfig({ host: 'db.local', password: '********' }, existing, noopEncryption);
+      expect(result.password).toBe('real-pw');
+      expect(result.host).toBe('db.local');
+    });
+  });
+});
diff --git a/server/src/modules/migration/migration-source.service.ts b/server/src/modules/migration/migration-source.service.ts
new file mode 100644
index 000000000..53c2d0420
--- /dev/null
+++ b/server/src/modules/migration/migration-source.service.ts
@@ -0,0 +1,161 @@
+import { BadRequestException, ConflictException, Injectable, InternalServerErrorException, NotFoundException } from '@nestjs/common';
+
+import type { MigrationSource } from '../../db/schema';
+import { CreateMigrationSourceDto } from './dto/create-migration-source.dto';
+import { TestMigrationSourceDto } from './dto/test-migration-source.dto';
+import { parseConnectionConfig, PASSWORD_REDACTED_SENTINEL } from './core/connection-config';
+import { sanitizeSourceForApi } from './core/api-sanitizers';
+import { MigrationEncryptionService } from './core/migration-encryption.service';
+import { MigrationRepository } from './migration.repository';
+import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
+
+const ACTIVE_LIVE_STATES = new Set(['running']);
+
+@Injectable()
+export class MigrationSourceService {
+  constructor(
+    private readonly repo: MigrationRepository,
+    private readonly adapterRegistry: SourceAdapterRegistry,
+    private readonly encryption: MigrationEncryptionService,
+  ) {}
+
+  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 decryptedConfig = this.encryption.decryptConfig(source.connectionConfig);
+    const result = await adapter.validate(parseConnectionConfig(source.type, decryptedConfig));
+
+    await this.repo.updateSourceValidation(source.id, {
+      capabilities: {
+        ok: result.ok,
+        sourceType: result.sourceType,
+        sourceVersion: result.sourceVersion,
+        warnings: result.warnings,
+        counts: result.counts,
+        missingTables: result.missingTables,
+      },
+      lastValidatedAt: result.ok ? new Date() : null,
+    });
+    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 sources = await this.repo.listSources();
+    const existingSource = sources[0] ?? null;
+    const connectionConfig = resolveConnectionConfig(dto.connectionConfig, existingSource, this.encryption);
+
+    const validation = await adapter.validate(parseConnectionConfig(dto.type, connectionConfig));
+    if (!validation.ok) {
+      throw new BadRequestException(
+        `Migration source validation failed. Missing required tables: ${validation.missingTables.join(', ') || 'unknown'}`,
+      );
+    }
+    const encryptedConfig = this.encryption.encryptConfig(connectionConfig);
+    const payload = {
+      type: dto.type.trim().toLowerCase(),
+      name: dto.name.trim(),
+      connectionConfig: encryptedConfig,
+      capabilities: {
+        ok: validation.ok,
+        sourceType: validation.sourceType,
+        sourceVersion: validation.sourceVersion,
+        warnings: validation.warnings,
+        counts: validation.counts,
+        missingTables: validation.missingTables,
+      },
+      createdByUserId: userId,
+    } as const;
+
+    const source = existingSource
+      ? await this.repo.updateSource(existingSource.id, {
+          ...payload,
+          name: buildUniqueSourceName(payload.name, payload.type, sources, existingSource.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,
+      connectionConfig: this.encryption.decryptConfig(source.connectionConfig),
+    });
+  }
+
+  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 decryptedConfig = this.encryption.decryptConfig(source.connectionConfig);
+    const prefixes = await adapter.fetchPathPrefixes(parseConnectionConfig(source.type, decryptedConfig));
+    return { prefixes };
+  }
+
+  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}).`);
+  }
+}
+
+export function resolveConnectionConfig(
+  incoming: Record<string, unknown>,
+  existingSource: MigrationSource | null,
+  encryption: MigrationEncryptionService,
+): Record<string, unknown> {
+  if (!existingSource) return incoming;
+
+  const existingConfig = encryption.decryptConfig(existingSource.connectionConfig);
+  const resolved = { ...incoming };
+
+  for (const [key, value] of Object.entries(resolved)) {
+    if (typeof value === 'string' && value === PASSWORD_REDACTED_SENTINEL) {
+      resolved[key] = existingConfig[key] ?? '';
+    }
+  }
+
+  return resolved;
+}
+
+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()}`;
+}
diff --git a/server/src/modules/migration/migration.controller.ts b/server/src/modules/migration/migration.controller.ts
index ebc4caa22..7605592ae 100644
--- a/server/src/modules/migration/migration.controller.ts
+++ b/server/src/modules/migration/migration.controller.ts
@@ -1,4 +1,5 @@
-import { Body, Controller, Get, HttpCode, HttpStatus, Param, ParseIntPipe, Post, Query } from '@nestjs/common';
+import { Body, Controller, Get, HttpCode, HttpStatus, Param, ParseIntPipe, Post, Query, Res } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
 import { Permission } from '@projectx/types';
 
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
@@ -7,89 +8,118 @@ 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 { ResolveDuplicateMatchesDto } from './dto/resolve-duplicate-matches.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 { MigrationSourceService } from './migration-source.service';
+import { MigrationProfileService } from './migration-profile.service';
 import { MigrationService } from './migration.service';
 
 @Controller('migration')
 @RequirePermission(Permission.ManageAppSettings)
 export class MigrationController {
-  constructor(private readonly service: MigrationService) {}
+  constructor(
+    private readonly sourceService: MigrationSourceService,
+    private readonly profileService: MigrationProfileService,
+    private readonly runService: MigrationService,
+  ) {}
 
   @Get('supported-types')
   listSupportedTypes() {
-    return this.service.listSupportedSourceTypes();
+    return this.sourceService.listSupportedSourceTypes();
   }
 
   @Post('sources/test')
   testSource(@Body() dto: TestMigrationSourceDto) {
-    return this.service.testSource(dto);
+    return this.sourceService.testSource(dto);
   }
 
   @Get('state')
   getWorkflowState() {
-    return this.service.getWorkflowState();
+    return this.runService.getWorkflowState();
   }
 
   @Get('target-users')
   listTargetUsers() {
-    return this.service.listTargetUsers();
+    return this.profileService.listTargetUsers();
   }
 
   @Post('sources')
   createSource(@Body() dto: CreateMigrationSourceDto, @CurrentUser() user: RequestUser) {
-    return this.service.createSource(dto, user.id);
+    return this.sourceService.createSource(dto, user.id);
   }
 
   @Post('sources/:id/validate')
   @HttpCode(HttpStatus.OK)
   validateSourceById(@Param('id', ParseIntPipe) sourceId: number) {
-    return this.service.validateSourceById(sourceId);
+    return this.sourceService.validateSourceById(sourceId);
   }
 
   @Get('sources/:id/path-prefixes')
   getSourcePathPrefixes(@Param('id', ParseIntPipe) sourceId: number) {
-    return this.service.getSourcePathPrefixes(sourceId);
+    return this.sourceService.getSourcePathPrefixes(sourceId);
   }
 
   @Get('sources/:id/user-mapping-suggestions')
   suggestUserMappings(@Param('id', ParseIntPipe) sourceId: number) {
-    return this.service.suggestUserMappings(sourceId);
+    return this.profileService.suggestUserMappings(sourceId);
   }
 
   @Post('sources/:id/path-mappings/validate')
   validatePathMappings(@Param('id', ParseIntPipe) sourceId: number, @Body() dto: ValidatePathMappingsDto) {
-    return this.service.validatePathMappings(sourceId, dto);
+    return this.profileService.validatePathMappings(sourceId, dto);
   }
 
   @Post('profiles')
   createProfile(@Body() dto: CreateMigrationProfileDto, @CurrentUser() user: RequestUser) {
-    return this.service.createProfile(dto, user.id);
+    return this.profileService.createProfile(dto, user.id);
   }
 
   @Post('plans/dry-run')
   createDryRunPlan(@Body() dto: CreateDryRunPlanDto, @CurrentUser() user: RequestUser) {
-    return this.service.createDryRunPlan(dto, user.id);
+    return this.runService.createDryRunPlan(dto, user.id);
+  }
+
+  @Post('plans/:id/resolve-duplicates')
+  @HttpCode(HttpStatus.OK)
+  resolveDuplicateMatches(@Param('id', ParseIntPipe) artifactId: number, @Body() dto: ResolveDuplicateMatchesDto) {
+    return this.runService.resolveDuplicateMatches(artifactId, dto);
   }
 
   @Post('runs/live')
   startLiveRun(@Body() dto: StartLiveRunDto, @CurrentUser() user: RequestUser) {
-    return this.service.startLiveRun(dto, user.id);
+    return this.runService.startLiveRun(dto, user.id);
+  }
+
+  @Post('runs/:id/cancel')
+  @HttpCode(HttpStatus.OK)
+  cancelRun(@Param('id', ParseIntPipe) runId: number) {
+    return this.runService.cancelRun(runId);
+  }
+
+  @Post('runs/:id/retry')
+  @HttpCode(HttpStatus.OK)
+  retryRun(@Param('id', ParseIntPipe) runId: number) {
+    return this.runService.retryFailedRun(runId);
   }
 
   @Get('runs/:id/progress')
   getRunProgress(@Param('id', ParseIntPipe) runId: number) {
-    return this.service.getRunProgress(runId);
+    return this.runService.getRunProgress(runId);
   }
 
   @Get('runs/:id/report')
   getRunReport(@Param('id', ParseIntPipe) runId: number) {
-    return this.service.getRunReport(runId);
+    return this.runService.getRunReport(runId);
   }
 
   @Get('runs/:id/report/export')
-  exportRunReport(@Param('id', ParseIntPipe) runId: number, @Query('format') format?: string) {
-    return this.service.exportRunReport(runId, format);
+  async exportRunReport(@Param('id', ParseIntPipe) runId: number, @Query('format') format: string | undefined, @Res() reply: FastifyReply) {
+    const result = await this.runService.exportRunReport(runId, format);
+    return reply
+      .header('Content-Type', result.contentType)
+      .header('Content-Disposition', `attachment; filename="${result.fileName}"`)
+      .send(result.content);
   }
 }
diff --git a/server/src/modules/migration/migration.module.test.ts b/server/src/modules/migration/migration.module.test.ts
index 2c75cb565..9124decf2 100644
--- a/server/src/modules/migration/migration.module.test.ts
+++ b/server/src/modules/migration/migration.module.test.ts
@@ -1,9 +1,13 @@
 import { MODULE_METADATA } from '@nestjs/common/constants';
 
 import { MigrationController } from './migration.controller';
+import { MigrationProgressGateway } from './migration-progress.gateway';
 import { MigrationModule } from './migration.module';
 import { MigrationRepository } from './migration.repository';
+import { MigrationSourceService } from './migration-source.service';
+import { MigrationProfileService } from './migration-profile.service';
 import { MigrationService } from './migration.service';
+import { MigrationEncryptionService } from './core/migration-encryption.service';
 import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
 import { MigrationPlannerService } from './planner/planner.service';
 import { PathMappingValidationService } from './planner/path-mapping-validation.service';
@@ -20,12 +24,16 @@ describe('MigrationModule', () => {
     expect(providers).toEqual(
       expect.arrayContaining([
         MigrationRepository,
+        MigrationEncryptionService,
         SourceAdapterRegistry,
         MigrationPlannerService,
         PathMappingValidationService,
         MigrationExecutorService,
         MigrationReportingService,
+        MigrationSourceService,
+        MigrationProfileService,
         MigrationService,
+        MigrationProgressGateway,
       ]),
     );
     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
index 077a0ce6e..128705f22 100644
--- a/server/src/modules/migration/migration.module.ts
+++ b/server/src/modules/migration/migration.module.ts
@@ -1,30 +1,60 @@
 import { Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtModule } from '@nestjs/jwt';
+import type { StringValue } from 'ms';
 
+import { AuthModule } from '../auth/auth.module';
 import { MigrationController } from './migration.controller';
+import { MigrationProgressGateway } from './migration-progress.gateway';
 import { MigrationRepository } from './migration.repository';
+import { MigrationSourceService } from './migration-source.service';
+import { MigrationProfileService } from './migration-profile.service';
 import { MigrationService } from './migration.service';
+import { MigrationEncryptionService } from './core/migration-encryption.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 { MigrationImportRepository } from './executor/migration-import.repository';
+import { SharedOverlaysImporter } from './executor/shared-overlays.importer';
+import { CoverImporter } from './executor/cover.importer';
+import { UserStateImporter } from './executor/user-state.importer';
 import { MigrationExecutorService } from './executor/migration-executor.service';
 import { MigrationReportingService } from './reporting/migration-reporting.service';
 
 @Module({
+  imports: [
+    AuthModule,
+    JwtModule.registerAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.getOrThrow<string>('auth.jwtSecret'),
+        signOptions: { expiresIn: config.getOrThrow<StringValue | number>('auth.jwtExpiresIn') },
+      }),
+    }),
+  ],
   controllers: [MigrationController],
   providers: [
     MigrationRepository,
+    MigrationImportRepository,
+    MigrationEncryptionService,
     BookloreConnector,
     BookloreSourceAdapter,
     SourceAdapterRegistry,
     MatchingService,
     MigrationPlannerService,
     PathMappingValidationService,
+    SharedOverlaysImporter,
+    CoverImporter,
+    UserStateImporter,
     MigrationExecutorService,
     MigrationReportingService,
+    MigrationSourceService,
+    MigrationProfileService,
     MigrationService,
+    MigrationProgressGateway,
   ],
   exports: [MigrationRepository, MigrationService],
 })
diff --git a/server/src/modules/migration/migration.repository.ts b/server/src/modules/migration/migration.repository.ts
index 61c24210b..c7effa1a4 100644
--- a/server/src/modules/migration/migration.repository.ts
+++ b/server/src/modules/migration/migration.repository.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, inArray, notInArray, sql } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 import { DB } from '../../db';
@@ -93,21 +93,39 @@ export class MigrationRepository {
       .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;
+  async createProfile(values: Pick<schema.NewMigrationProfile, 'sourceId' | 'name' | 'userMappings' | 'pathMappings' | 'scope' | 'createdByUserId'>) {
+    return this.db.transaction(async (tx) => {
+      const [versionRow] = await tx.select({ maxVersion: sql<number>`COALESCE(MAX(version), 0)` }).from(
+        tx
+          .select({ version: schema.migrationProfiles.version })
+          .from(schema.migrationProfiles)
+          .where(and(eq(schema.migrationProfiles.sourceId, values.sourceId), eq(schema.migrationProfiles.name, values.name)))
+          .for('update')
+          .as('locked'),
+      );
+
+      const nextVersion = (versionRow?.maxVersion ?? 0) + 1;
+      const [row] = await tx
+        .insert(schema.migrationProfiles)
+        .values({ ...values, version: nextVersion })
+        .returning();
+      return row;
+    });
   }
 
   findProfileById(id: number) {
     return this.db.query.migrationProfiles.findFirst({ where: eq(schema.migrationProfiles.id, id) });
   }
 
+  async updateProfileScope(id: number, scope: unknown) {
+    const [row] = await this.db.update(schema.migrationProfiles).set({ scope }).where(eq(schema.migrationProfiles.id, id)).returning();
+    return row ?? null;
+  }
+
   async createPlanArtifact(
     values: Pick<
       schema.NewMigrationPlanArtifact,
-      'sourceId' | 'profileId' | 'sourceSnapshotHash' | 'profileHash' | 'planHash' | 'plan' | 'summary' | 'createdByUserId'
+      'sourceId' | 'profileId' | 'sourceSnapshotHash' | 'profileHash' | 'planHash' | 'plan' | 'sourceData' | 'summary' | 'createdByUserId'
     >,
   ) {
     const [row] = await this.db.insert(schema.migrationPlanArtifacts).values(values).returning();
@@ -129,9 +147,34 @@ export class MigrationRepository {
     return this.db.query.migrationPlanArtifacts.findFirst({ where: eq(schema.migrationPlanArtifacts.id, id) });
   }
 
+  async updatePlanArtifact(id: number, values: { plan: unknown; sourceData?: unknown; summary: unknown }) {
+    const [row] = await this.db
+      .update(schema.migrationPlanArtifacts)
+      .set({ plan: values.plan, sourceData: values.sourceData, summary: values.summary })
+      .where(eq(schema.migrationPlanArtifacts.id, id))
+      .returning();
+    return row;
+  }
+
   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));
+    await this.db
+      .delete(schema.migrationRuns)
+      .where(and(eq(schema.migrationRuns.sourceId, sourceId), sql`${schema.migrationRuns.state} != 'completed'`));
+
+    const completedRuns = await this.db
+      .select({ planArtifactId: schema.migrationRuns.planArtifactId })
+      .from(schema.migrationRuns)
+      .where(and(eq(schema.migrationRuns.sourceId, sourceId), eq(schema.migrationRuns.state, 'completed')));
+    const retainedArtifactIds = completedRuns.map((row) => row.planArtifactId).filter((id): id is number => id != null);
+
+    if (retainedArtifactIds.length === 0) {
+      await this.db.delete(schema.migrationPlanArtifacts).where(eq(schema.migrationPlanArtifacts.sourceId, sourceId));
+      return;
+    }
+
+    await this.db
+      .delete(schema.migrationPlanArtifacts)
+      .where(and(eq(schema.migrationPlanArtifacts.sourceId, sourceId), notInArray(schema.migrationPlanArtifacts.id, retainedArtifactIds)));
   }
 
   async findBookTitlesByIds(ids: number[]): Promise<Map<number, string | null>> {
@@ -151,24 +194,20 @@ export class MigrationRepository {
   ): 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)}))`);
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${buildRunLockKey()}))`);
 
       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),
-          ),
-        )
+        .where(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));
+      await tx
+        .delete(schema.migrationRuns)
+        .where(and(eq(schema.migrationRuns.sourceId, values.sourceId), sql`${schema.migrationRuns.state} != 'completed'`));
 
       const [run] = await tx
         .insert(schema.migrationRuns)
@@ -202,54 +241,52 @@ export class MigrationRepository {
     return row ?? null;
   }
 
-  async incrementRunMetric(
+  async setRunMetric(
     runId: number,
     stage: string,
     entityType: string,
-    delta: Partial<Pick<typeof schema.migrationRunMetrics.$inferInsert, 'processed' | 'imported' | 'skipped' | 'unresolved' | 'failed'>>,
+    values: 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()`,
+    const [row] = await this.db
+      .insert(schema.migrationRunMetrics)
+      .values({
+        runId,
+        stage,
+        entityType,
+        processed: values.processed ?? 0,
+        imported: values.imported ?? 0,
+        skipped: values.skipped ?? 0,
+        unresolved: values.unresolved ?? 0,
+        failed: values.failed ?? 0,
+      })
+      .onConflictDoUpdate({
+        target: [schema.migrationRunMetrics.runId, schema.migrationRunMetrics.stage, schema.migrationRunMetrics.entityType],
+        set: {
+          processed: sql`excluded.processed`,
+          imported: sql`excluded.imported`,
+          skipped: sql`excluded.skipped`,
+          unresolved: sql`excluded.unresolved`,
+          failed: sql`excluded.failed`,
+          updatedAt: sql`now()`,
+        },
       })
-      .where(eq(schema.migrationRunMetrics.id, existing.id))
       .returning();
-    return updated;
+    return row;
+  }
+
+  async clearStageMetrics(runId: number, stage: string): Promise<void> {
+    await this.db
+      .delete(schema.migrationRunMetrics)
+      .where(and(eq(schema.migrationRunMetrics.runId, runId), eq(schema.migrationRunMetrics.stage, stage)));
+  }
+
+  async hasStageMetrics(runId: number, stage: string): Promise<boolean> {
+    const rows = await this.db
+      .select({ id: schema.migrationRunMetrics.id })
+      .from(schema.migrationRunMetrics)
+      .where(and(eq(schema.migrationRunMetrics.runId, runId), eq(schema.migrationRunMetrics.stage, stage)))
+      .limit(1);
+    return rows.length > 0;
   }
 
   listRunMetrics(runId: number) {
@@ -261,6 +298,6 @@ export class MigrationRepository {
   }
 }
 
-function buildRunLockKey(sourceId: number, targetKey: string): string {
-  return `migration-run-lock:${sourceId}:${targetKey}`;
+function buildRunLockKey(): string {
+  return 'migration-run-lock:global';
 }
diff --git a/server/src/modules/migration/migration.service.test.ts b/server/src/modules/migration/migration.service.test.ts
index 936f80be1..205e3670a 100644
--- a/server/src/modules/migration/migration.service.test.ts
+++ b/server/src/modules/migration/migration.service.test.ts
@@ -1,8 +1,14 @@
-import { BadRequestException, ConflictException } from '@nestjs/common';
+import { BadRequestException, ConflictException, InternalServerErrorException, NotFoundException } from '@nestjs/common';
 import { describe, expect, it, vi } from 'vitest';
 
 import { MigrationService } from './migration.service';
 
+const noopEncryption = {
+  encryptConfig: (c: Record<string, unknown>) => c,
+  decryptConfig: (c: unknown) => c as Record<string, unknown>,
+  isConfigured: () => false,
+} as never;
+
 function createService(overrides: Partial<Record<string, unknown>> = {}): MigrationService {
   const repo = {
     findSourceById: vi.fn(() =>
@@ -29,7 +35,6 @@ function createService(overrides: Partial<Record<string, unknown>> = {}): Migrat
       ]),
     ),
     listProfiles: vi.fn(() => Promise.resolve([])),
-    createProfile: vi.fn(),
     findProfileById: vi.fn(() =>
       Promise.resolve({
         id: 2,
@@ -45,6 +50,9 @@ function createService(overrides: Partial<Record<string, unknown>> = {}): Migrat
       }),
     ),
     listRuns: vi.fn(() => Promise.resolve([])),
+    listSources: vi.fn(() => Promise.resolve([])),
+    findRunById: vi.fn(),
+    updateRunState: vi.fn(),
     findPlanArtifactById: vi.fn(() =>
       Promise.resolve({
         id: 100,
@@ -81,36 +89,20 @@ function createService(overrides: Partial<Record<string, unknown>> = {}): Migrat
       }),
     ),
     purgeRunState: vi.fn(() => Promise.resolve()),
+    listPlanArtifacts: 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,
+    noopEncryption,
   );
 }
 
 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();
 
@@ -166,6 +158,7 @@ describe('MigrationService', () => {
       planArtifactId: 100,
       state: 'running',
       currentStage: 'init',
+      targetKey: 'projectx',
       startedAt: run.startedAt,
       endedAt: null,
       errorMessage: null,
@@ -195,57 +188,461 @@ describe('MigrationService', () => {
     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,
+  describe('cancelRun', () => {
+    it('cancels a running migration', async () => {
+      const updatedRun = {
+        id: 77,
         sourceId: 1,
-        name: 'Booklore Migration',
-        version: 4,
-        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
-        pathMappings: [],
-        scope: {},
-        createdByUserId: 1,
+        profileId: 2,
+        planArtifactId: 100,
+        targetKey: 'projectx',
+        state: 'failed',
+        currentStage: 'cancelled',
+        triggeredByUserId: 1,
+        startedAt: new Date(),
+        endedAt: new Date(),
+        errorMessage: 'Migration cancelled by user',
         createdAt: new Date(),
         updatedAt: new Date(),
-      }),
-    );
-    const service = createService({
-      listProfiles: vi.fn(() =>
-        Promise.resolve([
-          {
-            id: 2,
+      };
+      const service = createService({
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
             sourceId: 1,
-            name: 'Booklore Migration',
-            version: 3,
-            userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
-            pathMappings: [],
-            scope: {},
-            createdByUserId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            state: 'running',
+            currentStage: 'shared_overlays',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: null,
+            errorMessage: null,
             createdAt: new Date(),
             updatedAt: new Date(),
-          },
-        ]),
-      ),
-      createProfile,
+          }),
+        ),
+        updateRunState: vi.fn(() => Promise.resolve(updatedRun)),
+      });
+
+      const result = await service.cancelRun(77);
+      expect(result.state).toBe('failed');
+      expect(result.currentStage).toBe('cancelled');
+      expect(result.errorMessage).toBe('Migration cancelled by user');
     });
 
-    await service.createProfile(
-      {
-        sourceId: 1,
-        name: 'Booklore Migration',
-        userMappings: [{ sourceUserId: 'src-user', targetUserId: 10 }],
-        pathMappings: [],
-      },
-      1,
-    );
+    it('throws NotFoundException for missing run', async () => {
+      const service = createService({
+        findRunById: vi.fn(() => Promise.resolve(undefined)),
+      });
 
-    expect(createProfile).toHaveBeenCalledWith(
-      expect.objectContaining({
+      await expect(service.cancelRun(999)).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('throws BadRequestException for non-running run', async () => {
+      const service = createService({
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
+            state: 'completed',
+            sourceId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            currentStage: 'completed',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: new Date(),
+            errorMessage: null,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }),
+        ),
+      });
+
+      await expect(service.cancelRun(77)).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('throws InternalServerErrorException when update fails', async () => {
+      const service = createService({
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
+            state: 'running',
+            sourceId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            currentStage: 'init',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: null,
+            errorMessage: null,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }),
+        ),
+        updateRunState: vi.fn(() => Promise.resolve(null)),
+      });
+
+      await expect(service.cancelRun(77)).rejects.toBeInstanceOf(InternalServerErrorException);
+    });
+  });
+
+  it('rejects live run start when duplicate book matches exist', async () => {
+    const service = createService({
+      findPlanArtifactById: vi.fn(() =>
+        Promise.resolve({
+          id: 100,
+          sourceId: 1,
+          profileId: 2,
+          sourceSnapshotHash: 'a',
+          profileHash: 'b',
+          planHash: 'd',
+          plan: { duplicateBookMatches: [{ targetBookId: 1, sourceBookIds: ['a', 'b'] }] },
+          summary: {},
+          createdByUserId: 1,
+          createdAt: new Date(Date.now() + 1000),
+          updatedAt: new Date(),
+        }),
+      ),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects live run when source has never been validated', async () => {
+    const service = createService({
+      findSourceById: vi.fn(() =>
+        Promise.resolve({
+          id: 1,
+          type: 'booklore',
+          name: 'Booklore',
+          connectionConfig: {},
+          capabilities: null,
+          lastValidatedAt: null,
+          createdByUserId: 1,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        }),
+      ),
+      findPlanArtifactById: vi.fn(() =>
+        Promise.resolve({
+          id: 100,
+          sourceId: 1,
+          profileId: 2,
+          plan: {},
+          summary: {},
+          createdByUserId: 1,
+          createdAt: new Date(Date.now() + 1000),
+          updatedAt: new Date(),
+        }),
+      ),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects live run when dry-run plan is stale', async () => {
+    const now = new Date();
+    const service = createService({
+      findSourceById: vi.fn(() =>
+        Promise.resolve({
+          id: 1,
+          type: 'booklore',
+          name: 'Booklore',
+          connectionConfig: {},
+          capabilities: null,
+          lastValidatedAt: now,
+          createdByUserId: 1,
+          createdAt: now,
+          updatedAt: new Date(now.getTime() + 5000),
+        }),
+      ),
+      findPlanArtifactById: vi.fn(() =>
+        Promise.resolve({
+          id: 100,
+          sourceId: 1,
+          profileId: 2,
+          plan: {},
+          summary: {},
+          createdByUserId: 1,
+          createdAt: new Date(now.getTime() - 10000),
+          updatedAt: now,
+        }),
+      ),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it('rejects live run when target users no longer exist', async () => {
+    const service = createService({
+      findPlanArtifactById: vi.fn(() =>
+        Promise.resolve({
+          id: 100,
+          sourceId: 1,
+          profileId: 2,
+          plan: {},
+          summary: {},
+          createdByUserId: 1,
+          createdAt: new Date(Date.now() + 1000),
+          updatedAt: new Date(),
+        }),
+      ),
+      findProfileById: vi.fn(() =>
+        Promise.resolve({
+          id: 2,
+          sourceId: 1,
+          name: 'Booklore Migration',
+          version: 1,
+          userMappings: [{ sourceUserId: 'src-user', targetUserId: 999 }],
+          pathMappings: [],
+          scope: { preflight: { pathValidatedAt: new Date().toISOString() } },
+          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' }]),
+      ),
+    });
+
+    await expect(service.startLiveRun({ planArtifactId: 100, targetKey: 'projectx' }, 1)).rejects.toThrow('Target users no longer exist');
+  });
+
+  describe('retryFailedRun', () => {
+    it('retries a failed run by resetting state to running', async () => {
+      const startFn = vi.fn();
+      const updatedRun = {
+        id: 77,
         sourceId: 1,
-        name: 'Booklore Migration',
-        version: 4,
-      }),
-    );
+        profileId: 2,
+        planArtifactId: 100,
+        targetKey: 'projectx',
+        state: 'running',
+        currentStage: 'user_state',
+        triggeredByUserId: 1,
+        startedAt: new Date(),
+        endedAt: null,
+        errorMessage: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const service = createService({
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
+            sourceId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            state: 'failed',
+            currentStage: 'user_state',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: new Date(),
+            errorMessage: 'Connection lost',
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }),
+        ),
+        updateRunState: vi.fn(() => Promise.resolve(updatedRun)),
+      });
+
+      (service as any).executor = { start: startFn };
+
+      const result = await service.retryFailedRun(77);
+      expect(result.state).toBe('running');
+      expect(result.errorMessage).toBeNull();
+      expect(startFn).toHaveBeenCalledWith(77);
+    });
+
+    it('throws NotFoundException for missing run', async () => {
+      const service = createService({
+        findRunById: vi.fn(() => Promise.resolve(undefined)),
+      });
+
+      await expect(service.retryFailedRun(999)).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('throws BadRequestException for non-failed run', async () => {
+      const service = createService({
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
+            state: 'running',
+            sourceId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            currentStage: 'shared_overlays',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: null,
+            errorMessage: null,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }),
+        ),
+      });
+
+      await expect(service.retryFailedRun(77)).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('throws ConflictException when another run is already active', async () => {
+      const service = createService({
+        listRuns: vi.fn(() =>
+          Promise.resolve([
+            {
+              id: 88,
+              state: 'running',
+              sourceId: 1,
+              profileId: 2,
+            },
+          ]),
+        ),
+        findRunById: vi.fn(() =>
+          Promise.resolve({
+            id: 77,
+            state: 'failed',
+            sourceId: 1,
+            profileId: 2,
+            planArtifactId: 100,
+            targetKey: 'projectx',
+            currentStage: 'user_state',
+            triggeredByUserId: 1,
+            startedAt: new Date(),
+            endedAt: new Date(),
+            errorMessage: 'error',
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }),
+        ),
+      });
+
+      await expect(service.retryFailedRun(77)).rejects.toBeInstanceOf(ConflictException);
+    });
+  });
+
+  describe('resolveDuplicateMatches', () => {
+    const duplicatePlanArtifact = {
+      id: 100,
+      sourceId: 1,
+      profileId: 2,
+      sourceSnapshotHash: 'a',
+      profileHash: 'b',
+      planHash: 'd',
+      plan: {
+        matchedBooks: [{ sourceBookId: 'sb1', targetBookId: 1, strategy: 'isbn' }],
+        unresolvedBooks: [{ sourceBookId: 'sb99', title: null, reason: 'no_isbn_match' }],
+        duplicateBookMatches: [
+          { targetBookId: 5, sourceBookIds: ['sb10', 'sb11'], strategies: ['isbn', 'title_author'], reason: 'duplicate_target_match' },
+          {
+            targetBookId: 6,
+            sourceBookIds: ['sb20', 'sb21', 'sb22'],
+            strategies: ['file_hash', 'file_hash', 'title_author'],
+            reason: 'duplicate_target_match',
+          },
+        ],
+      },
+      sourceData: null,
+      summary: {
+        status: 'blocked',
+        matchedBooks: 1,
+        unresolvedBooks: 1,
+        duplicateBookMatches: 2,
+      },
+      createdByUserId: 1,
+      createdAt: new Date(Date.now() + 1000),
+      updatedAt: new Date(),
+    };
+
+    it('resolves duplicate matches by moving selected to matched and others to unresolved', async () => {
+      const updateFn = vi.fn((id: number, vals: { plan: unknown; summary: unknown }) => {
+        return Promise.resolve({ ...duplicatePlanArtifact, id, plan: vals.plan, summary: vals.summary });
+      });
+      const service = createService({
+        findPlanArtifactById: vi.fn(() => Promise.resolve({ ...duplicatePlanArtifact })),
+        updatePlanArtifact: updateFn,
+      });
+
+      const result = await service.resolveDuplicateMatches(100, {
+        resolutions: [
+          { targetBookId: 5, selectedSourceBookId: 'sb10' },
+          { targetBookId: 6, selectedSourceBookId: 'sb22' },
+        ],
+      });
+
+      expect(updateFn).toHaveBeenCalledOnce();
+      const updatedPlan = (updateFn.mock.calls as unknown[][])[0][1] as { plan: Record<string, unknown>; summary: Record<string, unknown> };
+      const plan = updatedPlan.plan as Record<string, unknown>;
+      const matchedBooks = plan.matchedBooks as Array<{ sourceBookId: string; targetBookId: number }>;
+      const unresolvedBooks = plan.unresolvedBooks as Array<{ sourceBookId: string }>;
+      const duplicateBookMatches = plan.duplicateBookMatches as unknown[];
+
+      expect(matchedBooks).toHaveLength(3);
+      expect(matchedBooks.find((m) => m.sourceBookId === 'sb10' && m.targetBookId === 5)).toBeTruthy();
+      expect(matchedBooks.find((m) => m.sourceBookId === 'sb22' && m.targetBookId === 6)).toBeTruthy();
+
+      expect(unresolvedBooks).toHaveLength(4);
+      expect(unresolvedBooks.find((u) => u.sourceBookId === 'sb11')).toBeTruthy();
+      expect(unresolvedBooks.find((u) => u.sourceBookId === 'sb20')).toBeTruthy();
+      expect(unresolvedBooks.find((u) => u.sourceBookId === 'sb21')).toBeTruthy();
+
+      expect(duplicateBookMatches).toHaveLength(0);
+      expect(result.summary?.status).toBe('ready_for_live_run');
+      expect(result.summary?.duplicateBookMatches).toBe(0);
+    });
+
+    it('throws NotFoundException for missing artifact', async () => {
+      const service = createService({
+        findPlanArtifactById: vi.fn(() => Promise.resolve(undefined)),
+      });
+      await expect(service.resolveDuplicateMatches(999, { resolutions: [{ targetBookId: 1, selectedSourceBookId: 'sb1' }] })).rejects.toBeInstanceOf(
+        NotFoundException,
+      );
+    });
+
+    it('throws BadRequestException when no duplicates exist', async () => {
+      const service = createService({
+        findPlanArtifactById: vi.fn(() =>
+          Promise.resolve({
+            ...duplicatePlanArtifact,
+            plan: { ...duplicatePlanArtifact.plan, duplicateBookMatches: [] },
+          }),
+        ),
+      });
+      await expect(service.resolveDuplicateMatches(100, { resolutions: [{ targetBookId: 5, selectedSourceBookId: 'sb10' }] })).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+    });
+
+    it('throws BadRequestException when selected source book is not in the group', async () => {
+      const service = createService({
+        findPlanArtifactById: vi.fn(() => Promise.resolve({ ...duplicatePlanArtifact })),
+      });
+      await expect(
+        service.resolveDuplicateMatches(100, {
+          resolutions: [
+            { targetBookId: 5, selectedSourceBookId: 'sb99' },
+            { targetBookId: 6, selectedSourceBookId: 'sb22' },
+          ],
+        }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('throws BadRequestException when not all groups are resolved', async () => {
+      const service = createService({
+        findPlanArtifactById: vi.fn(() => Promise.resolve({ ...duplicatePlanArtifact })),
+      });
+      await expect(
+        service.resolveDuplicateMatches(100, {
+          resolutions: [{ targetBookId: 5, selectedSourceBookId: 'sb10' }],
+        }),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
   });
 });
diff --git a/server/src/modules/migration/migration.service.ts b/server/src/modules/migration/migration.service.ts
index 23d66a83a..d1e60c943 100644
--- a/server/src/modules/migration/migration.service.ts
+++ b/server/src/modules/migration/migration.service.ts
@@ -1,268 +1,49 @@
-import { BadRequestException, ConflictException, Injectable, InternalServerErrorException, NotFoundException } from '@nestjs/common';
+import { BadRequestException, ConflictException, Injectable, InternalServerErrorException, Logger, NotFoundException } from '@nestjs/common';
 
+import type { MigrationSource, MigrationProfile, MigrationPlanArtifact, MigrationRun } from '../../db/schema';
 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 type { ResolveDuplicateMatchesDto } from './dto/resolve-duplicate-matches.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 { buildPathMappingsHash, buildPlanHash, buildProfileHash, buildSourceSnapshotHash } from './core/plan-hash';
+import { asInteger, asRecord, asString } from './core/coerce';
+import {
+  type ApiMigrationRun,
+  sanitizeSourceForApi,
+  sanitizeProfileForApi,
+  sanitizePlanArtifactForApi,
+  sanitizeRunForApi,
+} from './core/api-sanitizers';
+import { MigrationEncryptionService } from './core/migration-encryption.service';
 import { MigrationRepository } from './migration.repository';
-import { SourceAdapterRegistry } from './adapters/source-adapter.registry';
-import { MigrationPlannerService } from './planner/planner.service';
+import { buildUserPreview, MigrationPlannerService } from './planner/planner.service';
+import type { SourceExportData } from './adapters/source-adapter.types';
+import type { MatchStrategy, PlannedBookMatch } from './planner/planner.types';
 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';
+
+export type { ApiMigrationSource, ApiMigrationProfile, ApiMigrationPlanArtifact, ApiMigrationRun } from './core/api-sanitizers';
 
 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;
+  source: MigrationSource;
+  profile: MigrationProfile | null;
+  plan: MigrationPlanArtifact | null;
+  run: MigrationRun | null;
 }
 
 @Injectable()
 export class MigrationService {
+  private readonly logger = new Logger(MigrationService.name);
+
   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,
+    private readonly encryption: MigrationEncryptionService,
   ) {}
 
-  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();
 
@@ -275,7 +56,7 @@ export class MigrationService {
     await this.repo.purgeRunState(source.id);
 
     const planned = await this.planner.buildPlan({
-      source,
+      source: this.withDecryptedConfig(source),
       profile,
       scopeOverride: dto.scopeOverride,
     });
@@ -283,6 +64,8 @@ export class MigrationService {
     const sourceSnapshotHash = buildSourceSnapshotHash(planned.plan.snapshot);
     const profileHash = buildProfileHash(profile);
     const planHash = buildPlanHash({ sourceSnapshotHash, profileHash, plan: planned.plan });
+    const planSizeBytes = jsonByteLength(planned.plan);
+    const sourceDataSizeBytes = jsonByteLength(planned.execution.sourceData);
 
     const summary = {
       generatedAt: planned.plan.generatedAt,
@@ -296,6 +79,11 @@ export class MigrationService {
       }, {}),
       mappedUsers: planned.plan.userPreview.length,
       perUserPreview: planned.plan.userPreview,
+      artifactSizeBytes: {
+        plan: planSizeBytes,
+        sourceData: sourceDataSizeBytes,
+        total: planSizeBytes + sourceDataSizeBytes,
+      },
     };
 
     const artifact = await this.repo.createPlanArtifact({
@@ -305,12 +93,102 @@ export class MigrationService {
       profileHash,
       planHash,
       plan: planned.plan,
+      sourceData: planned.execution.sourceData,
       summary,
       createdByUserId: userId,
     });
     return sanitizePlanArtifactForApi(artifact);
   }
 
+  async resolveDuplicateMatches(artifactId: number, dto: ResolveDuplicateMatchesDto) {
+    const artifact = await this.repo.findPlanArtifactById(artifactId);
+    if (!artifact) throw new NotFoundException(`Migration plan artifact not found: ${artifactId}`);
+
+    const plan = asRecord(artifact.plan);
+    const duplicates: Array<{
+      targetBookId: number;
+      matches?: PlannedBookMatch[];
+      sourceBookIds: string[];
+      strategies: MatchStrategy[];
+      reason: string;
+    }> = Array.isArray(plan.duplicateBookMatches) ? plan.duplicateBookMatches : [];
+
+    if (duplicates.length === 0) {
+      throw new BadRequestException('No duplicate matches to resolve.');
+    }
+
+    const dupMap = new Map(duplicates.map((d) => [d.targetBookId, d]));
+    const matchedBooks: PlannedBookMatch[] = Array.isArray(plan.matchedBooks) ? ([...plan.matchedBooks] as PlannedBookMatch[]) : [];
+    const unresolvedBooks: unknown[] = Array.isArray(plan.unresolvedBooks) ? [...plan.unresolvedBooks] : [];
+    const sourceData = artifact.sourceData as SourceExportData | null;
+    const sourceBooksById = new Map(sourceData?.books.map((book) => [book.sourceBookId, book]) ?? []);
+    const resolved = new Set<number>();
+
+    for (const resolution of dto.resolutions) {
+      const dup = dupMap.get(resolution.targetBookId);
+      if (!dup) {
+        throw new BadRequestException(`No duplicate match found for target book ${resolution.targetBookId}.`);
+      }
+      const dupMatches = normalizeDuplicateMatches(dup);
+      if (!dupMatches.some((match) => match.sourceBookId === resolution.selectedSourceBookId)) {
+        throw new BadRequestException(
+          `Source book ${resolution.selectedSourceBookId} is not in the duplicate group for target book ${resolution.targetBookId}.`,
+        );
+      }
+
+      const winnerStrategy = dupMatches.find((match) => match.sourceBookId === resolution.selectedSourceBookId)?.strategy ?? 'title_author';
+      matchedBooks.push({
+        sourceBookId: resolution.selectedSourceBookId,
+        targetBookId: resolution.targetBookId,
+        strategy: winnerStrategy,
+      });
+
+      for (const duplicateMatch of dupMatches) {
+        if (duplicateMatch.sourceBookId !== resolution.selectedSourceBookId) {
+          unresolvedBooks.push({
+            sourceBookId: duplicateMatch.sourceBookId,
+            title: sourceBooksById.get(duplicateMatch.sourceBookId)?.title ?? null,
+            reason: 'duplicate_target_match',
+          });
+        }
+      }
+
+      resolved.add(resolution.targetBookId);
+    }
+
+    const remainingDuplicates = duplicates.filter((d) => !resolved.has(d.targetBookId));
+    if (remainingDuplicates.length > 0) {
+      throw new BadRequestException(`All duplicate groups must be resolved. Missing: ${remainingDuplicates.map((d) => d.targetBookId).join(', ')}`);
+    }
+
+    const userMappings = parsePlanUserMappings(plan.userMappings);
+    const matchedBookIds = new Set(matchedBooks.map((entry) => entry.sourceBookId));
+    const userPreview = sourceData ? buildUserPreview(sourceData, userMappings, matchedBookIds) : plan.userPreview;
+    const unresolvedByReason = summarizeUnresolvedByReason(unresolvedBooks);
+
+    const updatedPlan = { ...plan, matchedBooks, unresolvedBooks, duplicateBookMatches: [], userPreview };
+    const summary = asRecord(artifact.summary);
+    const updatedSummary = {
+      ...summary,
+      status: 'ready_for_live_run',
+      matchedBooks: matchedBooks.length,
+      unresolvedBooks: unresolvedBooks.length,
+      duplicateBookMatches: 0,
+      unresolvedByReason,
+      perUserPreview: userPreview,
+      mappedUsers: Array.isArray(userPreview) ? userPreview.length : summary.mappedUsers,
+    };
+
+    const updated = await this.repo.updatePlanArtifact(artifact.id, {
+      plan: updatedPlan,
+      sourceData: artifact.sourceData,
+      summary: updatedSummary,
+    });
+
+    this.logger.log(`[plan.resolve_duplicates] [end] artifactId=${artifactId} resolved=${resolved.size} - duplicates resolved`);
+    return sanitizePlanArtifactForApi(updated);
+  }
+
   async startLiveRun(dto: StartLiveRunDto, userId: number) {
     await this.assertNoGlobalActiveRun();
 
@@ -327,6 +205,11 @@ export class MigrationService {
     if (!source.lastValidatedAt) {
       throw new BadRequestException('Validate source before starting migration.');
     }
+    const sourceCapabilities = asRecord(source.capabilities);
+    if (sourceCapabilities.ok === false) {
+      const missingTables = Array.isArray(sourceCapabilities.missingTables) ? sourceCapabilities.missingTables.join(', ') : 'unknown';
+      throw new BadRequestException(`Source validation is not successful. Missing required tables: ${missingTables || 'unknown'}`);
+    }
 
     const profile = await this.repo.findProfileById(artifact.profileId);
     if (!profile) throw new NotFoundException(`Migration profile not found: ${artifact.profileId}`);
@@ -338,11 +221,22 @@ export class MigrationService {
       throw new BadRequestException('Save user mappings before starting migration.');
     }
 
+    const targetUserIds = profileMappings.map((m) => asInteger(asRecord(m).targetUserId)).filter((id): id is number => id !== null);
+    if (targetUserIds.length > 0) {
+      const existingUsers = await this.repo.listTargetUsersForMapping();
+      const existingIds = new Set(existingUsers.map((u) => u.id));
+      const missing = targetUserIds.filter((id) => !existingIds.has(id));
+      if (missing.length > 0) {
+        throw new BadRequestException(`Target users no longer exist: ${missing.join(', ')}. Update user mappings.`);
+      }
+    }
+
     const scope = asRecord(profile.scope);
     const preflightScope = asRecord(scope.preflight);
     const pathValidatedAt = asString(preflightScope.pathValidatedAt);
+    const pathMappingsHash = asString(preflightScope.pathMappingsHash);
     const pathMappings = Array.isArray(profile.pathMappings) ? profile.pathMappings : [];
-    if (pathMappings.length > 0 && !pathValidatedAt) {
+    if (pathMappings.length > 0 && (!pathValidatedAt || pathMappingsHash !== buildPathMappingsHash(pathMappings))) {
       throw new BadRequestException('Validate path mappings before starting migration.');
     }
 
@@ -364,7 +258,7 @@ export class MigrationService {
     });
     if (!run && activeRun) {
       throw new ConflictException(
-        `Another migration run is active for source=${artifact.sourceId} target=${targetKey} (runId=${activeRun.id}, state=${activeRun.state})`,
+        `Another migration run is active (runId=${activeRun.id}, source=${activeRun.sourceId}, target=${activeRun.targetKey}, state=${activeRun.state})`,
       );
     }
     if (!run) {
@@ -375,6 +269,49 @@ export class MigrationService {
     return sanitizeRunForApi(run);
   }
 
+  async cancelRun(runId: number): Promise<ApiMigrationRun> {
+    const run = await this.repo.findRunById(runId);
+    if (!run) throw new NotFoundException(`Migration run not found: ${runId}`);
+    if (run.state !== 'running') {
+      throw new BadRequestException(`Cannot cancel run in state "${run.state}" - only running migrations can be cancelled`);
+    }
+    const updated = await this.repo.updateRunState(runId, 'failed', {
+      currentStage: 'cancelled',
+      endedAt: new Date(),
+      errorMessage: 'Migration cancelled by user',
+    });
+    if (!updated) throw new InternalServerErrorException('Failed to cancel migration run');
+    return sanitizeRunForApi(updated);
+  }
+
+  async retryFailedRun(runId: number): Promise<ApiMigrationRun> {
+    await this.assertNoGlobalActiveRun();
+
+    const run = await this.repo.findRunById(runId);
+    if (!run) throw new NotFoundException(`Migration run not found: ${runId}`);
+    if (run.state !== 'failed') {
+      throw new BadRequestException(`Cannot retry run in state "${run.state}" - only failed migrations can be retried`);
+    }
+    if (!run.planArtifactId) {
+      throw new BadRequestException('Run is missing a plan artifact. Create a new dry-run plan.');
+    }
+
+    const source = await this.repo.findSourceById(run.sourceId);
+    if (!source) throw new NotFoundException(`Migration source no longer exists: ${run.sourceId}`);
+
+    const artifact = await this.repo.findPlanArtifactById(run.planArtifactId);
+    if (!artifact) throw new NotFoundException(`Plan artifact no longer exists: ${run.planArtifactId}`);
+
+    const updated = await this.repo.updateRunState(runId, 'running', {
+      endedAt: null,
+      errorMessage: null,
+    });
+    if (!updated) throw new InternalServerErrorException('Failed to reset migration run for retry');
+
+    this.executor.start(updated.id);
+    return sanitizeRunForApi(updated);
+  }
+
   getRunProgress(runId: number) {
     return this.reporting.getRunProgress(runId);
   }
@@ -403,7 +340,7 @@ export class MigrationService {
     return {
       active: activeBundle
         ? {
-            source: sanitizeSourceForApi(activeBundle.source),
+            source: sanitizeSourceForApi(this.withDecryptedConfig(activeBundle.source)),
             profile: activeBundle.profile ? sanitizeProfileForApi(activeBundle.profile) : null,
             plan: activeBundle.plan ? sanitizePlanArtifactForApi(activeBundle.plan) : null,
             run: activeBundle.run ? sanitizeRunForApi(activeBundle.run) : null,
@@ -414,10 +351,10 @@ export class MigrationService {
   }
 
   private resolveActiveBundle(
-    source: MigrationSourceRow | null,
-    profiles: Awaited<ReturnType<MigrationRepository['listProfiles']>>,
-    plans: Awaited<ReturnType<MigrationRepository['listPlanArtifacts']>>,
-    runs: Awaited<ReturnType<MigrationRepository['listRuns']>>,
+    source: MigrationSource | null,
+    profiles: MigrationProfile[],
+    plans: MigrationPlanArtifact[],
+    runs: MigrationRun[],
   ): WorkflowStateBundle | null {
     if (!source) return null;
     const profile = profiles.find((row) => row.sourceId === source.id) ?? null;
@@ -434,13 +371,53 @@ export class MigrationService {
     if (!active) return;
     throw new ConflictException(`Another migration run is active (runId=${active.id}, state=${active.state}).`);
   }
+
+  private withDecryptedConfig(source: MigrationSource): MigrationSource {
+    return { ...source, connectionConfig: this.encryption.decryptConfig(source.connectionConfig) };
+  }
 }
 
-function parseConnectionConfig(type: string, raw: unknown): unknown {
-  if (type === 'booklore') {
-    return parseBookloreConnectionConfig(raw);
+function normalizeDuplicateMatches(duplicate: {
+  targetBookId: number;
+  matches?: PlannedBookMatch[];
+  sourceBookIds: string[];
+  strategies: MatchStrategy[];
+}): PlannedBookMatch[] {
+  if (Array.isArray(duplicate.matches) && duplicate.matches.length > 0) {
+    return duplicate.matches.filter((match) => match.sourceBookId && Number.isFinite(match.targetBookId));
   }
-  return asRecord(raw);
+
+  return duplicate.sourceBookIds.map((sourceBookId, index) => ({
+    sourceBookId,
+    targetBookId: duplicate.targetBookId,
+    strategy: duplicate.strategies[index] ?? duplicate.strategies[0] ?? 'title_author',
+  }));
+}
+
+function parsePlanUserMappings(raw: unknown): Map<string, number> {
+  const out = new Map<string, number>();
+  if (!Array.isArray(raw)) return out;
+
+  for (const item of raw) {
+    const row = asRecord(item);
+    const sourceUserId = asString(row.sourceUserId);
+    const targetUserId = asInteger(row.targetUserId);
+    if (sourceUserId && targetUserId != null) out.set(sourceUserId, targetUserId);
+  }
+
+  return out;
+}
+
+function summarizeUnresolvedByReason(rows: unknown[]): Record<string, number> {
+  return rows.reduce<Record<string, number>>((acc, row) => {
+    const reason = asString(asRecord(row).reason);
+    if (reason) acc[reason] = (acc[reason] ?? 0) + 1;
+    return acc;
+  }, {});
+}
+
+function jsonByteLength(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
 }
 
 function normalizeTargetKey(value: string | undefined): string {
@@ -448,128 +425,6 @@ function normalizeTargetKey(value: string | undefined): string {
   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
index 1178d3cb0..cb3daf564 100644
--- a/server/src/modules/migration/planner/matching.service.test.ts
+++ b/server/src/modules/migration/planner/matching.service.test.ts
@@ -16,6 +16,27 @@ describe('applyPathMappings', () => {
     const mapped = applyPathMappings('/other/path/file.epub', [{ sourcePrefix: '/mnt/books', targetPrefix: '/library' }]);
     expect(mapped).toBe('/other/path/file.epub');
   });
+
+  it('returns null when filePath is null', () => {
+    expect(applyPathMappings(null, [{ sourcePrefix: '/mnt', targetPrefix: '/lib' }])).toBeNull();
+  });
+
+  it('handles empty mappings list', () => {
+    expect(applyPathMappings('/mnt/books/file.epub', [])).toBe('/mnt/books/file.epub');
+  });
+
+  it('strips trailing slash from prefixes', () => {
+    const mapped = applyPathMappings('/mnt/books/file.epub', [{ sourcePrefix: '/mnt/books/', targetPrefix: '/library/' }]);
+    expect(mapped).toBe('/library/file.epub');
+  });
+
+  it('skips mappings with empty prefixes', () => {
+    const mapped = applyPathMappings('/mnt/books/file.epub', [
+      { sourcePrefix: '', targetPrefix: '/library' },
+      { sourcePrefix: '/mnt/books', targetPrefix: '/target' },
+    ]);
+    expect(mapped).toBe('/target/file.epub');
+  });
 });
 
 describe('deriveUnresolvedReason', () => {
@@ -29,4 +50,8 @@ describe('deriveUnresolvedReason', () => {
   it('returns insufficient_source_data when no strategy could be attempted', () => {
     expect(deriveUnresolvedReason([])).toBe('insufficient_source_data');
   });
+
+  it('returns title_author even if earlier strategies are missing', () => {
+    expect(deriveUnresolvedReason(['title_author'])).toBe('no_title_author_match');
+  });
 });
diff --git a/server/src/modules/migration/planner/matching.service.ts b/server/src/modules/migration/planner/matching.service.ts
index 07364b223..5def376af 100644
--- a/server/src/modules/migration/planner/matching.service.ts
+++ b/server/src/modules/migration/planner/matching.service.ts
@@ -1,5 +1,5 @@
-import { Inject, Injectable } from '@nestjs/common';
-import { and, eq, ilike, or } from 'drizzle-orm';
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { and, eq, ilike, inArray, sql } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 import { DB } from '../../../db';
@@ -10,57 +10,80 @@ import type { PathMapping, PlannedBookMatch, PlannedUnresolvedBook, UnresolvedRe
 type Db = NodePgDatabase<typeof schema>;
 type MatchAttempt = 'isbn' | 'file_hash' | 'file_path' | 'title_author';
 
+type LookupResult = { kind: 'found'; bookId: number } | { kind: 'ambiguous' } | { kind: 'none' };
+
+function found(bookId: number): LookupResult {
+  return { kind: 'found', bookId };
+}
+const AMBIGUOUS: LookupResult = { kind: 'ambiguous' };
+const NONE: LookupResult = { kind: 'none' };
+
 @Injectable()
 export class MatchingService {
+  private readonly logger = new Logger(MatchingService.name);
+
   constructor(@Inject(DB) private readonly db: Db) {}
 
   async matchBooks(
     sourceBooks: SourceBook[],
     pathMappings: PathMapping[],
   ): Promise<{ matches: PlannedBookMatch[]; unresolved: PlannedUnresolvedBook[] }> {
+    const startMs = Date.now();
+    this.logger.log(`[book.matching] [start] sourceBooks=${sourceBooks.length} pathMappings=${pathMappings.length} - matching started`);
+
     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>();
+    const isbnIndex = await this.batchLookupIsbns(sourceBooks);
+    const hashIndex = await this.batchLookupFileHashes(sourceBooks);
 
-    for (const sourceBook of sourceBooks) {
+    const filePathCache = new Map<string, LookupResult>();
+    const titleAuthorCache = new Map<string, LookupResult>();
+
+    sourceBooksLoop: for (const sourceBook of sourceBooks) {
       const attempts: MatchAttempt[] = [];
-      const isbn = sourceBook.isbn13 ?? sourceBook.isbn10;
+      let ambiguousStrategy: MatchAttempt | null = null;
+
+      const isbn = normalizeIsbn(sourceBook.isbn13) ?? normalizeIsbn(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' });
+        const result = isbnIndex.get(isbn) ?? NONE;
+        if (result.kind === 'found') {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: result.bookId, strategy: 'isbn' });
           continue;
         }
+        if (result.kind === 'ambiguous') ambiguousStrategy = 'isbn';
       }
 
-      if (sourceBook.fileHash) {
+      const sourceHashes = sourceFileHashes(sourceBook);
+      if (sourceHashes.length > 0) {
         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;
+        for (const sourceHash of sourceHashes) {
+          const result = hashIndex.get(sourceHash) ?? NONE;
+          if (result.kind === 'found') {
+            matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: result.bookId, strategy: 'file_hash' });
+            continue sourceBooksLoop;
+          }
+          if (result.kind === 'ambiguous') ambiguousStrategy ??= 'file_hash';
         }
       }
 
-      const mappedPath = applyPathMappings(sourceBook.filePath, pathMappings);
-      if (mappedPath) {
+      const mappedPaths = sourceFilePaths(sourceBook)
+        .map((path) => applyPathMappings(path, pathMappings))
+        .filter((path): path is string => !!path);
+      if (mappedPaths.length > 0) {
         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;
+        for (const mappedPath of [...new Set(mappedPaths)]) {
+          let result = filePathCache.get(mappedPath);
+          if (!result) {
+            result = await this.lookupByFilePath(mappedPath);
+            filePathCache.set(mappedPath, result);
+          }
+          if (result.kind === 'found') {
+            matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: result.bookId, strategy: 'path_mapping' });
+            continue sourceBooksLoop;
+          }
+          if (result.kind === 'ambiguous') ambiguousStrategy ??= 'file_path';
         }
       }
 
@@ -69,62 +92,162 @@ export class MatchingService {
         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' });
+        let result = titleAuthorCache.get(cacheKey);
+        if (!result) {
+          result = await this.lookupByTitleAuthor(sourceBook.title ?? '', authorNames);
+          titleAuthorCache.set(cacheKey, result);
+        }
+        if (result.kind === 'found') {
+          matches.push({ sourceBookId: sourceBook.sourceBookId, targetBookId: result.bookId, strategy: 'title_author' });
           continue;
         }
+        if (result.kind === 'ambiguous') ambiguousStrategy ??= 'title_author';
       }
 
       unresolved.push({
         sourceBookId: sourceBook.sourceBookId,
         title: sourceBook.title,
-        reason: deriveUnresolvedReason(attempts),
+        reason: ambiguousStrategy ? deriveAmbiguousReason(ambiguousStrategy) : deriveUnresolvedReason(attempts),
       });
+      this.logger.debug(
+        `[book.matching] sourceBookId=${sourceBook.sourceBookId} reason=${ambiguousStrategy ? deriveAmbiguousReason(ambiguousStrategy) : deriveUnresolvedReason(attempts)} attempts=${attempts.join(',')} - unresolved`,
+      );
     }
 
+    const durationMs = Date.now() - startMs;
+    this.logger.log(`[book.matching] [end] matched=${matches.length} unresolved=${unresolved.length} durationMs=${durationMs} - matching completed`);
     return { matches, unresolved };
   }
 
-  private async findByIsbn(isbn13: string | null, isbn10: string | null): Promise<number | null> {
-    if (!isbn13 && !isbn10) return null;
+  private async batchLookupIsbns(sourceBooks: SourceBook[]): Promise<Map<string, LookupResult>> {
+    const isbn13s = new Set<string>();
+    const isbn10s = new Set<string>();
+    for (const book of sourceBooks) {
+      const isbn13 = normalizeIsbn(book.isbn13);
+      const isbn10 = normalizeIsbn(book.isbn10);
+      if (isbn13) isbn13s.add(isbn13);
+      if (isbn10) isbn10s.add(isbn10);
+    }
 
-    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 results = new Map<string, LookupResult>();
+    if (isbn13s.size === 0 && isbn10s.size === 0) return results;
 
-    const rows = await this.db.select({ bookId: schema.bookMetadata.bookId }).from(schema.bookMetadata).where(where).limit(2);
+    const chunkSize = 500;
+    const bookIdsByIsbn = new Map<string, number[]>();
 
-    return singleBookId(rows);
+    const allIsbns13 = [...isbn13s];
+    for (let i = 0; i < allIsbns13.length; i += chunkSize) {
+      const chunk = allIsbns13.slice(i, i + chunkSize);
+      const normalizedTargetIsbn13 = normalizedIsbnSql(schema.bookMetadata.isbn13);
+      const rows = await this.db
+        .select({ bookId: schema.bookMetadata.bookId, isbn13: normalizedTargetIsbn13 })
+        .from(schema.bookMetadata)
+        .where(inArray(normalizedTargetIsbn13, chunk));
+      for (const row of rows) {
+        const isbn = normalizeIsbn(row.isbn13);
+        if (!isbn) continue;
+        const existing = bookIdsByIsbn.get(isbn) ?? [];
+        existing.push(row.bookId);
+        bookIdsByIsbn.set(isbn, existing);
+      }
+    }
+
+    const allIsbns10 = [...isbn10s];
+    for (let i = 0; i < allIsbns10.length; i += chunkSize) {
+      const chunk = allIsbns10.slice(i, i + chunkSize);
+      const normalizedTargetIsbn10 = normalizedIsbnSql(schema.bookMetadata.isbn10);
+      const rows = await this.db
+        .select({ bookId: schema.bookMetadata.bookId, isbn10: normalizedTargetIsbn10 })
+        .from(schema.bookMetadata)
+        .where(inArray(normalizedTargetIsbn10, chunk));
+      for (const row of rows) {
+        const isbn = normalizeIsbn(row.isbn10);
+        if (!isbn) continue;
+        const existing = bookIdsByIsbn.get(isbn) ?? [];
+        existing.push(row.bookId);
+        bookIdsByIsbn.set(isbn, existing);
+      }
+    }
+
+    for (const book of sourceBooks) {
+      const isbn = normalizeIsbn(book.isbn13) ?? normalizeIsbn(book.isbn10);
+      if (!isbn) continue;
+
+      const isbn13 = normalizeIsbn(book.isbn13);
+      const isbn10 = normalizeIsbn(book.isbn10);
+      const isbn13Hits = isbn13 ? (bookIdsByIsbn.get(isbn13) ?? []) : [];
+      const isbn10Hits = isbn10 ? (bookIdsByIsbn.get(isbn10) ?? []) : [];
+      const uniqueBookIds = [...new Set([...isbn13Hits, ...isbn10Hits])];
+
+      if (uniqueBookIds.length === 1) {
+        results.set(isbn, found(uniqueBookIds[0]));
+      } else if (uniqueBookIds.length > 1) {
+        results.set(isbn, AMBIGUOUS);
+      } else {
+        results.set(isbn, NONE);
+      }
+    }
+
+    return results;
   }
 
-  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);
+  private async batchLookupFileHashes(sourceBooks: SourceBook[]): Promise<Map<string, LookupResult>> {
+    const hashes = new Set<string>();
+    for (const book of sourceBooks) {
+      for (const hash of sourceFileHashes(book)) hashes.add(hash);
+    }
 
-    return singleBookId(rows);
+    const results = new Map<string, LookupResult>();
+    if (hashes.size === 0) return results;
+
+    const chunkSize = 500;
+    const bookIdsByHash = new Map<string, number[]>();
+    const allHashes = [...hashes];
+
+    for (let i = 0; i < allHashes.length; i += chunkSize) {
+      const chunk = allHashes.slice(i, i + chunkSize);
+      const rows = await this.db
+        .select({ bookId: schema.bookFiles.bookId, hash: schema.bookFiles.hash })
+        .from(schema.bookFiles)
+        .where(inArray(schema.bookFiles.hash, chunk));
+      for (const row of rows) {
+        if (!row.hash) continue;
+        const existing = bookIdsByHash.get(row.hash) ?? [];
+        existing.push(row.bookId);
+        bookIdsByHash.set(row.hash, existing);
+      }
+    }
+
+    for (const [hash, bookIds] of bookIdsByHash) {
+      const unique = [...new Set(bookIds)];
+      if (unique.length === 1) {
+        results.set(hash, found(unique[0]));
+      } else if (unique.length > 1) {
+        results.set(hash, AMBIGUOUS);
+      } else {
+        results.set(hash, NONE);
+      }
+    }
+
+    return results;
   }
 
-  private async findByFilePath(filePath: string): Promise<number | null> {
+  private async lookupByFilePath(filePath: string): Promise<LookupResult> {
     const rows = await this.db
       .select({ bookId: schema.bookFiles.bookId })
       .from(schema.bookFiles)
       .where(eq(schema.bookFiles.absolutePath, filePath))
       .limit(2);
 
-    return singleBookId(rows);
+    return toLookupResult(rows);
   }
 
-  private async findByTitleAuthor(title: string, authors: string[]): Promise<number | null> {
+  private async lookupByTitleAuthor(title: string, authors: string[]): Promise<LookupResult> {
     const normalizedTitle = title.trim();
-    if (!normalizedTitle) return null;
+    if (!normalizedTitle) return NONE;
 
     const normalizedAuthors = authors.map((author) => normalizeAuthor(author)).filter((author): author is string => !!author);
-    if (normalizedAuthors.length === 0) return null;
+    if (normalizedAuthors.length === 0) return NONE;
 
     for (const normalizedAuthor of normalizedAuthors) {
       const exactRows = await this.db
@@ -132,10 +255,12 @@ export class MatchingService {
         .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)))
+        .where(
+          and(sql`lower(${schema.bookMetadata.title}) = lower(${normalizedTitle})`, sql`lower(${schema.authors.name}) = lower(${normalizedAuthor})`),
+        )
         .limit(2);
-      const exactBookId = singleBookId(exactRows);
-      if (exactBookId) return exactBookId;
+      const result = toLookupResult(exactRows);
+      if (result.kind !== 'none') return result;
     }
 
     for (const normalizedAuthor of normalizedAuthors) {
@@ -144,16 +269,24 @@ export class MatchingService {
         .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)}%`)))
+        .where(
+          and(sql`lower(${schema.bookMetadata.title}) = lower(${normalizedTitle})`, ilike(schema.authors.name, `%${escapeLike(normalizedAuthor)}%`)),
+        )
         .limit(2);
-      const approxBookId = singleBookId(approxRows);
-      if (approxBookId) return approxBookId;
+      const result = toLookupResult(approxRows);
+      if (result.kind !== 'none') return result;
     }
 
-    return null;
+    return NONE;
   }
 }
 
+function toLookupResult(rows: Array<{ bookId: number }>): LookupResult {
+  if (rows.length === 1) return found(rows[0].bookId);
+  if (rows.length > 1) return AMBIGUOUS;
+  return NONE;
+}
+
 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';
@@ -162,6 +295,19 @@ export function deriveUnresolvedReason(attempts: MatchAttempt[]): UnresolvedReas
   return 'insufficient_source_data';
 }
 
+function deriveAmbiguousReason(strategy: MatchAttempt): UnresolvedReasonCode {
+  switch (strategy) {
+    case 'isbn':
+      return 'ambiguous_isbn_match';
+    case 'file_hash':
+      return 'ambiguous_file_hash_match';
+    case 'file_path':
+      return 'ambiguous_file_path_match';
+    case 'title_author':
+      return 'ambiguous_title_author_match';
+  }
+}
+
 function normalizeTitle(value: string | null): string | null {
   if (!value) return null;
   const normalized = value.trim().toLowerCase();
@@ -174,6 +320,34 @@ function normalizeAuthor(value: string | null): string | null {
   return normalized.length > 0 ? normalized : null;
 }
 
+function normalizeIsbn(value: string | null): string | null {
+  if (!value) return null;
+  const normalized = value.replace(/[^0-9Xx]/g, '').toUpperCase();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizedIsbnSql(column: typeof schema.bookMetadata.isbn10 | typeof schema.bookMetadata.isbn13) {
+  return sql<string>`regexp_replace(upper(coalesce(${column}, '')), '[^0-9X]', '', 'g')`;
+}
+
+function sourceFileHashes(sourceBook: SourceBook): string[] {
+  const hashes = new Set<string>();
+  if (sourceBook.fileHash) hashes.add(sourceBook.fileHash);
+  for (const file of sourceBook.files ?? []) {
+    if (file.fileHash) hashes.add(file.fileHash);
+  }
+  return [...hashes];
+}
+
+function sourceFilePaths(sourceBook: SourceBook): string[] {
+  const paths = new Set<string>();
+  if (sourceBook.filePath) paths.add(sourceBook.filePath);
+  for (const file of sourceBook.files ?? []) {
+    if (file.filePath) paths.add(file.filePath);
+  }
+  return [...paths];
+}
+
 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;
@@ -189,10 +363,6 @@ function buildTitleAuthorCacheKey(title: string | null, authors: string[]): stri
   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;
 
@@ -202,7 +372,7 @@ export function applyPathMappings(filePath: string | null, mappings: PathMapping
     const targetPrefix = normalizePathPrefix(mapping.targetPrefix);
     if (!sourcePrefix || !targetPrefix) continue;
 
-    if (filePath.startsWith(sourcePrefix)) {
+    if (pathMatchesPrefix(filePath, sourcePrefix)) {
       return `${targetPrefix}${filePath.slice(sourcePrefix.length)}`;
     }
   }
@@ -210,6 +380,11 @@ export function applyPathMappings(filePath: string | null, mappings: PathMapping
   return filePath;
 }
 
+export function pathMatchesPrefix(filePath: string, sourcePrefix: string): boolean {
+  if (sourcePrefix === '/') return filePath.startsWith('/');
+  return filePath === sourcePrefix || filePath.startsWith(`${sourcePrefix}/`);
+}
+
 function normalizePathPrefix(value: string): string {
   const trimmed = value.trim();
   if (!trimmed) return '';
diff --git a/server/src/modules/migration/planner/path-mapping-validation.service.ts b/server/src/modules/migration/planner/path-mapping-validation.service.ts
index b115b22c9..3dfc122a4 100644
--- a/server/src/modules/migration/planner/path-mapping-validation.service.ts
+++ b/server/src/modules/migration/planner/path-mapping-validation.service.ts
@@ -2,6 +2,7 @@ import { Injectable } from '@nestjs/common';
 
 import type { SourceBook } from '../adapters/source-adapter.types';
 import { MigrationRepository } from '../migration.repository';
+import { pathMatchesPrefix } from './matching.service';
 import type { PathMapping } from './planner.types';
 
 interface MappedPathRow {
@@ -118,7 +119,7 @@ export class PathMappingValidationService {
 
 function findMatchingMapping(sourcePath: string, mappings: PathMapping[]): { index: number; mapping: PathMapping } | null {
   for (const [index, mapping] of mappings.entries()) {
-    if (sourcePath.startsWith(mapping.sourcePrefix)) {
+    if (pathMatchesPrefix(sourcePath, mapping.sourcePrefix)) {
       return { index, mapping };
     }
   }
diff --git a/server/src/modules/migration/planner/planner.service.ts b/server/src/modules/migration/planner/planner.service.ts
index bdb3ddd7b..e51604b38 100644
--- a/server/src/modules/migration/planner/planner.service.ts
+++ b/server/src/modules/migration/planner/planner.service.ts
@@ -3,7 +3,8 @@ 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 { parseConnectionConfig } from '../core/connection-config';
+import { asRecord, asString, asNumber } from '../core/coerce';
 import { MatchingService } from './matching.service';
 import type {
   PathMapping,
@@ -88,8 +89,9 @@ function splitDuplicateMatches(matches: PlannedBookMatch[]): {
     duplicateTargetIds.add(targetBookId);
     duplicateBookMatches.push({
       targetBookId,
+      matches: rows,
       sourceBookIds: rows.map((row) => row.sourceBookId),
-      strategies: [...new Set(rows.map((row) => row.strategy))],
+      strategies: rows.map((row) => row.strategy),
       reason: 'duplicate_target_match',
     });
   }
@@ -100,13 +102,6 @@ function splitDuplicateMatches(matches: PlannedBookMatch[]): {
   };
 }
 
-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 [];
 
@@ -114,8 +109,8 @@ function parseUserMappings(raw: unknown): 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);
+    const sourceUserId = asString((item as Record<string, unknown>).sourceUserId ?? (item as Record<string, unknown>).source_user_id);
+    const targetUserId = asNumber((item as Record<string, unknown>).targetUserId ?? (item as Record<string, unknown>).target_user_id);
     if (!sourceUserId || !targetUserId) continue;
 
     out.push({ sourceUserId, targetUserId });
@@ -131,8 +126,8 @@ function parsePathMappings(raw: unknown): 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);
+    const sourcePrefix = asString((item as Record<string, unknown>).sourcePrefix ?? (item as Record<string, unknown>).source_prefix);
+    const targetPrefix = asString((item as Record<string, unknown>).targetPrefix ?? (item as Record<string, unknown>).target_prefix);
     if (!sourcePrefix || !targetPrefix) continue;
 
     out.push({ sourcePrefix, targetPrefix });
@@ -141,7 +136,7 @@ function parsePathMappings(raw: unknown): PathMapping[] {
   return out;
 }
 
-function buildUserPreview(sourceData: SourceExportData, mappedUsers: Map<string, number>, matchedBookIds: Set<string>): PlannedUserPreview[] {
+export 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 }>();
 
@@ -185,23 +180,3 @@ function buildUserPreview(sourceData: SourceExportData, mappedUsers: Map<string,
     };
   });
 }
-
-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
index 06b072df5..f21bb926d 100644
--- a/server/src/modules/migration/planner/planner.types.ts
+++ b/server/src/modules/migration/planner/planner.types.ts
@@ -17,7 +17,12 @@ export type UnresolvedReasonCode =
   | 'no_isbn_match'
   | 'no_file_hash_match'
   | 'no_file_path_match'
-  | 'no_title_author_match';
+  | 'no_title_author_match'
+  | 'ambiguous_isbn_match'
+  | 'ambiguous_file_hash_match'
+  | 'ambiguous_file_path_match'
+  | 'ambiguous_title_author_match'
+  | 'duplicate_target_match';
 
 export interface PlannedBookMatch {
   sourceBookId: string;
@@ -27,6 +32,7 @@ export interface PlannedBookMatch {
 
 export interface PlannedDuplicateBookMatch {
   targetBookId: number;
+  matches: PlannedBookMatch[];
   sourceBookIds: string[];
   strategies: MatchStrategy[];
   reason: 'duplicate_target_match';
diff --git a/server/src/modules/migration/reporting/migration-reporting.service.ts b/server/src/modules/migration/reporting/migration-reporting.service.ts
index be7b87760..2f4ec8d63 100644
--- a/server/src/modules/migration/reporting/migration-reporting.service.ts
+++ b/server/src/modules/migration/reporting/migration-reporting.service.ts
@@ -1,6 +1,7 @@
 import { Injectable, NotFoundException } from '@nestjs/common';
 
 import { MigrationRepository } from '../migration.repository';
+import { sanitizeRunForApi } from '../core/api-sanitizers';
 
 @Injectable()
 export class MigrationReportingService {
@@ -103,22 +104,6 @@ export class MigrationReportingService {
   }
 }
 
-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]);
diff --git a/server/test/e2e/app-harness.ts b/server/test/e2e/app-harness.ts
index dcbaf7e28..00e36f3da 100644
--- a/server/test/e2e/app-harness.ts
+++ b/server/test/e2e/app-harness.ts
@@ -3,11 +3,13 @@ import { expect } from 'vitest';
 import fastifyCookie from '@fastify/cookie';
 import { count, eq, inArray, isNull, sql } from 'drizzle-orm';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { ValidationPipe } from '@nestjs/common';
 import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
 import { Test } from '@nestjs/testing';
 import { DEFAULT_FORMAT_PRIORITY } from '@projectx/types';
 
 import { AppModule } from '../../src/app.module';
+import { GlobalExceptionFilter } from '../../src/common/filters/http-exception.filter';
 import { DB } from '../../src/db';
 import * as schema from '../../src/db/schema';
 import { books, bookFiles, libraries, libraryFolders, scanJobs } from '../../src/db/schema';
@@ -76,6 +78,14 @@ export async function createE2EContext(): Promise<E2EContext> {
 
   const app = moduleFixture.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
   app.setGlobalPrefix('api/v1');
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+    }),
+  );
+  app.useGlobalFilters(new GlobalExceptionFilter());
   await app.register(fastifyCookie as never);
   await app.init();
   await app.getHttpAdapter().getInstance().ready();
diff --git a/server/test/e2e/migration-booklore/migration-booklore-fixture-builder.ts b/server/test/e2e/migration-booklore/migration-booklore-fixture-builder.ts
new file mode 100644
index 000000000..9831307e5
--- /dev/null
+++ b/server/test/e2e/migration-booklore/migration-booklore-fixture-builder.ts
@@ -0,0 +1,1030 @@
+import { dirname, join, relative } from 'path';
+import { mkdir, writeFile } from 'fs/promises';
+import sharp from 'sharp';
+import { eq } from 'drizzle-orm';
+import type mysql from 'mysql2/promise';
+
+import * as schema from '../../../src/db/schema';
+import {
+  buildBookloreConnectionConfig,
+  createUser,
+  seedLibrary,
+  type CreatedUser,
+  type MigrationBookloreE2EContext,
+  withBookloreConnection,
+} from './migration-booklore-harness';
+
+interface SeededBook {
+  bookId: number;
+  primaryFileId: number;
+  fileIds: number[];
+  absolutePaths: string[];
+}
+
+export interface CanonicalMigrationScenario {
+  connectionConfig: Record<string, unknown>;
+  pathMappings: Array<{ sourcePrefix: string; targetPrefix: string }>;
+  targetUsers: {
+    alice: CreatedUser;
+    bob: CreatedUser;
+  };
+  books: {
+    isbn: SeededBook;
+    hash: SeededBook;
+    audio: SeededBook;
+    titleAuthor: SeededBook;
+    duplicate: SeededBook;
+  };
+  sourceBookIds: {
+    isbn: string;
+    hash: string;
+    audio: string;
+    titleAuthor: string;
+    duplicatePreferred: string;
+    duplicateRejected: string;
+    unmatched: string;
+  };
+}
+
+export interface CompatibilityScenario {
+  connectionConfig: Record<string, unknown>;
+  pathMappings: Array<{ sourcePrefix: string; targetPrefix: string }>;
+  targetUser: CreatedUser;
+  book: SeededBook;
+}
+
+export interface MinimalScenario {
+  connectionConfig: Record<string, unknown>;
+  targetUser: CreatedUser;
+  book: SeededBook;
+}
+
+let nextInode = 1000;
+
+export async function seedCanonicalScenario(ctx: MigrationBookloreE2EContext): Promise<CanonicalMigrationScenario> {
+  const alice = await createUser(ctx, {
+    username: 'migration-booklore-alice-source',
+    email: 'alice-source@example.com',
+  });
+  const bob = await createUser(ctx, {
+    username: 'migration-booklore-bob-source',
+    email: 'bob-source@example.com',
+  });
+
+  const libraryRoot = join(ctx.booksPath, 'target-library');
+  const { libraryId, libraryFolderId } = await seedLibrary(ctx.db, {
+    rootPath: libraryRoot,
+    mode: 'book_per_folder',
+    name: 'Migration Booklore Library',
+  });
+
+  const isbn = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'isbn-match',
+    files: [{ relativePath: 'isbn-match/book.epub', format: 'epub', hash: 'target-isbn-hash' }],
+    metadata: {
+      title: 'Old ISBN Title',
+      subtitle: 'Old ISBN Subtitle',
+      description: 'Old description',
+      isbn13: '9781111111111',
+      publisher: 'Old Publisher',
+      publishedYear: 1999,
+      language: 'fr',
+      pageCount: 12,
+      seriesName: 'Old Series',
+      seriesIndex: 0.5,
+      rating: 1,
+      googleBooksId: 'old-google',
+      goodreadsId: 'old-gr',
+      amazonId: 'OLDASIN',
+      hardcoverId: 'old-hc',
+      audibleId: 'old-aud',
+      comicvineId: 'old-cv',
+      durationSeconds: 10,
+      abridged: false,
+    },
+    authors: ['Obsolete Author'],
+    narrators: ['Obsolete Narrator'],
+    genres: ['Obsolete Genre'],
+    tags: ['Obsolete Tag'],
+  });
+
+  const hash = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'hash-match',
+    files: [{ relativePath: 'hash-match/hash-match.epub', format: 'epub', hash: 'shared-hash-match' }],
+    metadata: {
+      title: 'Old Hash Title',
+      subtitle: 'Will clear',
+      description: 'Old hash description',
+      rating: 4,
+      googleBooksId: 'will-clear',
+    },
+    authors: ['Old Hash Author'],
+    tags: ['Old Hash Tag'],
+  });
+
+  const audio = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'audio-path-match',
+    files: [
+      { relativePath: 'audio-path-match/disc-1/part1.mp3', format: 'mp3', hash: 'audio-hash-1', durationSeconds: 120 },
+      { relativePath: 'audio-path-match/disc-1/part2.mp3', format: 'mp3', hash: 'audio-hash-2', durationSeconds: 180 },
+    ],
+    metadata: {
+      title: 'Old Audio Title',
+      subtitle: 'Old Audio Subtitle',
+    },
+    authors: ['Placeholder Audio Author'],
+  });
+
+  const titleAuthor = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'title-author-match',
+    files: [{ relativePath: 'title-author-match/title-author.epub', format: 'epub', hash: 'target-title-hash' }],
+    metadata: {
+      title: 'Title Author Match',
+      subtitle: 'Should stay null',
+    },
+    authors: ['Unique Title Author'],
+  });
+
+  const duplicate = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'duplicate-match',
+    files: [{ relativePath: 'duplicate-match/duplicate.epub', format: 'epub', hash: 'dup-target-hash' }],
+    metadata: {
+      title: 'Duplicate Target',
+      isbn13: '9789999999995',
+    },
+    authors: ['Duplicate Target Author'],
+  });
+
+  await ctx.db.insert(schema.collections).values({
+    userId: alice.id,
+    name: 'Favorites',
+    description: 'Existing favorites collection',
+    syncToKobo: false,
+    displayOrder: 0,
+  });
+
+  await withBookloreConnection(ctx, async (conn) => {
+    await createCanonicalSchema(conn);
+
+    await insertRows(
+      conn,
+      'users',
+      ['id', 'username', 'name', 'email'],
+      [
+        [1, 'alice-source', 'Alice Source', 'alice-source@example.com'],
+        [2, 'bob-source', 'Bob Source', 'bob-source@example.com'],
+        [3, 'ghost-source', 'Ghost Source', 'ghost-source@example.com'],
+      ],
+    );
+
+    await insertRows(conn, 'library_path', ['id', 'path'], [[1, '/booklore-media/library']]);
+
+    await insertRows(
+      conn,
+      'book',
+      ['id', 'library_path_id', 'deleted'],
+      [
+        [101, 1, 0],
+        [102, 1, 0],
+        [103, 1, 0],
+        [104, 1, 0],
+        [105, 1, 0],
+        [106, 1, 0],
+        [107, 1, 0],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_metadata',
+      [
+        'book_id',
+        'title',
+        'author',
+        'subtitle',
+        'isbn10',
+        'isbn13',
+        'description',
+        'publisher',
+        'published_year',
+        'language',
+        'page_count',
+        'series_name',
+        'series_number',
+        'rating',
+        'google_books_id',
+        'goodreads_id',
+        'asin',
+        'hardcover_id',
+        'audible_id',
+        'comicvine_id',
+        'duration_seconds',
+        'abridged',
+        'narrator',
+      ],
+      [
+        [
+          101,
+          'Imported ISBN Title',
+          'Legacy Author',
+          'Imported Subtitle',
+          '1234567890',
+          '9781111111111',
+          'Long imported description',
+          'Imported Publisher',
+          2021,
+          'en',
+          321,
+          'Series Prime',
+          2.5,
+          5,
+          'google-101',
+          'gr-101',
+          'ASIN101',
+          'hc-101',
+          'aud-101',
+          'cv-101',
+          11111,
+          1,
+          'Narrator One|Narrator Two',
+        ],
+        [
+          102,
+          'Imported Hash Title',
+          'Single Hash Author',
+          null,
+          null,
+          null,
+          'Hash description',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+        ],
+        [
+          103,
+          'Audio Path Match',
+          '["Audio Author","Guest Author"]',
+          null,
+          null,
+          null,
+          'Audio description',
+          'Audio Publisher',
+          2020,
+          'en',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          'audio-id-103',
+          null,
+          300,
+          'yes',
+          '["Narrator Alpha","Narrator Beta"]',
+        ],
+        [
+          104,
+          'Title Author Match',
+          'Unique Title Author',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+        ],
+        [
+          105,
+          'Duplicate Preferred',
+          'Duplicate Preferred Author',
+          null,
+          null,
+          '9789999999995',
+          'Preferred duplicate',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+        ],
+        [
+          106,
+          'Duplicate Rejected',
+          'Duplicate Rejected Author',
+          null,
+          null,
+          '9789999999995',
+          'Rejected duplicate',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+        ],
+        [
+          107,
+          'Unmatched Source',
+          'Missing Match',
+          null,
+          null,
+          null,
+          'Unmatched book',
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+        ],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_file',
+      ['id', 'book_id', 'absolute_path', 'file_name', 'file_sub_path', 'current_hash', 'initial_hash', 'duration_seconds', 'is_book'],
+      [
+        [1001, 101, '/booklore-media/library/isbn-match/book.epub', 'book.epub', 'isbn-match', 'source-hash-101', null, null, 1],
+        [1002, 102, '/unmapped/hash-match.epub', 'hash-match.epub', 'hash-match', 'shared-hash-match', null, null, 1],
+        [
+          1003,
+          103,
+          '/booklore-media/library/audio-path-match/disc-1/part1.mp3',
+          'part1.mp3',
+          'audio-path-match/disc-1',
+          'audio-hash-1',
+          null,
+          120,
+          1,
+        ],
+        [
+          1004,
+          103,
+          '/booklore-media/library/audio-path-match/disc-1/part2.mp3',
+          'part2.mp3',
+          'audio-path-match/disc-1',
+          'audio-hash-2',
+          null,
+          180,
+          1,
+        ],
+        [1005, 104, '/other/no-match/title-author.epub', 'title-author.epub', 'title-author-match', 'title-author-no-match', null, null, 1],
+        [1006, 105, '/dup/preferred.epub', 'preferred.epub', 'duplicate-match', 'dup-hash-1', null, null, 1],
+        [1007, 106, '/dup/rejected.epub', 'rejected.epub', 'duplicate-match', 'dup-hash-2', null, null, 1],
+        [1008, 107, '/missing/unmatched.epub', 'unmatched.epub', 'unmatched', 'unmatched-hash', null, null, 1],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'author',
+      ['id', 'name', 'sort_name', 'description'],
+      [
+        [1, 'Jane Primary', 'Primary, Jane', 'Primary author bio'],
+        [2, 'John Secondary', 'Secondary, John', 'Secondary author bio'],
+        [3, 'Single Hash Author', 'Hash, Single', null],
+        [4, 'Duplicate Preferred Author', 'Preferred, Duplicate', null],
+        [5, 'Duplicate Rejected Author', 'Rejected, Duplicate', null],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_metadata_author_mapping',
+      ['book_id', 'author_id', 'sort_order'],
+      [
+        [101, 1, 0],
+        [101, 2, 1],
+        [102, 3, 0],
+        [105, 4, 0],
+        [106, 5, 0],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'category',
+      ['id', 'name'],
+      [
+        [1, 'Fantasy'],
+        [2, 'Adventure'],
+        [3, 'Audio Fiction'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_metadata_category_mapping',
+      ['book_id', 'category_id'],
+      [
+        [101, 1],
+        [101, 2],
+        [103, 3],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'tag',
+      ['id', 'name'],
+      [
+        [1, 'Imported Tag 1'],
+        [2, 'Imported Tag 2'],
+        [3, 'Hash Imported Tag'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_metadata_tag_mapping',
+      ['book_id', 'tag_id'],
+      [
+        [101, 1],
+        [101, 2],
+        [102, 3],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'user_book_progress',
+      ['user_id', 'book_id', 'status', 'percentage', 'started_at', 'finished_at', 'updated_at'],
+      [
+        [1, 101, 'completed', 100, '2024-01-02 12:00:00', '2024-01-10 12:00:00', '2024-01-11 12:00:00'],
+        [2, 103, null, 55, '2024-02-01 12:00:00', null, '2024-02-02 12:00:00'],
+        [3, 104, 'reading', 12, '2024-03-01 12:00:00', null, '2024-03-02 12:00:00'],
+        [1, 105, 'wishlist', 0, null, null, '2024-04-02 12:00:00'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'user_book_file_progress',
+      ['user_id', 'book_id', 'book_file_id', 'percentage', 'cfi', 'position_href', 'page_number', 'position_seconds', 'updated_at'],
+      [
+        [1, 101, 1001, 33.3, 'epubcfi(/6/2[chap]!/4/1:0)', null, null, null, '2024-01-11 13:00:00'],
+        [1, 102, null, 22.4, null, null, 10, null, '2024-01-12 13:00:00'],
+        [2, 103, 1004, 66, null, null, null, 12.5, '2024-02-02 13:00:00'],
+        [3, 104, 1005, 12, 'epubcfi(/6/2!/4/1:0)', null, null, null, '2024-03-02 13:00:00'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_marks',
+      ['user_id', 'book_id', 'book_file_id', 'title', 'cfi', 'position_seconds', 'track_index', 'created_at'],
+      [
+        [1, 101, 1001, 'Chapter 1', 'epubcfi(/6/2[chap]!/4/1:0)', null, null, '2024-01-03 12:00:00'],
+        [2, 103, null, null, null, 15, 2, '2024-02-03 12:00:00'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'annotations',
+      ['user_id', 'book_id', 'cfi', 'text', 'color', 'style', 'note', 'chapter_title', 'created_at', 'updated_at'],
+      [
+        [
+          1,
+          101,
+          'epubcfi(/6/4!/4/2:10)',
+          'Important quote',
+          'blue',
+          'underline',
+          'remember this',
+          'Chapter One',
+          '2024-01-04 12:00:00',
+          '2024-01-05 12:00:00',
+        ],
+        [2, 104, 'epubcfi(/6/8!/4/4:1)', 'Fallback defaults', null, null, null, null, '2024-02-04 12:00:00', '2024-02-05 12:00:00'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'shelf',
+      ['id', 'user_id', 'name'],
+      [
+        [501, 1, 'Favorites'],
+        [502, 2, 'Audio Shelf'],
+      ],
+    );
+
+    await insertRows(
+      conn,
+      'book_shelf_mapping',
+      ['shelf_id', 'book_id'],
+      [
+        [501, 101],
+        [501, 104],
+        [502, 103],
+      ],
+    );
+  });
+
+  await writeSourceCover(ctx, '101', { format: 'jpeg', color: '#cc3344', writeThumbnail: false });
+  await writeSourceCover(ctx, '103', { format: 'png', color: '#2255cc', writeThumbnail: true });
+
+  return {
+    connectionConfig: buildBookloreConnectionConfig(ctx),
+    pathMappings: [{ sourcePrefix: '/booklore-media/library', targetPrefix: libraryRoot }],
+    targetUsers: { alice, bob },
+    books: { isbn, hash, audio, titleAuthor, duplicate },
+    sourceBookIds: {
+      isbn: '101',
+      hash: '102',
+      audio: '103',
+      titleAuthor: '104',
+      duplicatePreferred: '105',
+      duplicateRejected: '106',
+      unmatched: '107',
+    },
+  };
+}
+
+export async function seedCompatibilityScenario(ctx: MigrationBookloreE2EContext): Promise<CompatibilityScenario> {
+  const targetUser = await createUser(ctx, {
+    username: 'migration-booklore-variant-source',
+    email: 'variant-source@example.com',
+  });
+  const libraryRoot = join(ctx.booksPath, 'variant-target-library');
+  const { libraryId, libraryFolderId } = await seedLibrary(ctx.db, {
+    rootPath: libraryRoot,
+    mode: 'book_per_folder',
+    name: 'Migration Booklore Variant Library',
+  });
+
+  const book = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'variant-book',
+    files: [{ relativePath: 'variant-book/book.pdf', format: 'pdf', hash: 'variant-target-hash' }],
+    metadata: {
+      title: 'Existing Variant Title',
+      subtitle: 'Keep this subtitle',
+      description: 'Old variant description',
+    },
+    authors: ['Existing Variant Author'],
+  });
+
+  await withBookloreConnection(ctx, async (conn) => {
+    await createCompatibilitySchema(conn);
+
+    await insertRows(
+      conn,
+      'users',
+      ['user_id', 'user_name', 'display_name', 'mail'],
+      [[41, 'variant-source', 'Variant Source User', 'variant-source@example.com']],
+    );
+    await insertRows(conn, 'library_path', ['id', 'absolute_path'], [[11, '/alt-source/root']]);
+    await insertRows(conn, 'book', ['id', 'librarypath_id', 'deleted'], [[401, 11, 0]]);
+    await insertRows(
+      conn,
+      'book_metadata',
+      [
+        'id',
+        'title',
+        'author',
+        'isbn_10',
+        'isbn_13',
+        'description',
+        'publisher',
+        'published_date',
+        'language',
+        'pages',
+        'series',
+        'series_position',
+        'rating',
+        'google_id',
+        'duration',
+        'abridged',
+        'narrators',
+      ],
+      [
+        [
+          401,
+          'Variant Imported Title',
+          '["Variant Author","Second Variant Author"]',
+          '0123456789',
+          '9780000000401',
+          'Variant imported description',
+          'Variant Publisher',
+          '2022-05-06',
+          'en',
+          222,
+          'Variant Series',
+          1.25,
+          4,
+          'variant-google-id',
+          987,
+          'no',
+          'Narrator Gamma|Narrator Delta',
+        ],
+      ],
+    );
+    await insertRows(conn, 'author', ['id', 'name'], [[1, 'Unused Variant Author']]);
+    await insertRows(conn, 'book_metadata_author_mapping', ['book_id', 'author_id', 'sort_order'], []);
+    await insertRows(
+      conn,
+      'book_file',
+      ['id', 'bookid', 'file_name', 'file_subpath', 'file_hash', 'duration'],
+      [[501, 401, 'book.pdf', 'variant-book', 'variant-source-hash', null]],
+    );
+    await insertRows(
+      conn,
+      'user_book_progress',
+      ['userid', 'bookid', 'read_status', 'progress_percent', 'date_started', 'date_finished', 'last_read_time'],
+      [[41, 401, 'paused', 78, '2024-03-01 12:00:00', null, '2024-03-02 12:00:00']],
+    );
+    await insertRows(
+      conn,
+      'user_book_file_progress',
+      ['userid', 'book_file_id', 'progress', 'location', 'href', 'page', 'position_ms', 'modified_at'],
+      [[41, 501, 78, 'epubcfi(/6/10!/4/2:20)', '/chapter-9', 9, 6500, '2024-03-02 12:30:00']],
+    );
+    await insertRows(
+      conn,
+      'book_marks',
+      ['userid', 'bookid', 'file_id', 'name', 'location', 'position_ms', 'track', 'createdat'],
+      [[41, 401, 501, 'Variant bookmark', 'epubcfi(/6/12!/4/2:1)', 2500, null, '2024-03-03 12:00:00']],
+    );
+  });
+
+  return {
+    connectionConfig: buildBookloreConnectionConfig(ctx),
+    pathMappings: [{ sourcePrefix: '/alt-source/root', targetPrefix: libraryRoot }],
+    targetUser,
+    book,
+  };
+}
+
+export async function seedWarningsOnlyScenario(ctx: MigrationBookloreE2EContext): Promise<MinimalScenario> {
+  const targetUser = await createUser(ctx, {
+    username: 'migration-booklore-warnings-source',
+  });
+  const libraryRoot = join(ctx.booksPath, 'warnings-library');
+  const { libraryId, libraryFolderId } = await seedLibrary(ctx.db, {
+    rootPath: libraryRoot,
+    mode: 'book_per_folder',
+    name: 'Migration Warnings Library',
+  });
+
+  const book = await insertTargetBook(ctx, {
+    libraryId,
+    libraryFolderId,
+    libraryRoot,
+    folderName: 'hash-only',
+    files: [{ relativePath: 'hash-only/hash-only.epub', format: 'epub', hash: 'warnings-hash' }],
+    metadata: {
+      title: 'Hash Only Target',
+    },
+    authors: ['Hash Only Author'],
+  });
+
+  await withBookloreConnection(ctx, async (conn) => {
+    await createWarningsOnlySchema(conn);
+    await insertRows(conn, 'users', ['id', 'username'], [[91, 'warnings-source']]);
+    await insertRows(conn, 'book', ['id', 'deleted'], [[901, 0]]);
+    await insertRows(
+      conn,
+      'book_file',
+      ['id', 'book_id', 'absolute_path', 'current_hash', 'is_book'],
+      [[9901, 901, '/warnings/hash-only.epub', 'warnings-hash', 1]],
+    );
+  });
+
+  return {
+    connectionConfig: buildBookloreConnectionConfig(ctx, { mediaRootPath: null }),
+    targetUser,
+    book,
+  };
+}
+
+export async function seedMissingRequiredTablesScenario(ctx: MigrationBookloreE2EContext): Promise<Record<string, unknown>> {
+  await withBookloreConnection(ctx, async (conn) => {
+    await createMissingRequiredSchema(conn);
+    await insertRows(conn, 'users', ['id', 'username'], [[71, 'incomplete-source']]);
+    await insertRows(conn, 'book', ['id', 'deleted'], [[701, 0]]);
+  });
+
+  return buildBookloreConnectionConfig(ctx);
+}
+
+interface InsertTargetBookInput {
+  libraryId: number;
+  libraryFolderId: number;
+  libraryRoot: string;
+  folderName: string;
+  files: Array<{
+    relativePath: string;
+    format: string;
+    hash: string | null;
+    durationSeconds?: number | null;
+  }>;
+  metadata?: Partial<typeof schema.bookMetadata.$inferInsert>;
+  authors?: string[];
+  narrators?: string[];
+  genres?: string[];
+  tags?: string[];
+}
+
+async function insertTargetBook(ctx: MigrationBookloreE2EContext, input: InsertTargetBookInput): Promise<SeededBook> {
+  const folderPath = join(input.libraryRoot, input.folderName);
+  await mkdir(folderPath, { recursive: true });
+
+  const [book] = await ctx.db
+    .insert(schema.books)
+    .values({
+      libraryId: input.libraryId,
+      libraryFolderId: input.libraryFolderId,
+      folderPath,
+      status: 'present',
+    })
+    .returning({ id: schema.books.id });
+
+  const fileIds: number[] = [];
+  const absolutePaths: string[] = [];
+
+  for (const [index, file] of input.files.entries()) {
+    const absolutePath = join(input.libraryRoot, file.relativePath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, `target file ${file.relativePath}`);
+
+    const [insertedFile] = await ctx.db
+      .insert(schema.bookFiles)
+      .values({
+        bookId: book.id,
+        libraryFolderId: input.libraryFolderId,
+        absolutePath,
+        relPath: relative(input.libraryRoot, absolutePath),
+        ino: nextInode++,
+        sizeBytes: 128,
+        mtime: new Date('2024-01-01T12:00:00Z'),
+        hash: file.hash,
+        format: file.format,
+        role: 'content',
+        sortOrder: index,
+        durationSeconds: file.durationSeconds ?? null,
+      })
+      .returning({ id: schema.bookFiles.id, absolutePath: schema.bookFiles.absolutePath });
+
+    fileIds.push(insertedFile.id);
+    absolutePaths.push(insertedFile.absolutePath);
+  }
+
+  await ctx.db.update(schema.books).set({ primaryFileId: fileIds[0] }).where(eq(schema.books.id, book.id));
+
+  if (input.metadata) {
+    await ctx.db.insert(schema.bookMetadata).values({
+      bookId: book.id,
+      ...input.metadata,
+    });
+  }
+
+  if (input.authors?.length) {
+    for (const [index, name] of input.authors.entries()) {
+      const authorId = await ensureAuthorId(ctx, name);
+      await ctx.db.insert(schema.bookAuthors).values({ bookId: book.id, authorId, displayOrder: index });
+    }
+  }
+
+  if (input.narrators?.length) {
+    for (const [index, name] of input.narrators.entries()) {
+      const narratorId = await ensureNarratorId(ctx, name);
+      await ctx.db.insert(schema.bookNarrators).values({ bookId: book.id, narratorId, displayOrder: index });
+    }
+  }
+
+  if (input.genres?.length) {
+    for (const name of input.genres) {
+      const genreId = await ensureGenreId(ctx, name);
+      await ctx.db.insert(schema.bookGenres).values({ bookId: book.id, genreId });
+    }
+  }
+
+  if (input.tags?.length) {
+    for (const name of input.tags) {
+      const tagId = await ensureTagId(ctx, name);
+      await ctx.db.insert(schema.bookTags).values({ bookId: book.id, tagId });
+    }
+  }
+
+  return {
+    bookId: book.id,
+    primaryFileId: fileIds[0],
+    fileIds,
+    absolutePaths,
+  };
+}
+
+async function ensureAuthorId(ctx: MigrationBookloreE2EContext, name: string): Promise<number> {
+  const existing = await ctx.db.query.authors.findFirst({ where: eq(schema.authors.name, name) });
+  if (existing) return existing.id;
+
+  const [inserted] = await ctx.db.insert(schema.authors).values({ name, sortName: name }).returning({ id: schema.authors.id });
+  return inserted.id;
+}
+
+async function ensureNarratorId(ctx: MigrationBookloreE2EContext, name: string): Promise<number> {
+  const existing = await ctx.db.query.narrators.findFirst({ where: eq(schema.narrators.name, name) });
+  if (existing) return existing.id;
+
+  const [inserted] = await ctx.db.insert(schema.narrators).values({ name, sortName: name }).returning({ id: schema.narrators.id });
+  return inserted.id;
+}
+
+async function ensureGenreId(ctx: MigrationBookloreE2EContext, name: string): Promise<number> {
+  const existing = await ctx.db.query.genres.findFirst({ where: eq(schema.genres.name, name) });
+  if (existing) return existing.id;
+
+  const [inserted] = await ctx.db.insert(schema.genres).values({ name }).returning({ id: schema.genres.id });
+  return inserted.id;
+}
+
+async function ensureTagId(ctx: MigrationBookloreE2EContext, name: string): Promise<number> {
+  const existing = await ctx.db.query.tags.findFirst({ where: eq(schema.tags.name, name) });
+  if (existing) return existing.id;
+
+  const [inserted] = await ctx.db.insert(schema.tags).values({ name }).returning({ id: schema.tags.id });
+  return inserted.id;
+}
+
+async function writeSourceCover(
+  ctx: MigrationBookloreE2EContext,
+  sourceBookId: string,
+  options: { format: 'jpeg' | 'png'; color: string; writeThumbnail: boolean },
+): Promise<void> {
+  const imageDir = join(ctx.sourceMediaRoot, 'images', sourceBookId);
+  await mkdir(imageDir, { recursive: true });
+
+  const buffer = await sharp({
+    create: {
+      width: 300,
+      height: 450,
+      channels: 3,
+      background: options.color,
+    },
+  })
+    [options.format]()
+    .toBuffer();
+
+  await writeFile(join(imageDir, 'cover.jpg'), buffer);
+
+  if (options.writeThumbnail) {
+    const thumbnail = await sharp({
+      create: {
+        width: 120,
+        height: 180,
+        channels: 3,
+        background: '#f5f5f5',
+      },
+    })
+      .jpeg()
+      .toBuffer();
+    await writeFile(join(imageDir, 'thumbnail.jpg'), thumbnail);
+  }
+}
+
+async function insertRows(conn: mysql.Connection, tableName: string, columns: string[], rows: Array<unknown[]>): Promise<void> {
+  if (rows.length === 0) return;
+
+  const placeholders = rows.map(() => `(${columns.map(() => '?').join(', ')})`).join(', ');
+  const sqlText = `INSERT INTO \`${tableName}\` (${columns.map((column) => `\`${column}\``).join(', ')}) VALUES ${placeholders}`;
+  await conn.execute(sqlText, rows.flat());
+}
+
+async function createCanonicalSchema(conn: mysql.Connection): Promise<void> {
+  await executeStatements(conn, [
+    'CREATE TABLE `users` (`id` INT PRIMARY KEY, `username` VARCHAR(100), `name` VARCHAR(255), `email` VARCHAR(255))',
+    'CREATE TABLE `library_path` (`id` INT PRIMARY KEY, `path` VARCHAR(1024))',
+    'CREATE TABLE `book` (`id` INT PRIMARY KEY, `library_path_id` INT, `deleted` TINYINT DEFAULT 0)',
+    'CREATE TABLE `book_metadata` (`book_id` INT PRIMARY KEY, `title` VARCHAR(255), `author` TEXT, `subtitle` VARCHAR(255), `isbn10` VARCHAR(20), `isbn13` VARCHAR(20), `description` TEXT, `publisher` VARCHAR(255), `published_year` INT, `language` VARCHAR(40), `page_count` INT, `series_name` VARCHAR(255), `series_number` DECIMAL(10,2), `rating` INT, `google_books_id` VARCHAR(100), `goodreads_id` VARCHAR(100), `asin` VARCHAR(100), `hardcover_id` VARCHAR(100), `audible_id` VARCHAR(100), `comicvine_id` VARCHAR(100), `duration_seconds` INT, `abridged` VARCHAR(10), `narrator` TEXT)',
+    'CREATE TABLE `book_file` (`id` INT PRIMARY KEY, `book_id` INT, `absolute_path` VARCHAR(1024), `file_name` VARCHAR(255), `file_sub_path` VARCHAR(1024), `current_hash` VARCHAR(64), `initial_hash` VARCHAR(64), `duration_seconds` INT, `is_book` TINYINT DEFAULT 1)',
+    'CREATE TABLE `author` (`id` INT PRIMARY KEY, `name` VARCHAR(255), `sort_name` VARCHAR(255), `description` TEXT)',
+    'CREATE TABLE `book_metadata_author_mapping` (`book_id` INT, `author_id` INT, `sort_order` INT)',
+    'CREATE TABLE `user_book_progress` (`user_id` INT, `book_id` INT, `status` VARCHAR(50), `percentage` DECIMAL(8,2), `started_at` DATETIME, `finished_at` DATETIME, `updated_at` DATETIME)',
+    'CREATE TABLE `user_book_file_progress` (`user_id` INT, `book_id` INT, `book_file_id` INT, `percentage` DECIMAL(8,2), `cfi` VARCHAR(2000), `position_href` VARCHAR(255), `page_number` INT, `position_seconds` DECIMAL(10,2), `updated_at` DATETIME)',
+    'CREATE TABLE `book_marks` (`user_id` INT, `book_id` INT, `book_file_id` INT, `title` VARCHAR(255), `cfi` VARCHAR(2000), `position_seconds` DECIMAL(10,2), `track_index` INT, `created_at` DATETIME)',
+    'CREATE TABLE `annotations` (`user_id` INT, `book_id` INT, `cfi` VARCHAR(2000), `text` TEXT, `color` VARCHAR(20), `style` VARCHAR(20), `note` TEXT, `chapter_title` VARCHAR(255), `created_at` DATETIME, `updated_at` DATETIME)',
+    'CREATE TABLE `shelf` (`id` INT PRIMARY KEY, `user_id` INT, `name` VARCHAR(255))',
+    'CREATE TABLE `book_shelf_mapping` (`shelf_id` INT, `book_id` INT)',
+    'CREATE TABLE `category` (`id` INT PRIMARY KEY, `name` VARCHAR(255))',
+    'CREATE TABLE `book_metadata_category_mapping` (`book_id` INT, `category_id` INT)',
+    'CREATE TABLE `tag` (`id` INT PRIMARY KEY, `name` VARCHAR(255))',
+    'CREATE TABLE `book_metadata_tag_mapping` (`book_id` INT, `tag_id` INT)',
+  ]);
+}
+
+async function createCompatibilitySchema(conn: mysql.Connection): Promise<void> {
+  await executeStatements(conn, [
+    'CREATE TABLE `users` (`user_id` INT PRIMARY KEY, `user_name` VARCHAR(100), `display_name` VARCHAR(255), `mail` VARCHAR(255))',
+    'CREATE TABLE `library_path` (`id` INT PRIMARY KEY, `absolute_path` VARCHAR(1024))',
+    'CREATE TABLE `book` (`id` INT PRIMARY KEY, `librarypath_id` INT, `deleted` TINYINT DEFAULT 0)',
+    'CREATE TABLE `book_metadata` (`id` INT PRIMARY KEY, `title` VARCHAR(255), `author` TEXT, `isbn_10` VARCHAR(20), `isbn_13` VARCHAR(20), `description` TEXT, `publisher` VARCHAR(255), `published_date` VARCHAR(40), `language` VARCHAR(20), `pages` INT, `series` VARCHAR(255), `series_position` DECIMAL(10,2), `rating` INT, `google_id` VARCHAR(100), `duration` INT, `abridged` VARCHAR(10), `narrators` TEXT)',
+    'CREATE TABLE `author` (`id` INT PRIMARY KEY, `name` VARCHAR(255))',
+    'CREATE TABLE `book_metadata_author_mapping` (`book_id` INT, `author_id` INT, `sort_order` INT)',
+    'CREATE TABLE `book_file` (`id` INT PRIMARY KEY, `bookid` INT, `file_name` VARCHAR(255), `file_subpath` VARCHAR(1024), `file_hash` VARCHAR(64), `duration` INT)',
+    'CREATE TABLE `user_book_progress` (`userid` INT, `bookid` INT, `read_status` VARCHAR(50), `progress_percent` DECIMAL(8,2), `date_started` DATETIME, `date_finished` DATETIME, `last_read_time` DATETIME)',
+    'CREATE TABLE `user_book_file_progress` (`userid` INT, `book_file_id` INT, `progress` DECIMAL(8,2), `location` VARCHAR(2000), `href` VARCHAR(255), `page` INT, `position_ms` BIGINT, `modified_at` DATETIME)',
+    'CREATE TABLE `book_marks` (`userid` INT, `bookid` INT, `file_id` INT, `name` VARCHAR(255), `location` VARCHAR(2000), `position_ms` BIGINT, `track` INT, `createdat` DATETIME)',
+  ]);
+}
+
+async function createWarningsOnlySchema(conn: mysql.Connection): Promise<void> {
+  await executeStatements(conn, [
+    'CREATE TABLE `users` (`id` INT PRIMARY KEY, `username` VARCHAR(100))',
+    'CREATE TABLE `book` (`id` INT PRIMARY KEY, `deleted` TINYINT DEFAULT 0)',
+    'CREATE TABLE `book_file` (`id` INT PRIMARY KEY, `book_id` INT, `absolute_path` VARCHAR(1024), `current_hash` VARCHAR(64), `is_book` TINYINT DEFAULT 1)',
+  ]);
+}
+
+async function createMissingRequiredSchema(conn: mysql.Connection): Promise<void> {
+  await executeStatements(conn, [
+    'CREATE TABLE `users` (`id` INT PRIMARY KEY, `username` VARCHAR(100))',
+    'CREATE TABLE `book` (`id` INT PRIMARY KEY, `deleted` TINYINT DEFAULT 0)',
+  ]);
+}
+
+async function executeStatements(conn: mysql.Connection, statements: string[]): Promise<void> {
+  for (const statement of statements) {
+    await conn.execute(statement);
+  }
+}
diff --git a/server/test/e2e/migration-booklore/migration-booklore-harness.ts b/server/test/e2e/migration-booklore/migration-booklore-harness.ts
new file mode 100644
index 000000000..185bed99c
--- /dev/null
+++ b/server/test/e2e/migration-booklore/migration-booklore-harness.ts
@@ -0,0 +1,521 @@
+import { randomUUID } from 'crypto';
+import { spawn } from 'child_process';
+import { mkdir, mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { hash } from 'bcryptjs';
+import { sql } from 'drizzle-orm';
+import mysql from 'mysql2/promise';
+
+import type { Permission } from '@projectx/types';
+import { coverDirPath } from '../../../src/modules/metadata/lib/cover';
+import * as schema from '../../../src/db/schema';
+import { closeE2EContext, createE2EContext, seedLibrary, type Db, type E2EContext, waitForCondition } from '../app-harness';
+
+const TEST_USER_PREFIX = 'migration-booklore-';
+const ENCRYPTION_KEY = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+
+interface EnvSnapshot {
+  booksPath: string | undefined;
+  migrationEncryptionKey: string | undefined;
+}
+
+export interface MariaDbService {
+  containerName: string;
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+  rootPassword: string;
+}
+
+export interface MigrationBookloreE2EContext extends E2EContext {
+  db: Db;
+  fixtureRoot: string;
+  booksPath: string;
+  sourceMediaRoot: string;
+  envSnapshot: EnvSnapshot;
+  mariadb: MariaDbService;
+}
+
+export interface CreatedUser {
+  id: number;
+  username: string;
+  password: string;
+  accessToken?: string;
+}
+
+export interface JsonResponse<T> {
+  statusCode: number;
+  body: T;
+}
+
+export async function createMigrationBookloreE2EContext(): Promise<MigrationBookloreE2EContext> {
+  const fixtureRoot = await mkdtemp(join(tmpdir(), 'projectx-migration-booklore-'));
+  const booksPath = join(fixtureRoot, 'books');
+  const sourceMediaRoot = join(fixtureRoot, 'booklore-media');
+  const envSnapshot: EnvSnapshot = {
+    booksPath: process.env.BOOKS_PATH,
+    migrationEncryptionKey: process.env.MIGRATION_ENCRYPTION_KEY,
+  };
+
+  await mkdir(booksPath, { recursive: true });
+  await mkdir(sourceMediaRoot, { recursive: true });
+  process.env.BOOKS_PATH = booksPath;
+  process.env.MIGRATION_ENCRYPTION_KEY = ENCRYPTION_KEY;
+
+  let base: E2EContext | null = null;
+  let mariadb: MariaDbService | null = null;
+
+  try {
+    base = await createE2EContext();
+    mariadb = await startMariaDbContainer();
+    await resetBookloreDatabase(mariadb);
+
+    return {
+      ...base,
+      fixtureRoot,
+      booksPath,
+      sourceMediaRoot,
+      envSnapshot,
+      mariadb,
+    };
+  } catch (error) {
+    if (base) {
+      await closeE2EContext(base);
+    }
+    if (mariadb) {
+      await stopMariaDbContainer(mariadb);
+    }
+    await rm(fixtureRoot, { recursive: true, force: true });
+    restoreEnv(envSnapshot);
+    throw error;
+  }
+}
+
+export async function closeMigrationBookloreE2EContext(ctx: MigrationBookloreE2EContext): Promise<void> {
+  await closeE2EContext(ctx);
+  await stopMariaDbContainer(ctx.mariadb);
+  await rm(ctx.fixtureRoot, { recursive: true, force: true });
+  restoreEnv(ctx.envSnapshot);
+}
+
+export async function resetMigrationBookloreState(ctx: MigrationBookloreE2EContext): Promise<void> {
+  await truncateScenarioTables(ctx.db);
+  await deleteTestUsers(ctx.db);
+  await resetDirectory(ctx.booksPath);
+  await resetDirectory(ctx.sourceMediaRoot);
+  await resetBookloreDatabase(ctx.mariadb);
+}
+
+export function authHeader(token: string): Record<string, string> {
+  return { authorization: `Bearer ${token}` };
+}
+
+export async function apiJson<T>(
+  ctx: MigrationBookloreE2EContext,
+  input: {
+    method: string;
+    url: string;
+    payload?: unknown;
+    token?: string;
+    headers?: Record<string, string>;
+  },
+): Promise<JsonResponse<T>> {
+  const response = await ctx.app.inject({
+    method: input.method,
+    url: input.url,
+    payload: input.payload,
+    headers: {
+      ...(input.token ? authHeader(input.token) : {}),
+      ...(input.headers ?? {}),
+    },
+  });
+
+  return {
+    statusCode: response.statusCode,
+    body: response.json() as T,
+  };
+}
+
+export async function apiText(
+  ctx: MigrationBookloreE2EContext,
+  input: {
+    method: string;
+    url: string;
+    payload?: unknown;
+    token?: string;
+    headers?: Record<string, string>;
+  },
+): Promise<{ statusCode: number; body: string; headers: Record<string, string | string[] | undefined> }> {
+  const response = await ctx.app.inject({
+    method: input.method,
+    url: input.url,
+    payload: input.payload,
+    headers: {
+      ...(input.token ? authHeader(input.token) : {}),
+      ...(input.headers ?? {}),
+    },
+  });
+
+  return {
+    statusCode: response.statusCode,
+    body: response.body,
+    headers: response.headers,
+  };
+}
+
+export async function createUser(
+  ctx: MigrationBookloreE2EContext,
+  options: {
+    username?: string;
+    password?: string;
+    email?: string;
+    isSuperuser?: boolean;
+    permissions?: Permission[];
+    login?: boolean;
+  } = {},
+): Promise<CreatedUser> {
+  const suffix = randomUUID().replaceAll('-', '');
+  const username = options.username ?? `${TEST_USER_PREFIX}${suffix}`;
+  const password = options.password ?? 'MigrationBooklore123';
+  const email = options.email ?? `${username}@example.com`;
+  const passwordHash = await hash(password, 12);
+
+  const [created] = await ctx.db
+    .insert(schema.users)
+    .values({
+      username,
+      name: `Migration Booklore ${suffix}`,
+      email,
+      passwordHash,
+      isSuperuser: options.isSuperuser ?? false,
+      isDefaultPassword: false,
+      provisioningMethod: 'local',
+    })
+    .returning({ id: schema.users.id });
+
+  if (options.permissions?.length) {
+    await ctx.db.insert(schema.userPermissions).values(options.permissions.map((permissionName) => ({ userId: created.id, permissionName })));
+  }
+
+  const accessToken = options.login ? await loginForToken(ctx, username, password) : undefined;
+  return { id: created.id, username, password, accessToken };
+}
+
+export async function waitForMigrationToFinish(
+  ctx: MigrationBookloreE2EContext,
+  runId: number,
+  timeoutMs = 45_000,
+): Promise<{
+  progress: {
+    run: { id: number; state: string; currentStage: string | null };
+    totals: { processed: number; imported: number; skipped: number; unresolved: number; failed: number };
+    metrics: Array<Record<string, unknown>>;
+  };
+  report: {
+    run: { id: number; state: string; currentStage: string | null };
+    metrics: Array<Record<string, unknown>>;
+    plan: Record<string, unknown> | null;
+    summary: Record<string, unknown> | null;
+  };
+}> {
+  let latestProgress:
+    | {
+        run: { id: number; state: string; currentStage: string | null };
+        totals: { processed: number; imported: number; skipped: number; unresolved: number; failed: number };
+        metrics: Array<Record<string, unknown>>;
+      }
+    | undefined;
+
+  await waitForCondition(
+    async () => {
+      const response = await apiJson<{
+        run: { id: number; state: string; currentStage: string | null };
+        totals: { processed: number; imported: number; skipped: number; unresolved: number; failed: number };
+        metrics: Array<Record<string, unknown>>;
+      }>(ctx, {
+        method: 'GET',
+        url: `/api/v1/migration/runs/${runId}/progress`,
+        token: ctx.adminToken,
+      });
+
+      if (response.statusCode !== 200) {
+        throw new Error(`Unexpected progress response: ${response.statusCode}`);
+      }
+      latestProgress = response.body;
+      if (response.body.run.state === 'running') {
+        throw new Error(`Migration run ${runId} is still running`);
+      }
+    },
+    timeoutMs,
+    200,
+  );
+
+  const reportResponse = await apiJson<{
+    run: { id: number; state: string; currentStage: string | null };
+    metrics: Array<Record<string, unknown>>;
+    plan: Record<string, unknown> | null;
+    summary: Record<string, unknown> | null;
+  }>(ctx, {
+    method: 'GET',
+    url: `/api/v1/migration/runs/${runId}/report`,
+    token: ctx.adminToken,
+  });
+
+  if (reportResponse.statusCode !== 200) {
+    throw new Error(`Unexpected report response: ${reportResponse.statusCode}`);
+  }
+
+  return {
+    progress: latestProgress!,
+    report: reportResponse.body,
+  };
+}
+
+export function coverDirectoryForBook(ctx: MigrationBookloreE2EContext, bookId: number): string {
+  return coverDirPath(ctx.booksPath, bookId);
+}
+
+export function buildBookloreConnectionConfig(
+  ctx: MigrationBookloreE2EContext,
+  overrides: Partial<Record<'host' | 'port' | 'user' | 'password' | 'database' | 'ssl' | 'mediaRootPath', unknown>> = {},
+): Record<string, unknown> {
+  const config: Record<string, unknown> = {
+    host: ctx.mariadb.host,
+    port: ctx.mariadb.port,
+    user: ctx.mariadb.user,
+    password: ctx.mariadb.password,
+    database: ctx.mariadb.database,
+    ssl: false,
+    mediaRootPath: ctx.sourceMediaRoot,
+    ...overrides,
+  };
+
+  if (config.mediaRootPath === null) {
+    delete config.mediaRootPath;
+  }
+
+  return config;
+}
+
+export async function withBookloreConnection<T>(
+  ctx: MigrationBookloreE2EContext,
+  handler: (connection: mysql.Connection) => Promise<T>,
+  options: { root?: boolean; database?: string } = {},
+): Promise<T> {
+  const connection = await mysql.createConnection({
+    host: ctx.mariadb.host,
+    port: ctx.mariadb.port,
+    user: options.root ? 'root' : ctx.mariadb.user,
+    password: options.root ? ctx.mariadb.rootPassword : ctx.mariadb.password,
+    database: options.database ?? ctx.mariadb.database,
+    multipleStatements: true,
+  });
+
+  try {
+    return await handler(connection);
+  } finally {
+    await connection.end();
+  }
+}
+
+async function loginForToken(ctx: MigrationBookloreE2EContext, username: string, password: string): Promise<string> {
+  const response = await ctx.app.inject({
+    method: 'POST',
+    url: '/api/v1/auth/login',
+    payload: { username, password },
+  });
+
+  if (response.statusCode !== 200) {
+    throw new Error(`Login failed for ${username}: ${response.statusCode} ${response.body}`);
+  }
+
+  const body = response.json() as { accessToken?: string };
+  if (!body.accessToken) {
+    throw new Error(`Login returned no accessToken for ${username}`);
+  }
+
+  return body.accessToken;
+}
+
+async function startMariaDbContainer(): Promise<MariaDbService> {
+  await runCommand('docker', ['version', '--format', '{{.Server.Version}}']);
+
+  const containerName = `projectx-migration-booklore-${randomUUID()}`;
+  const database = 'booklore';
+  const user = 'booklore';
+  const password = 'booklore-secret';
+  const rootPassword = 'root-secret';
+
+  await runCommand('docker', [
+    'run',
+    '--rm',
+    '-d',
+    '--name',
+    containerName,
+    '-e',
+    `MARIADB_DATABASE=${database}`,
+    '-e',
+    `MARIADB_USER=${user}`,
+    '-e',
+    `MARIADB_PASSWORD=${password}`,
+    '-e',
+    `MARIADB_ROOT_PASSWORD=${rootPassword}`,
+    '-p',
+    '127.0.0.1::3306',
+    'mariadb:11.4',
+    '--character-set-server=utf8mb4',
+    '--collation-server=utf8mb4_unicode_ci',
+  ]);
+
+  const portText = await runCommand('docker', ['inspect', '-f', '{{(index (index .NetworkSettings.Ports "3306/tcp") 0).HostPort}}', containerName]);
+  const port = Number(portText.trim());
+
+  if (!Number.isFinite(port) || port < 1) {
+    throw new Error(`Could not resolve MariaDB port for container ${containerName}`);
+  }
+
+  const service: MariaDbService = {
+    containerName,
+    host: '127.0.0.1',
+    port,
+    database,
+    user,
+    password,
+    rootPassword,
+  };
+
+  await waitForCondition(
+    async () => {
+      const connection = await mysql.createConnection({
+        host: service.host,
+        port: service.port,
+        user: 'root',
+        password: service.rootPassword,
+      });
+      try {
+        await connection.query('SELECT 1');
+      } finally {
+        await connection.end();
+      }
+    },
+    60_000,
+    1_000,
+  );
+
+  return service;
+}
+
+async function stopMariaDbContainer(service: MariaDbService): Promise<void> {
+  await runCommand('docker', ['rm', '-f', service.containerName], true);
+}
+
+async function resetBookloreDatabase(service: MariaDbService): Promise<void> {
+  const connection = await mysql.createConnection({
+    host: service.host,
+    port: service.port,
+    user: 'root',
+    password: service.rootPassword,
+    multipleStatements: true,
+  });
+
+  try {
+    await connection.query(`DROP DATABASE IF EXISTS \`${service.database}\``);
+    await connection.query(`CREATE DATABASE \`${service.database}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+    await connection.query(`GRANT ALL PRIVILEGES ON \`${service.database}\`.* TO '${service.user}'@'%'`);
+    await connection.query('FLUSH PRIVILEGES');
+  } finally {
+    await connection.end();
+  }
+}
+
+async function runCommand(command: string, args: string[], allowFailure = false): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.once('error', (error) => {
+      reject(error);
+    });
+
+    child.once('exit', (code) => {
+      if (code === 0 || allowFailure) {
+        resolve(stdout.trim());
+        return;
+      }
+
+      reject(new Error(`${command} ${args.join(' ')} failed: ${stderr.trim() || stdout.trim() || `exit code ${code ?? 'unknown'}`}`));
+    });
+  });
+}
+
+async function truncateScenarioTables(db: Db): Promise<void> {
+  await db.execute(
+    sql.raw(`
+      TRUNCATE TABLE
+        migration_run_metrics,
+        migration_runs,
+        migration_plan_artifacts,
+        migration_profiles,
+        migration_sources,
+        collection_books,
+        collections,
+        annotations,
+        bookmarks,
+        audiobook_progress,
+        reading_progress,
+        user_book_status,
+        reader_preferences,
+        reader_default_preferences,
+        reading_sessions,
+        user_reading_daily_stats,
+        book_tags,
+        tags,
+        book_genres,
+        genres,
+        book_narrators,
+        narrators,
+        book_authors,
+        authors,
+        book_metadata,
+        book_files,
+        books,
+        library_folders,
+        libraries
+      RESTART IDENTITY CASCADE
+    `),
+  );
+}
+
+async function deleteTestUsers(db: Db): Promise<void> {
+  await db.execute(sql.raw(`DELETE FROM user_permissions WHERE user_id IN (SELECT id FROM users WHERE username LIKE '${TEST_USER_PREFIX}%')`));
+  await db.execute(sql.raw(`DELETE FROM user_library_access WHERE user_id IN (SELECT id FROM users WHERE username LIKE '${TEST_USER_PREFIX}%')`));
+  await db.execute(sql.raw(`DELETE FROM refresh_tokens WHERE user_id IN (SELECT id FROM users WHERE username LIKE '${TEST_USER_PREFIX}%')`));
+  await db.execute(sql.raw(`DELETE FROM password_reset_tokens WHERE user_id IN (SELECT id FROM users WHERE username LIKE '${TEST_USER_PREFIX}%')`));
+  await db.execute(sql.raw(`DELETE FROM users WHERE username LIKE '${TEST_USER_PREFIX}%'`));
+}
+
+async function resetDirectory(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true });
+  await mkdir(path, { recursive: true });
+}
+
+function restoreEnv(snapshot: EnvSnapshot): void {
+  process.env.BOOKS_PATH = snapshot.booksPath;
+  process.env.MIGRATION_ENCRYPTION_KEY = snapshot.migrationEncryptionKey;
+}
+
+export { seedLibrary };
diff --git a/server/test/migration-booklore.e2e-spec.ts b/server/test/migration-booklore.e2e-spec.ts
new file mode 100644
index 000000000..6fd1dfc82
--- /dev/null
+++ b/server/test/migration-booklore.e2e-spec.ts
@@ -0,0 +1,1060 @@
+import { access, readFile } from 'fs/promises';
+import { join } from 'path';
+import { eq, inArray } from 'drizzle-orm';
+
+import * as schema from '../src/db/schema';
+import { assertNoIntegrityViolations } from './e2e/app-harness';
+import {
+  apiJson,
+  apiText,
+  buildBookloreConnectionConfig,
+  closeMigrationBookloreE2EContext,
+  coverDirectoryForBook,
+  createMigrationBookloreE2EContext,
+  createUser,
+  resetMigrationBookloreState,
+  type MigrationBookloreE2EContext,
+  waitForMigrationToFinish,
+} from './e2e/migration-booklore/migration-booklore-harness';
+import {
+  seedCanonicalScenario,
+  seedCompatibilityScenario,
+  seedMissingRequiredTablesScenario,
+  seedWarningsOnlyScenario,
+} from './e2e/migration-booklore/migration-booklore-fixture-builder';
+
+interface MetricRow {
+  stage: string;
+  entityType: string;
+  processed: number;
+  imported: number;
+  skipped: number;
+  unresolved: number;
+  failed: number;
+  updatedAt: string;
+}
+
+describe('Migration Booklore API to DB (e2e)', { timeout: 240_000 }, () => {
+  let ctx: MigrationBookloreE2EContext | null = null;
+
+  beforeAll(async () => {
+    ctx = await createMigrationBookloreE2EContext();
+  }, 60_000);
+
+  beforeEach(async () => {
+    if (!ctx) throw new Error('Migration Booklore test context failed to initialize');
+    await resetMigrationBookloreState(ctx);
+  }, 60_000);
+
+  afterAll(async () => {
+    if (!ctx) return;
+    await closeMigrationBookloreE2EContext(ctx);
+  }, 60_000);
+
+  it('imports canonical Booklore data from API through Postgres and covers', async () => {
+    const scenario = await seedCanonicalScenario(ctx);
+
+    const supportedTypes = await apiJson<string[]>(ctx, {
+      method: 'GET',
+      url: '/api/v1/migration/supported-types',
+      token: ctx.adminToken,
+    });
+    expect(supportedTypes.statusCode).toBe(200);
+    expect(supportedTypes.body).toEqual(['booklore']);
+
+    const testedSource = await apiJson<{
+      ok: boolean;
+      sourceType: string;
+      warnings: string[];
+      counts: Record<string, number>;
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources/test',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(testedSource.statusCode).toBe(201);
+    expect(testedSource.body.ok).toBe(true);
+    expect(testedSource.body.sourceType).toBe('booklore');
+    expect(testedSource.body.warnings).toEqual([]);
+    expect(testedSource.body.counts.book).toBe(7);
+
+    const createdSource = await apiJson<{
+      id: number;
+      type: string;
+      name: string;
+      connectionConfig: Record<string, unknown>;
+      lastValidatedAt: string | null;
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        name: 'Canonical Booklore',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(createdSource.statusCode).toBe(201);
+    expect(createdSource.body.connectionConfig).toMatchObject({
+      host: '127.0.0.1',
+      user: 'booklore',
+      database: 'booklore',
+      password: '********',
+      mediaRootPath: ctx.sourceMediaRoot,
+    });
+
+    const sourceId = createdSource.body.id;
+
+    const validatedSource = await apiJson<{
+      ok: boolean;
+      missingTables: string[];
+      warnings: string[];
+    }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${sourceId}/validate`,
+      token: ctx.adminToken,
+    });
+    expect(validatedSource.statusCode).toBe(200);
+    expect(validatedSource.body.ok).toBe(true);
+    expect(validatedSource.body.missingTables).toEqual([]);
+    expect(validatedSource.body.warnings).toEqual([]);
+
+    const sourcePrefixes = await apiJson<{ prefixes: string[] }>(ctx, {
+      method: 'GET',
+      url: `/api/v1/migration/sources/${sourceId}/path-prefixes`,
+      token: ctx.adminToken,
+    });
+    expect(sourcePrefixes.statusCode).toBe(200);
+    expect(sourcePrefixes.body.prefixes).toEqual(['/booklore-media/library']);
+
+    const suggestions = await apiJson<{
+      sourceId: number;
+      suggestions: Array<{
+        sourceUserId: string;
+        suggestedTargetUserId: number | null;
+        confidence: string | null;
+      }>;
+    }>(ctx, {
+      method: 'GET',
+      url: `/api/v1/migration/sources/${sourceId}/user-mapping-suggestions`,
+      token: ctx.adminToken,
+    });
+    expect(suggestions.statusCode).toBe(200);
+    expect(suggestions.body.sourceId).toBe(sourceId);
+    expect(suggestions.body.suggestions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          sourceUserId: '1',
+          suggestedTargetUserId: scenario.targetUsers.alice.id,
+          confidence: 'high',
+        }),
+        expect.objectContaining({
+          sourceUserId: '2',
+          suggestedTargetUserId: scenario.targetUsers.bob.id,
+          confidence: 'high',
+        }),
+      ]),
+    );
+
+    const profile = await apiJson<{
+      id: number;
+      sourceId: number;
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/profiles',
+      token: ctx.adminToken,
+      payload: {
+        sourceId,
+        name: 'Canonical Profile',
+        userMappings: [
+          { sourceUserId: '1', targetUserId: scenario.targetUsers.alice.id },
+          { sourceUserId: '2', targetUserId: scenario.targetUsers.bob.id },
+        ],
+        pathMappings: scenario.pathMappings,
+      },
+    });
+    expect(profile.statusCode).toBe(201);
+    expect(profile.body.sourceId).toBe(sourceId);
+
+    const pathValidation = await apiJson<{
+      sourceId: number;
+      persistedProfileId: number | null;
+      summary: {
+        totalSourceBooks: number;
+        booksWithFilePath: number;
+        mappedByPrefix: number;
+        matchedTargetPaths: number;
+        unmatchedTargetPaths: number;
+      };
+    }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${sourceId}/path-mappings/validate`,
+      token: ctx.adminToken,
+      payload: {
+        pathMappings: scenario.pathMappings,
+        sampleLimit: 5,
+      },
+    });
+    expect(pathValidation.statusCode).toBe(201);
+    expect(pathValidation.body.sourceId).toBe(sourceId);
+    expect(pathValidation.body.persistedProfileId).toBe(profile.body.id);
+    expect(pathValidation.body.summary.totalSourceBooks).toBe(7);
+    expect(pathValidation.body.summary.booksWithFilePath).toBe(7);
+    expect(pathValidation.body.summary.mappedByPrefix).toBe(2);
+    expect(pathValidation.body.summary.matchedTargetPaths).toBe(2);
+    expect(pathValidation.body.summary.unmatchedTargetPaths).toBe(5);
+
+    const dryRun = await apiJson<{
+      id: number;
+      profileId: number;
+      plan: {
+        duplicateBookMatches: Array<{ targetBookId: number; sourceBookIds: string[] }>;
+      };
+      summary: {
+        status: string;
+        matchedBooks: number;
+        unresolvedBooks: number;
+        duplicateBookMatches: number;
+        perUserPreview: Array<{
+          sourceUserId: string;
+          targetUserId: number;
+          counts: { statuses: number; fileProgress: number; bookmarks: number; annotations: number; shelves: number };
+        }>;
+      };
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/plans/dry-run',
+      token: ctx.adminToken,
+      payload: {
+        profileId: profile.body.id,
+      },
+    });
+    expect(dryRun.statusCode).toBe(201);
+    expect(dryRun.body.profileId).toBe(profile.body.id);
+    expect(dryRun.body.summary.status).toBe('blocked');
+    expect(dryRun.body.summary.matchedBooks).toBe(4);
+    expect(dryRun.body.summary.unresolvedBooks).toBe(1);
+    expect(dryRun.body.summary.duplicateBookMatches).toBe(1);
+    expect(dryRun.body.plan.duplicateBookMatches).toEqual([
+      expect.objectContaining({
+        targetBookId: scenario.books.duplicate.bookId,
+        sourceBookIds: [scenario.sourceBookIds.duplicatePreferred, scenario.sourceBookIds.duplicateRejected],
+      }),
+    ]);
+    expect(dryRun.body.summary.perUserPreview).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          sourceUserId: '1',
+          targetUserId: scenario.targetUsers.alice.id,
+          counts: expect.objectContaining({
+            statuses: 1,
+            fileProgress: 2,
+            bookmarks: 1,
+            annotations: 1,
+            shelves: 2,
+          }),
+        }),
+        expect.objectContaining({
+          sourceUserId: '2',
+          targetUserId: scenario.targetUsers.bob.id,
+          counts: expect.objectContaining({
+            statuses: 1,
+            fileProgress: 1,
+            bookmarks: 1,
+            annotations: 1,
+            shelves: 1,
+          }),
+        }),
+      ]),
+    );
+
+    const blockedRun = await apiJson<{ message: string }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/runs/live',
+      token: ctx.adminToken,
+      payload: { planArtifactId: dryRun.body.id },
+    });
+    expectError(blockedRun, 400, 'duplicate target book matches');
+
+    const resolvedPlan = await apiJson<{
+      id: number;
+      summary: {
+        status: string;
+        matchedBooks: number;
+        unresolvedBooks: number;
+        duplicateBookMatches: number;
+        unresolvedByReason: Record<string, number>;
+      };
+      plan: {
+        duplicateBookMatches: unknown[];
+      };
+    }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/plans/${dryRun.body.id}/resolve-duplicates`,
+      token: ctx.adminToken,
+      payload: {
+        resolutions: [{ targetBookId: scenario.books.duplicate.bookId, selectedSourceBookId: scenario.sourceBookIds.duplicatePreferred }],
+      },
+    });
+    expect(resolvedPlan.statusCode).toBe(200);
+    expect(resolvedPlan.body.summary.status).toBe('ready_for_live_run');
+    expect(resolvedPlan.body.summary.matchedBooks).toBe(5);
+    expect(resolvedPlan.body.summary.unresolvedBooks).toBe(2);
+    expect(resolvedPlan.body.summary.duplicateBookMatches).toBe(0);
+    expect(resolvedPlan.body.summary.unresolvedByReason).toEqual({
+      no_title_author_match: 1,
+      duplicate_target_match: 1,
+    });
+    expect(resolvedPlan.body.plan.duplicateBookMatches).toEqual([]);
+
+    const startedRun = await apiJson<{
+      id: number;
+      state: string;
+      currentStage: string | null;
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/runs/live',
+      token: ctx.adminToken,
+      payload: { planArtifactId: resolvedPlan.body.id },
+    });
+    expect(startedRun.statusCode).toBe(201);
+    expect(startedRun.body.state).toBe('running');
+    expect(startedRun.body.currentStage).toBe('init');
+
+    const finished = await waitForMigrationToFinish(ctx, startedRun.body.id);
+    expect(finished.progress.run.state).toBe('completed');
+    expect(finished.report.run.state).toBe('completed');
+    expect(finished.report.plan).not.toBeNull();
+    expect(finished.report.summary).not.toBeNull();
+
+    const workflowState = await apiJson<{
+      active: {
+        source: { id: number; connectionConfig: Record<string, unknown> };
+        profile: { id: number } | null;
+        plan: { id: number } | null;
+        run: { id: number; state: string } | null;
+      } | null;
+      hasActiveRun: boolean;
+    }>(ctx, {
+      method: 'GET',
+      url: '/api/v1/migration/state',
+      token: ctx.adminToken,
+    });
+    expect(workflowState.statusCode).toBe(200);
+    expect(workflowState.body.hasActiveRun).toBe(false);
+    expect(workflowState.body.active).toEqual(
+      expect.objectContaining({
+        source: expect.objectContaining({
+          id: sourceId,
+          connectionConfig: expect.objectContaining({
+            host: '127.0.0.1',
+            user: 'booklore',
+            password: '********',
+          }),
+        }),
+        profile: expect.objectContaining({ id: profile.body.id }),
+        plan: expect.objectContaining({ id: resolvedPlan.body.id }),
+        run: expect.objectContaining({ id: startedRun.body.id, state: 'completed' }),
+      }),
+    );
+
+    const jsonExport = await apiText(ctx, {
+      method: 'GET',
+      url: `/api/v1/migration/runs/${startedRun.body.id}/report/export?format=json`,
+      token: ctx.adminToken,
+    });
+    expect(jsonExport.statusCode).toBe(200);
+    expect(jsonExport.headers['content-type']).toContain('application/json');
+    expect(jsonExport.body).toContain('"state": "completed"');
+
+    const csvExport = await apiText(ctx, {
+      method: 'GET',
+      url: `/api/v1/migration/runs/${startedRun.body.id}/report/export?format=csv`,
+      token: ctx.adminToken,
+    });
+    expect(csvExport.statusCode).toBe(200);
+    expect(csvExport.headers['content-type']).toContain('text/csv');
+    expect(csvExport.body).toContain('section,stage,entityType,processed,imported,skipped,unresolved,failed,code,message,createdAt');
+
+    const metricByKey = buildMetricMap(finished.report.metrics as MetricRow[]);
+    expect(metricByKey.get('shared_overlays:book_metadata')).toMatchObject({
+      processed: 5,
+      imported: 5,
+      skipped: 0,
+      unresolved: 0,
+      failed: 0,
+    });
+    expect(metricByKey.get('shared_overlays:book_authors')).toMatchObject({
+      processed: 5,
+      imported: 7,
+    });
+    expect(metricByKey.get('shared_overlays:book_narrators')).toMatchObject({
+      processed: 5,
+      imported: 4,
+    });
+    expect(metricByKey.get('shared_overlays:book_genres')).toMatchObject({
+      processed: 5,
+      imported: 3,
+    });
+    expect(metricByKey.get('shared_overlays:book_tags')).toMatchObject({
+      processed: 5,
+      imported: 3,
+    });
+    expect(metricByKey.get('book_covers:book_covers')).toMatchObject({
+      processed: 5,
+      imported: 2,
+      unresolved: 3,
+      failed: 0,
+    });
+    expect(metricByKey.get('user_state:user_book_status')).toMatchObject({
+      processed: 4,
+      imported: 3,
+      unresolved: 1,
+    });
+    expect(metricByKey.get('user_state:reading_progress')).toMatchObject({
+      processed: 4,
+      imported: 3,
+      unresolved: 1,
+    });
+    expect(metricByKey.get('user_state:audiobook_progress')).toMatchObject({
+      processed: 1,
+      imported: 1,
+    });
+    expect(metricByKey.get('user_state:bookmarks')).toMatchObject({
+      processed: 2,
+      imported: 2,
+    });
+    expect(metricByKey.get('user_state:annotations')).toMatchObject({
+      processed: 2,
+      imported: 2,
+    });
+    expect(metricByKey.get('user_state:collections')).toMatchObject({
+      processed: 3,
+      imported: 3,
+    });
+
+    const metadataRows = await ctx.db
+      .select()
+      .from(schema.bookMetadata)
+      .where(
+        inArray(schema.bookMetadata.bookId, [
+          scenario.books.isbn.bookId,
+          scenario.books.hash.bookId,
+          scenario.books.audio.bookId,
+          scenario.books.titleAuthor.bookId,
+          scenario.books.duplicate.bookId,
+        ]),
+      );
+    const metadataByBookId = new Map(metadataRows.map((row) => [row.bookId, row]));
+
+    expect(metadataByBookId.get(scenario.books.isbn.bookId)).toMatchObject({
+      title: 'Imported ISBN Title',
+      subtitle: 'Imported Subtitle',
+      description: 'Long imported description',
+      isbn10: '1234567890',
+      isbn13: '9781111111111',
+      publisher: 'Imported Publisher',
+      publishedYear: 2021,
+      language: 'en',
+      pageCount: 321,
+      seriesName: 'Series Prime',
+      seriesIndex: 2.5,
+      rating: 5,
+      googleBooksId: 'google-101',
+      goodreadsId: 'gr-101',
+      amazonId: 'ASIN101',
+      hardcoverId: 'hc-101',
+      audibleId: 'aud-101',
+      comicvineId: 'cv-101',
+      durationSeconds: 11111,
+      abridged: true,
+      coverSource: 'custom',
+    });
+    expect(metadataByBookId.get(scenario.books.hash.bookId)).toMatchObject({
+      title: 'Imported Hash Title',
+      description: 'Hash description',
+      subtitle: null,
+      rating: null,
+      googleBooksId: null,
+    });
+    expect(metadataByBookId.get(scenario.books.audio.bookId)).toMatchObject({
+      title: 'Audio Path Match',
+      description: 'Audio description',
+      publisher: 'Audio Publisher',
+      audibleId: 'audio-id-103',
+      durationSeconds: 300,
+      abridged: true,
+      coverSource: 'custom',
+    });
+    expect(metadataByBookId.get(scenario.books.titleAuthor.bookId)?.title).toBe('Title Author Match');
+    expect(metadataByBookId.get(scenario.books.duplicate.bookId)?.title).toBe('Duplicate Preferred');
+
+    await expectContributorNames(ctx, scenario.books.isbn.bookId, 'author', ['Jane Primary', 'John Secondary']);
+    await expectContributorNames(ctx, scenario.books.audio.bookId, 'author', ['Audio Author', 'Guest Author']);
+    await expectContributorNames(ctx, scenario.books.titleAuthor.bookId, 'author', ['Unique Title Author']);
+    await expectContributorNames(ctx, scenario.books.audio.bookId, 'narrator', ['Narrator Alpha', 'Narrator Beta']);
+
+    expect(await loadNamesForBook(ctx, scenario.books.isbn.bookId, 'genre')).toEqual(['Adventure', 'Fantasy']);
+    expect(await loadNamesForBook(ctx, scenario.books.isbn.bookId, 'tag')).toEqual(['Imported Tag 1', 'Imported Tag 2']);
+    expect(await loadNamesForBook(ctx, scenario.books.hash.bookId, 'tag')).toEqual(['Hash Imported Tag']);
+
+    const statusRows = await ctx.db.select().from(schema.userBookStatus);
+    expect(statusRows).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookId: scenario.books.isbn.bookId,
+          status: 'read',
+          source: 'manual',
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.bob.id,
+          bookId: scenario.books.audio.bookId,
+          status: 'reading',
+          source: 'manual',
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookId: scenario.books.duplicate.bookId,
+          status: 'want_to_read',
+          source: 'manual',
+        }),
+      ]),
+    );
+    expect(statusRows.some((row) => row.userId !== scenario.targetUsers.alice.id && row.userId !== scenario.targetUsers.bob.id)).toBe(false);
+
+    const progressRows = await ctx.db.select().from(schema.readingProgress);
+    expect(progressRows).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookFileId: scenario.books.isbn.primaryFileId,
+          percentage: 33.3,
+          cfi: 'epubcfi(/6/2[chap]!/4/1:0)',
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookFileId: scenario.books.hash.primaryFileId,
+          percentage: 22.4,
+          pageNumber: 10,
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.bob.id,
+          bookFileId: scenario.books.audio.fileIds[1],
+          percentage: 66,
+          positionSeconds: 12.5,
+        }),
+      ]),
+    );
+    expect(progressRows).toHaveLength(3);
+
+    const audioProgressRows = await ctx.db.select().from(schema.audiobookProgress);
+    expect(audioProgressRows).toEqual([
+      expect.objectContaining({
+        userId: scenario.targetUsers.bob.id,
+        bookId: scenario.books.audio.bookId,
+        currentFileId: scenario.books.audio.fileIds[1],
+        percentage: 66,
+        positionSeconds: 12.5,
+      }),
+    ]);
+
+    const bookmarks = await ctx.db.select().from(schema.bookmarks);
+    expect(bookmarks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookId: scenario.books.isbn.bookId,
+          title: 'Chapter 1',
+          cfi: 'epubcfi(/6/2[chap]!/4/1:0)',
+          positionSeconds: null,
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.bob.id,
+          bookId: scenario.books.audio.bookId,
+          title: 'Imported bookmark',
+          cfi: null,
+          positionSeconds: 135,
+        }),
+      ]),
+    );
+
+    const annotations = await ctx.db.select().from(schema.annotations);
+    expect(annotations).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          userId: scenario.targetUsers.alice.id,
+          bookId: scenario.books.isbn.bookId,
+          color: 'blue',
+          style: 'underline',
+          note: 'remember this',
+          chapterTitle: 'Chapter One',
+        }),
+        expect.objectContaining({
+          userId: scenario.targetUsers.bob.id,
+          bookId: scenario.books.titleAuthor.bookId,
+          color: 'yellow',
+          style: 'highlight',
+          note: null,
+          chapterTitle: null,
+        }),
+      ]),
+    );
+
+    const importedCollections = await ctx.db.select().from(schema.collections).where(eq(schema.collections.userId, scenario.targetUsers.alice.id));
+    expect(importedCollections).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'Favorites', description: 'Existing favorites collection' }),
+        expect.objectContaining({
+          name: 'Favorites (Booklore)',
+          description: 'Imported from Booklore migration shelf: 501',
+        }),
+      ]),
+    );
+
+    const importedFavorites = importedCollections.find((row) => row.description === 'Imported from Booklore migration shelf: 501');
+    expect(importedFavorites).toBeDefined();
+    const importedCollectionBooks = await ctx.db
+      .select()
+      .from(schema.collectionBooks)
+      .where(eq(schema.collectionBooks.collectionId, importedFavorites!.id));
+    expect(importedCollectionBooks.map((row) => row.bookId).sort((left, right) => left - right)).toEqual(
+      [scenario.books.isbn.bookId, scenario.books.titleAuthor.bookId].sort((left, right) => left - right),
+    );
+
+    const isbnCoverDir = coverDirectoryForBook(ctx, scenario.books.isbn.bookId);
+    const audioCoverDir = coverDirectoryForBook(ctx, scenario.books.audio.bookId);
+    await access(join(isbnCoverDir, 'cover_custom.jpg'));
+    await access(join(isbnCoverDir, 'thumbnail.jpg'));
+    await access(join(audioCoverDir, 'cover_custom.png'));
+    await access(join(audioCoverDir, 'thumbnail.jpg'));
+
+    const audioCoverBytes = await readFile(join(audioCoverDir, 'cover_custom.png'));
+    expect(audioCoverBytes[0]).toBe(0x89);
+    expect(audioCoverBytes[1]).toBe(0x50);
+
+    await assertNoIntegrityViolations(ctx.db);
+  });
+
+  it('supports alternate Booklore schema variants and join-through file progress', async () => {
+    const scenario = await seedCompatibilityScenario(ctx);
+
+    const createdSource = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        name: 'Compatibility Booklore',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(createdSource.statusCode).toBe(201);
+
+    const validatedSource = await apiJson<{ ok: boolean }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${createdSource.body.id}/validate`,
+      token: ctx.adminToken,
+    });
+    expect(validatedSource.statusCode).toBe(200);
+    expect(validatedSource.body.ok).toBe(true);
+
+    const profile = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/profiles',
+      token: ctx.adminToken,
+      payload: {
+        sourceId: createdSource.body.id,
+        name: 'Compatibility Profile',
+        userMappings: [{ sourceUserId: '41', targetUserId: scenario.targetUser.id }],
+        pathMappings: scenario.pathMappings,
+      },
+    });
+    expect(profile.statusCode).toBe(201);
+
+    const validatedMappings = await apiJson<{ persistedProfileId: number | null }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${createdSource.body.id}/path-mappings/validate`,
+      token: ctx.adminToken,
+      payload: {
+        pathMappings: scenario.pathMappings,
+      },
+    });
+    expect(validatedMappings.statusCode).toBe(201);
+    expect(validatedMappings.body.persistedProfileId).toBe(profile.body.id);
+
+    const dryRun = await apiJson<{ id: number; summary: { status: string; matchedBooks: number } }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/plans/dry-run',
+      token: ctx.adminToken,
+      payload: { profileId: profile.body.id },
+    });
+    expect(dryRun.statusCode).toBe(201);
+    expect(dryRun.body.summary).toMatchObject({
+      status: 'ready_for_live_run',
+      matchedBooks: 1,
+    });
+
+    const startedRun = await apiJson<{ id: number; state: string }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/runs/live',
+      token: ctx.adminToken,
+      payload: { planArtifactId: dryRun.body.id },
+    });
+    expect(startedRun.statusCode).toBe(201);
+    expect(startedRun.body.state).toBe('running');
+
+    await waitForMigrationToFinish(ctx, startedRun.body.id);
+
+    const metadata = await ctx.db.query.bookMetadata.findFirst({
+      where: eq(schema.bookMetadata.bookId, scenario.book.bookId),
+    });
+    expect(metadata).toMatchObject({
+      title: 'Variant Imported Title',
+      subtitle: 'Keep this subtitle',
+      description: 'Variant imported description',
+      isbn10: '0123456789',
+      isbn13: '9780000000401',
+      publisher: 'Variant Publisher',
+      publishedYear: 2022,
+      language: 'en',
+      pageCount: 222,
+      seriesName: 'Variant Series',
+      seriesIndex: 1.25,
+      rating: 4,
+      googleBooksId: 'variant-google-id',
+      durationSeconds: 987,
+      abridged: false,
+    });
+
+    await expectContributorNames(ctx, scenario.book.bookId, 'author', ['Variant Author', 'Second Variant Author']);
+    await expectContributorNames(ctx, scenario.book.bookId, 'narrator', ['Narrator Gamma', 'Narrator Delta']);
+
+    const userStatus = await ctx.db.query.userBookStatus.findFirst({
+      where: eq(schema.userBookStatus.bookId, scenario.book.bookId),
+    });
+    expect(userStatus).toMatchObject({
+      userId: scenario.targetUser.id,
+      status: 'on_hold',
+      source: 'manual',
+    });
+
+    const readingProgress = await ctx.db.query.readingProgress.findFirst({
+      where: eq(schema.readingProgress.bookFileId, scenario.book.primaryFileId),
+    });
+    expect(readingProgress).toMatchObject({
+      userId: scenario.targetUser.id,
+      percentage: 78,
+      cfi: 'epubcfi(/6/10!/4/2:20)',
+      pageNumber: 9,
+      positionSeconds: 6.5,
+    });
+
+    const bookmarks = await ctx.db.select().from(schema.bookmarks).where(eq(schema.bookmarks.bookId, scenario.book.bookId));
+    expect(bookmarks).toEqual([
+      expect.objectContaining({
+        userId: scenario.targetUser.id,
+        title: 'Variant bookmark',
+        cfi: 'epubcfi(/6/12!/4/2:1)',
+        positionSeconds: 2.5,
+      }),
+    ]);
+  });
+
+  it('fails validation and source creation when required Booklore tables are missing', async () => {
+    const connectionConfig = await seedMissingRequiredTablesScenario(ctx);
+
+    const testedSource = await apiJson<{
+      ok: boolean;
+      missingTables: string[];
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources/test',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        connectionConfig,
+      },
+    });
+    expect(testedSource.statusCode).toBe(201);
+    expect(testedSource.body.ok).toBe(false);
+    expect(testedSource.body.missingTables).toContain('book_file');
+
+    const createdSource = await apiJson<{ message: string }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        name: 'Missing Tables',
+        connectionConfig,
+      },
+    });
+    expectError(createdSource, 400, 'Missing required tables');
+  });
+
+  it('runs safely with optional domains missing and records warnings plus skipped metrics', async () => {
+    const scenario = await seedWarningsOnlyScenario(ctx);
+
+    const testedSource = await apiJson<{
+      ok: boolean;
+      warnings: string[];
+    }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources/test',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(testedSource.statusCode).toBe(201);
+    expect(testedSource.body.ok).toBe(true);
+    expect(testedSource.body.warnings).toEqual(
+      expect.arrayContaining([
+        'book_metadata table not found; metadata overlays will be limited',
+        'author mapping tables not found; author migration disabled',
+        'user_book_progress table not found; status migration disabled',
+        'book_marks table not found; bookmark migration disabled',
+        'mediaRootPath not configured; book cover/thumbnail import disabled',
+      ]),
+    );
+
+    const source = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        name: 'Warnings Source',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(source.statusCode).toBe(201);
+
+    const validatedSource = await apiJson<{ ok: boolean }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${source.body.id}/validate`,
+      token: ctx.adminToken,
+    });
+    expect(validatedSource.statusCode).toBe(200);
+    expect(validatedSource.body.ok).toBe(true);
+
+    const profile = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/profiles',
+      token: ctx.adminToken,
+      payload: {
+        sourceId: source.body.id,
+        name: 'Warnings Profile',
+        userMappings: [{ sourceUserId: '91', targetUserId: scenario.targetUser.id }],
+        pathMappings: [],
+      },
+    });
+    expect(profile.statusCode).toBe(201);
+
+    const dryRun = await apiJson<{ id: number; summary: { status: string; matchedBooks: number } }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/plans/dry-run',
+      token: ctx.adminToken,
+      payload: { profileId: profile.body.id },
+    });
+    expect(dryRun.statusCode).toBe(201);
+    expect(dryRun.body.summary).toMatchObject({
+      status: 'ready_for_live_run',
+      matchedBooks: 1,
+    });
+
+    const startedRun = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/runs/live',
+      token: ctx.adminToken,
+      payload: { planArtifactId: dryRun.body.id },
+    });
+    expect(startedRun.statusCode).toBe(201);
+
+    const finished = await waitForMigrationToFinish(ctx, startedRun.body.id);
+    const metricByKey = buildMetricMap(finished.report.metrics as MetricRow[]);
+
+    expect(metricByKey.get('shared_overlays:book_metadata')).toMatchObject({
+      processed: 1,
+      imported: 0,
+      skipped: 1,
+    });
+    expect(metricByKey.get('shared_overlays:book_authors')).toMatchObject({
+      processed: 1,
+      imported: 0,
+      skipped: 1,
+    });
+    expect(metricByKey.get('book_covers:book_covers')).toMatchObject({
+      processed: 1,
+      imported: 0,
+      skipped: 1,
+      unresolved: 0,
+    });
+    expect(metricByKey.get('user_state:user_book_status')).toMatchObject({
+      processed: 0,
+      imported: 0,
+      skipped: 0,
+      unresolved: 0,
+    });
+
+    expect(await ctx.db.select().from(schema.userBookStatus)).toHaveLength(0);
+    expect(await ctx.db.select().from(schema.bookmarks)).toHaveLength(0);
+    expect(await ctx.db.select().from(schema.annotations)).toHaveLength(0);
+  });
+
+  it('invalidates dry-run plans after the source is revalidated', async () => {
+    const scenario = await seedWarningsOnlyScenario(ctx);
+
+    const source = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        name: 'Stale Plan Source',
+        connectionConfig: scenario.connectionConfig,
+      },
+    });
+    expect(source.statusCode).toBe(201);
+
+    const profile = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/profiles',
+      token: ctx.adminToken,
+      payload: {
+        sourceId: source.body.id,
+        name: 'Stale Plan Profile',
+        userMappings: [{ sourceUserId: '91', targetUserId: scenario.targetUser.id }],
+      },
+    });
+    expect(profile.statusCode).toBe(201);
+
+    const dryRun = await apiJson<{ id: number }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/plans/dry-run',
+      token: ctx.adminToken,
+      payload: { profileId: profile.body.id },
+    });
+    expect(dryRun.statusCode).toBe(201);
+
+    const revalidated = await apiJson<{ ok: boolean }>(ctx, {
+      method: 'POST',
+      url: `/api/v1/migration/sources/${source.body.id}/validate`,
+      token: ctx.adminToken,
+    });
+    expect(revalidated.statusCode).toBe(200);
+    expect(revalidated.body.ok).toBe(true);
+
+    const startedRun = await apiJson<{ message: string }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/runs/live',
+      token: ctx.adminToken,
+      payload: { planArtifactId: dryRun.body.id },
+    });
+    expectError(startedRun, 404, 'Migration plan artifact not found');
+  });
+
+  it('enforces authz and DTO validation for migration endpoints', async () => {
+    const anonymous = await apiJson<{ message: string }>(ctx, {
+      method: 'GET',
+      url: '/api/v1/migration/state',
+    });
+    expectError(anonymous, 401, 'Unauthorized');
+
+    const regularUser = await createUser(ctx, { login: true });
+    const forbidden = await apiJson<{ message: string }>(ctx, {
+      method: 'GET',
+      url: '/api/v1/migration/state',
+      token: regularUser.accessToken,
+    });
+    expectError(forbidden, 403, 'Missing permission');
+
+    const invalidDto = await apiJson<{ message: string | string[] }>(ctx, {
+      method: 'POST',
+      url: '/api/v1/migration/sources/test',
+      token: ctx.adminToken,
+      payload: {
+        type: 'booklore',
+        connectionConfig: buildBookloreConnectionConfig(ctx),
+        bogus: true,
+      },
+    });
+    expect(invalidDto.statusCode).toBe(400);
+    expect(JSON.stringify(invalidDto.body)).toContain('bogus');
+  });
+});
+
+function buildMetricMap(metrics: MetricRow[]): Map<string, MetricRow> {
+  return new Map(metrics.map((metric) => [`${metric.stage}:${metric.entityType}`, metric]));
+}
+
+function expectError<T>(response: { statusCode: number; body: T }, statusCode: number, messageFragment: string): void {
+  expect(response.statusCode).toBe(statusCode);
+  expect(JSON.stringify(response.body)).toContain(messageFragment);
+}
+
+async function expectContributorNames(
+  ctx: MigrationBookloreE2EContext,
+  bookId: number,
+  type: 'author' | 'narrator',
+  expectedNames: string[],
+): Promise<void> {
+  const names = await loadNamesForBook(ctx, bookId, type);
+  expect(names).toEqual(expectedNames);
+}
+
+async function loadNamesForBook(ctx: MigrationBookloreE2EContext, bookId: number, type: 'author' | 'narrator' | 'genre' | 'tag'): Promise<string[]> {
+  if (type === 'author') {
+    const rows = await ctx.db
+      .select({
+        name: schema.authors.name,
+        displayOrder: schema.bookAuthors.displayOrder,
+      })
+      .from(schema.bookAuthors)
+      .innerJoin(schema.authors, eq(schema.authors.id, schema.bookAuthors.authorId))
+      .where(eq(schema.bookAuthors.bookId, bookId))
+      .orderBy(schema.bookAuthors.displayOrder);
+    return rows.map((row) => row.name);
+  }
+
+  if (type === 'narrator') {
+    const rows = await ctx.db
+      .select({
+        name: schema.narrators.name,
+        displayOrder: schema.bookNarrators.displayOrder,
+      })
+      .from(schema.bookNarrators)
+      .innerJoin(schema.narrators, eq(schema.narrators.id, schema.bookNarrators.narratorId))
+      .where(eq(schema.bookNarrators.bookId, bookId))
+      .orderBy(schema.bookNarrators.displayOrder);
+    return rows.map((row) => row.name);
+  }
+
+  if (type === 'genre') {
+    const rows = await ctx.db
+      .select({
+        name: schema.genres.name,
+      })
+      .from(schema.bookGenres)
+      .innerJoin(schema.genres, eq(schema.genres.id, schema.bookGenres.genreId))
+      .where(eq(schema.bookGenres.bookId, bookId))
+      .orderBy(schema.genres.name);
+    return rows.map((row) => row.name);
+  }
+
+  const rows = await ctx.db
+    .select({
+      name: schema.tags.name,
+    })
+    .from(schema.bookTags)
+    .innerJoin(schema.tags, eq(schema.tags.id, schema.bookTags.tagId))
+    .where(eq(schema.bookTags.bookId, bookId))
+    .orderBy(schema.tags.name);
+  return rows.map((row) => row.name);
+}