From cb783cb0f1ee4a466828e955162ebef001872a4a Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 00:29:26 +0200
Subject: [PATCH 01/27] feat(catalog): browse a peer's catalog on a dedicated
 page

Add a management catalog module that groups a peer's releases into titles,
a /catalog/[peerId] page that lists them, and clickable peer entries.
---
 apps/backend/src/__tests__/catalog.test.ts    | 122 ++++++++++++++++++
 apps/backend/src/management-app.ts            |   5 +
 .../src/modules/catalog/catalog.controller.ts |  32 +++++
 .../src/modules/catalog/catalog.lib.ts        |  80 ++++++++++++
 .../src/modules/catalog/catalog.router.ts     |  17 +++
 apps/ui/app/components/ConnectorCard.vue      |   2 +
 apps/ui/app/components/PeersSection.vue       |   1 +
 apps/ui/app/pages/catalog/[peerId].vue        |  63 +++++++++
 apps/ui/app/pages/index.vue                   |   4 +-
 apps/ui/app/types/management.ts               |  16 +++
 10 files changed, 340 insertions(+), 2 deletions(-)
 create mode 100644 apps/backend/src/__tests__/catalog.test.ts
 create mode 100644 apps/backend/src/modules/catalog/catalog.controller.ts
 create mode 100644 apps/backend/src/modules/catalog/catalog.lib.ts
 create mode 100644 apps/backend/src/modules/catalog/catalog.router.ts
 create mode 100644 apps/ui/app/pages/catalog/[peerId].vue

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
new file mode 100644
index 0000000..30d4052
--- /dev/null
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -0,0 +1,122 @@
+import type { Release } from '../lib/release'
+import { describe, expect, test } from 'bun:test'
+import { NotFoundError } from '../lib/errors/NotFoundError'
+import { CatalogController } from '../modules/catalog/catalog.controller'
+import { groupReleasesIntoTitles } from '../modules/catalog/catalog.lib'
+
+function movie(overrides: Partial<Release> = {}): Release {
+  return {
+    id: `movie:${Math.random()}`,
+    title: 'Movie.2024.1080p',
+    filename: 'Movie.2024.1080p.mkv',
+    category: 2000,
+    size: 100,
+    ...overrides,
+  }
+}
+
+function episode(overrides: Partial<Release> = {}): Release {
+  return {
+    id: `episode:${Math.random()}`,
+    title: 'Show.S01E01.1080p',
+    filename: 'Show.S01E01.1080p.mkv',
+    category: 5000,
+    size: 50,
+    ...overrides,
+  }
+}
+
+describe('groupReleasesIntoTitles', () => {
+  test('groups movie + tv releases by their strong ids', () => {
+    const releases: Release[] = [
+      movie({ tmdbId: 603, size: 100 }),
+      movie({ tmdbId: 603, size: 200, quality: { resolution: 1080 } }),
+      movie({ tmdbId: 603, size: 300, quality: { resolution: 2160 } }),
+      episode({ tvdbId: 1396, seriesTitle: 'Breaking Bad', size: 50 }),
+      episode({ tvdbId: 1396, seriesTitle: 'Breaking Bad', size: 60 }),
+    ]
+
+    const titles = groupReleasesIntoTitles(releases)
+
+    expect(titles).toHaveLength(2)
+
+    const movieTitle = titles.find(t => t.mediaType === 'movie')
+    expect(movieTitle).toBeDefined()
+    expect(movieTitle!.tmdbId).toBe(603)
+    expect(movieTitle!.releaseCount).toBe(3)
+    expect(movieTitle!.totalSize).toBe(600)
+
+    const tvTitle = titles.find(t => t.mediaType === 'tv')
+    expect(tvTitle).toBeDefined()
+    expect(tvTitle!.tvdbId).toBe(1396)
+    expect(tvTitle!.releaseCount).toBe(2)
+    expect(tvTitle!.totalSize).toBe(110)
+    expect(tvTitle!.displayTitle).toBe('Breaking Bad')
+  })
+
+  test('collapses id-less movies with the same title into one name-keyed entry', () => {
+    const releases: Release[] = [
+      movie({ title: 'Foo.2024', size: 100 }),
+      movie({ title: 'Foo.2024', size: 200 }),
+    ]
+
+    const titles = groupReleasesIntoTitles(releases)
+
+    expect(titles).toHaveLength(1)
+    expect(titles[0]!.releaseCount).toBe(2)
+    expect(titles[0]!.totalSize).toBe(300)
+    expect(titles[0]!.key).toContain('name:')
+  })
+
+  test('aliases an id-less tv release into the strong-id bucket of the same series', () => {
+    const releases: Release[] = [
+      episode({ seriesTitle: 'Some Show', size: 50 }),
+      episode({ seriesTitle: 'Some Show', tvdbId: 999, size: 60 }),
+    ]
+
+    const titles = groupReleasesIntoTitles(releases)
+
+    expect(titles).toHaveLength(1)
+    expect(titles[0]!.releaseCount).toBe(2)
+    expect(titles[0]!.tvdbId).toBe(999)
+    expect(titles[0]!.key).toContain('id:999')
+  })
+
+  test('sorts titles by display title', () => {
+    const releases: Release[] = [
+      movie({ title: 'Zebra', tmdbId: 1 }),
+      movie({ title: 'Apple', tmdbId: 2 }),
+    ]
+
+    const titles = groupReleasesIntoTitles(releases)
+
+    expect(titles.map(t => t.displayTitle)).toEqual(['Apple', 'Zebra'])
+  })
+})
+
+describe('catalogController', () => {
+  function makeConnectors(peers: any[]) {
+    return { servers: [], peers }
+  }
+
+  test('returns the peer and its grouped titles', async () => {
+    const peer = {
+      id: 'peer-1',
+      name: 'Friend Jack',
+      listReleases: async () => [movie({ tmdbId: 603 }), movie({ tmdbId: 603 })],
+    }
+    const controller = new CatalogController(makeConnectors([peer]) as any)
+
+    const result = await controller.getPeerCatalog('peer-1')
+
+    expect(result.peer).toEqual({ id: 'peer-1', name: 'Friend Jack' })
+    expect(result.titles).toHaveLength(1)
+    expect(result.titles[0]!.releaseCount).toBe(2)
+  })
+
+  test('throws NotFoundError for an unknown peer id', () => {
+    const controller = new CatalogController(makeConnectors([]) as any)
+
+    expect(controller.getPeerCatalog('missing')).rejects.toBeInstanceOf(NotFoundError)
+  })
+})
diff --git a/apps/backend/src/management-app.ts b/apps/backend/src/management-app.ts
index 2c40b34..082d89f 100644
--- a/apps/backend/src/management-app.ts
+++ b/apps/backend/src/management-app.ts
@@ -8,6 +8,8 @@ import { handleError } from './middleware/handle-error'
 import { requireManagementKey } from './middleware/require-management-key'
 import { ApiKeysController } from './modules/api-keys/api-keys.controller'
 import { getApiKeysRouter } from './modules/api-keys/api-keys.router'
+import { CatalogController } from './modules/catalog/catalog.controller'
+import { getCatalogRouter } from './modules/catalog/catalog.router'
 import { ConfigController } from './modules/config/config.controller'
 import { getConfigRouter } from './modules/config/config.router'
 import { StatusController } from './modules/status/status.controller'
@@ -38,6 +40,9 @@ export function getManagementApp(params: {
   const statusController = new StatusController(params.connectors, params.downloadsRepository)
   app.route('/', getStatusRouter(statusController))
 
+  const catalogController = new CatalogController(params.connectors)
+  app.route('/catalog', getCatalogRouter(catalogController))
+
   if (params.apiKeysRepository) {
     const apiKeysController = new ApiKeysController(params.apiKeysRepository)
     app.route('/api-keys', getApiKeysRouter(apiKeysController))
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
new file mode 100644
index 0000000..821ed68
--- /dev/null
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -0,0 +1,32 @@
+import type { ArrServerConnector } from '../../lib/servers/arr/base'
+import type { PeerConnector } from '../../lib/servers/peer'
+import type { CatalogTitle } from './catalog.lib'
+import { NotFoundError } from '../../lib/errors/NotFoundError'
+import { groupReleasesIntoTitles } from './catalog.lib'
+
+export interface PeerCatalogResponse {
+  peer: { id: string, name: string }
+  titles: CatalogTitle[]
+}
+
+export class CatalogController {
+  constructor(
+    private readonly connectors: { servers: ArrServerConnector[], peers: PeerConnector[] },
+  ) {}
+
+  private requirePeer(peerId: string): PeerConnector {
+    const peer = this.connectors.peers.find(p => p.id === peerId)
+    if (!peer)
+      throw new NotFoundError(`No peer found with id "${peerId}"`)
+    return peer
+  }
+
+  async getPeerCatalog(peerId: string): Promise<PeerCatalogResponse> {
+    const peer = this.requirePeer(peerId)
+    const releases = await peer.listReleases()
+    return {
+      peer: { id: peer.id, name: peer.name },
+      titles: groupReleasesIntoTitles(releases),
+    }
+  }
+}
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
new file mode 100644
index 0000000..31dc21b
--- /dev/null
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -0,0 +1,80 @@
+import type { Release } from '../../lib/release'
+import { ReleaseCategory } from '../../lib/release'
+
+export interface CatalogTitle {
+  // Stable grouping key, also used as the client-side list key.
+  key: string
+  mediaType: 'movie' | 'tv'
+  tmdbId?: number
+  imdbId?: string
+  tvdbId?: number
+  // Best display name available pre-TMDB: series title for tv, else the release/scene title.
+  displayTitle: string
+  releaseCount: number
+  totalSize: number
+}
+
+function mediaTypeOf(release: Release): 'movie' | 'tv' {
+  return release.category === ReleaseCategory.Tv ? 'tv' : 'movie'
+}
+
+/** The strong (id-based) grouping key for a release, or null when it carries no id. */
+function strongKey(release: Release): string | null {
+  const mediaType = mediaTypeOf(release)
+  const id = mediaType === 'tv'
+    ? (release.tvdbId ?? release.tmdbId)
+    : (release.tmdbId ?? release.imdbId)
+  return id == null ? null : `${mediaType}:id:${id}`
+}
+
+/** The fallback (name-based) key for a release with no usable id. */
+function nameKey(release: Release): string {
+  const mediaType = mediaTypeOf(release)
+  const name = (mediaType === 'tv' ? (release.seriesTitle ?? release.title) : release.title).toLowerCase()
+  return `${mediaType}:name:${name}`
+}
+
+/**
+ * Group a peer's flat release list into one entry per movie/series.
+ *
+ * Two passes so a title that appears both WITH and WITHOUT an id still collapses:
+ * pass 1 records, per fallback name, the strong id key seen for it; pass 2 routes
+ * each release to its strong key, else the alias discovered in pass 1, else its name.
+ */
+export function groupReleasesIntoTitles(releases: Release[]): CatalogTitle[] {
+  const nameToStrongKey = new Map<string, string>()
+  for (const release of releases) {
+    const sk = strongKey(release)
+    if (sk && !nameToStrongKey.has(nameKey(release)))
+      nameToStrongKey.set(nameKey(release), sk)
+  }
+
+  const byKey = new Map<string, CatalogTitle>()
+  for (const release of releases) {
+    const key = strongKey(release) ?? nameToStrongKey.get(nameKey(release)) ?? nameKey(release)
+
+    const existing = byKey.get(key)
+    if (existing) {
+      existing.releaseCount += 1
+      existing.totalSize += release.size
+      // Backfill ids if a later release carries one the first lacked.
+      existing.tmdbId ??= release.tmdbId
+      existing.imdbId ??= release.imdbId
+      existing.tvdbId ??= release.tvdbId
+      continue
+    }
+
+    byKey.set(key, {
+      key,
+      mediaType: mediaTypeOf(release),
+      tmdbId: release.tmdbId,
+      imdbId: release.imdbId,
+      tvdbId: release.tvdbId,
+      displayTitle: mediaTypeOf(release) === 'tv' ? (release.seriesTitle ?? release.title) : release.title,
+      releaseCount: 1,
+      totalSize: release.size,
+    })
+  }
+
+  return [...byKey.values()].sort((a, b) => a.displayTitle.localeCompare(b.displayTitle))
+}
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
new file mode 100644
index 0000000..745d24a
--- /dev/null
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -0,0 +1,17 @@
+import type { CatalogController } from './catalog.controller'
+import { Hono } from 'hono'
+import { validator as zValidator } from 'hono-openapi'
+import { z } from 'zod'
+
+const peerParam = z.object({ peerId: z.string().min(1) })
+
+export function getCatalogRouter(controller: CatalogController) {
+  const app = new Hono()
+
+  app.get('/:peerId', zValidator('param', peerParam), async (c) => {
+    const { peerId } = c.req.valid('param')
+    return c.json(await controller.getPeerCatalog(peerId))
+  })
+
+  return app
+}
diff --git a/apps/ui/app/components/ConnectorCard.vue b/apps/ui/app/components/ConnectorCard.vue
index 6075a0f..92893e4 100644
--- a/apps/ui/app/components/ConnectorCard.vue
+++ b/apps/ui/app/components/ConnectorCard.vue
@@ -7,6 +7,7 @@ defineProps<{
   initialized: boolean
   error?: string | null
   status: { color: BadgeProps['color'], label: string }
+  to?: string
 }>()
 defineEmits<{ edit: [], remove: [] }>()
 </script>
@@ -25,6 +26,7 @@ defineEmits<{ edit: [], remove: [] }>()
         </p>
       </div>
       <UBadge v-bind="status" variant="subtle" />
+      <UButton v-if="to" :to="to" icon="i-ph-list-magnifying-glass" color="neutral" variant="ghost" size="sm" :aria-label="`Browse ${name} catalog`" />
       <UButton icon="i-ph-pencil-simple" color="neutral" variant="ghost" size="sm" :aria-label="`Edit ${name}`" @click="$emit('edit')" />
       <UButton icon="i-ph-trash" color="neutral" variant="ghost" size="sm" :aria-label="`Remove ${name}`" @click="$emit('remove')" />
     </div>
diff --git a/apps/ui/app/components/PeersSection.vue b/apps/ui/app/components/PeersSection.vue
index d6ed9ae..4d6b4c3 100644
--- a/apps/ui/app/components/PeersSection.vue
+++ b/apps/ui/app/components/PeersSection.vue
@@ -140,6 +140,7 @@ async function confirmDelete() {
           :initialized="peer.initialized"
           :error="peer.initializationError"
           :status="statusBadge(peer)"
+          :to="`/catalog/${peer.id}`"
           @edit="openEdit(peer)"
           @remove="confirmTarget = peer"
         >
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
new file mode 100644
index 0000000..e3516af
--- /dev/null
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import type { PeerCatalogResponse } from '~/types/management'
+
+const route = useRoute()
+const peerId = computed(() => String(route.params.peerId))
+const { request } = useManagement()
+
+const { data, pending, error } = await useAsyncData(
+  `catalog-${peerId.value}`,
+  () => request<PeerCatalogResponse>(`catalog/${peerId.value}`),
+  { watch: [peerId] },
+)
+
+const titles = computed(() => data.value?.titles ?? [])
+const peerName = computed(() => data.value?.peer.name ?? 'Peer')
+</script>
+
+<template>
+  <UDashboardPanel id="catalog">
+    <template #header>
+      <UDashboardNavbar :title="peerName">
+        <template #leading>
+          <UButton icon="i-ph-arrow-left" color="neutral" variant="ghost" to="/settings" aria-label="Back to settings" />
+        </template>
+      </UDashboardNavbar>
+    </template>
+
+    <template #body>
+      <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load this peer's catalog." />
+
+      <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
+        <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
+        Loading…
+      </p>
+
+      <UCard v-else-if="titles.length === 0" variant="subtle">
+        <div class="flex flex-col items-center gap-3 py-6 text-center">
+          <UIcon name="i-ph-film-slate" class="size-8 text-dimmed" />
+          <p class="text-sm text-muted">
+            This peer isn't sharing anything yet.
+          </p>
+        </div>
+      </UCard>
+
+      <div v-else class="space-y-2">
+        <UCard v-for="title in titles" :key="title.key" variant="subtle" :ui="{ body: 'sm:p-4' }">
+          <div class="flex items-center gap-3">
+            <UIcon :name="title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip'" class="size-5 shrink-0 text-muted" />
+            <div class="min-w-0 flex-1">
+              <p class="truncate font-medium text-default" :title="title.displayTitle">
+                {{ title.displayTitle }}
+              </p>
+              <p class="text-xs text-muted">
+                {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} · {{ formatBytes(title.totalSize) }}
+              </p>
+            </div>
+            <UBadge :label="title.mediaType === 'tv' ? 'TV' : 'Movie'" color="neutral" variant="subtle" size="sm" />
+          </div>
+        </UCard>
+      </div>
+    </template>
+  </UDashboardPanel>
+</template>
diff --git a/apps/ui/app/pages/index.vue b/apps/ui/app/pages/index.vue
index 11425ef..050d67e 100644
--- a/apps/ui/app/pages/index.vue
+++ b/apps/ui/app/pages/index.vue
@@ -132,13 +132,13 @@ function serverRole(server: { source: boolean, destination: boolean }) {
                 No peers yet.
               </p>
               <div v-else class="divide-y divide-default">
-                <div v-for="peer in overview.peers.items" :key="peer.id" class="flex items-center gap-3 px-4 py-2.5">
+                <NuxtLink v-for="peer in overview.peers.items" :key="peer.id" :to="`/catalog/${peer.id}`" class="flex items-center gap-3 px-4 py-2.5 hover:bg-muted">
                   <ConnDot :initialized="peer.initialized" :error="peer.initializationError" />
                   <span class="flex-1 truncate text-sm text-default" :title="peer.name">{{ peer.name }}</span>
                   <span class="text-xs tabular-nums" :class="peer.initialized ? 'text-muted' : 'text-error'">
                     {{ peer.initialized ? (peer.version ?? '—') : 'unreachable' }}
                   </span>
-                </div>
+                </NuxtLink>
               </div>
             </UCard>
 
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index a3a0ad3..a57cd59 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -45,6 +45,22 @@ export interface DownloadItem {
   expectedBytesMismatch: boolean
 }
 
+export interface CatalogTitle {
+  key: string
+  mediaType: 'movie' | 'tv'
+  tmdbId?: number
+  imdbId?: string
+  tvdbId?: number
+  displayTitle: string
+  releaseCount: number
+  totalSize: number
+}
+
+export interface PeerCatalogResponse {
+  peer: { id: string, name: string }
+  titles: CatalogTitle[]
+}
+
 export interface Overview {
   peers: { total: number, initialized: number, items: PeerItem[] }
   servers: { total: number, initialized: number, sources: number, destinations: number, items: OverviewServerItem[] }

From 0f5897a2cb177c728fb3c2fd3f4099a56280fb14 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 00:35:07 +0200
Subject: [PATCH 02/27] feat(catalog): add TMDB config and connection status

Add an optional tmdbApiKey to config.jack, a TmdbClient that reads movie/tv
metadata, and a /catalog/tmdb/status endpoint. Expose a managed TMDB key
field and connection status in the Settings Jack section.
---
 apps/backend/src/__tests__/catalog.test.ts    | 37 ++++++++
 .../backend/src/__tests__/tmdb-client.test.ts | 69 +++++++++++++++
 apps/backend/src/index.ts                     |  1 +
 apps/backend/src/lib/config.ts                |  3 +
 apps/backend/src/lib/tmdb/client.ts           | 86 +++++++++++++++++++
 apps/backend/src/management-app.ts            |  5 +-
 .../src/modules/catalog/catalog.controller.ts | 19 ++++
 .../src/modules/catalog/catalog.router.ts     |  3 +
 apps/ui/app/components/JackConfigForm.vue     | 10 +++
 apps/ui/app/pages/settings.vue                | 19 ++++
 apps/ui/app/types/management.ts               |  1 +
 11 files changed, 252 insertions(+), 1 deletion(-)
 create mode 100644 apps/backend/src/__tests__/tmdb-client.test.ts
 create mode 100644 apps/backend/src/lib/tmdb/client.ts

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 30d4052..6075622 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -120,3 +120,40 @@ describe('catalogController', () => {
     expect(controller.getPeerCatalog('missing')).rejects.toBeInstanceOf(NotFoundError)
   })
 })
+
+describe('catalogController.getTmdbStatus', () => {
+  function makeConnectors() {
+    return { servers: [], peers: [] }
+  }
+
+  test('reports not configured when no tmdb client is supplied', async () => {
+    const controller = new CatalogController(makeConnectors() as any)
+
+    expect(await controller.getTmdbStatus()).toEqual({ configured: false, ok: false })
+  })
+
+  test('reports ok when the client ping resolves true', async () => {
+    const tmdb = { ping: async () => true }
+    const controller = new CatalogController(makeConnectors() as any, tmdb as any)
+
+    expect(await controller.getTmdbStatus()).toEqual({ configured: true, ok: true })
+  })
+
+  test('reports configured but not ok when the client ping resolves false', async () => {
+    const tmdb = { ping: async () => false }
+    const controller = new CatalogController(makeConnectors() as any, tmdb as any)
+
+    expect(await controller.getTmdbStatus()).toEqual({ configured: true, ok: false })
+  })
+
+  test('reports the error message when the client ping throws', async () => {
+    const tmdb = {
+      ping: async () => {
+        throw new Error('boom')
+      },
+    }
+    const controller = new CatalogController(makeConnectors() as any, tmdb as any)
+
+    expect(await controller.getTmdbStatus()).toEqual({ configured: true, ok: false, error: 'boom' })
+  })
+})
diff --git a/apps/backend/src/__tests__/tmdb-client.test.ts b/apps/backend/src/__tests__/tmdb-client.test.ts
new file mode 100644
index 0000000..38adef1
--- /dev/null
+++ b/apps/backend/src/__tests__/tmdb-client.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'bun:test'
+import { buildImageUrl, mapTmdbDetail } from '../lib/tmdb/client'
+
+describe('buildImageUrl', () => {
+  test('assembles a full image url from a poster path with the default size', () => {
+    expect(buildImageUrl('/abc.jpg')).toBe('https://image.tmdb.org/t/p/w500/abc.jpg')
+  })
+
+  test('honors a custom size', () => {
+    expect(buildImageUrl('/abc.jpg', 'w780')).toBe('https://image.tmdb.org/t/p/w780/abc.jpg')
+  })
+
+  test('returns null for a null path', () => {
+    expect(buildImageUrl(null)).toBeNull()
+  })
+
+  test('returns null for an undefined path', () => {
+    expect(buildImageUrl(undefined)).toBeNull()
+  })
+})
+
+describe('mapTmdbDetail', () => {
+  test('maps a movie detail (title/release_date/vote_average)', () => {
+    const meta = mapTmdbDetail({
+      id: 550,
+      title: 'Fight Club',
+      overview: 'A man and his alter ego.',
+      release_date: '1999-10-15',
+      vote_average: 8.4,
+      poster_path: '/poster.jpg',
+      backdrop_path: '/backdrop.jpg',
+      genres: [{ id: 18, name: 'Drama' }],
+    })
+
+    expect(meta.tmdbId).toBe(550)
+    expect(meta.title).toBe('Fight Club')
+    expect(meta.year).toBe(1999)
+    expect(meta.rating).toBe(8.4)
+    expect(meta.overview).toBe('A man and his alter ego.')
+    expect(meta.posterUrl).toBe('https://image.tmdb.org/t/p/w500/poster.jpg')
+    expect(meta.backdropUrl).toBe('https://image.tmdb.org/t/p/w780/backdrop.jpg')
+    expect(meta.genres).toEqual(['Drama'])
+  })
+
+  test('maps a tv detail from name/first_air_date when title/release_date are absent', () => {
+    const meta = mapTmdbDetail({
+      id: 1396,
+      name: 'Breaking Bad',
+      first_air_date: '2008-01-20',
+      vote_average: 8.9,
+    })
+
+    expect(meta.title).toBe('Breaking Bad')
+    expect(meta.year).toBe(2008)
+    expect(meta.rating).toBe(8.9)
+  })
+
+  test('falls back to null year/rating and empty genres when fields are missing', () => {
+    const meta = mapTmdbDetail({ id: 1 })
+
+    expect(meta.title).toBe('Untitled')
+    expect(meta.year).toBeNull()
+    expect(meta.rating).toBeNull()
+    expect(meta.posterUrl).toBeNull()
+    expect(meta.backdropUrl).toBeNull()
+    expect(meta.genres).toEqual([])
+    expect(meta.overview).toBeNull()
+  })
+})
diff --git a/apps/backend/src/index.ts b/apps/backend/src/index.ts
index 5f52a37..5c2cd08 100644
--- a/apps/backend/src/index.ts
+++ b/apps/backend/src/index.ts
@@ -83,6 +83,7 @@ function startManagementServer() {
     configService,
     downloadsRepository,
     apiKeysRepository,
+    tmdbApiKey: config.jack.tmdbApiKey,
   })
   const instance = Bun.serve({ port: envs.MANAGEMENT_PORT, fetch: managementApp.fetch })
   logger.info({ port: instance.port }, 'Management API listening')
diff --git a/apps/backend/src/lib/config.ts b/apps/backend/src/lib/config.ts
index 3fead06..d4a1e76 100644
--- a/apps/backend/src/lib/config.ts
+++ b/apps/backend/src/lib/config.ts
@@ -155,6 +155,8 @@ export const JackConfig = z.object({
   // only an internalUrl, in which case the public API authenticates via generated
   // keys (see require-auth.ts), not this key.
   apiKey: ConfigSecret().optional(),
+  // Optional TMDB v3 API key for enriching peer catalogs with artwork/metadata.
+  tmdbApiKey: ConfigSecret().optional(),
 })
 
 export type JackConfig = z.infer<typeof JackConfig>
@@ -164,6 +166,7 @@ export type JackConfig = z.infer<typeof JackConfig>
 export const RawJackConfig = z.object({
   internalUrl: z.url(),
   apiKey: RawConfigSecret.optional(),
+  tmdbApiKey: RawConfigSecret.optional(),
 })
 
 export type RawJackConfig = z.infer<typeof RawJackConfig>
diff --git a/apps/backend/src/lib/tmdb/client.ts b/apps/backend/src/lib/tmdb/client.ts
new file mode 100644
index 0000000..02fbca4
--- /dev/null
+++ b/apps/backend/src/lib/tmdb/client.ts
@@ -0,0 +1,86 @@
+const TMDB_API_BASE = 'https://api.themoviedb.org/3'
+const TMDB_IMAGE_BASE = 'https://image.tmdb.org/t/p/'
+
+export type TmdbMediaType = 'movie' | 'tv'
+
+export interface TmdbMetadata {
+  tmdbId: number
+  title: string
+  overview: string | null
+  year: number | null
+  rating: number | null
+  posterUrl: string | null
+  backdropUrl: string | null
+  genres: string[]
+}
+
+interface TmdbRawDetail {
+  id: number
+  title?: string
+  name?: string
+  overview?: string | null
+  release_date?: string | null
+  first_air_date?: string | null
+  vote_average?: number | null
+  poster_path?: string | null
+  backdrop_path?: string | null
+  genres?: Array<{ id: number, name: string }>
+}
+
+/** Assemble a TMDB image URL, or null when the path is absent. */
+export function buildImageUrl(path: string | null | undefined, size = 'w500', base = TMDB_IMAGE_BASE): string | null {
+  if (!path)
+    return null
+  return `${base}${size}${path}`
+}
+
+/** Normalize a TMDB movie/tv detail payload into our flat metadata shape. */
+export function mapTmdbDetail(raw: TmdbRawDetail): TmdbMetadata {
+  const date = raw.release_date ?? raw.first_air_date ?? null
+  const yearNum = date && date.length >= 4 ? Number(date.slice(0, 4)) : Number.NaN
+  return {
+    tmdbId: raw.id,
+    title: raw.title ?? raw.name ?? 'Untitled',
+    overview: raw.overview || null,
+    year: Number.isFinite(yearNum) ? yearNum : null,
+    rating: typeof raw.vote_average === 'number' ? raw.vote_average : null,
+    posterUrl: buildImageUrl(raw.poster_path),
+    backdropUrl: buildImageUrl(raw.backdrop_path, 'w780'),
+    genres: (raw.genres ?? []).map(g => g.name).filter((n): n is string => Boolean(n)),
+  }
+}
+
+/**
+ * Thin TMDB v3 read client. Holds a per-process cache keyed by media/id so a
+ * catalog full of repeated titles enriches each unique id once.
+ */
+export class TmdbClient {
+  private readonly cache = new Map<string, TmdbMetadata | null>()
+  constructor(private readonly apiKey: string) {}
+
+  /** True when the key authenticates against TMDB (`/configuration` returns 200). */
+  async ping(): Promise<boolean> {
+    const res = await fetch(`${TMDB_API_BASE}/configuration?api_key=${this.apiKey}`)
+    return res.ok
+  }
+
+  /** Normalized metadata for a tmdb id, cached per process; null on 404. */
+  async getMetadata(mediaType: TmdbMediaType, tmdbId: number): Promise<TmdbMetadata | null> {
+    const key = `${mediaType}:${tmdbId}`
+    const cached = this.cache.get(key)
+    if (cached !== undefined)
+      return cached
+
+    const res = await fetch(`${TMDB_API_BASE}/${mediaType}/${tmdbId}?api_key=${this.apiKey}`)
+    if (res.status === 404) {
+      this.cache.set(key, null)
+      return null
+    }
+    if (!res.ok)
+      throw new Error(`TMDB ${mediaType}/${tmdbId} failed: ${res.status}`)
+    const raw = await res.json() as TmdbRawDetail
+    const meta = mapTmdbDetail(raw)
+    this.cache.set(key, meta)
+    return meta
+  }
+}
diff --git a/apps/backend/src/management-app.ts b/apps/backend/src/management-app.ts
index 082d89f..d7c5f53 100644
--- a/apps/backend/src/management-app.ts
+++ b/apps/backend/src/management-app.ts
@@ -4,6 +4,7 @@ import type { ConfigService } from './modules/config/config.service'
 import type { DownloadsRepository } from './modules/downloads/downloads.repository'
 import { Hono } from 'hono'
 import { secureHeaders } from 'hono/secure-headers'
+import { TmdbClient } from './lib/tmdb/client'
 import { handleError } from './middleware/handle-error'
 import { requireManagementKey } from './middleware/require-management-key'
 import { ApiKeysController } from './modules/api-keys/api-keys.controller'
@@ -23,6 +24,7 @@ export function getManagementApp(params: {
   configService?: ConfigService
   downloadsRepository?: DownloadsRepository
   apiKeysRepository?: ApiKeysRepository
+  tmdbApiKey?: string
 }) {
   const app = new Hono()
 
@@ -40,7 +42,8 @@ export function getManagementApp(params: {
   const statusController = new StatusController(params.connectors, params.downloadsRepository)
   app.route('/', getStatusRouter(statusController))
 
-  const catalogController = new CatalogController(params.connectors)
+  const tmdbClient = params.tmdbApiKey ? new TmdbClient(params.tmdbApiKey) : undefined
+  const catalogController = new CatalogController(params.connectors, tmdbClient)
   app.route('/catalog', getCatalogRouter(catalogController))
 
   if (params.apiKeysRepository) {
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index 821ed68..cce86ba 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -1,5 +1,6 @@
 import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { PeerConnector } from '../../lib/servers/peer'
+import type { TmdbClient } from '../../lib/tmdb/client'
 import type { CatalogTitle } from './catalog.lib'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
 import { groupReleasesIntoTitles } from './catalog.lib'
@@ -9,9 +10,16 @@ export interface PeerCatalogResponse {
   titles: CatalogTitle[]
 }
 
+export interface TmdbStatus {
+  configured: boolean
+  ok: boolean
+  error?: string
+}
+
 export class CatalogController {
   constructor(
     private readonly connectors: { servers: ArrServerConnector[], peers: PeerConnector[] },
+    private readonly tmdb?: TmdbClient,
   ) {}
 
   private requirePeer(peerId: string): PeerConnector {
@@ -29,4 +37,15 @@ export class CatalogController {
       titles: groupReleasesIntoTitles(releases),
     }
   }
+
+  async getTmdbStatus(): Promise<TmdbStatus> {
+    if (!this.tmdb)
+      return { configured: false, ok: false }
+    try {
+      return { configured: true, ok: await this.tmdb.ping() }
+    }
+    catch (err) {
+      return { configured: true, ok: false, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
 }
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index 745d24a..c5cea11 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -8,6 +8,9 @@ const peerParam = z.object({ peerId: z.string().min(1) })
 export function getCatalogRouter(controller: CatalogController) {
   const app = new Hono()
 
+  // Register the static path before `/:peerId` so "tmdb" isn't captured as a peerId.
+  app.get('/tmdb/status', async c => c.json(await controller.getTmdbStatus()))
+
   app.get('/:peerId', zValidator('param', peerParam), async (c) => {
     const { peerId } = c.req.valid('param')
     return c.json(await controller.getPeerCatalog(peerId))
diff --git a/apps/ui/app/components/JackConfigForm.vue b/apps/ui/app/components/JackConfigForm.vue
index d0db2af..65b978f 100644
--- a/apps/ui/app/components/JackConfigForm.vue
+++ b/apps/ui/app/components/JackConfigForm.vue
@@ -14,6 +14,7 @@ const editing = computed(() => Boolean(props.initial))
 const state = reactive({
   internalUrl: props.initial?.internalUrl ?? '',
   apiKey: (props.initial?.apiKey ?? null) as SecretRef | null,
+  tmdbApiKey: (props.initial?.tmdbApiKey ?? null) as SecretRef | null,
 })
 
 // internalUrl is the only required field; the Main API key is optional/clearable.
@@ -28,6 +29,8 @@ function onSubmit() {
   // SecretInput emits null when cleared → omit apiKey entirely (optional).
   if (state.apiKey)
     input.apiKey = state.apiKey
+  if (state.tmdbApiKey)
+    input.tmdbApiKey = state.tmdbApiKey
   emit('submit', input)
 }
 </script>
@@ -50,6 +53,13 @@ function onSubmit() {
       </template>
     </UFormField>
 
+    <UFormField name="tmdbApiKey" label="TMDB API key" hint="Optional">
+      <SecretInput v-model="state.tmdbApiKey" :editing="editing" />
+      <template #help>
+        <span>Enables artwork and metadata when browsing peer catalogs. Applies after a restart.</span>
+      </template>
+    </UFormField>
+
     <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" :title="error" />
 
     <div class="flex justify-end pt-2">
diff --git a/apps/ui/app/pages/settings.vue b/apps/ui/app/pages/settings.vue
index f345b88..a01697c 100644
--- a/apps/ui/app/pages/settings.vue
+++ b/apps/ui/app/pages/settings.vue
@@ -15,6 +15,11 @@ const keys = computed(() => data.value ?? [])
 const { data: jack, pending: jackPending, error: jackLoadError, refresh: refreshJack }
   = await useAsyncData('jack-config', () => request<JackConfig | null>('config/jack'))
 
+// Whether the running TMDB key authenticates — surfaced beside the key field so a
+// saved key can be confirmed at a glance.
+const { data: tmdbStatus } = await useAsyncData('tmdb-status', () =>
+  request<{ configured: boolean, ok: boolean }>('catalog/tmdb/status'))
+
 const jackSubmitting = ref(false)
 const jackError = ref<string | null>(null)
 const jackSaved = ref(false)
@@ -191,6 +196,20 @@ async function confirmRevoke() {
               icon="i-ph-check-circle"
               title="Saved. Restart the server for the change to take effect."
             />
+            <p class="flex items-center gap-2 text-xs">
+              <template v-if="tmdbStatus?.ok">
+                <UIcon name="i-ph-check-circle" class="size-4 text-success" />
+                <span class="text-muted">TMDB connected.</span>
+              </template>
+              <template v-else-if="tmdbStatus?.configured">
+                <UIcon name="i-ph-warning" class="size-4 text-warning" />
+                <span class="text-muted">TMDB key set but not authenticating.</span>
+              </template>
+              <template v-else>
+                <UIcon name="i-ph-info" class="size-4 text-dimmed" />
+                <span class="text-muted">TMDB not configured — peer catalogs show names only.</span>
+              </template>
+            </p>
           </UCard>
         </SettingsSection>
 
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index a57cd59..ec340d4 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -101,6 +101,7 @@ export interface ServerInput {
 export interface JackConfig {
   internalUrl: string
   apiKey?: SecretRef | null
+  tmdbApiKey?: SecretRef | null
 }
 
 export interface ApiKey {

From 92ba226cc18a11a8729431e388478323313a99f6 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 00:39:44 +0200
Subject: [PATCH 03/27] feat(catalog): enrich peer catalog with TMDB metadata

Enrich grouped titles with TMDB artwork/overview/year/rating (concurrency-
capped, cached) and redesign the catalog page as a poster grid with a
per-title detail slideover.
---
 apps/backend/src/__tests__/catalog.test.ts    | 120 +++++++++++++++++-
 .../src/modules/catalog/catalog.controller.ts |  25 +++-
 .../src/modules/catalog/catalog.lib.ts        |  21 +++
 apps/ui/app/components/CatalogPosterCard.vue  |  49 +++++++
 apps/ui/app/components/CatalogTitleDetail.vue |  44 +++++++
 apps/ui/app/pages/catalog/[peerId].vue        |  54 +++++---
 apps/ui/app/types/management.ts               |  12 ++
 7 files changed, 304 insertions(+), 21 deletions(-)
 create mode 100644 apps/ui/app/components/CatalogPosterCard.vue
 create mode 100644 apps/ui/app/components/CatalogTitleDetail.vue

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 6075622..5f205a9 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -2,7 +2,7 @@ import type { Release } from '../lib/release'
 import { describe, expect, test } from 'bun:test'
 import { NotFoundError } from '../lib/errors/NotFoundError'
 import { CatalogController } from '../modules/catalog/catalog.controller'
-import { groupReleasesIntoTitles } from '../modules/catalog/catalog.lib'
+import { groupReleasesIntoTitles, mapLimit } from '../modules/catalog/catalog.lib'
 
 function movie(overrides: Partial<Release> = {}): Release {
   return {
@@ -121,6 +121,124 @@ describe('catalogController', () => {
   })
 })
 
+describe('mapLimit', () => {
+  test('preserves input order regardless of completion order', async () => {
+    const result = await mapLimit([3, 1, 2], 2, async (n) => {
+      await new Promise(resolve => setTimeout(resolve, n))
+      return n * 10
+    })
+
+    expect(result).toEqual([30, 10, 20])
+  })
+
+  test('runs exactly `limit` tasks in flight, never more', async () => {
+    let inFlight = 0
+    let peak = 0
+
+    await mapLimit([1, 2, 3, 4, 5, 6], 2, async () => {
+      inFlight += 1
+      peak = Math.max(peak, inFlight)
+      await new Promise(resolve => setTimeout(resolve, 5))
+      inFlight -= 1
+      return null
+    })
+
+    // Saturates the cap (catches a collapse-to-one-worker regression) without exceeding it.
+    expect(peak).toBe(2)
+  })
+
+  test('returns an empty array for empty input', async () => {
+    expect(await mapLimit([], 4, async () => 1)).toEqual([])
+  })
+})
+
+describe('catalogController enrichment', () => {
+  function makeConnectors(peers: any[]) {
+    return { servers: [], peers }
+  }
+
+  const breakingBad = {
+    tmdbId: 1396,
+    title: 'Breaking Bad',
+    overview: 'A chemistry teacher cooks meth.',
+    year: 2008,
+    rating: 8.9,
+    posterUrl: 'https://image.tmdb.org/t/p/w500/poster.jpg',
+    backdropUrl: 'https://image.tmdb.org/t/p/w780/backdrop.jpg',
+    genres: ['Drama'],
+  }
+
+  test('attaches metadata to titles with a tmdbId and leaves id-less titles untouched', async () => {
+    const calls: Array<[string, number]> = []
+    const tmdb = {
+      getMetadata: async (mediaType: string, tmdbId: number) => {
+        calls.push([mediaType, tmdbId])
+        return tmdbId === 603 ? { ...breakingBad, tmdbId: 603, title: 'The Matrix' } : null
+      },
+    }
+    const peer = {
+      id: 'peer-1',
+      name: 'Friend Jack',
+      listReleases: async () => [
+        movie({ tmdbId: 603, title: 'The.Matrix.1999' }),
+        movie({ title: 'No.Id.2024' }),
+      ],
+    }
+    const controller = new CatalogController(makeConnectors([peer]) as any, tmdb as any)
+
+    const result = await controller.getPeerCatalog('peer-1')
+
+    const enriched = result.titles.find(t => t.tmdbId === 603)
+    expect(enriched!.metadata).toMatchObject({ title: 'The Matrix' })
+
+    const idless = result.titles.find(t => t.tmdbId == null)
+    expect(idless!.metadata).toBeUndefined()
+
+    // No lookup is attempted for the id-less title.
+    expect(calls).toEqual([['movie', 603]])
+  })
+
+  test('keeps the catalog intact when a getMetadata lookup rejects', async () => {
+    const tmdb = {
+      getMetadata: async (_mediaType: string, tmdbId: number) => {
+        if (tmdbId === 603)
+          throw new Error('TMDB exploded')
+        return { ...breakingBad }
+      },
+    }
+    const peer = {
+      id: 'peer-1',
+      name: 'Friend Jack',
+      listReleases: async () => [
+        movie({ tmdbId: 603, title: 'The.Matrix.1999' }),
+        episode({ tvdbId: 1, tmdbId: 1396, seriesTitle: 'Breaking Bad' }),
+      ],
+    }
+    const controller = new CatalogController(makeConnectors([peer]) as any, tmdb as any)
+
+    const result = await controller.getPeerCatalog('peer-1')
+
+    const failed = result.titles.find(t => t.tmdbId === 603)
+    expect(failed!.metadata).toBeUndefined()
+
+    const ok = result.titles.find(t => t.mediaType === 'tv')
+    expect(ok!.metadata).toMatchObject({ title: 'Breaking Bad' })
+  })
+
+  test('makes no TMDB calls and attaches no metadata when no client is configured', async () => {
+    const peer = {
+      id: 'peer-1',
+      name: 'Friend Jack',
+      listReleases: async () => [movie({ tmdbId: 603 })],
+    }
+    const controller = new CatalogController(makeConnectors([peer]) as any)
+
+    const result = await controller.getPeerCatalog('peer-1')
+
+    expect(result.titles[0]!.metadata).toBeUndefined()
+  })
+})
+
 describe('catalogController.getTmdbStatus', () => {
   function makeConnectors() {
     return { servers: [], peers: [] }
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index cce86ba..a424adf 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -3,7 +3,9 @@ import type { PeerConnector } from '../../lib/servers/peer'
 import type { TmdbClient } from '../../lib/tmdb/client'
 import type { CatalogTitle } from './catalog.lib'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
-import { groupReleasesIntoTitles } from './catalog.lib'
+import { groupReleasesIntoTitles, mapLimit } from './catalog.lib'
+
+const TMDB_ENRICH_CONCURRENCY = 8
 
 export interface PeerCatalogResponse {
   peer: { id: string, name: string }
@@ -32,12 +34,31 @@ export class CatalogController {
   async getPeerCatalog(peerId: string): Promise<PeerCatalogResponse> {
     const peer = this.requirePeer(peerId)
     const releases = await peer.listReleases()
+    const titles = await this.enrichTitles(groupReleasesIntoTitles(releases))
     return {
       peer: { id: peer.id, name: peer.name },
-      titles: groupReleasesIntoTitles(releases),
+      titles,
     }
   }
 
+  private async enrichTitles(titles: CatalogTitle[]): Promise<CatalogTitle[]> {
+    if (!this.tmdb)
+      return titles
+    const tmdb = this.tmdb
+    return mapLimit(titles, TMDB_ENRICH_CONCURRENCY, async (title) => {
+      if (!title.tmdbId)
+        return title
+      try {
+        const metadata = await tmdb.getMetadata(title.mediaType, title.tmdbId)
+        return { ...title, metadata }
+      }
+      catch {
+        // Enrichment is best-effort: a failed lookup must not blank the catalog.
+        return title
+      }
+    })
+  }
+
   async getTmdbStatus(): Promise<TmdbStatus> {
     if (!this.tmdb)
       return { configured: false, ok: false }
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
index 31dc21b..49f02cc 100644
--- a/apps/backend/src/modules/catalog/catalog.lib.ts
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -1,4 +1,5 @@
 import type { Release } from '../../lib/release'
+import type { TmdbMetadata } from '../../lib/tmdb/client'
 import { ReleaseCategory } from '../../lib/release'
 
 export interface CatalogTitle {
@@ -12,6 +13,26 @@ export interface CatalogTitle {
   displayTitle: string
   releaseCount: number
   totalSize: number
+  metadata?: TmdbMetadata | null
+}
+
+/** Run `fn` over `items` with at most `limit` in flight; preserves order. */
+export async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const results = Array.from({ length: items.length }) as R[]
+  let cursor = 0
+  async function worker(): Promise<void> {
+    while (cursor < items.length) {
+      const index = cursor++
+      results[index] = await fn(items[index]!)
+    }
+  }
+  // Spawn each worker via its own call so they run concurrently; `.fill(worker())`
+  // would share one promise and silently collapse the pool to a single worker.
+  const workers: Array<Promise<void>> = []
+  for (let i = 0; i < Math.min(limit, items.length); i++)
+    workers.push(worker())
+  await Promise.all(workers)
+  return results
 }
 
 function mediaTypeOf(release: Release): 'movie' | 'tv' {
diff --git a/apps/ui/app/components/CatalogPosterCard.vue b/apps/ui/app/components/CatalogPosterCard.vue
new file mode 100644
index 0000000..8a6076e
--- /dev/null
+++ b/apps/ui/app/components/CatalogPosterCard.vue
@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import type { CatalogTitle } from '~/types/management'
+
+const props = defineProps<{ title: CatalogTitle }>()
+defineEmits<{ select: [] }>()
+
+const name = computed(() => props.title.metadata?.title ?? props.title.displayTitle)
+const poster = computed(() => props.title.metadata?.posterUrl ?? null)
+const year = computed(() => props.title.metadata?.year ?? null)
+const rating = computed(() => props.title.metadata?.rating ?? null)
+</script>
+
+<template>
+  <button
+    type="button"
+    class="group flex flex-col gap-2 text-left focus:outline-none"
+    @click="$emit('select')"
+  >
+    <div class="relative aspect-[2/3] overflow-hidden rounded-lg bg-muted ring-1 ring-default transition group-hover:ring-primary">
+      <img
+        v-if="poster"
+        :src="poster"
+        :alt="name"
+        loading="lazy"
+        class="size-full object-cover"
+      >
+      <div v-else class="flex size-full items-center justify-center">
+        <UIcon :name="title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip'" class="size-8 text-dimmed" />
+      </div>
+      <UBadge
+        v-if="rating"
+        :label="rating.toFixed(1)"
+        color="neutral"
+        variant="solid"
+        size="sm"
+        icon="i-ph-star-fill"
+        class="absolute right-1.5 top-1.5 bg-default/80 backdrop-blur"
+      />
+    </div>
+    <div class="min-w-0">
+      <p class="truncate text-sm font-medium text-default" :title="name">
+        {{ name }}
+      </p>
+      <p class="text-xs text-muted">
+        <span v-if="year">{{ year }} · </span>{{ title.mediaType === 'tv' ? 'TV' : 'Movie' }}
+      </p>
+    </div>
+  </button>
+</template>
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
new file mode 100644
index 0000000..032bf39
--- /dev/null
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import type { CatalogTitle } from '~/types/management'
+
+const props = defineProps<{ title: CatalogTitle }>()
+
+const name = computed(() => props.title.metadata?.title ?? props.title.displayTitle)
+const meta = computed(() => props.title.metadata ?? null)
+</script>
+
+<template>
+  <div class="space-y-4">
+    <div v-if="meta?.backdropUrl" class="aspect-video overflow-hidden rounded-lg bg-muted">
+      <img :src="meta.backdropUrl" :alt="name" class="size-full object-cover">
+    </div>
+
+    <div class="flex items-baseline gap-2">
+      <h3 class="text-lg font-semibold text-highlighted">
+        {{ name }}
+      </h3>
+      <span v-if="meta?.year" class="text-sm text-muted">{{ meta.year }}</span>
+    </div>
+
+    <div class="flex flex-wrap items-center gap-2">
+      <UBadge :label="title.mediaType === 'tv' ? 'TV' : 'Movie'" color="neutral" variant="subtle" />
+      <UBadge v-if="meta?.rating" :label="meta.rating.toFixed(1)" icon="i-ph-star-fill" color="warning" variant="subtle" />
+      <UBadge v-for="g in meta?.genres ?? []" :key="g" :label="g" color="neutral" variant="soft" size="sm" />
+    </div>
+
+    <p v-if="meta?.overview" class="text-sm leading-relaxed text-toned">
+      {{ meta.overview }}
+    </p>
+    <p v-else class="text-sm text-muted">
+      No description available.
+    </p>
+
+    <USeparator />
+
+    <p class="text-xs text-muted">
+      {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} on this peer · {{ formatBytes(title.totalSize) }}
+    </p>
+
+    <!-- Phase 5 inserts the Download button here. -->
+  </div>
+</template>
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index e3516af..711cd69 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { PeerCatalogResponse } from '~/types/management'
+import type { CatalogTitle, PeerCatalogResponse } from '~/types/management'
 
 const route = useRoute()
 const peerId = computed(() => String(route.params.peerId))
@@ -11,8 +11,14 @@ const { data, pending, error } = await useAsyncData(
   { watch: [peerId] },
 )
 
-const titles = computed(() => data.value?.titles ?? [])
 const peerName = computed(() => data.value?.peer.name ?? 'Peer')
+const typeFilter = ref<'all' | 'movie' | 'tv'>('all')
+const titles = computed(() => {
+  const all = data.value?.titles ?? []
+  return typeFilter.value === 'all' ? all : all.filter(t => t.mediaType === typeFilter.value)
+})
+
+const selected = ref<CatalogTitle | null>(null)
 </script>
 
 <template>
@@ -23,6 +29,16 @@ const peerName = computed(() => data.value?.peer.name ?? 'Peer')
           <UButton icon="i-ph-arrow-left" color="neutral" variant="ghost" to="/settings" aria-label="Back to settings" />
         </template>
       </UDashboardNavbar>
+      <UDashboardToolbar>
+        <template #right>
+          <UTabs
+            v-model="typeFilter"
+            size="sm"
+            :items="[{ label: 'All', value: 'all' }, { label: 'Movies', value: 'movie' }, { label: 'TV', value: 'tv' }]"
+            :content="false"
+          />
+        </template>
+      </UDashboardToolbar>
     </template>
 
     <template #body>
@@ -37,27 +53,29 @@ const peerName = computed(() => data.value?.peer.name ?? 'Peer')
         <div class="flex flex-col items-center gap-3 py-6 text-center">
           <UIcon name="i-ph-film-slate" class="size-8 text-dimmed" />
           <p class="text-sm text-muted">
-            This peer isn't sharing anything yet.
+            Nothing to show here.
           </p>
         </div>
       </UCard>
 
-      <div v-else class="space-y-2">
-        <UCard v-for="title in titles" :key="title.key" variant="subtle" :ui="{ body: 'sm:p-4' }">
-          <div class="flex items-center gap-3">
-            <UIcon :name="title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip'" class="size-5 shrink-0 text-muted" />
-            <div class="min-w-0 flex-1">
-              <p class="truncate font-medium text-default" :title="title.displayTitle">
-                {{ title.displayTitle }}
-              </p>
-              <p class="text-xs text-muted">
-                {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} · {{ formatBytes(title.totalSize) }}
-              </p>
-            </div>
-            <UBadge :label="title.mediaType === 'tv' ? 'TV' : 'Movie'" color="neutral" variant="subtle" size="sm" />
-          </div>
-        </UCard>
+      <div v-else class="grid grid-cols-3 gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-8">
+        <CatalogPosterCard
+          v-for="title in titles"
+          :key="title.key"
+          :title="title"
+          @select="selected = title"
+        />
       </div>
     </template>
   </UDashboardPanel>
+
+  <USlideover
+    :open="selected !== null"
+    :title="selected?.metadata?.title ?? selected?.displayTitle ?? 'Title'"
+    @update:open="(open) => { if (!open) selected = null }"
+  >
+    <template #body>
+      <CatalogTitleDetail v-if="selected" :title="selected" />
+    </template>
+  </USlideover>
 </template>
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index ec340d4..4301319 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -45,6 +45,17 @@ export interface DownloadItem {
   expectedBytesMismatch: boolean
 }
 
+export interface TmdbMetadata {
+  tmdbId: number
+  title: string
+  overview: string | null
+  year: number | null
+  rating: number | null
+  posterUrl: string | null
+  backdropUrl: string | null
+  genres: string[]
+}
+
 export interface CatalogTitle {
   key: string
   mediaType: 'movie' | 'tv'
@@ -54,6 +65,7 @@ export interface CatalogTitle {
   displayTitle: string
   releaseCount: number
   totalSize: number
+  metadata?: TmdbMetadata | null
 }
 
 export interface PeerCatalogResponse {

From 3adeaabc752fb707e3e6c7b9c9ccaf78177d33b5 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 00:44:06 +0200
Subject: [PATCH 04/27] feat(catalog): add *arr request options modal

Fetch each destination *arr's quality profiles and root folders via a
/catalog/request-options endpoint, and add a Download modal that pre-fills
them for the *arr matching the title's media type.
---
 apps/backend/src/__tests__/catalog.test.ts    | 82 ++++++++++++++++
 apps/backend/src/lib/servers/arr/base.ts      | 18 ++++
 .../src/modules/catalog/catalog.controller.ts | 32 ++++++
 .../src/modules/catalog/catalog.router.ts     |  3 +
 apps/ui/app/components/CatalogTitleDetail.vue | 14 ++-
 .../app/components/DownloadRequestModal.vue   | 97 +++++++++++++++++++
 apps/ui/app/pages/catalog/[peerId].vue        | 19 +++-
 apps/ui/app/types/management.ts               | 15 +++
 8 files changed, 277 insertions(+), 3 deletions(-)
 create mode 100644 apps/ui/app/components/DownloadRequestModal.vue

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 5f205a9..737e3be 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -239,6 +239,88 @@ describe('catalogController enrichment', () => {
   })
 })
 
+describe('catalogController.getRequestOptions', () => {
+  function fakeServer(overrides: Partial<{
+    id: string
+    name: string
+    type: 'radarr' | 'sonarr'
+    canDestination: boolean
+    isInitialized: boolean
+    getQualityProfiles: () => Promise<Array<{ id: number, name: string }>>
+    getRootFolders: () => Promise<Array<{ path: string, freeSpace?: number }>>
+  }> = {}) {
+    return {
+      id: 'radarr-1',
+      name: 'Radarr',
+      type: 'radarr',
+      canDestination: true,
+      isInitialized: true,
+      getQualityProfiles: async () => [{ id: 1, name: 'HD-1080p' }],
+      getRootFolders: async () => [{ path: '/movies', freeSpace: 1000 }],
+      ...overrides,
+    }
+  }
+
+  function makeConnectors(servers: any[]) {
+    return { servers, peers: [] }
+  }
+
+  test('returns only initialized destinations and tags movies with mediaType "movie"', async () => {
+    const radarr = fakeServer({ id: 'radarr-1', name: 'My Radarr', type: 'radarr' })
+    const sonarrSourceOnly = fakeServer({ id: 'sonarr-1', name: 'Source Sonarr', type: 'sonarr', canDestination: false })
+    const controller = new CatalogController(makeConnectors([radarr, sonarrSourceOnly]) as any)
+
+    const options = await controller.getRequestOptions()
+
+    expect(options).toHaveLength(1)
+    expect(options[0]!.id).toBe('radarr-1')
+    expect(options[0]!.name).toBe('My Radarr')
+    expect(options[0]!.type).toBe('radarr')
+    expect(options[0]!.mediaType).toBe('movie')
+    expect(options[0]!.qualityProfiles).toEqual([{ id: 1, name: 'HD-1080p' }])
+    expect(options[0]!.rootFolders).toEqual([{ path: '/movies', freeSpace: 1000 }])
+  })
+
+  test('tags a destination Sonarr with mediaType "tv"', async () => {
+    const sonarr = fakeServer({
+      id: 'sonarr-1',
+      name: 'My Sonarr',
+      type: 'sonarr',
+      getRootFolders: async () => [{ path: '/tv' }],
+    })
+    const controller = new CatalogController(makeConnectors([sonarr]) as any)
+
+    const options = await controller.getRequestOptions()
+
+    expect(options).toHaveLength(1)
+    expect(options[0]!.mediaType).toBe('tv')
+  })
+
+  test('excludes destinations that are not initialized', async () => {
+    const radarr = fakeServer({ isInitialized: false })
+    const controller = new CatalogController(makeConnectors([radarr]) as any)
+
+    expect(await controller.getRequestOptions()).toEqual([])
+  })
+
+  test('skips a destination whose getQualityProfiles rejects but keeps others', async () => {
+    const broken = fakeServer({
+      id: 'radarr-broken',
+      name: 'Broken Radarr',
+      getQualityProfiles: async () => {
+        throw new Error('unreachable')
+      },
+    })
+    const healthy = fakeServer({ id: 'radarr-ok', name: 'Healthy Radarr' })
+    const controller = new CatalogController(makeConnectors([broken, healthy]) as any)
+
+    const options = await controller.getRequestOptions()
+
+    expect(options).toHaveLength(1)
+    expect(options[0]!.id).toBe('radarr-ok')
+  })
+})
+
 describe('catalogController.getTmdbStatus', () => {
   function makeConnectors() {
     return { servers: [], peers: [] }
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index aa179fc..9caf467 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -171,6 +171,24 @@ export abstract class ArrServerConnector extends ServerConnector {
     return this.fetch('/api/v3/health', { schema: z.array(DestinationServerHealthIssue) })
   }
 
+  @requiresDestination
+  @requiresInitialization
+  async getQualityProfiles(): Promise<Array<{ id: number, name: string }>> {
+    const profiles = await this.arrGet<Array<{ id: number, name: string }>>('/api/v3/qualityprofile')
+    return (Array.isArray(profiles) ? profiles : [])
+      .filter(p => p.id != null && p.name != null)
+      .map(p => ({ id: p.id, name: p.name }))
+  }
+
+  @requiresDestination
+  @requiresInitialization
+  async getRootFolders(): Promise<Array<{ path: string, freeSpace?: number }>> {
+    const folders = await this.arrGet<Array<{ path: string, freeSpace?: number }>>('/api/v3/rootfolder')
+    return (Array.isArray(folders) ? folders : [])
+      .filter(f => typeof f.path === 'string')
+      .map(f => ({ path: f.path, freeSpace: f.freeSpace }))
+  }
+
   /**
    * Lowercased torrent infohashes (`downloadId`s) that this *arr has finished
    * importing recently, read from its history. The import watcher matches these
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index a424adf..84ebf50 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -18,6 +18,15 @@ export interface TmdbStatus {
   error?: string
 }
 
+export interface RequestServerOption {
+  id: string
+  name: string
+  type: 'radarr' | 'sonarr'
+  mediaType: 'movie' | 'tv'
+  qualityProfiles: Array<{ id: number, name: string }>
+  rootFolders: Array<{ path: string, freeSpace?: number }>
+}
+
 export class CatalogController {
   constructor(
     private readonly connectors: { servers: ArrServerConnector[], peers: PeerConnector[] },
@@ -59,6 +68,29 @@ export class CatalogController {
     })
   }
 
+  async getRequestOptions(): Promise<RequestServerOption[]> {
+    const destinations = this.connectors.servers.filter(s => s.canDestination && s.isInitialized)
+    const options = await Promise.all(destinations.map(async (s) => {
+      try {
+        const [qualityProfiles, rootFolders] = await Promise.all([s.getQualityProfiles(), s.getRootFolders()])
+        const type = s.type as 'radarr' | 'sonarr'
+        return {
+          id: s.id,
+          name: s.name,
+          type,
+          mediaType: type === 'sonarr' ? 'tv' : 'movie',
+          qualityProfiles,
+          rootFolders,
+        } satisfies RequestServerOption
+      }
+      catch {
+        // A destination that can't list its profiles can't take a request — drop it.
+        return null
+      }
+    }))
+    return options.filter((o): o is RequestServerOption => o !== null)
+  }
+
   async getTmdbStatus(): Promise<TmdbStatus> {
     if (!this.tmdb)
       return { configured: false, ok: false }
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index c5cea11..5b87915 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -11,6 +11,9 @@ export function getCatalogRouter(controller: CatalogController) {
   // Register the static path before `/:peerId` so "tmdb" isn't captured as a peerId.
   app.get('/tmdb/status', async c => c.json(await controller.getTmdbStatus()))
 
+  // Register before `/:peerId` so "request-options" isn't captured as a peerId.
+  app.get('/request-options', async c => c.json({ servers: await controller.getRequestOptions() }))
+
   app.get('/:peerId', zValidator('param', peerParam), async (c) => {
     const { peerId } = c.req.valid('param')
     return c.json(await controller.getPeerCatalog(peerId))
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index 032bf39..1f7ac32 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -2,9 +2,13 @@
 import type { CatalogTitle } from '~/types/management'
 
 const props = defineProps<{ title: CatalogTitle }>()
+const emit = defineEmits<{ download: [] }>()
 
 const name = computed(() => props.title.metadata?.title ?? props.title.displayTitle)
 const meta = computed(() => props.title.metadata ?? null)
+const canRequest = computed(() => props.title.mediaType === 'tv'
+  ? props.title.tvdbId != null
+  : props.title.tmdbId != null)
 </script>
 
 <template>
@@ -39,6 +43,14 @@ const meta = computed(() => props.title.metadata ?? null)
       {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} on this peer · {{ formatBytes(title.totalSize) }}
     </p>
 
-    <!-- Phase 5 inserts the Download button here. -->
+    <UTooltip :disabled="canRequest" text="This title has no matching id to request">
+      <UButton
+        label="Download"
+        icon="i-ph-download-simple"
+        :disabled="!canRequest"
+        block
+        @click="emit('download')"
+      />
+    </UTooltip>
   </div>
 </template>
diff --git a/apps/ui/app/components/DownloadRequestModal.vue b/apps/ui/app/components/DownloadRequestModal.vue
new file mode 100644
index 0000000..5d9c7d4
--- /dev/null
+++ b/apps/ui/app/components/DownloadRequestModal.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import type { CatalogRequestPayload, CatalogTitle, RequestServerOption } from '~/types/management'
+
+const props = defineProps<{ open: boolean, title: CatalogTitle | null, submitting?: boolean, error?: string | null }>()
+const emit = defineEmits<{ 'update:open': [boolean], 'confirm': [CatalogRequestPayload] }>()
+
+// Codebase convention (see settings.vue) is a computed get/set bridge for v-model,
+// not defineModel (which this app does not use).
+const open = computed({ get: () => props.open, set: v => emit('update:open', v) })
+
+const { request } = useManagement()
+const { data, pending } = await useAsyncData('request-options', () =>
+  request<{ servers: RequestServerOption[] }>('catalog/request-options'))
+
+const candidates = computed(() =>
+  (data.value?.servers ?? []).filter(s => props.title && s.mediaType === props.title.mediaType))
+
+// USelect's v-model does not accept null; undefined behaves identically under the
+// `!= null` / `== null` loose checks below, so we use undefined for "unset".
+const serverId = ref<string | undefined>(undefined)
+const qualityProfileId = ref<number | undefined>(undefined)
+const rootFolderPath = ref<string | undefined>(undefined)
+
+const server = computed(() => candidates.value.find(s => s.id === serverId.value) ?? null)
+
+watch(candidates, (list) => {
+  if (list.length && !list.some(s => s.id === serverId.value))
+    serverId.value = list[0]!.id
+}, { immediate: true })
+
+watch(server, (s) => {
+  qualityProfileId.value = s?.qualityProfiles[0]?.id ?? undefined
+  rootFolderPath.value = s?.rootFolders[0]?.path ?? undefined
+}, { immediate: true })
+
+const canSubmit = computed(() => Boolean(serverId.value && qualityProfileId.value != null && rootFolderPath.value))
+
+function onConfirm() {
+  if (!canSubmit.value || !serverId.value || qualityProfileId.value == null || !rootFolderPath.value)
+    return
+  emit('confirm', { serverId: serverId.value, qualityProfileId: Number(qualityProfileId.value), rootFolderPath: rootFolderPath.value })
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Add to your library" :ui="{ footer: 'justify-end' }">
+    <template #body>
+      <p v-if="pending" class="flex items-center gap-2 text-sm text-muted">
+        <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
+        Loading options…
+      </p>
+
+      <p v-else-if="candidates.length === 0" class="text-sm text-muted">
+        No {{ title?.mediaType === 'tv' ? 'Sonarr' : 'Radarr' }} destination is configured for this type. Add one in Settings.
+      </p>
+
+      <div v-else class="space-y-4">
+        <UFormField label="Send to">
+          <USelect
+            v-model="serverId"
+            :items="candidates.map(s => ({ label: s.name, value: s.id }))"
+            class="w-full"
+          />
+        </UFormField>
+
+        <UFormField label="Quality profile">
+          <USelect
+            v-model="qualityProfileId"
+            :items="(server?.qualityProfiles ?? []).map(p => ({ label: p.name, value: p.id }))"
+            class="w-full"
+          />
+        </UFormField>
+
+        <UFormField label="Root folder">
+          <USelect
+            v-model="rootFolderPath"
+            :items="(server?.rootFolders ?? []).map(f => ({ label: f.path, value: f.path }))"
+            class="w-full"
+          />
+        </UFormField>
+
+        <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" :title="error" />
+      </div>
+    </template>
+
+    <template #footer="{ close }">
+      <UButton label="Cancel" color="neutral" variant="ghost" @click="close" />
+      <UButton
+        label="Download"
+        icon="i-ph-download-simple"
+        :disabled="!canSubmit"
+        :loading="submitting"
+        @click="onConfirm"
+      />
+    </template>
+  </UModal>
+</template>
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index 711cd69..d9a7e3c 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { CatalogTitle, PeerCatalogResponse } from '~/types/management'
+import type { CatalogRequestPayload, CatalogTitle, PeerCatalogResponse } from '~/types/management'
 
 const route = useRoute()
 const peerId = computed(() => String(route.params.peerId))
@@ -19,6 +19,19 @@ const titles = computed(() => {
 })
 
 const selected = ref<CatalogTitle | null>(null)
+
+const requestOpen = ref(false)
+const requestTitle = ref<CatalogTitle | null>(null)
+
+function openRequest() {
+  requestTitle.value = selected.value
+  requestOpen.value = true
+}
+
+// Phase 5 replaces this with the POST to catalog/request.
+function onConfirm(_payload: CatalogRequestPayload) {
+  requestOpen.value = false
+}
 </script>
 
 <template>
@@ -75,7 +88,9 @@ const selected = ref<CatalogTitle | null>(null)
     @update:open="(open) => { if (!open) selected = null }"
   >
     <template #body>
-      <CatalogTitleDetail v-if="selected" :title="selected" />
+      <CatalogTitleDetail v-if="selected" :title="selected" @download="openRequest" />
     </template>
   </USlideover>
+
+  <DownloadRequestModal v-model:open="requestOpen" :title="requestTitle" @confirm="onConfirm" />
 </template>
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index 4301319..c60415f 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -73,6 +73,21 @@ export interface PeerCatalogResponse {
   titles: CatalogTitle[]
 }
 
+export interface RequestServerOption {
+  id: string
+  name: string
+  type: 'radarr' | 'sonarr'
+  mediaType: 'movie' | 'tv'
+  qualityProfiles: Array<{ id: number, name: string }>
+  rootFolders: Array<{ path: string, freeSpace?: number }>
+}
+
+export interface CatalogRequestPayload {
+  serverId: string
+  qualityProfileId: number
+  rootFolderPath: string
+}
+
 export interface Overview {
   peers: { total: number, initialized: number, items: PeerItem[] }
   servers: { total: number, initialized: number, sources: number, destinations: number, items: OverviewServerItem[] }

From 2404be33a62aaa2190cba3ded5121a23cb98c4d4 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 00:50:28 +0200
Subject: [PATCH 05/27] feat(catalog): request a peer title into Radarr/Sonarr

Add addAndSearch to the *arr connectors (lookup the title, then add it
monitored with auto-search) and a POST /catalog/request endpoint, and wire
the Download modal to it so requesting a title hands it to *arr.
---
 apps/backend/src/__tests__/catalog.test.ts    | 120 +++++++++++++++++-
 .../backend/src/__tests__/integration.test.ts |  95 ++++++++++++++
 apps/backend/src/lib/servers/arr/base.ts      |  16 +++
 apps/backend/src/lib/servers/arr/radarr.ts    |  25 ++++
 apps/backend/src/lib/servers/arr/sonarr.ts    |  25 ++++
 .../src/modules/catalog/catalog.controller.ts |  30 +++++
 .../src/modules/catalog/catalog.router.ts     |  13 ++
 apps/ui/app/pages/catalog/[peerId].vue        |  48 ++++++-
 8 files changed, 366 insertions(+), 6 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 737e3be..7aa69fe 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -1,5 +1,6 @@
 import type { Release } from '../lib/release'
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, mock, test } from 'bun:test'
+import { BadRequestError } from '../lib/errors/BadRequestError'
 import { NotFoundError } from '../lib/errors/NotFoundError'
 import { CatalogController } from '../modules/catalog/catalog.controller'
 import { groupReleasesIntoTitles, mapLimit } from '../modules/catalog/catalog.lib'
@@ -321,6 +322,123 @@ describe('catalogController.getRequestOptions', () => {
   })
 })
 
+describe('catalogController.requestDownload', () => {
+  function fakeServer(overrides: Partial<{
+    id: string
+    name: string
+    type: 'radarr' | 'sonarr'
+    canDestination: boolean
+    addAndSearch: (params: any) => Promise<void>
+  }> = {}) {
+    return {
+      id: 'radarr-1',
+      name: 'My Radarr',
+      type: 'radarr',
+      canDestination: true,
+      addAndSearch: mock(async () => {}),
+      ...overrides,
+    }
+  }
+
+  function makeConnectors(servers: any[]) {
+    return { servers, peers: [] }
+  }
+
+  test('throws NotFoundError for an unknown serverId', () => {
+    const controller = new CatalogController(makeConnectors([]) as any)
+
+    expect(controller.requestDownload({
+      serverId: 'missing',
+      mediaType: 'movie',
+      tmdbId: 603,
+      qualityProfileId: 1,
+      rootFolderPath: '/movies',
+    })).rejects.toBeInstanceOf(NotFoundError)
+  })
+
+  test('throws BadRequestError when the server is not a destination', () => {
+    const radarr = fakeServer({ canDestination: false })
+    const controller = new CatalogController(makeConnectors([radarr]) as any)
+
+    expect(controller.requestDownload({
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      qualityProfileId: 1,
+      rootFolderPath: '/movies',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
+  test('throws BadRequestError when a movie request targets a Sonarr server', () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
+    const controller = new CatalogController(makeConnectors([sonarr]) as any)
+
+    expect(controller.requestDownload({
+      serverId: 'sonarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      qualityProfileId: 1,
+      rootFolderPath: '/movies',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
+  test('throws BadRequestError when a tv request targets a Radarr server', () => {
+    const radarr = fakeServer()
+    const controller = new CatalogController(makeConnectors([radarr]) as any)
+
+    expect(controller.requestDownload({
+      serverId: 'radarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      qualityProfileId: 1,
+      rootFolderPath: '/tv',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
+  test('calls addAndSearch and returns ok for a valid matching request', async () => {
+    const radarr = fakeServer()
+    const controller = new CatalogController(makeConnectors([radarr]) as any)
+
+    const result = await controller.requestDownload({
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      qualityProfileId: 4,
+      rootFolderPath: '/movies',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Radarr' })
+    expect(radarr.addAndSearch).toHaveBeenCalledTimes(1)
+    expect(radarr.addAndSearch).toHaveBeenCalledWith({
+      tmdbId: 603,
+      tvdbId: undefined,
+      qualityProfileId: 4,
+      rootFolderPath: '/movies',
+    })
+  })
+
+  test('routes a tv request to the matching Sonarr destination', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
+    const controller = new CatalogController(makeConnectors([sonarr]) as any)
+
+    const result = await controller.requestDownload({
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      qualityProfileId: 7,
+      rootFolderPath: '/tv',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Sonarr' })
+    expect(sonarr.addAndSearch).toHaveBeenCalledWith({
+      tmdbId: undefined,
+      tvdbId: 81189,
+      qualityProfileId: 7,
+      rootFolderPath: '/tv',
+    })
+  })
+})
+
 describe('catalogController.getTmdbStatus', () => {
   function makeConnectors() {
     return { servers: [], peers: [] }
diff --git a/apps/backend/src/__tests__/integration.test.ts b/apps/backend/src/__tests__/integration.test.ts
index 79798cc..3341b2f 100644
--- a/apps/backend/src/__tests__/integration.test.ts
+++ b/apps/backend/src/__tests__/integration.test.ts
@@ -9,6 +9,7 @@ import { getApp } from '../app'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
 import { AppConfig, MIGRATIONS } from '../lib/config'
+import { BadRequestError } from '../lib/errors/BadRequestError'
 import { RadarrServerConnector } from '../lib/servers/arr/radarr'
 import { SonarrServerConnector } from '../lib/servers/arr/sonarr'
 import { PeerConnector } from '../lib/servers/peer'
@@ -528,6 +529,100 @@ describe('Auto-registration', () => {
   })
 })
 
+describe('addAndSearch', () => {
+  const lookedUpMovie = { tmdbId: 603, title: 'The Matrix', year: 1999, titleSlug: 'the-matrix-603', images: [] }
+  const lookedUpSeries = { tvdbId: 81189, title: 'Breaking Bad', year: 2008, titleSlug: 'breaking-bad-81189', images: [] }
+
+  test('Radarr: looks up the movie and POSTs it monitored with searchForMovie', async () => {
+    let lookupTerm: any = null
+    let postBody: any = null
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/movie/lookup`, ({ request }) => {
+        lookupTerm = new URL(request.url).searchParams.get('term')
+        return HttpResponse.json([lookedUpMovie])
+      }),
+      http.post(`${RADARR_URL}/api/v3/movie`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 1, ...lookedUpMovie })
+      }),
+    )
+
+    const radarr = markInitialized(makeRadarr())
+    await radarr.addAndSearch({ tmdbId: 603, qualityProfileId: 4, rootFolderPath: '/movies' })
+
+    expect(lookupTerm).toBe('tmdb:603')
+    expect(postBody).toMatchObject({
+      tmdbId: 603,
+      title: 'The Matrix',
+      qualityProfileId: 4,
+      rootFolderPath: '/movies',
+      monitored: true,
+    })
+    expect(postBody.addOptions).toMatchObject({ searchForMovie: true })
+  })
+
+  test('Radarr: throws BadRequestError when no tmdbId is given', async () => {
+    const radarr = markInitialized(makeRadarr())
+    await expect(radarr.addAndSearch({ qualityProfileId: 4, rootFolderPath: '/movies' })).rejects.toThrow(BadRequestError)
+  })
+
+  test('Radarr: throws BadRequestError naming the server and id when lookup is empty', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/movie/lookup`, () => HttpResponse.json([])),
+    )
+    const radarr = markInitialized(makeRadarr())
+    const promise = radarr.addAndSearch({ tmdbId: 603, qualityProfileId: 4, rootFolderPath: '/movies' })
+    await expect(promise).rejects.toThrow(BadRequestError)
+    await expect(promise).rejects.toThrow(/My Radarr/)
+    await expect(promise).rejects.toThrow(/603/)
+  })
+
+  test('Sonarr: looks up the series and POSTs it monitored with searchForMissingEpisodes', async () => {
+    let lookupTerm: any = null
+    let postBody: any = null
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/series/lookup`, ({ request }) => {
+        lookupTerm = new URL(request.url).searchParams.get('term')
+        return HttpResponse.json([lookedUpSeries])
+      }),
+      http.post(`${SONARR_URL}/api/v3/series`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 1, ...lookedUpSeries })
+      }),
+    )
+
+    const sonarr = markInitialized(makeSonarr())
+    await sonarr.addAndSearch({ tvdbId: 81189, qualityProfileId: 7, rootFolderPath: '/tv' })
+
+    expect(lookupTerm).toBe('tvdb:81189')
+    expect(postBody).toMatchObject({
+      tvdbId: 81189,
+      title: 'Breaking Bad',
+      qualityProfileId: 7,
+      rootFolderPath: '/tv',
+      monitored: true,
+      seasonFolder: true,
+    })
+    expect(postBody.addOptions).toMatchObject({ searchForMissingEpisodes: true })
+  })
+
+  test('Sonarr: throws BadRequestError when no tvdbId is given', async () => {
+    const sonarr = markInitialized(makeSonarr())
+    await expect(sonarr.addAndSearch({ qualityProfileId: 7, rootFolderPath: '/tv' })).rejects.toThrow(BadRequestError)
+  })
+
+  test('Sonarr: throws BadRequestError naming the server and id when lookup is empty', async () => {
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/series/lookup`, () => HttpResponse.json([])),
+    )
+    const sonarr = markInitialized(makeSonarr())
+    const promise = sonarr.addAndSearch({ tvdbId: 81189, qualityProfileId: 7, rootFolderPath: '/tv' })
+    await expect(promise).rejects.toThrow(BadRequestError)
+    await expect(promise).rejects.toThrow(/My Sonarr/)
+    await expect(promise).rejects.toThrow(/81189/)
+  })
+})
+
 describe('Routes mount without peers or sources', () => {
   function createBareApp() {
     return getApp(envs, config, { servers: [], peers: [] })
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index 9caf467..4335381 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -42,6 +42,13 @@ const JACK_DOWNLOAD_CLIENT_PRIORITY = 50
 
 export type ReleaseKind = 'movie' | 'episode'
 
+export interface AddAndSearchParams {
+  tmdbId?: number
+  tvdbId?: number
+  qualityProfileId: number
+  rootFolderPath: string
+}
+
 export function basename(path: string): string {
   return path.split(BASENAME_SEPARATOR_REGEX).pop() ?? path
 }
@@ -189,6 +196,15 @@ export abstract class ArrServerConnector extends ServerConnector {
       .map(f => ({ path: f.path, freeSpace: f.freeSpace }))
   }
 
+  /** Add a title to this *arr (monitored) and kick off an automatic search. */
+  @requiresDestination
+  @requiresInitialization
+  async addAndSearch(params: AddAndSearchParams): Promise<void> {
+    return this.doAddAndSearch(params)
+  }
+
+  protected abstract doAddAndSearch(params: AddAndSearchParams): Promise<void>
+
   /**
    * Lowercased torrent infohashes (`downloadId`s) that this *arr has finished
    * importing recently, read from its history. The import watcher matches these
diff --git a/apps/backend/src/lib/servers/arr/radarr.ts b/apps/backend/src/lib/servers/arr/radarr.ts
index dd9de37..f3ae703 100644
--- a/apps/backend/src/lib/servers/arr/radarr.ts
+++ b/apps/backend/src/lib/servers/arr/radarr.ts
@@ -1,6 +1,8 @@
 import type { MovieFileResource, MovieResource } from '@jack/schemas/radarr/types'
 import type { AutoRegisterConfig, ConnectorHeadersConfig } from '../../config'
 import type { Release } from '../../release'
+import type { AddAndSearchParams } from './base'
+import { BadRequestError } from '../../errors/BadRequestError'
 import { normalizeImdbId, ReleaseCategory } from '../../release'
 import { setSpanAttribute, setSpanAttributes } from '../../span-attributes'
 import { withSpan } from '../../tracing'
@@ -146,4 +148,27 @@ export class RadarrServerConnector extends ArrServerConnector {
     const movie = await this.getMovie(id)
     return (movie?.movieFile as MovieFileResource | undefined)?.path ?? null
   }
+
+  protected override async doAddAndSearch(params: AddAndSearchParams): Promise<void> {
+    if (params.tmdbId == null)
+      throw new BadRequestError('A tmdbId is required to add a movie to Radarr')
+    const lookup = await this.arrGet<MovieResource[]>('/api/v3/movie/lookup', { term: `tmdb:${params.tmdbId}` })
+    const movie = Array.isArray(lookup) ? lookup[0] : undefined
+    if (!movie)
+      throw new BadRequestError(`No movie found on ${this.name} for tmdbId ${params.tmdbId}`)
+
+    const body = {
+      ...movie,
+      qualityProfileId: params.qualityProfileId,
+      rootFolderPath: params.rootFolderPath,
+      monitored: true,
+      minimumAvailability: 'released',
+      addOptions: { searchForMovie: true },
+    }
+    await this.fetch('/api/v3/movie', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    } as any)
+  }
 }
diff --git a/apps/backend/src/lib/servers/arr/sonarr.ts b/apps/backend/src/lib/servers/arr/sonarr.ts
index 22f5018..91b2fdc 100644
--- a/apps/backend/src/lib/servers/arr/sonarr.ts
+++ b/apps/backend/src/lib/servers/arr/sonarr.ts
@@ -1,6 +1,8 @@
 import type { EpisodeFileResource, EpisodeResource, SeriesResource } from '@jack/schemas/sonarr/types'
 import type { AutoRegisterConfig, ConnectorHeadersConfig } from '../../config'
 import type { Release } from '../../release'
+import type { AddAndSearchParams } from './base'
+import { BadRequestError } from '../../errors/BadRequestError'
 import { ReleaseCategory } from '../../release'
 import { setSpanAttributes } from '../../span-attributes'
 import { withSpan } from '../../tracing'
@@ -163,4 +165,27 @@ export class SonarrServerConnector extends ArrServerConnector {
     const bundle = await this.fetchEpisodeBundle(id)
     return bundle?.file?.path ?? null
   }
+
+  protected override async doAddAndSearch(params: AddAndSearchParams): Promise<void> {
+    if (params.tvdbId == null)
+      throw new BadRequestError('A tvdbId is required to add a series to Sonarr')
+    const lookup = await this.arrGet<SeriesResource[]>('/api/v3/series/lookup', { term: `tvdb:${params.tvdbId}` })
+    const series = Array.isArray(lookup) ? lookup[0] : undefined
+    if (!series)
+      throw new BadRequestError(`No series found on ${this.name} for tvdbId ${params.tvdbId}`)
+
+    const body = {
+      ...series,
+      qualityProfileId: params.qualityProfileId,
+      rootFolderPath: params.rootFolderPath,
+      monitored: true,
+      seasonFolder: true,
+      addOptions: { monitor: 'all', searchForMissingEpisodes: true },
+    }
+    await this.fetch('/api/v3/series', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    } as any)
+  }
 }
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index 84ebf50..b9aa5d3 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -2,6 +2,7 @@ import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { PeerConnector } from '../../lib/servers/peer'
 import type { TmdbClient } from '../../lib/tmdb/client'
 import type { CatalogTitle } from './catalog.lib'
+import { BadRequestError } from '../../lib/errors/BadRequestError'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
 import { groupReleasesIntoTitles, mapLimit } from './catalog.lib'
 
@@ -27,6 +28,15 @@ export interface RequestServerOption {
   rootFolders: Array<{ path: string, freeSpace?: number }>
 }
 
+export interface CatalogRequestInput {
+  serverId: string
+  mediaType: 'movie' | 'tv'
+  tmdbId?: number
+  tvdbId?: number
+  qualityProfileId: number
+  rootFolderPath: string
+}
+
 export class CatalogController {
   constructor(
     private readonly connectors: { servers: ArrServerConnector[], peers: PeerConnector[] },
@@ -91,6 +101,26 @@ export class CatalogController {
     return options.filter((o): o is RequestServerOption => o !== null)
   }
 
+  async requestDownload(input: CatalogRequestInput): Promise<{ ok: true, server: string }> {
+    const server = this.connectors.servers.find(s => s.id === input.serverId)
+    if (!server)
+      throw new NotFoundError(`No server found with id "${input.serverId}"`)
+    if (!server.canDestination)
+      throw new BadRequestError(`Server "${server.name}" is not a destination`)
+    // Defense in depth (the UI already filters): a movie must go to Radarr, tv to Sonarr.
+    const expectedType = input.mediaType === 'tv' ? 'sonarr' : 'radarr'
+    if (server.type !== expectedType)
+      throw new BadRequestError(`Server "${server.name}" cannot handle ${input.mediaType} requests`)
+
+    await server.addAndSearch({
+      tmdbId: input.tmdbId,
+      tvdbId: input.tvdbId,
+      qualityProfileId: input.qualityProfileId,
+      rootFolderPath: input.rootFolderPath,
+    })
+    return { ok: true, server: server.name }
+  }
+
   async getTmdbStatus(): Promise<TmdbStatus> {
     if (!this.tmdb)
       return { configured: false, ok: false }
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index 5b87915..c748b1f 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -5,6 +5,15 @@ import { z } from 'zod'
 
 const peerParam = z.object({ peerId: z.string().min(1) })
 
+const requestBody = z.object({
+  serverId: z.string().min(1),
+  mediaType: z.enum(['movie', 'tv']),
+  tmdbId: z.number().int().optional(),
+  tvdbId: z.number().int().optional(),
+  qualityProfileId: z.number().int(),
+  rootFolderPath: z.string().min(1),
+})
+
 export function getCatalogRouter(controller: CatalogController) {
   const app = new Hono()
 
@@ -14,6 +23,10 @@ export function getCatalogRouter(controller: CatalogController) {
   // Register before `/:peerId` so "request-options" isn't captured as a peerId.
   app.get('/request-options', async c => c.json({ servers: await controller.getRequestOptions() }))
 
+  app.post('/request', zValidator('json', requestBody), async (c) => {
+    return c.json(await controller.requestDownload(c.req.valid('json')))
+  })
+
   app.get('/:peerId', zValidator('param', peerParam), async (c) => {
     const { peerId } = c.req.valid('param')
     return c.json(await controller.getPeerCatalog(peerId))
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index d9a7e3c..dd494e0 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -3,7 +3,8 @@ import type { CatalogRequestPayload, CatalogTitle, PeerCatalogResponse } from '~
 
 const route = useRoute()
 const peerId = computed(() => String(route.params.peerId))
-const { request } = useManagement()
+const { request, extractError } = useManagement()
+const toast = useToast()
 
 const { data, pending, error } = await useAsyncData(
   `catalog-${peerId.value}`,
@@ -22,15 +23,46 @@ const selected = ref<CatalogTitle | null>(null)
 
 const requestOpen = ref(false)
 const requestTitle = ref<CatalogTitle | null>(null)
+const requestSubmitting = ref(false)
+const requestError = ref<string | null>(null)
 
 function openRequest() {
   requestTitle.value = selected.value
+  requestError.value = null
   requestOpen.value = true
 }
 
-// Phase 5 replaces this with the POST to catalog/request.
-function onConfirm(_payload: CatalogRequestPayload) {
-  requestOpen.value = false
+async function onConfirm(payload: CatalogRequestPayload) {
+  const title = requestTitle.value
+  if (!title)
+    return
+  requestSubmitting.value = true
+  requestError.value = null
+  try {
+    await request('catalog/request', {
+      method: 'POST',
+      body: {
+        ...payload,
+        mediaType: title.mediaType,
+        tmdbId: title.tmdbId,
+        tvdbId: title.tvdbId,
+      },
+    })
+    requestOpen.value = false
+    selected.value = null
+    toast.add({
+      title: 'Added to your library',
+      description: `"${title.metadata?.title ?? title.displayTitle}" is being searched by your *arr.`,
+      color: 'success',
+      icon: 'i-ph-check-circle',
+    })
+  }
+  catch (err) {
+    requestError.value = extractError(err, 'Could not request this title.')
+  }
+  finally {
+    requestSubmitting.value = false
+  }
 }
 </script>
 
@@ -92,5 +124,11 @@ function onConfirm(_payload: CatalogRequestPayload) {
     </template>
   </USlideover>
 
-  <DownloadRequestModal v-model:open="requestOpen" :title="requestTitle" @confirm="onConfirm" />
+  <DownloadRequestModal
+    v-model:open="requestOpen"
+    :title="requestTitle"
+    :submitting="requestSubmitting"
+    :error="requestError"
+    @confirm="onConfirm"
+  />
 </template>

From 4867c7517554b4070ba9f6beff1366ab63b5f257 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 09:05:09 +0200
Subject: [PATCH 06/27] feat(torznab): tag Jack releases with the Internal
 indexer flag

Emit torznab attr tag=internal on every item; *arr maps it to the Internal
indexer flag, so releases are targetable by a custom format.
---
 apps/backend/src/__tests__/torznab.test.ts         | 10 ++++++++++
 apps/backend/src/modules/torznab/torznab.router.ts |  4 ++++
 2 files changed, 14 insertions(+)

diff --git a/apps/backend/src/__tests__/torznab.test.ts b/apps/backend/src/__tests__/torznab.test.ts
index b44189d..4aabaa0 100644
--- a/apps/backend/src/__tests__/torznab.test.ts
+++ b/apps/backend/src/__tests__/torznab.test.ts
@@ -53,6 +53,16 @@ describe('Torznab XML helpers', () => {
     expect(attrValue(item, 'uploadvolumefactor')).toBe(1)
   })
 
+  test('buildSearchResultXml tags every item as an internal release', () => {
+    // *arr's TorznabRssParser maps `tag=internal` to the Internal indexer flag,
+    // so a custom format (IndexerFlagSpecification) can target Jack releases.
+    const result = buildSearchResultXml([releaseToTorznab(movieRelease, 'peer1', 'Friend', 'http://localhost:3000', JACK_API_KEY)])
+    const tags = (result.rss.channel.item[0]['torznab:attr'] as Array<Record<string, any>>)
+      .filter(a => a['@name'] === 'tag')
+      .map(a => a['@value'])
+    expect(tags).toContain('internal')
+  })
+
   test('buildSearchResultXml emits tv attrs for episodes', () => {
     const result = buildSearchResultXml([releaseToTorznab(episodeRelease, 'peer1', 'Friend', 'http://localhost:3000', JACK_API_KEY)])
     const item = result.rss.channel.item[0]
diff --git a/apps/backend/src/modules/torznab/torznab.router.ts b/apps/backend/src/modules/torznab/torznab.router.ts
index 979363a..edd5271 100644
--- a/apps/backend/src/modules/torznab/torznab.router.ts
+++ b/apps/backend/src/modules/torznab/torznab.router.ts
@@ -64,6 +64,10 @@ function itemToObject(item: TorznabItem): Record<string, any> {
     // Jack files are always freely available; tell *arr not to weight ratio.
     { '@name': 'downloadvolumefactor', '@value': 0 },
     { '@name': 'uploadvolumefactor', '@value': 1 },
+    // *arr's TorznabRssParser maps `tag=internal` to the Internal indexer flag,
+    // marking every Jack release as coming from your own peer network so a custom
+    // format (IndexerFlagSpecification) can score/prefer it.
+    { '@name': 'tag', '@value': 'internal' },
   ]
   if (item.imdbId)
     attrs.push({ '@name': 'imdbid', '@value': item.imdbId })

From ac8a50ee494ae1b389f921be1fc4d30221a6c5b5 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 09:05:15 +0200
Subject: [PATCH 07/27] feat(arr): register a Jack-only custom format and
 quality profile

Auto-register (and ensure on demand) a 'Jack' custom format matching the
Internal indexer flag and a 'Jack' quality profile that only accepts releases
with it (minFormatScore 1, upgrades off). Catalog downloads force that profile
so *arr grabs the title only from Jack, never from other indexers. The
Internal flag value is per-app (Radarr 32, Sonarr 8).
---
 apps/backend/src/__tests__/catalog.test.ts    |  22 ++-
 .../backend/src/__tests__/integration.test.ts | 143 ++++++++++++++++++
 apps/backend/src/index.ts                     |  20 +--
 apps/backend/src/lib/autoregister.test.ts     |  30 +++-
 apps/backend/src/lib/autoregister.ts          |  16 +-
 apps/backend/src/lib/servers/arr/base.ts      | 105 ++++++++++++-
 apps/backend/src/lib/servers/arr/radarr.ts    |   4 +
 apps/backend/src/lib/servers/arr/sonarr.ts    |   4 +
 .../src/modules/catalog/catalog.controller.ts |  12 +-
 .../src/modules/catalog/catalog.router.ts     |   1 -
 .../app/components/DownloadRequestModal.vue   |  20 +--
 apps/ui/app/types/management.ts               |   2 -
 12 files changed, 326 insertions(+), 53 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 7aa69fe..5f9d7d0 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -247,7 +247,6 @@ describe('catalogController.getRequestOptions', () => {
     type: 'radarr' | 'sonarr'
     canDestination: boolean
     isInitialized: boolean
-    getQualityProfiles: () => Promise<Array<{ id: number, name: string }>>
     getRootFolders: () => Promise<Array<{ path: string, freeSpace?: number }>>
   }> = {}) {
     return {
@@ -256,7 +255,6 @@ describe('catalogController.getRequestOptions', () => {
       type: 'radarr',
       canDestination: true,
       isInitialized: true,
-      getQualityProfiles: async () => [{ id: 1, name: 'HD-1080p' }],
       getRootFolders: async () => [{ path: '/movies', freeSpace: 1000 }],
       ...overrides,
     }
@@ -278,7 +276,7 @@ describe('catalogController.getRequestOptions', () => {
     expect(options[0]!.name).toBe('My Radarr')
     expect(options[0]!.type).toBe('radarr')
     expect(options[0]!.mediaType).toBe('movie')
-    expect(options[0]!.qualityProfiles).toEqual([{ id: 1, name: 'HD-1080p' }])
+    expect(options[0]!).not.toHaveProperty('qualityProfiles')
     expect(options[0]!.rootFolders).toEqual([{ path: '/movies', freeSpace: 1000 }])
   })
 
@@ -304,11 +302,11 @@ describe('catalogController.getRequestOptions', () => {
     expect(await controller.getRequestOptions()).toEqual([])
   })
 
-  test('skips a destination whose getQualityProfiles rejects but keeps others', async () => {
+  test('skips a destination whose getRootFolders rejects but keeps others', async () => {
     const broken = fakeServer({
       id: 'radarr-broken',
       name: 'Broken Radarr',
-      getQualityProfiles: async () => {
+      getRootFolders: async () => {
         throw new Error('unreachable')
       },
     })
@@ -328,6 +326,7 @@ describe('catalogController.requestDownload', () => {
     name: string
     type: 'radarr' | 'sonarr'
     canDestination: boolean
+    ensureJackQualityProfile: () => Promise<number>
     addAndSearch: (params: any) => Promise<void>
   }> = {}) {
     return {
@@ -335,6 +334,7 @@ describe('catalogController.requestDownload', () => {
       name: 'My Radarr',
       type: 'radarr',
       canDestination: true,
+      ensureJackQualityProfile: mock(async () => 77),
       addAndSearch: mock(async () => {}),
       ...overrides,
     }
@@ -351,7 +351,6 @@ describe('catalogController.requestDownload', () => {
       serverId: 'missing',
       mediaType: 'movie',
       tmdbId: 603,
-      qualityProfileId: 1,
       rootFolderPath: '/movies',
     })).rejects.toBeInstanceOf(NotFoundError)
   })
@@ -364,7 +363,6 @@ describe('catalogController.requestDownload', () => {
       serverId: 'radarr-1',
       mediaType: 'movie',
       tmdbId: 603,
-      qualityProfileId: 1,
       rootFolderPath: '/movies',
     })).rejects.toBeInstanceOf(BadRequestError)
   })
@@ -377,7 +375,6 @@ describe('catalogController.requestDownload', () => {
       serverId: 'sonarr-1',
       mediaType: 'movie',
       tmdbId: 603,
-      qualityProfileId: 1,
       rootFolderPath: '/movies',
     })).rejects.toBeInstanceOf(BadRequestError)
   })
@@ -390,7 +387,6 @@ describe('catalogController.requestDownload', () => {
       serverId: 'radarr-1',
       mediaType: 'tv',
       tvdbId: 81189,
-      qualityProfileId: 1,
       rootFolderPath: '/tv',
     })).rejects.toBeInstanceOf(BadRequestError)
   })
@@ -403,16 +399,17 @@ describe('catalogController.requestDownload', () => {
       serverId: 'radarr-1',
       mediaType: 'movie',
       tmdbId: 603,
-      qualityProfileId: 4,
       rootFolderPath: '/movies',
     })
 
     expect(result).toEqual({ ok: true, server: 'My Radarr' })
+    expect(radarr.ensureJackQualityProfile).toHaveBeenCalledTimes(1)
     expect(radarr.addAndSearch).toHaveBeenCalledTimes(1)
+    // The Jack profile (77) is forced regardless of any client input.
     expect(radarr.addAndSearch).toHaveBeenCalledWith({
       tmdbId: 603,
       tvdbId: undefined,
-      qualityProfileId: 4,
+      qualityProfileId: 77,
       rootFolderPath: '/movies',
     })
   })
@@ -425,7 +422,6 @@ describe('catalogController.requestDownload', () => {
       serverId: 'sonarr-1',
       mediaType: 'tv',
       tvdbId: 81189,
-      qualityProfileId: 7,
       rootFolderPath: '/tv',
     })
 
@@ -433,7 +429,7 @@ describe('catalogController.requestDownload', () => {
     expect(sonarr.addAndSearch).toHaveBeenCalledWith({
       tmdbId: undefined,
       tvdbId: 81189,
-      qualityProfileId: 7,
+      qualityProfileId: 77,
       rootFolderPath: '/tv',
     })
   })
diff --git a/apps/backend/src/__tests__/integration.test.ts b/apps/backend/src/__tests__/integration.test.ts
index 3341b2f..2f1aee3 100644
--- a/apps/backend/src/__tests__/integration.test.ts
+++ b/apps/backend/src/__tests__/integration.test.ts
@@ -623,6 +623,149 @@ describe('addAndSearch', () => {
   })
 })
 
+describe('ensureJackCustomFormat', () => {
+  test('Radarr: POSTs a "Jack" custom format matching the Internal flag (value 32)', async () => {
+    let postBody: any = null
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
+      http.post(`${RADARR_URL}/api/v3/customformat`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 11, name: 'Jack' })
+      }),
+    )
+
+    const radarr = markInitialized(makeRadarr())
+    const id = await radarr.ensureJackCustomFormat()
+
+    expect(id).toBe(11)
+    expect(postBody).toMatchObject({ name: 'Jack', includeCustomFormatWhenRenaming: false })
+    expect(postBody.specifications).toHaveLength(1)
+    expect(postBody.specifications[0]).toMatchObject({
+      name: 'Internal',
+      implementation: 'IndexerFlagSpecification',
+      negate: false,
+      required: true,
+    })
+    expect(postBody.specifications[0].fields).toEqual([{ name: 'value', value: 32 }])
+  })
+
+  test('Sonarr: uses the Internal flag value 8', async () => {
+    let postBody: any = null
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
+      http.post(`${SONARR_URL}/api/v3/customformat`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 5, name: 'Jack' })
+      }),
+    )
+
+    const sonarr = markInitialized(makeSonarr())
+    const id = await sonarr.ensureJackCustomFormat()
+
+    expect(id).toBe(5)
+    expect(postBody.specifications[0].fields).toEqual([{ name: 'value', value: 8 }])
+  })
+
+  test('upserts an existing "Jack" custom format with a PUT to /{id}', async () => {
+    let putBody: any = null
+    let posted = false
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([{ id: 9, name: 'Jack' }])),
+      http.post(`${RADARR_URL}/api/v3/customformat`, () => {
+        posted = true
+        return HttpResponse.json({ id: 9, name: 'Jack' })
+      }),
+      http.put(`${RADARR_URL}/api/v3/customformat/9`, async ({ request }) => {
+        putBody = await request.json()
+        return HttpResponse.json({ id: 9, name: 'Jack' })
+      }),
+    )
+
+    const radarr = markInitialized(makeRadarr())
+    const id = await radarr.ensureJackCustomFormat()
+
+    expect(id).toBe(9)
+    expect(posted).toBe(false)
+    expect(putBody).toMatchObject({ id: 9, name: 'Jack' })
+  })
+})
+
+describe('ensureJackQualityProfile', () => {
+  const schemaTemplate = {
+    name: '',
+    upgradeAllowed: false,
+    cutoff: 1,
+    minFormatScore: 0,
+    cutoffFormatScore: 0,
+    items: [
+      { quality: { id: 1, name: 'SDTV' }, allowed: false },
+      { name: 'HD', allowed: false, items: [{ quality: { id: 2, name: 'WEBDL-1080p' }, allowed: false }] },
+    ],
+    formatItems: [
+      { format: 11, name: 'Jack', score: 0 },
+      { format: 12, name: 'Other', score: 0 },
+    ],
+  }
+
+  test('Radarr: ensures the CF then POSTs a "Jack" profile that only scores the Jack flag', async () => {
+    let postBody: any = null
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
+      http.post(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json({ id: 11, name: 'Jack' })),
+      http.get(`${RADARR_URL}/api/v3/qualityprofile/schema`, () => HttpResponse.json(schemaTemplate)),
+      http.get(`${RADARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([])),
+      http.post(`${RADARR_URL}/api/v3/qualityprofile`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 77, name: 'Jack' })
+      }),
+    )
+
+    const radarr = markInitialized(makeRadarr())
+    const id = await radarr.ensureJackQualityProfile()
+
+    expect(id).toBe(77)
+    expect(postBody).toMatchObject({
+      name: 'Jack',
+      upgradeAllowed: false,
+      minFormatScore: 1,
+      cutoffFormatScore: 1,
+    })
+    // All qualities allowed — recursively, including the nested group.
+    expect(postBody.items[0].allowed).toBe(true)
+    expect(postBody.items[1].allowed).toBe(true)
+    expect(postBody.items[1].items[0].allowed).toBe(true)
+    // Only the Jack format is scored 1; others stay at 0.
+    expect(postBody.formatItems.find((f: any) => f.name === 'Jack').score).toBe(1)
+    expect(postBody.formatItems.find((f: any) => f.name === 'Other').score).toBe(0)
+  })
+
+  test('upserts an existing "Jack" profile with a PUT to /{id}', async () => {
+    let putBody: any = null
+    let posted = false
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([{ id: 11, name: 'Jack' }])),
+      http.put(`${RADARR_URL}/api/v3/customformat/11`, () => HttpResponse.json({ id: 11, name: 'Jack' })),
+      http.get(`${RADARR_URL}/api/v3/qualityprofile/schema`, () => HttpResponse.json(schemaTemplate)),
+      http.get(`${RADARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([{ id: 42, name: 'Jack' }])),
+      http.post(`${RADARR_URL}/api/v3/qualityprofile`, () => {
+        posted = true
+        return HttpResponse.json({ id: 42, name: 'Jack' })
+      }),
+      http.put(`${RADARR_URL}/api/v3/qualityprofile/42`, async ({ request }) => {
+        putBody = await request.json()
+        return HttpResponse.json({ id: 42, name: 'Jack' })
+      }),
+    )
+
+    const radarr = markInitialized(makeRadarr())
+    const id = await radarr.ensureJackQualityProfile()
+
+    expect(id).toBe(42)
+    expect(posted).toBe(false)
+    expect(putBody).toMatchObject({ id: 42, name: 'Jack', minFormatScore: 1 })
+  })
+})
+
 describe('Routes mount without peers or sources', () => {
   function createBareApp() {
     return getApp(envs, config, { servers: [], peers: [] })
diff --git a/apps/backend/src/index.ts b/apps/backend/src/index.ts
index 5c2cd08..6fea726 100644
--- a/apps/backend/src/index.ts
+++ b/apps/backend/src/index.ts
@@ -113,15 +113,17 @@ for (const dest of registrable) {
     internalUrl: jackConfig.internalUrl,
     downloads: Boolean(downloads),
     category: qbCategoryForServer(dest.id),
-    onSuccess: (kind, name, meta) =>
-      logger.info(
-        kind === 'download client'
-          ? { destination: name, downloadClientId: meta.downloadClientId }
-          : { destination: name, categories: meta.categories, downloadClientId: meta.downloadClientId },
-        kind === 'download client'
-          ? 'Registered Jack as qBittorrent download client'
-          : 'Registered Jack as Torznab indexer',
-      ),
+    onSuccess: (kind, name, meta) => {
+      if (kind === 'download client') {
+        logger.info({ destination: name, downloadClientId: meta.downloadClientId }, 'Registered Jack as qBittorrent download client')
+        return
+      }
+      if (kind === 'quality profile') {
+        logger.info({ destination: name, profileId: meta.profileId }, 'Registered Jack-only quality profile')
+        return
+      }
+      logger.info({ destination: name, categories: meta.categories, downloadClientId: meta.downloadClientId }, 'Registered Jack as Torznab indexer')
+    },
     onFailure: logRegistrationFailure,
   })
 }
diff --git a/apps/backend/src/lib/autoregister.test.ts b/apps/backend/src/lib/autoregister.test.ts
index 377a513..79ef47b 100644
--- a/apps/backend/src/lib/autoregister.test.ts
+++ b/apps/backend/src/lib/autoregister.test.ts
@@ -1,7 +1,7 @@
 import type { ManagedRegistrationDeps } from './autoregister'
 import type { ArrServerConnector } from './servers/arr/base'
 import { Database } from 'bun:sqlite'
-import { beforeEach, describe, expect, test } from 'bun:test'
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
 import { drizzle } from 'drizzle-orm/bun-sqlite'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
@@ -21,7 +21,7 @@ describe('registerManagedForDestination', () => {
     service = new ManagedApiKeys(repo)
   })
 
-  function stubDest(over: Partial<{ registerIndexer: () => Promise<void>, registerDownloadClient: () => Promise<number> }> = {}): ArrServerConnector {
+  function stubDest(over: Partial<{ registerIndexer: () => Promise<void>, registerDownloadClient: () => Promise<number>, ensureJackQualityProfile: () => Promise<number> }> = {}): ArrServerConnector {
     return {
       id: 'srv-a',
       name: 'Radarr',
@@ -29,6 +29,7 @@ describe('registerManagedForDestination', () => {
       autoRegister: { enable: true, priority: 1 },
       registerDownloadClient: over.registerDownloadClient ?? (async () => 1),
       registerIndexer: over.registerIndexer ?? (async () => {}),
+      ensureJackQualityProfile: over.ensureJackQualityProfile ?? (async () => 99),
     } as unknown as ArrServerConnector
   }
 
@@ -93,4 +94,29 @@ describe('registerManagedForDestination', () => {
     )
     expect(repo.findByServerId('srv-a').map(r => r.id)).toEqual([old.id])
   })
+
+  test('registers the Jack quality profile and reports it via onSuccess', async () => {
+    const profileCall = mock(async () => 77)
+    const successes: Array<[string, number | undefined]> = []
+    await registerManagedForDestination(
+      stubDest({ ensureJackQualityProfile: profileCall }),
+      { ...deps(), onSuccess: (kind, _name, meta) => successes.push([kind, meta.profileId]) },
+    )
+    expect(profileCall).toHaveBeenCalledTimes(1)
+    expect(successes).toContainEqual(['quality profile', 77])
+  })
+
+  test('a failing quality-profile registration does not gate the managed-key commit', async () => {
+    const old = service.provision('srv-a')
+    const failures: string[] = []
+    await registerManagedForDestination(
+      stubDest({ ensureJackQualityProfile: async () => { throw new Error('qp') } }),
+      { ...deps(), onFailure: kind => failures.push(kind) },
+    )
+    // Download client + indexer both succeeded → still a full commit despite the profile failing.
+    const rows = repo.findByServerId('srv-a')
+    expect(rows).toHaveLength(1)
+    expect(rows[0]!.id).not.toBe(old.id)
+    expect(failures).toContain('quality profile')
+  })
 })
diff --git a/apps/backend/src/lib/autoregister.ts b/apps/backend/src/lib/autoregister.ts
index 28987f0..a0310ce 100644
--- a/apps/backend/src/lib/autoregister.ts
+++ b/apps/backend/src/lib/autoregister.ts
@@ -4,6 +4,7 @@ import type { ArrServerConnector } from './servers/arr/base'
 export interface ManagedRegistrationMeta {
   downloadClientId?: number
   categories?: number[]
+  profileId?: number
 }
 
 export interface ManagedRegistrationDeps {
@@ -11,8 +12,8 @@ export interface ManagedRegistrationDeps {
   internalUrl: string
   downloads: boolean
   category: string
-  onSuccess: (kind: 'download client' | 'indexer', name: string, meta: ManagedRegistrationMeta) => void
-  onFailure: (kind: 'download client' | 'indexer', name: string, err: unknown) => void
+  onSuccess: (kind: 'download client' | 'indexer' | 'quality profile', name: string, meta: ManagedRegistrationMeta) => void
+  onFailure: (kind: 'download client' | 'indexer' | 'quality profile', name: string, err: unknown) => void
 }
 
 /**
@@ -66,6 +67,17 @@ export async function registerManagedForDestination(
     deps.onFailure('indexer', dest.name, err)
   }
 
+  // Best-effort: register the Jack-only custom format + quality profile so *arr
+  // won't grab a catalog title from a non-Jack indexer. Independent of the
+  // download client/indexer; its failure must not gate the managed-key commit.
+  try {
+    const profileId = await dest.ensureJackQualityProfile()
+    deps.onSuccess('quality profile', dest.name, { profileId })
+  }
+  catch (err) {
+    deps.onFailure('quality profile', dest.name, err)
+  }
+
   // "Attempted" download = only when downloads is enabled. The indexer is always attempted.
   const allAttemptedOk = (downloads ? downloadDelivered : true) && indexerDelivered
   const anyDelivered = downloadDelivered || indexerDelivered
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index 4335381..0c986ca 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -33,6 +33,10 @@ export const DestinationServerHealthIssue = z.array(
 // the auto-registered indexer to it.
 const DownloadClientResource = z.object({ id: z.number().int() })
 
+// *arr returns the saved custom format / quality profile on create; we only need
+// its id (to score the format and to force the profile on catalog downloads).
+const CreatedResourceId = z.object({ id: z.number().int() })
+
 // Register the Jack client at *arr's lowest selectable priority (the UI caps it
 // at 50). *arr's general client pool only round-robins among the best-priority
 // group, so a worst-priority Jack client is never picked for real torrents from
@@ -89,6 +93,9 @@ export abstract class ArrServerConnector extends ServerConnector {
   abstract get categories(): number[]
   // qBittorrent settings use a per-app category field name.
   protected abstract get qbCategoryFieldName(): string
+  // *arr's IndexerFlagSpecification value for the "Internal" flag differs per app
+  // (Sonarr = 8, Radarr = 32); a single hardcoded value would silently mismatch.
+  protected abstract get internalIndexerFlagValue(): number
 
   protected override async runInit(): Promise<void> {
     const apiInfo = await this.ping(z.object({ appName: z.string(), version: z.string() }))
@@ -178,13 +185,101 @@ export abstract class ArrServerConnector extends ServerConnector {
     return this.fetch('/api/v3/health', { schema: z.array(DestinationServerHealthIssue) })
   }
 
+  /**
+   * Upsert a custom format named "Jack" that matches *arr's Internal indexer flag
+   * (which jack emits as `tag=internal` on its Torznab items). Returns the format id.
+   */
+  @requiresDestination
+  @requiresInitialization
+  async ensureJackCustomFormat(): Promise<number> {
+    const existingFormats = await this.arrGet<any[]>('/api/v3/customformat')
+    const existing: any = Array.isArray(existingFormats)
+      ? existingFormats.find((cf: any) => cf.name === 'Jack')
+      : null
+
+    const body = {
+      name: 'Jack',
+      includeCustomFormatWhenRenaming: false,
+      specifications: [{
+        name: 'Internal',
+        implementation: 'IndexerFlagSpecification',
+        negate: false,
+        required: true,
+        fields: [{ name: 'value', value: this.internalIndexerFlagValue }],
+      }],
+    }
+
+    if (existing) {
+      await this.fetch(`/api/v3/customformat/${existing.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...body, id: existing.id }),
+      } as any)
+      return existing.id as number
+    }
+
+    const created = await this.fetch<typeof CreatedResourceId>('/api/v3/customformat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      schema: CreatedResourceId,
+    } as any)
+    return created.id
+  }
+
+  /**
+   * Ensure the Jack custom format exists, then upsert a quality profile named
+   * "Jack" that accepts every quality but only scores the Jack flag (minFormatScore
+   * 1), so *arr won't grab a matching release from a non-Jack indexer. Returns the
+   * profile id.
+   */
   @requiresDestination
   @requiresInitialization
-  async getQualityProfiles(): Promise<Array<{ id: number, name: string }>> {
-    const profiles = await this.arrGet<Array<{ id: number, name: string }>>('/api/v3/qualityprofile')
-    return (Array.isArray(profiles) ? profiles : [])
-      .filter(p => p.id != null && p.name != null)
-      .map(p => ({ id: p.id, name: p.name }))
+  async ensureJackQualityProfile(): Promise<number> {
+    const cfId = await this.ensureJackCustomFormat()
+    const schema = await this.arrGet<any>('/api/v3/qualityprofile/schema')
+
+    // Each item may itself nest an `items` array (quality groups); allow at every level.
+    const allowAll = (items: any[]): any[] =>
+      items.map((item: any) => ({
+        ...item,
+        allowed: true,
+        ...(Array.isArray(item.items) ? { items: allowAll(item.items) } : {}),
+      }))
+
+    const profile = {
+      ...schema,
+      name: 'Jack',
+      // Grab the peer's file once and stop — no chasing "better" Jack releases.
+      upgradeAllowed: false,
+      items: allowAll(Array.isArray(schema?.items) ? schema.items : []),
+      minFormatScore: 1,
+      cutoffFormatScore: 1,
+      formatItems: (Array.isArray(schema?.formatItems) ? schema.formatItems : []).map((fi: any) =>
+        (fi.name === 'Jack' || fi.format === cfId) ? { ...fi, score: 1 } : fi),
+    }
+
+    const existingProfiles = await this.arrGet<any[]>('/api/v3/qualityprofile')
+    const existing: any = Array.isArray(existingProfiles)
+      ? existingProfiles.find((p: any) => p.name === 'Jack')
+      : null
+
+    if (existing) {
+      await this.fetch(`/api/v3/qualityprofile/${existing.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...profile, id: existing.id }),
+      } as any)
+      return existing.id as number
+    }
+
+    const created = await this.fetch<typeof CreatedResourceId>('/api/v3/qualityprofile', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(profile),
+      schema: CreatedResourceId,
+    } as any)
+    return created.id
   }
 
   @requiresDestination
diff --git a/apps/backend/src/lib/servers/arr/radarr.ts b/apps/backend/src/lib/servers/arr/radarr.ts
index f3ae703..b00feb4 100644
--- a/apps/backend/src/lib/servers/arr/radarr.ts
+++ b/apps/backend/src/lib/servers/arr/radarr.ts
@@ -26,6 +26,10 @@ export class RadarrServerConnector extends ArrServerConnector {
     return 'movieCategory'
   }
 
+  protected override get internalIndexerFlagValue(): number {
+    return 32
+  }
+
   private toRelease(movie: MovieResource): Release | null {
     const file = movie.movieFile
     if (!movie.id || !movie.hasFile || !file)
diff --git a/apps/backend/src/lib/servers/arr/sonarr.ts b/apps/backend/src/lib/servers/arr/sonarr.ts
index 91b2fdc..1014254 100644
--- a/apps/backend/src/lib/servers/arr/sonarr.ts
+++ b/apps/backend/src/lib/servers/arr/sonarr.ts
@@ -28,6 +28,10 @@ export class SonarrServerConnector extends ArrServerConnector {
     return 'tvCategory'
   }
 
+  protected override get internalIndexerFlagValue(): number {
+    return 8
+  }
+
   private buildRelease(episode: EpisodeResource, series: SeriesResource | undefined, file: EpisodeFileResource | undefined): Release | null {
     if (!episode.id || !episode.hasFile || !file)
       return null
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index b9aa5d3..da6795e 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -24,7 +24,6 @@ export interface RequestServerOption {
   name: string
   type: 'radarr' | 'sonarr'
   mediaType: 'movie' | 'tv'
-  qualityProfiles: Array<{ id: number, name: string }>
   rootFolders: Array<{ path: string, freeSpace?: number }>
 }
 
@@ -33,7 +32,6 @@ export interface CatalogRequestInput {
   mediaType: 'movie' | 'tv'
   tmdbId?: number
   tvdbId?: number
-  qualityProfileId: number
   rootFolderPath: string
 }
 
@@ -82,19 +80,18 @@ export class CatalogController {
     const destinations = this.connectors.servers.filter(s => s.canDestination && s.isInitialized)
     const options = await Promise.all(destinations.map(async (s) => {
       try {
-        const [qualityProfiles, rootFolders] = await Promise.all([s.getQualityProfiles(), s.getRootFolders()])
+        const rootFolders = await s.getRootFolders()
         const type = s.type as 'radarr' | 'sonarr'
         return {
           id: s.id,
           name: s.name,
           type,
           mediaType: type === 'sonarr' ? 'tv' : 'movie',
-          qualityProfiles,
           rootFolders,
         } satisfies RequestServerOption
       }
       catch {
-        // A destination that can't list its profiles can't take a request — drop it.
+        // A destination that can't list its root folders can't take a request — drop it.
         return null
       }
     }))
@@ -112,10 +109,13 @@ export class CatalogController {
     if (server.type !== expectedType)
       throw new BadRequestError(`Server "${server.name}" cannot handle ${input.mediaType} requests`)
 
+    // Force Jack's dedicated profile so *arr only grabs this release from the Jack
+    // indexer (the profile rejects releases without the Internal flag).
+    const qualityProfileId = await server.ensureJackQualityProfile()
     await server.addAndSearch({
       tmdbId: input.tmdbId,
       tvdbId: input.tvdbId,
-      qualityProfileId: input.qualityProfileId,
+      qualityProfileId,
       rootFolderPath: input.rootFolderPath,
     })
     return { ok: true, server: server.name }
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index c748b1f..88bd636 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -10,7 +10,6 @@ const requestBody = z.object({
   mediaType: z.enum(['movie', 'tv']),
   tmdbId: z.number().int().optional(),
   tvdbId: z.number().int().optional(),
-  qualityProfileId: z.number().int(),
   rootFolderPath: z.string().min(1),
 })
 
diff --git a/apps/ui/app/components/DownloadRequestModal.vue b/apps/ui/app/components/DownloadRequestModal.vue
index 5d9c7d4..ce4728a 100644
--- a/apps/ui/app/components/DownloadRequestModal.vue
+++ b/apps/ui/app/components/DownloadRequestModal.vue
@@ -18,7 +18,6 @@ const candidates = computed(() =>
 // USelect's v-model does not accept null; undefined behaves identically under the
 // `!= null` / `== null` loose checks below, so we use undefined for "unset".
 const serverId = ref<string | undefined>(undefined)
-const qualityProfileId = ref<number | undefined>(undefined)
 const rootFolderPath = ref<string | undefined>(undefined)
 
 const server = computed(() => candidates.value.find(s => s.id === serverId.value) ?? null)
@@ -29,16 +28,15 @@ watch(candidates, (list) => {
 }, { immediate: true })
 
 watch(server, (s) => {
-  qualityProfileId.value = s?.qualityProfiles[0]?.id ?? undefined
   rootFolderPath.value = s?.rootFolders[0]?.path ?? undefined
 }, { immediate: true })
 
-const canSubmit = computed(() => Boolean(serverId.value && qualityProfileId.value != null && rootFolderPath.value))
+const canSubmit = computed(() => Boolean(serverId.value && rootFolderPath.value))
 
 function onConfirm() {
-  if (!canSubmit.value || !serverId.value || qualityProfileId.value == null || !rootFolderPath.value)
+  if (!canSubmit.value || !serverId.value || !rootFolderPath.value)
     return
-  emit('confirm', { serverId: serverId.value, qualityProfileId: Number(qualityProfileId.value), rootFolderPath: rootFolderPath.value })
+  emit('confirm', { serverId: serverId.value, rootFolderPath: rootFolderPath.value })
 }
 </script>
 
@@ -63,14 +61,6 @@ function onConfirm() {
           />
         </UFormField>
 
-        <UFormField label="Quality profile">
-          <USelect
-            v-model="qualityProfileId"
-            :items="(server?.qualityProfiles ?? []).map(p => ({ label: p.name, value: p.id }))"
-            class="w-full"
-          />
-        </UFormField>
-
         <UFormField label="Root folder">
           <USelect
             v-model="rootFolderPath"
@@ -79,6 +69,10 @@ function onConfirm() {
           />
         </UFormField>
 
+        <p class="text-sm text-muted">
+          Jack downloads use a dedicated profile so *arr only grabs this release from Jack.
+        </p>
+
         <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" :title="error" />
       </div>
     </template>
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index c60415f..b6a4a27 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -78,13 +78,11 @@ export interface RequestServerOption {
   name: string
   type: 'radarr' | 'sonarr'
   mediaType: 'movie' | 'tv'
-  qualityProfiles: Array<{ id: number, name: string }>
   rootFolders: Array<{ path: string, freeSpace?: number }>
 }
 
 export interface CatalogRequestPayload {
   serverId: string
-  qualityProfileId: number
   rootFolderPath: string
 }
 

From 6031c418d0f23db31ad4f90b6ff3aba17f8a0dfb Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 10:05:05 +0200
Subject: [PATCH 08/27] fix(torznab): embed the requester's key in download
 URLs

The feed embedded the deprecated main key in each release's download URL, so
grabs 401'd when *arr authenticated the indexer with a managed key (the main
key is often unset). Thread the requesting key (apikey query / x-api-key
header) through to each download URL so the grab passes auth.
---
 .../backend/src/__tests__/integration.test.ts | 30 ++++++++++++++
 apps/backend/src/__tests__/torznab.test.ts    | 40 ++++++++++++++++++-
 .../src/modules/torznab/torznab.controller.ts | 21 +++++-----
 .../src/modules/torznab/torznab.router.ts     | 14 +++++--
 4 files changed, 91 insertions(+), 14 deletions(-)

diff --git a/apps/backend/src/__tests__/integration.test.ts b/apps/backend/src/__tests__/integration.test.ts
index 2f1aee3..ff62e2a 100644
--- a/apps/backend/src/__tests__/integration.test.ts
+++ b/apps/backend/src/__tests__/integration.test.ts
@@ -14,6 +14,8 @@ import { RadarrServerConnector } from '../lib/servers/arr/radarr'
 import { SonarrServerConnector } from '../lib/servers/arr/sonarr'
 import { PeerConnector } from '../lib/servers/peer'
 import { DownloadsRepository } from '../modules/downloads/downloads.repository'
+import { ManagedKeysRepository } from '../modules/managed-keys/managed-keys.repository'
+import { ManagedApiKeys } from '../modules/managed-keys/managed-keys.service'
 
 const RADARR_URL = 'http://radarr.test:7878'
 const SONARR_URL = 'http://sonarr.test:8989'
@@ -307,6 +309,34 @@ describe('Torrent download', () => {
     const res = await app.request(`/torznab/download/${encodeURIComponent(guid)}.torrent`)
     expect(res.status).toBe(401)
   })
+
+  // Production scenario: the main key is unset and Radarr authenticates the indexer
+  // with a managed key. The feed must embed THAT managed key in each download URL,
+  // and grabbing the .torrent with it must succeed (regression for the 401-on-grab).
+  test('feed embeds the requester managed key, and the grab round-trips', async () => {
+    const database = new Database(':memory:')
+    testDatabases.push(database)
+    database.exec('pragma foreign_keys = ON')
+    const db = drizzle({ client: database, schema })
+    runMigrations(db)
+    const downloadsRepository = new DownloadsRepository(db)
+    const managedKeysRepository = new ManagedKeysRepository(db)
+
+    const radarr = markInitialized(makeRadarr())
+    const peer = markInitialized(new PeerConnector({ url: PEER_JACK_URL, apiKey: 'peer-api-key', name: 'Friend Jack' }))
+    const { key: managedKey } = new ManagedApiKeys(managedKeysRepository).provision(radarr.id)
+
+    const app = getApp(envs, config, { servers: [radarr], peers: [peer] }, { downloadsRepository, managedKeysRepository })
+
+    const feed = await (await app.request(`/torznab/api?t=movie&tmdbid=603&apikey=${managedKey}`)).text()
+    expect(feed).toContain(peerRelease.title)
+    expect(feed).toContain(`apikey=${managedKey}`)
+    expect(feed).not.toContain('apikey=test-api-key')
+
+    const guid = `${peer.id}:${peerRelease.id}`
+    const grab = await app.request(`/torznab/download/${encodeURIComponent(guid)}.torrent?apikey=${managedKey}`)
+    expect(grab.status).toBe(200)
+  })
 })
 
 describe('Downloads API', () => {
diff --git a/apps/backend/src/__tests__/torznab.test.ts b/apps/backend/src/__tests__/torznab.test.ts
index 4aabaa0..33ec893 100644
--- a/apps/backend/src/__tests__/torznab.test.ts
+++ b/apps/backend/src/__tests__/torznab.test.ts
@@ -1,6 +1,7 @@
 import type { Release } from '../lib/release'
+import type { PeerConnector } from '../lib/servers/peer'
 import { describe, expect, test } from 'bun:test'
-import { releaseToTorznab } from '../modules/torznab/torznab.controller'
+import { releaseToTorznab, TorznabController } from '../modules/torznab/torznab.controller'
 import { buildErrorXml, buildSearchResultXml } from '../modules/torznab/torznab.router'
 
 const movieRelease: Release = {
@@ -97,6 +98,43 @@ describe('Torznab XML helpers', () => {
   })
 })
 
+describe('TorznabController embeds the requester key in download URLs', () => {
+  // The main key is deprecated/often unset; the requester (Radarr) authenticates
+  // the indexer with a managed key. Each download URL must carry THAT key so the
+  // grab passes auth — not the main key, which would 401 when unset.
+  const jackConfig = { internalUrl: 'http://localhost:3000', apiKey: 'main-key' } as any
+
+  function fakePeer(releases: Release[]): PeerConnector {
+    return {
+      id: 'peer1',
+      name: 'Friend',
+      searchByTmdbId: async () => releases,
+      searchByImdbId: async () => releases,
+      searchByTvdbId: async () => releases,
+      listReleases: async () => releases,
+    } as unknown as PeerConnector
+  }
+
+  test('searchMovie embeds the passed request key, not the main key', async () => {
+    const controller = new TorznabController(() => [fakePeer([movieRelease])], jackConfig)
+    const items = await controller.searchMovie({ tmdbId: '12345' }, 'jack_managed_abc')
+    expect(items).toHaveLength(1)
+    expect(new URL(items[0]!.downloadUrl).searchParams.get('apikey')).toBe('jack_managed_abc')
+  })
+
+  test('searchTv embeds the passed request key', async () => {
+    const controller = new TorznabController(() => [fakePeer([episodeRelease])], jackConfig)
+    const items = await controller.searchTv('654321', 1, 2, 'jack_managed_tv')
+    expect(new URL(items[0]!.downloadUrl).searchParams.get('apikey')).toBe('jack_managed_tv')
+  })
+
+  test('catalog embeds the passed request key', async () => {
+    const controller = new TorznabController(() => [fakePeer([movieRelease])], jackConfig)
+    const items = await controller.catalog('jack_managed_xyz')
+    expect(new URL(items[0]!.downloadUrl).searchParams.get('apikey')).toBe('jack_managed_xyz')
+  })
+})
+
 describe('releaseToTorznab', () => {
   test('maps a movie release', () => {
     const result = releaseToTorznab(movieRelease, 'peer1', 'Friend', 'http://localhost:3000', JACK_API_KEY)
diff --git a/apps/backend/src/modules/torznab/torznab.controller.ts b/apps/backend/src/modules/torznab/torznab.controller.ts
index 6175bda..cdd0efb 100644
--- a/apps/backend/src/modules/torznab/torznab.controller.ts
+++ b/apps/backend/src/modules/torznab/torznab.controller.ts
@@ -54,7 +54,7 @@ export class TorznabController {
     private readonly jackConfig: NonNullable<AppConfig['jack']>,
   ) {}
 
-  private async fanOut(label: string, search: (peer: PeerConnector) => Promise<Release[]>): Promise<TorznabItem[]> {
+  private async fanOut(label: string, search: (peer: PeerConnector) => Promise<Release[]>, apiKey: string): Promise<TorznabItem[]> {
     // We fan out to ALL peers — no isInitialized pre-filter. A peer that failed
     // to connect at boot gets re-initialized lazily by @requireInitialization on
     // the call below, so a peer that came back online rejoins searches without a
@@ -80,7 +80,10 @@ export class TorznabController {
             }, async (peerSpan) => {
               const releases = await search(peer)
               setSpanAttribute(peerSpan, 'release.count', releases.length)
-              return releases.map(release => releaseToTorznab(release, peer.id, peer.name, this.jackConfig.internalUrl, this.jackConfig.apiKey ?? ''))
+              // Embed the SAME key the requester authenticated with (passed down
+              // from the request), so the grab of this release's .torrent passes
+              // auth — the deprecated main key (jackConfig.apiKey) is often unset.
+              return releases.map(release => releaseToTorznab(release, peer.id, peer.name, this.jackConfig.internalUrl, apiKey))
             })
           }
           catch (err) {
@@ -96,23 +99,23 @@ export class TorznabController {
     })
   }
 
-  async searchMovie(ids: { tmdbId?: string, imdbId?: string }): Promise<TorznabItem[]> {
+  async searchMovie(ids: { tmdbId?: string, imdbId?: string }, apiKey: string): Promise<TorznabItem[]> {
     const { tmdbId, imdbId } = ids
     // Prefer tmdbid: Radarr filters by it server-side (a targeted lookup), and it
     // doesn't depend on the tt-prefix quirk. imdbid is the fallback.
     if (tmdbId)
-      return this.fanOut(`tmdb:${tmdbId}`, peer => peer.searchByTmdbId(tmdbId))
+      return this.fanOut(`tmdb:${tmdbId}`, peer => peer.searchByTmdbId(tmdbId), apiKey)
     if (imdbId)
-      return this.fanOut(`imdb:${imdbId}`, peer => peer.searchByImdbId(imdbId))
+      return this.fanOut(`imdb:${imdbId}`, peer => peer.searchByImdbId(imdbId), apiKey)
     return []
   }
 
-  async searchTv(tvdbId: string, season?: number, episode?: number): Promise<TorznabItem[]> {
-    return this.fanOut(`tvdb:${tvdbId} s:${season ?? '-'} e:${episode ?? '-'}`, peer => peer.searchByTvdbId(tvdbId, season, episode))
+  async searchTv(tvdbId: string, season: number | undefined, episode: number | undefined, apiKey: string): Promise<TorznabItem[]> {
+    return this.fanOut(`tvdb:${tvdbId} s:${season ?? '-'} e:${episode ?? '-'}`, peer => peer.searchByTvdbId(tvdbId, season, episode), apiKey)
   }
 
   /** Full catalog of every peer's releases — backs the torznab RSS/test query. */
-  async catalog(): Promise<TorznabItem[]> {
-    return this.fanOut('catalog', peer => peer.listReleases())
+  async catalog(apiKey: string): Promise<TorznabItem[]> {
+    return this.fanOut('catalog', peer => peer.listReleases(), apiKey)
   }
 }
diff --git a/apps/backend/src/modules/torznab/torznab.router.ts b/apps/backend/src/modules/torznab/torznab.router.ts
index edd5271..fbb62b3 100644
--- a/apps/backend/src/modules/torznab/torznab.router.ts
+++ b/apps/backend/src/modules/torznab/torznab.router.ts
@@ -133,6 +133,11 @@ export function getTorznabRouter(controller: TorznabController) {
       return xml(c, body, 400)
     }
 
+    // The key the requester (Radarr/Sonarr) authenticated with — extracted the
+    // same way requireApiKey does. Embedded into each release's download URL so
+    // the subsequent grab passes auth (managed indexer keys, not the main key).
+    const apiKey = c.req.query('apikey') ?? c.req.header('x-api-key') ?? ''
+
     switch (t) {
       case 'caps': {
         return xml(c, CAPS_XML)
@@ -144,7 +149,7 @@ export function getTorznabRouter(controller: TorznabController) {
       // self-test, which *arr requires to return results).
       case 'search': {
         const q = c.req.query('q')?.trim()
-        const items = q ? [] : await controller.catalog()
+        const items = q ? [] : await controller.catalog(apiKey)
         const body = buildSearchResultXml(filterByCategory(items, c.req.query('cat')))
         return xml(c, body)
       }
@@ -155,9 +160,9 @@ export function getTorznabRouter(controller: TorznabController) {
         const q = c.req.query('q')?.trim()
         let items: TorznabItem[]
         if (tmdbId || imdbId)
-          items = await controller.searchMovie({ tmdbId, imdbId })
+          items = await controller.searchMovie({ tmdbId, imdbId }, apiKey)
         else
-          items = q ? [] : await controller.catalog()
+          items = q ? [] : await controller.catalog(apiKey)
         const body = buildSearchResultXml(filterByCategory(items, c.req.query('cat')))
         return xml(c, body)
       }
@@ -173,10 +178,11 @@ export function getTorznabRouter(controller: TorznabController) {
             tvdbId,
             season ? Number(season) : undefined,
             ep ? Number(ep) : undefined,
+            apiKey,
           )
         }
         else {
-          items = q ? [] : await controller.catalog()
+          items = q ? [] : await controller.catalog(apiKey)
         }
         const body = buildSearchResultXml(filterByCategory(items, c.req.query('cat')))
         return xml(c, body)

From 8b37bcdd053b6b951b5769f2f4ff2402b400a8d2 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 10:36:32 +0200
Subject: [PATCH 09/27] perf(catalog): enrich peer titles lazily from the
 client
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The catalog endpoint ran every TMDB lookup server-side, 8 at a time, before
returning — freezing the page on large peers. Return titles unenriched and add
a per-title GET /catalog/tmdb/:mediaType/:tmdbId route the grid calls once per
visible card, so metadata fills in progressively. Paginate (48/page) to bound
how many lookups fire at once.
---
 apps/backend/src/__tests__/catalog.test.ts    | 137 ++++++------------
 .../src/modules/catalog/catalog.controller.ts |  31 ++--
 .../src/modules/catalog/catalog.lib.ts        |  19 ---
 .../src/modules/catalog/catalog.router.ts     |  11 ++
 apps/ui/app/components/CatalogPosterCard.vue  |  19 ++-
 apps/ui/app/components/CatalogTitleDetail.vue |   8 +-
 apps/ui/app/composables/useCatalogMetadata.ts |  47 ++++++
 apps/ui/app/pages/catalog/[peerId].vue        |  41 ++++--
 8 files changed, 160 insertions(+), 153 deletions(-)
 create mode 100644 apps/ui/app/composables/useCatalogMetadata.ts

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 5f9d7d0..00c6bfe 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, mock, test } from 'bun:test'
 import { BadRequestError } from '../lib/errors/BadRequestError'
 import { NotFoundError } from '../lib/errors/NotFoundError'
 import { CatalogController } from '../modules/catalog/catalog.controller'
-import { groupReleasesIntoTitles, mapLimit } from '../modules/catalog/catalog.lib'
+import { groupReleasesIntoTitles } from '../modules/catalog/catalog.lib'
 
 function movie(overrides: Partial<Release> = {}): Release {
   return {
@@ -122,121 +122,66 @@ describe('catalogController', () => {
   })
 })
 
-describe('mapLimit', () => {
-  test('preserves input order regardless of completion order', async () => {
-    const result = await mapLimit([3, 1, 2], 2, async (n) => {
-      await new Promise(resolve => setTimeout(resolve, n))
-      return n * 10
-    })
-
-    expect(result).toEqual([30, 10, 20])
-  })
-
-  test('runs exactly `limit` tasks in flight, never more', async () => {
-    let inFlight = 0
-    let peak = 0
-
-    await mapLimit([1, 2, 3, 4, 5, 6], 2, async () => {
-      inFlight += 1
-      peak = Math.max(peak, inFlight)
-      await new Promise(resolve => setTimeout(resolve, 5))
-      inFlight -= 1
-      return null
-    })
-
-    // Saturates the cap (catches a collapse-to-one-worker regression) without exceeding it.
-    expect(peak).toBe(2)
-  })
-
-  test('returns an empty array for empty input', async () => {
-    expect(await mapLimit([], 4, async () => 1)).toEqual([])
-  })
-})
-
-describe('catalogController enrichment', () => {
+describe('catalogController.getPeerCatalog metadata', () => {
   function makeConnectors(peers: any[]) {
     return { servers: [], peers }
   }
 
-  const breakingBad = {
-    tmdbId: 1396,
-    title: 'Breaking Bad',
-    overview: 'A chemistry teacher cooks meth.',
-    year: 2008,
-    rating: 8.9,
-    posterUrl: 'https://image.tmdb.org/t/p/w500/poster.jpg',
-    backdropUrl: 'https://image.tmdb.org/t/p/w780/backdrop.jpg',
-    genres: ['Drama'],
-  }
-
-  test('attaches metadata to titles with a tmdbId and leaves id-less titles untouched', async () => {
-    const calls: Array<[string, number]> = []
-    const tmdb = {
-      getMetadata: async (mediaType: string, tmdbId: number) => {
-        calls.push([mediaType, tmdbId])
-        return tmdbId === 603 ? { ...breakingBad, tmdbId: 603, title: 'The Matrix' } : null
-      },
-    }
+  test('returns titles unenriched and makes no TMDB calls', async () => {
+    const getMetadata = mock(async () => ({ title: 'Should not be called' }))
     const peer = {
       id: 'peer-1',
       name: 'Friend Jack',
-      listReleases: async () => [
-        movie({ tmdbId: 603, title: 'The.Matrix.1999' }),
-        movie({ title: 'No.Id.2024' }),
-      ],
+      listReleases: async () => [movie({ tmdbId: 603 })],
     }
-    const controller = new CatalogController(makeConnectors([peer]) as any, tmdb as any)
+    const controller = new CatalogController(makeConnectors([peer]) as any, { getMetadata } as any)
 
     const result = await controller.getPeerCatalog('peer-1')
 
-    const enriched = result.titles.find(t => t.tmdbId === 603)
-    expect(enriched!.metadata).toMatchObject({ title: 'The Matrix' })
-
-    const idless = result.titles.find(t => t.tmdbId == null)
-    expect(idless!.metadata).toBeUndefined()
-
-    // No lookup is attempted for the id-less title.
-    expect(calls).toEqual([['movie', 603]])
+    expect(result.titles[0]!.metadata).toBeUndefined()
+    expect(getMetadata).not.toHaveBeenCalled()
   })
+})
 
-  test('keeps the catalog intact when a getMetadata lookup rejects', async () => {
-    const tmdb = {
-      getMetadata: async (_mediaType: string, tmdbId: number) => {
-        if (tmdbId === 603)
-          throw new Error('TMDB exploded')
-        return { ...breakingBad }
-      },
-    }
-    const peer = {
-      id: 'peer-1',
-      name: 'Friend Jack',
-      listReleases: async () => [
-        movie({ tmdbId: 603, title: 'The.Matrix.1999' }),
-        episode({ tvdbId: 1, tmdbId: 1396, seriesTitle: 'Breaking Bad' }),
-      ],
-    }
-    const controller = new CatalogController(makeConnectors([peer]) as any, tmdb as any)
+describe('catalogController.getTitleMetadata', () => {
+  function makeConnectors() {
+    return { servers: [], peers: [] }
+  }
 
-    const result = await controller.getPeerCatalog('peer-1')
+  const matrix = {
+    tmdbId: 603,
+    title: 'The Matrix',
+    overview: 'A hacker learns the truth.',
+    year: 1999,
+    rating: 8.2,
+    posterUrl: 'https://image.tmdb.org/t/p/w500/poster.jpg',
+    backdropUrl: 'https://image.tmdb.org/t/p/w780/backdrop.jpg',
+    genres: ['Action'],
+  }
+
+  test('delegates to the tmdb client and returns its metadata', async () => {
+    const getMetadata = mock(async () => matrix)
+    const controller = new CatalogController(makeConnectors() as any, { getMetadata } as any)
 
-    const failed = result.titles.find(t => t.tmdbId === 603)
-    expect(failed!.metadata).toBeUndefined()
+    const result = await controller.getTitleMetadata('movie', 603)
 
-    const ok = result.titles.find(t => t.mediaType === 'tv')
-    expect(ok!.metadata).toMatchObject({ title: 'Breaking Bad' })
+    expect(result).toMatchObject({ title: 'The Matrix' })
+    expect(getMetadata).toHaveBeenCalledWith('movie', 603)
   })
 
-  test('makes no TMDB calls and attaches no metadata when no client is configured', async () => {
-    const peer = {
-      id: 'peer-1',
-      name: 'Friend Jack',
-      listReleases: async () => [movie({ tmdbId: 603 })],
-    }
-    const controller = new CatalogController(makeConnectors([peer]) as any)
+  test('returns null when no tmdb client is configured', async () => {
+    const controller = new CatalogController(makeConnectors() as any)
 
-    const result = await controller.getPeerCatalog('peer-1')
+    expect(await controller.getTitleMetadata('movie', 603)).toBeNull()
+  })
 
-    expect(result.titles[0]!.metadata).toBeUndefined()
+  test('propagates a lookup rejection to the caller', () => {
+    const getMetadata = mock(async () => {
+      throw new Error('TMDB exploded')
+    })
+    const controller = new CatalogController(makeConnectors() as any, { getMetadata } as any)
+
+    expect(controller.getTitleMetadata('movie', 603)).rejects.toThrow('TMDB exploded')
   })
 })
 
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index da6795e..f6eebc9 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -1,12 +1,10 @@
 import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { PeerConnector } from '../../lib/servers/peer'
-import type { TmdbClient } from '../../lib/tmdb/client'
+import type { TmdbClient, TmdbMediaType, TmdbMetadata } from '../../lib/tmdb/client'
 import type { CatalogTitle } from './catalog.lib'
 import { BadRequestError } from '../../lib/errors/BadRequestError'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
-import { groupReleasesIntoTitles, mapLimit } from './catalog.lib'
-
-const TMDB_ENRICH_CONCURRENCY = 8
+import { groupReleasesIntoTitles } from './catalog.lib'
 
 export interface PeerCatalogResponse {
   peer: { id: string, name: string }
@@ -51,29 +49,20 @@ export class CatalogController {
   async getPeerCatalog(peerId: string): Promise<PeerCatalogResponse> {
     const peer = this.requirePeer(peerId)
     const releases = await peer.listReleases()
-    const titles = await this.enrichTitles(groupReleasesIntoTitles(releases))
+    // Return titles immediately, unenriched. TMDB lookups are driven per-title by
+    // the client (see getTitleMetadata) so the catalog renders without waiting on
+    // hundreds of upstream round-trips.
     return {
       peer: { id: peer.id, name: peer.name },
-      titles,
+      titles: groupReleasesIntoTitles(releases),
     }
   }
 
-  private async enrichTitles(titles: CatalogTitle[]): Promise<CatalogTitle[]> {
+  /** TMDB metadata for a single title; null when TMDB is unconfigured or the id is unknown. */
+  async getTitleMetadata(mediaType: TmdbMediaType, tmdbId: number): Promise<TmdbMetadata | null> {
     if (!this.tmdb)
-      return titles
-    const tmdb = this.tmdb
-    return mapLimit(titles, TMDB_ENRICH_CONCURRENCY, async (title) => {
-      if (!title.tmdbId)
-        return title
-      try {
-        const metadata = await tmdb.getMetadata(title.mediaType, title.tmdbId)
-        return { ...title, metadata }
-      }
-      catch {
-        // Enrichment is best-effort: a failed lookup must not blank the catalog.
-        return title
-      }
-    })
+      return null
+    return this.tmdb.getMetadata(mediaType, tmdbId)
   }
 
   async getRequestOptions(): Promise<RequestServerOption[]> {
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
index 49f02cc..e4c8fde 100644
--- a/apps/backend/src/modules/catalog/catalog.lib.ts
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -16,25 +16,6 @@ export interface CatalogTitle {
   metadata?: TmdbMetadata | null
 }
 
-/** Run `fn` over `items` with at most `limit` in flight; preserves order. */
-export async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
-  const results = Array.from({ length: items.length }) as R[]
-  let cursor = 0
-  async function worker(): Promise<void> {
-    while (cursor < items.length) {
-      const index = cursor++
-      results[index] = await fn(items[index]!)
-    }
-  }
-  // Spawn each worker via its own call so they run concurrently; `.fill(worker())`
-  // would share one promise and silently collapse the pool to a single worker.
-  const workers: Array<Promise<void>> = []
-  for (let i = 0; i < Math.min(limit, items.length); i++)
-    workers.push(worker())
-  await Promise.all(workers)
-  return results
-}
-
 function mediaTypeOf(release: Release): 'movie' | 'tv' {
   return release.category === ReleaseCategory.Tv ? 'tv' : 'movie'
 }
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index 88bd636..fd9b69c 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -5,6 +5,11 @@ import { z } from 'zod'
 
 const peerParam = z.object({ peerId: z.string().min(1) })
 
+const tmdbParam = z.object({
+  mediaType: z.enum(['movie', 'tv']),
+  tmdbId: z.coerce.number().int(),
+})
+
 const requestBody = z.object({
   serverId: z.string().min(1),
   mediaType: z.enum(['movie', 'tv']),
@@ -19,6 +24,12 @@ export function getCatalogRouter(controller: CatalogController) {
   // Register the static path before `/:peerId` so "tmdb" isn't captured as a peerId.
   app.get('/tmdb/status', async c => c.json(await controller.getTmdbStatus()))
 
+  // Per-title TMDB lookup the catalog grid calls once per visible card.
+  app.get('/tmdb/:mediaType/:tmdbId', zValidator('param', tmdbParam), async (c) => {
+    const { mediaType, tmdbId } = c.req.valid('param')
+    return c.json(await controller.getTitleMetadata(mediaType, tmdbId))
+  })
+
   // Register before `/:peerId` so "request-options" isn't captured as a peerId.
   app.get('/request-options', async c => c.json({ servers: await controller.getRequestOptions() }))
 
diff --git a/apps/ui/app/components/CatalogPosterCard.vue b/apps/ui/app/components/CatalogPosterCard.vue
index 8a6076e..96b3424 100644
--- a/apps/ui/app/components/CatalogPosterCard.vue
+++ b/apps/ui/app/components/CatalogPosterCard.vue
@@ -4,10 +4,19 @@ import type { CatalogTitle } from '~/types/management'
 const props = defineProps<{ title: CatalogTitle }>()
 defineEmits<{ select: [] }>()
 
-const name = computed(() => props.title.metadata?.title ?? props.title.displayTitle)
-const poster = computed(() => props.title.metadata?.posterUrl ?? null)
-const year = computed(() => props.title.metadata?.year ?? null)
-const rating = computed(() => props.title.metadata?.rating ?? null)
+const { load, entryFor } = useCatalogMetadata()
+const entry = computed(() => entryFor(props.title))
+const metadata = computed(() => entry.value?.data ?? props.title.metadata ?? null)
+// Loading until the lookup settles; titles with no tmdbId never load, so they're
+// not "loading" — they just stay on the placeholder.
+const loading = computed(() => props.title.tmdbId != null && (entry.value === null || entry.value.status === 'loading'))
+
+const name = computed(() => metadata.value?.title ?? props.title.displayTitle)
+const poster = computed(() => metadata.value?.posterUrl ?? null)
+const year = computed(() => metadata.value?.year ?? null)
+const rating = computed(() => metadata.value?.rating ?? null)
+
+onMounted(() => load(props.title))
 </script>
 
 <template>
@@ -24,7 +33,7 @@ const rating = computed(() => props.title.metadata?.rating ?? null)
         loading="lazy"
         class="size-full object-cover"
       >
-      <div v-else class="flex size-full items-center justify-center">
+      <div v-else class="flex size-full items-center justify-center" :class="{ 'animate-pulse': loading }">
         <UIcon :name="title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip'" class="size-8 text-dimmed" />
       </div>
       <UBadge
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index 1f7ac32..bec75aa 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -4,8 +4,12 @@ import type { CatalogTitle } from '~/types/management'
 const props = defineProps<{ title: CatalogTitle }>()
 const emit = defineEmits<{ download: [] }>()
 
-const name = computed(() => props.title.metadata?.title ?? props.title.displayTitle)
-const meta = computed(() => props.title.metadata ?? null)
+const { load, entryFor } = useCatalogMetadata()
+// Reuse the cache the grid populated; load() is a no-op if the card already fetched it.
+const meta = computed(() => entryFor(props.title)?.data ?? props.title.metadata ?? null)
+const name = computed(() => meta.value?.title ?? props.title.displayTitle)
+
+onMounted(() => load(props.title))
 const canRequest = computed(() => props.title.mediaType === 'tv'
   ? props.title.tvdbId != null
   : props.title.tmdbId != null)
diff --git a/apps/ui/app/composables/useCatalogMetadata.ts b/apps/ui/app/composables/useCatalogMetadata.ts
new file mode 100644
index 0000000..bb9eb6d
--- /dev/null
+++ b/apps/ui/app/composables/useCatalogMetadata.ts
@@ -0,0 +1,47 @@
+import type { CatalogTitle, TmdbMetadata } from '~/types/management'
+
+export interface CatalogMetadataEntry {
+  status: 'loading' | 'loaded' | 'error'
+  data: TmdbMetadata | null
+}
+
+/**
+ * Drives per-title TMDB enrichment from the client. The catalog endpoint returns
+ * titles unenriched; each visible poster card calls `load` on mount and reads its
+ * metadata back from a shared, page-scoped cache. The browser's own connection
+ * pool handles concurrency, so titles fill in progressively instead of blocking
+ * the whole catalog on one giant server-side fan-out.
+ */
+export function useCatalogMetadata() {
+  const { request } = useManagement()
+  // useState (not a module-level ref) so the cache survives card unmount/remount
+  // across pagination and filter changes, and is shared by every card + the detail panel.
+  const cache = useState<Record<string, CatalogMetadataEntry>>('catalog-tmdb', () => ({}))
+
+  function keyFor(title: CatalogTitle): string | null {
+    return title.tmdbId == null ? null : `${title.mediaType}:${title.tmdbId}`
+  }
+
+  function entryFor(title: CatalogTitle): CatalogMetadataEntry | null {
+    const key = keyFor(title)
+    return key ? (cache.value[key] ?? null) : null
+  }
+
+  async function load(title: CatalogTitle): Promise<void> {
+    const key = keyFor(title)
+    // No id to look up, or already loading/loaded — don't refetch.
+    if (!key || cache.value[key])
+      return
+    cache.value[key] = { status: 'loading', data: null }
+    try {
+      const data = await request<TmdbMetadata | null>(`catalog/tmdb/${title.mediaType}/${title.tmdbId}`)
+      cache.value[key] = { status: 'loaded', data }
+    }
+    catch {
+      // A failed lookup must not blank the card — fall back to the placeholder.
+      cache.value[key] = { status: 'error', data: null }
+    }
+  }
+
+  return { load, entryFor }
+}
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index dd494e0..415354d 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -4,6 +4,7 @@ import type { CatalogRequestPayload, CatalogTitle, PeerCatalogResponse } from '~
 const route = useRoute()
 const peerId = computed(() => String(route.params.peerId))
 const { request, extractError } = useManagement()
+const { entryFor } = useCatalogMetadata()
 const toast = useToast()
 
 const { data, pending, error } = await useAsyncData(
@@ -19,6 +20,20 @@ const titles = computed(() => {
   return typeFilter.value === 'all' ? all : all.filter(t => t.mediaType === typeFilter.value)
 })
 
+// Paginate so only the current page's cards mount — that bounds how many TMDB
+// lookups fire at once (each card fetches its own metadata on mount).
+const PAGE_SIZE = 48
+const page = ref(1)
+const pagedTitles = computed(() => titles.value.slice((page.value - 1) * PAGE_SIZE, page.value * PAGE_SIZE))
+// Jump back to the first page whenever the filter narrows the list.
+watch(typeFilter, () => {
+  page.value = 1
+})
+
+function titleName(title: CatalogTitle): string {
+  return entryFor(title)?.data?.title ?? title.metadata?.title ?? title.displayTitle
+}
+
 const selected = ref<CatalogTitle | null>(null)
 
 const requestOpen = ref(false)
@@ -52,7 +67,7 @@ async function onConfirm(payload: CatalogRequestPayload) {
     selected.value = null
     toast.add({
       title: 'Added to your library',
-      description: `"${title.metadata?.title ?? title.displayTitle}" is being searched by your *arr.`,
+      description: `"${titleName(title)}" is being searched by your *arr.`,
       color: 'success',
       icon: 'i-ph-check-circle',
     })
@@ -103,20 +118,26 @@ async function onConfirm(payload: CatalogRequestPayload) {
         </div>
       </UCard>
 
-      <div v-else class="grid grid-cols-3 gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-8">
-        <CatalogPosterCard
-          v-for="title in titles"
-          :key="title.key"
-          :title="title"
-          @select="selected = title"
-        />
-      </div>
+      <template v-else>
+        <div class="grid grid-cols-3 gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-8">
+          <CatalogPosterCard
+            v-for="title in pagedTitles"
+            :key="title.key"
+            :title="title"
+            @select="selected = title"
+          />
+        </div>
+
+        <div v-if="titles.length > PAGE_SIZE" class="mt-6 flex justify-center">
+          <UPagination v-model:page="page" :total="titles.length" :items-per-page="PAGE_SIZE" />
+        </div>
+      </template>
     </template>
   </UDashboardPanel>
 
   <USlideover
     :open="selected !== null"
-    :title="selected?.metadata?.title ?? selected?.displayTitle ?? 'Title'"
+    :title="selected ? titleName(selected) : 'Title'"
     @update:open="(open) => { if (!open) selected = null }"
   >
     <template #body>

From 831c4ea44f3785bc8d4f0cb8f029a1670445d267 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 14:18:48 +0200
Subject: [PATCH 10/27] feat(catalog): direct-download peer movies and
 ManualImport into *arr

Replace the addAndSearch request path with a direct download + explicit
*arr ManualImport. Connectors gain add() (no search, idempotent, returns
entity id) and manualImport(); downloads carry an import_mode/import_target
marker (0008 migration) and a startDirectDownload entry; the ImportWatcher
pushes ManualImport once per jack_manual row, confirmed via the existing
deriveHash history match. Movie catalog flow picks the best peer release
and wires the UI; Sonarr methods land too so the package compiles.
---
 .../drizzle/0008_typical_rocket_racer.sql     |   2 +
 apps/backend/drizzle/meta/0008_snapshot.json  | 336 ++++++++++++++++++
 apps/backend/drizzle/meta/_journal.json       |   7 +
 apps/backend/src/__tests__/catalog.test.ts    | 149 +++++---
 .../src/__tests__/downloads-service.test.ts   |  24 ++
 .../src/__tests__/import-watcher.test.ts      |  94 ++++-
 .../backend/src/__tests__/integration.test.ts |  95 -----
 .../src/__tests__/qbittorrent-mapper.test.ts  |   2 +
 apps/backend/src/database/schema.ts           |   5 +
 apps/backend/src/index.ts                     |   1 +
 .../lib/servers/arr/arr-add-import.test.ts    | 299 ++++++++++++++++
 apps/backend/src/lib/servers/arr/base.ts      |  44 ++-
 apps/backend/src/lib/servers/arr/radarr.ts    |  62 +++-
 apps/backend/src/lib/servers/arr/sonarr.ts    |  63 +++-
 apps/backend/src/management-app.ts            |   4 +-
 .../src/modules/catalog/catalog.controller.ts |  38 +-
 .../src/modules/catalog/catalog.lib.ts        |  30 ++
 .../src/modules/catalog/catalog.router.ts     |   1 +
 .../modules/downloads/downloads.repository.ts |   9 +
 .../modules/downloads/downloads.service.ts    |  46 +++
 .../src/modules/downloads/import-watcher.ts   |  33 +-
 .../app/components/DownloadRequestModal.vue   |   4 -
 apps/ui/app/pages/catalog/[peerId].vue        |   3 +-
 23 files changed, 1174 insertions(+), 177 deletions(-)
 create mode 100644 apps/backend/drizzle/0008_typical_rocket_racer.sql
 create mode 100644 apps/backend/drizzle/meta/0008_snapshot.json
 create mode 100644 apps/backend/src/lib/servers/arr/arr-add-import.test.ts

diff --git a/apps/backend/drizzle/0008_typical_rocket_racer.sql b/apps/backend/drizzle/0008_typical_rocket_racer.sql
new file mode 100644
index 0000000..036deaf
--- /dev/null
+++ b/apps/backend/drizzle/0008_typical_rocket_racer.sql
@@ -0,0 +1,2 @@
+ALTER TABLE `downloads` ADD `import_mode` text;--> statement-breakpoint
+ALTER TABLE `downloads` ADD `import_target` text;
\ No newline at end of file
diff --git a/apps/backend/drizzle/meta/0008_snapshot.json b/apps/backend/drizzle/meta/0008_snapshot.json
new file mode 100644
index 0000000..8d88aa4
--- /dev/null
+++ b/apps/backend/drizzle/meta/0008_snapshot.json
@@ -0,0 +1,336 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "364866ab-f386-439e-af39-505eada0b51e",
+  "prevId": "db1b9834-4df7-4b99-a413-be6d9a0f5428",
+  "tables": {
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "downloads": {
+      "name": "downloads",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "torrent_filename": {
+          "name": "torrent_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "peer_id": {
+          "name": "peer_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "peer_name": {
+          "name": "peer_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "dest_path": {
+          "name": "dest_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "part_path": {
+          "name": "part_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "release_size": {
+          "name": "release_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "release_json": {
+          "name": "release_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expected_bytes": {
+          "name": "expected_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expected_bytes_source": {
+          "name": "expected_bytes_source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expected_bytes_mismatch": {
+          "name": "expected_bytes_mismatch",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        },
+        "downloaded_bytes": {
+          "name": "downloaded_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "attempts": {
+          "name": "attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "qb_category": {
+          "name": "qb_category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "qb_source_server": {
+          "name": "qb_source_server",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "import_mode": {
+          "name": "import_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "import_target": {
+          "name": "import_target",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "downloads_status_idx": {
+          "name": "downloads_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "downloads_updated_at_idx": {
+          "name": "downloads_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {
+        "downloads_status_check": {
+          "name": "downloads_status_check",
+          "value": "\"downloads\".\"status\" in ('downloading', 'import_queued', 'imported', 'failed')"
+        },
+        "downloads_expected_bytes_source_check": {
+          "name": "downloads_expected_bytes_source_check",
+          "value": "\"downloads\".\"expected_bytes_source\" is null or \"downloads\".\"expected_bytes_source\" in ('content_length', 'content_range', 'release_size')"
+        }
+      }
+    },
+    "managed_keys": {
+      "name": "managed_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "server_id": {
+          "name": "server_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "managed_keys_key_hash_unique": {
+          "name": "managed_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/apps/backend/drizzle/meta/_journal.json b/apps/backend/drizzle/meta/_journal.json
index 665f923..7f8f9b4 100644
--- a/apps/backend/drizzle/meta/_journal.json
+++ b/apps/backend/drizzle/meta/_journal.json
@@ -57,6 +57,13 @@
       "when": 1782431314780,
       "tag": "0007_flaky_polaris",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1782561669632,
+      "tag": "0008_typical_rocket_racer",
+      "breakpoints": true
     }
   ]
 }
diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 00c6bfe..db21da1 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, mock, test } from 'bun:test'
 import { BadRequestError } from '../lib/errors/BadRequestError'
 import { NotFoundError } from '../lib/errors/NotFoundError'
 import { CatalogController } from '../modules/catalog/catalog.controller'
-import { groupReleasesIntoTitles } from '../modules/catalog/catalog.lib'
+import { groupReleasesIntoTitles, pickBestPerEpisode, pickBestRelease } from '../modules/catalog/catalog.lib'
 
 function movie(overrides: Partial<Release> = {}): Release {
   return {
@@ -95,6 +95,44 @@ describe('groupReleasesIntoTitles', () => {
   })
 })
 
+describe('pickBestRelease', () => {
+  test('returns undefined for an empty list', () => {
+    expect(pickBestRelease([])).toBeUndefined()
+  })
+
+  test('prefers the higher resolution even when a lower one has a larger file', () => {
+    const sd = movie({ id: 'a', quality: { resolution: 720 }, size: 999 })
+    const hd = movie({ id: 'b', quality: { resolution: 1080 }, size: 1 })
+    expect(pickBestRelease([sd, hd])).toBe(hd)
+  })
+
+  test('breaks a resolution tie by the larger file', () => {
+    const small = movie({ id: 'a', quality: { resolution: 1080 }, size: 10 })
+    const big = movie({ id: 'b', quality: { resolution: 1080 }, size: 20 })
+    expect(pickBestRelease([small, big])).toBe(big)
+  })
+
+  test('breaks a full tie deterministically by the lowest release id, regardless of input order', () => {
+    const z = movie({ id: 'zzz', quality: { resolution: 1080 }, size: 10 })
+    const a = movie({ id: 'aaa', quality: { resolution: 1080 }, size: 10 })
+    expect(pickBestRelease([z, a])).toBe(a)
+    expect(pickBestRelease([a, z])).toBe(a)
+  })
+})
+
+describe('pickBestPerEpisode', () => {
+  test('keeps the best release per season/episode key', () => {
+    const s1e1Sd = episode({ id: 'a', season: 1, episode: 1, quality: { resolution: 720 } })
+    const s1e1Hd = episode({ id: 'b', season: 1, episode: 1, quality: { resolution: 1080 } })
+    const s1e2 = episode({ id: 'c', season: 1, episode: 2, quality: { resolution: 720 } })
+    const best = pickBestPerEpisode([s1e1Sd, s1e1Hd, s1e2])
+    expect(best).toHaveLength(2)
+    expect(best).toContain(s1e1Hd)
+    expect(best).toContain(s1e2)
+    expect(best).not.toContain(s1e1Sd)
+  })
+})
+
 describe('catalogController', () => {
   function makeConnectors(peers: any[]) {
     return { servers: [], peers }
@@ -271,28 +309,54 @@ describe('catalogController.requestDownload', () => {
     name: string
     type: 'radarr' | 'sonarr'
     canDestination: boolean
-    ensureJackQualityProfile: () => Promise<number>
-    addAndSearch: (params: any) => Promise<void>
+    add: (params: any) => Promise<number>
   }> = {}) {
     return {
       id: 'radarr-1',
       name: 'My Radarr',
       type: 'radarr',
       canDestination: true,
-      ensureJackQualityProfile: mock(async () => 77),
-      addAndSearch: mock(async () => {}),
+      add: mock(async () => 123),
       ...overrides,
     }
   }
 
-  function makeConnectors(servers: any[]) {
-    return { servers, peers: [] }
+  function fakePeer(overrides: Partial<{ searchByTmdbId: (tmdbId: string) => Promise<Release[]> }> = {}) {
+    return {
+      id: 'peer-1',
+      name: 'Friend Jack',
+      searchByTmdbId: overrides.searchByTmdbId ?? mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]),
+    }
+  }
+
+  function fakeDownloads(overrides: Partial<{ startDirectDownload: (input: any) => Promise<string> }> = {}) {
+    return {
+      startDirectDownload: overrides.startDirectDownload ?? mock(async () => 'started'),
+    }
+  }
+
+  function makeConnectors(servers: any[], peers: any[] = []) {
+    return { servers, peers }
   }
 
+  test('throws BadRequestError when downloads are not configured', () => {
+    const radarr = fakeServer()
+    const controller = new CatalogController(makeConnectors([radarr], [fakePeer()]) as any)
+
+    expect(controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      rootFolderPath: '/movies',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
   test('throws NotFoundError for an unknown serverId', () => {
-    const controller = new CatalogController(makeConnectors([]) as any)
+    const controller = new CatalogController(makeConnectors([], [fakePeer()]) as any, undefined, fakeDownloads() as any)
 
     expect(controller.requestDownload({
+      peerId: 'peer-1',
       serverId: 'missing',
       mediaType: 'movie',
       tmdbId: 603,
@@ -302,9 +366,10 @@ describe('catalogController.requestDownload', () => {
 
   test('throws BadRequestError when the server is not a destination', () => {
     const radarr = fakeServer({ canDestination: false })
-    const controller = new CatalogController(makeConnectors([radarr]) as any)
+    const controller = new CatalogController(makeConnectors([radarr], [fakePeer()]) as any, undefined, fakeDownloads() as any)
 
     expect(controller.requestDownload({
+      peerId: 'peer-1',
       serverId: 'radarr-1',
       mediaType: 'movie',
       tmdbId: 603,
@@ -314,9 +379,10 @@ describe('catalogController.requestDownload', () => {
 
   test('throws BadRequestError when a movie request targets a Sonarr server', () => {
     const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
-    const controller = new CatalogController(makeConnectors([sonarr]) as any)
+    const controller = new CatalogController(makeConnectors([sonarr], [fakePeer()]) as any, undefined, fakeDownloads() as any)
 
     expect(controller.requestDownload({
+      peerId: 'peer-1',
       serverId: 'sonarr-1',
       mediaType: 'movie',
       tmdbId: 603,
@@ -324,58 +390,57 @@ describe('catalogController.requestDownload', () => {
     })).rejects.toBeInstanceOf(BadRequestError)
   })
 
-  test('throws BadRequestError when a tv request targets a Radarr server', () => {
-    const radarr = fakeServer()
-    const controller = new CatalogController(makeConnectors([radarr]) as any)
+  test('throws BadRequestError for a tv request (not supported until Phase 2)', () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
+    const controller = new CatalogController(makeConnectors([sonarr], [fakePeer()]) as any, undefined, fakeDownloads() as any)
 
     expect(controller.requestDownload({
-      serverId: 'radarr-1',
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
       mediaType: 'tv',
       tvdbId: 81189,
       rootFolderPath: '/tv',
     })).rejects.toBeInstanceOf(BadRequestError)
   })
 
-  test('calls addAndSearch and returns ok for a valid matching request', async () => {
+  test('throws NotFoundError when the peer has no release for the tmdbId, and does not add', async () => {
     const radarr = fakeServer()
-    const controller = new CatalogController(makeConnectors([radarr]) as any)
+    const peer = fakePeer({ searchByTmdbId: mock(async () => []) })
+    const controller = new CatalogController(makeConnectors([radarr], [peer]) as any, undefined, fakeDownloads() as any)
 
-    const result = await controller.requestDownload({
+    await expect(controller.requestDownload({
+      peerId: 'peer-1',
       serverId: 'radarr-1',
       mediaType: 'movie',
       tmdbId: 603,
       rootFolderPath: '/movies',
-    })
-
-    expect(result).toEqual({ ok: true, server: 'My Radarr' })
-    expect(radarr.ensureJackQualityProfile).toHaveBeenCalledTimes(1)
-    expect(radarr.addAndSearch).toHaveBeenCalledTimes(1)
-    // The Jack profile (77) is forced regardless of any client input.
-    expect(radarr.addAndSearch).toHaveBeenCalledWith({
-      tmdbId: 603,
-      tvdbId: undefined,
-      qualityProfileId: 77,
-      rootFolderPath: '/movies',
-    })
+    })).rejects.toBeInstanceOf(NotFoundError)
+    expect(radarr.add).not.toHaveBeenCalled()
   })
 
-  test('routes a tv request to the matching Sonarr destination', async () => {
-    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
-    const controller = new CatalogController(makeConnectors([sonarr]) as any)
+  test('adds the movie without search and starts a direct download for the best release', async () => {
+    const radarr = fakeServer({ add: mock(async () => 123) })
+    const best = movie({ id: 'rel:best', tmdbId: 603, quality: { resolution: 1080 }, size: 100 })
+    const worse = movie({ id: 'rel:worse', tmdbId: 603, quality: { resolution: 720 }, size: 999 })
+    const peer = fakePeer({ searchByTmdbId: mock(async () => [worse, best]) })
+    const downloads = fakeDownloads()
+    const controller = new CatalogController(makeConnectors([radarr], [peer]) as any, undefined, downloads as any)
 
     const result = await controller.requestDownload({
-      serverId: 'sonarr-1',
-      mediaType: 'tv',
-      tvdbId: 81189,
-      rootFolderPath: '/tv',
+      peerId: 'peer-1',
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      rootFolderPath: '/movies',
     })
 
-    expect(result).toEqual({ ok: true, server: 'My Sonarr' })
-    expect(sonarr.addAndSearch).toHaveBeenCalledWith({
-      tmdbId: undefined,
-      tvdbId: 81189,
-      qualityProfileId: 77,
-      rootFolderPath: '/tv',
+    expect(result).toEqual({ ok: true, server: 'My Radarr', started: 1 })
+    expect(radarr.add).toHaveBeenCalledWith({ tmdbId: 603, rootFolderPath: '/movies' })
+    expect(downloads.startDirectDownload).toHaveBeenCalledWith({
+      peerId: 'peer-1',
+      itemId: 'rel:best',
+      destinationServerName: 'My Radarr',
+      importTarget: { kind: 'movie', movieId: 123 },
     })
   })
 })
diff --git a/apps/backend/src/__tests__/downloads-service.test.ts b/apps/backend/src/__tests__/downloads-service.test.ts
index 3e54ebe..3810d20 100644
--- a/apps/backend/src/__tests__/downloads-service.test.ts
+++ b/apps/backend/src/__tests__/downloads-service.test.ts
@@ -318,4 +318,28 @@ describe('DownloadsService download progress persistence', () => {
     expect(repository.list()).toHaveLength(0)
     handle.close()
   })
+
+  test('startDirectDownload creates a jack_manual row carrying the importTarget and ends import_queued', async () => {
+    const handle = await openDatabase({ appConfigPath: join(tempDir, 'config.jsonc') })
+    const repository = new DownloadsRepository(handle.db)
+    const service = new DownloadsService(downloadsConfig(), { peers: [fakePeer() as any] }, repository)
+
+    const result = await service.startDirectDownload({
+      peerId: 'peer-1',
+      itemId: 'movie:1',
+      destinationServerName: 'My Radarr',
+      importTarget: { kind: 'movie', movieId: 42 },
+    })
+
+    expect(result).toBe('started')
+    await waitForStatus(repository, 'import_queued')
+
+    const rows = repository.list()
+    expect(rows).toHaveLength(1)
+    expect(rows[0]?.status).toBe('import_queued')
+    expect(rows[0]?.qbSourceServer).toBe('My Radarr')
+    expect(rows[0]?.importMode).toBe('jack_manual')
+    expect(rows[0]?.importTarget).toEqual({ kind: 'movie', movieId: 42 })
+    handle.close()
+  })
 })
diff --git a/apps/backend/src/__tests__/import-watcher.test.ts b/apps/backend/src/__tests__/import-watcher.test.ts
index 90fc70e..f62f72d 100644
--- a/apps/backend/src/__tests__/import-watcher.test.ts
+++ b/apps/backend/src/__tests__/import-watcher.test.ts
@@ -1,6 +1,7 @@
 import type { DownloadsRepository } from '../modules/downloads/downloads.repository'
+import { dirname } from 'node:path'
 import { Database } from 'bun:sqlite'
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, mock, test } from 'bun:test'
 import { drizzle } from 'drizzle-orm/bun-sqlite'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
@@ -92,3 +93,94 @@ describe('ImportWatcher', () => {
     expect(repo.get(row.id)?.status).toBe('import_queued')
   })
 })
+
+// A jack_manual import_queued row: the watcher must push an explicit ManualImport
+// to *arr (vs. the qB-added rows above, which *arr imports on its own).
+function manualRow(repo: DownloadsRepository, qbSourceServer: string) {
+  const row = repo.create({
+    torrentFilename: 't.torrent',
+    peerId: 'peer-1',
+    peerName: 'Friend',
+    itemId: 'movie:1',
+    filename: release.filename,
+    destPath: '/tmp/movies/x.mkv',
+    partPath: '/tmp/movies/x.mkv.part',
+    releaseSize: release.size,
+    release,
+    qbSourceServer,
+    importMode: 'jack_manual',
+    importTarget: { kind: 'movie', movieId: 42 },
+  })
+  repo.markImportQueued(row.id)
+  return row
+}
+
+function manualServer(name: string, importedHashes: string[], manualImport: (params: unknown) => Promise<void>, opts: { initialized?: boolean } = {}) {
+  return {
+    name,
+    isInitialized: opts.initialized ?? true,
+    recentlyImportedDownloadIds: async () => new Set(importedHashes.map(h => h.toLowerCase())),
+    manualImport,
+  } as any
+}
+
+describe('ImportWatcher jack_manual trigger', () => {
+  test('pushes manualImport once across two ticks while the hash is absent from history', async () => {
+    const repo = makeRepo()
+    const row = manualRow(repo, 'My Radarr')
+    const manualImport = mock(async () => {})
+    const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
+
+    await watcher.tick()
+    await watcher.tick()
+
+    expect(manualImport).toHaveBeenCalledTimes(1)
+    expect(manualImport).toHaveBeenCalledWith({
+      folder: dirname(row.destPath),
+      paths: [row.destPath],
+      target: { kind: 'movie', movieId: 42 },
+      downloadId: HASH,
+    })
+    expect(repo.get(row.id)?.status).toBe('import_queued')
+  })
+
+  test('marks the row imported (and skips the push) once the hash appears in *arr history', async () => {
+    const repo = makeRepo()
+    const row = manualRow(repo, 'My Radarr')
+    const manualImport = mock(async () => {})
+    const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [HASH], manualImport)] }, 1000)
+
+    expect(await watcher.tick()).toBe(1)
+    expect(repo.get(row.id)?.status).toBe('imported')
+    expect(manualImport).not.toHaveBeenCalled()
+  })
+
+  test('re-triggers after a restart (a fresh watcher with an empty triggered set)', async () => {
+    const repo = makeRepo()
+    manualRow(repo, 'My Radarr')
+    const manualImport = mock(async () => {})
+    const first = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
+    await first.tick()
+    expect(manualImport).toHaveBeenCalledTimes(1)
+
+    const second = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
+    await second.tick()
+    expect(manualImport).toHaveBeenCalledTimes(2)
+  })
+
+  test('retries on the next tick when the manual-import push throws', async () => {
+    const repo = makeRepo()
+    manualRow(repo, 'My Radarr')
+    let calls = 0
+    const manualImport = mock(async () => {
+      calls++
+      if (calls === 1)
+        throw new Error('arr down')
+    })
+    const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
+
+    await watcher.tick()
+    await watcher.tick()
+    expect(manualImport).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/apps/backend/src/__tests__/integration.test.ts b/apps/backend/src/__tests__/integration.test.ts
index ff62e2a..a3190e9 100644
--- a/apps/backend/src/__tests__/integration.test.ts
+++ b/apps/backend/src/__tests__/integration.test.ts
@@ -9,7 +9,6 @@ import { getApp } from '../app'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
 import { AppConfig, MIGRATIONS } from '../lib/config'
-import { BadRequestError } from '../lib/errors/BadRequestError'
 import { RadarrServerConnector } from '../lib/servers/arr/radarr'
 import { SonarrServerConnector } from '../lib/servers/arr/sonarr'
 import { PeerConnector } from '../lib/servers/peer'
@@ -559,100 +558,6 @@ describe('Auto-registration', () => {
   })
 })
 
-describe('addAndSearch', () => {
-  const lookedUpMovie = { tmdbId: 603, title: 'The Matrix', year: 1999, titleSlug: 'the-matrix-603', images: [] }
-  const lookedUpSeries = { tvdbId: 81189, title: 'Breaking Bad', year: 2008, titleSlug: 'breaking-bad-81189', images: [] }
-
-  test('Radarr: looks up the movie and POSTs it monitored with searchForMovie', async () => {
-    let lookupTerm: any = null
-    let postBody: any = null
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/movie/lookup`, ({ request }) => {
-        lookupTerm = new URL(request.url).searchParams.get('term')
-        return HttpResponse.json([lookedUpMovie])
-      }),
-      http.post(`${RADARR_URL}/api/v3/movie`, async ({ request }) => {
-        postBody = await request.json()
-        return HttpResponse.json({ id: 1, ...lookedUpMovie })
-      }),
-    )
-
-    const radarr = markInitialized(makeRadarr())
-    await radarr.addAndSearch({ tmdbId: 603, qualityProfileId: 4, rootFolderPath: '/movies' })
-
-    expect(lookupTerm).toBe('tmdb:603')
-    expect(postBody).toMatchObject({
-      tmdbId: 603,
-      title: 'The Matrix',
-      qualityProfileId: 4,
-      rootFolderPath: '/movies',
-      monitored: true,
-    })
-    expect(postBody.addOptions).toMatchObject({ searchForMovie: true })
-  })
-
-  test('Radarr: throws BadRequestError when no tmdbId is given', async () => {
-    const radarr = markInitialized(makeRadarr())
-    await expect(radarr.addAndSearch({ qualityProfileId: 4, rootFolderPath: '/movies' })).rejects.toThrow(BadRequestError)
-  })
-
-  test('Radarr: throws BadRequestError naming the server and id when lookup is empty', async () => {
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/movie/lookup`, () => HttpResponse.json([])),
-    )
-    const radarr = markInitialized(makeRadarr())
-    const promise = radarr.addAndSearch({ tmdbId: 603, qualityProfileId: 4, rootFolderPath: '/movies' })
-    await expect(promise).rejects.toThrow(BadRequestError)
-    await expect(promise).rejects.toThrow(/My Radarr/)
-    await expect(promise).rejects.toThrow(/603/)
-  })
-
-  test('Sonarr: looks up the series and POSTs it monitored with searchForMissingEpisodes', async () => {
-    let lookupTerm: any = null
-    let postBody: any = null
-    server.use(
-      http.get(`${SONARR_URL}/api/v3/series/lookup`, ({ request }) => {
-        lookupTerm = new URL(request.url).searchParams.get('term')
-        return HttpResponse.json([lookedUpSeries])
-      }),
-      http.post(`${SONARR_URL}/api/v3/series`, async ({ request }) => {
-        postBody = await request.json()
-        return HttpResponse.json({ id: 1, ...lookedUpSeries })
-      }),
-    )
-
-    const sonarr = markInitialized(makeSonarr())
-    await sonarr.addAndSearch({ tvdbId: 81189, qualityProfileId: 7, rootFolderPath: '/tv' })
-
-    expect(lookupTerm).toBe('tvdb:81189')
-    expect(postBody).toMatchObject({
-      tvdbId: 81189,
-      title: 'Breaking Bad',
-      qualityProfileId: 7,
-      rootFolderPath: '/tv',
-      monitored: true,
-      seasonFolder: true,
-    })
-    expect(postBody.addOptions).toMatchObject({ searchForMissingEpisodes: true })
-  })
-
-  test('Sonarr: throws BadRequestError when no tvdbId is given', async () => {
-    const sonarr = markInitialized(makeSonarr())
-    await expect(sonarr.addAndSearch({ qualityProfileId: 7, rootFolderPath: '/tv' })).rejects.toThrow(BadRequestError)
-  })
-
-  test('Sonarr: throws BadRequestError naming the server and id when lookup is empty', async () => {
-    server.use(
-      http.get(`${SONARR_URL}/api/v3/series/lookup`, () => HttpResponse.json([])),
-    )
-    const sonarr = markInitialized(makeSonarr())
-    const promise = sonarr.addAndSearch({ tvdbId: 81189, qualityProfileId: 7, rootFolderPath: '/tv' })
-    await expect(promise).rejects.toThrow(BadRequestError)
-    await expect(promise).rejects.toThrow(/My Sonarr/)
-    await expect(promise).rejects.toThrow(/81189/)
-  })
-})
-
 describe('ensureJackCustomFormat', () => {
   test('Radarr: POSTs a "Jack" custom format matching the Internal flag (value 32)', async () => {
     let postBody: any = null
diff --git a/apps/backend/src/__tests__/qbittorrent-mapper.test.ts b/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
index 1744d01..d88be65 100644
--- a/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
+++ b/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
@@ -26,6 +26,8 @@ function baseRecord(overrides: Partial<DownloadRecord> = {}): DownloadRecord {
     error: null,
     qbCategory: 'jack-abc12345',
     qbSourceServer: 'My Radarr',
+    importMode: null,
+    importTarget: null,
     ...overrides,
   }
 }
diff --git a/apps/backend/src/database/schema.ts b/apps/backend/src/database/schema.ts
index dc58ceb..c94ef1a 100644
--- a/apps/backend/src/database/schema.ts
+++ b/apps/backend/src/database/schema.ts
@@ -33,6 +33,11 @@ export const downloads = sqliteTable('downloads', {
   // download (→ *arr-pull import, no jack push). Null for blackhole-added rows.
   qbCategory: text('qb_category'),
   qbSourceServer: text('qb_source_server'),
+  // Direct catalog downloads: 'jack_manual' means the import watcher must push an
+  // explicit *arr ManualImport (vs. null = qB/blackhole, where *arr imports itself).
+  importMode: text('import_mode').$type<'jack_manual' | null>(),
+  // JSON ManualImportTarget: {"kind":"movie","movieId":N} | {"kind":"series","seriesId":N}.
+  importTarget: text('import_target'),
 }, t => [
   check('downloads_status_check', sql`${t.status} in ('downloading', 'import_queued', 'imported', 'failed')`),
   check('downloads_expected_bytes_source_check', sql`${t.expectedBytesSource} is null or ${t.expectedBytesSource} in ('content_length', 'content_range', 'release_size')`),
diff --git a/apps/backend/src/index.ts b/apps/backend/src/index.ts
index 6fea726..a476dd2 100644
--- a/apps/backend/src/index.ts
+++ b/apps/backend/src/index.ts
@@ -82,6 +82,7 @@ function startManagementServer() {
     connectors: connectorManager,
     configService,
     downloadsRepository,
+    downloadsService,
     apiKeysRepository,
     tmdbApiKey: config.jack.tmdbApiKey,
   })
diff --git a/apps/backend/src/lib/servers/arr/arr-add-import.test.ts b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
new file mode 100644
index 0000000..41c854b
--- /dev/null
+++ b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
@@ -0,0 +1,299 @@
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+import { z } from 'zod'
+import { BadRequestError } from '../../errors/BadRequestError'
+import { RadarrServerConnector } from './radarr'
+import { SonarrServerConnector } from './sonarr'
+
+const RADARR_URL = 'http://radarr.test:7878'
+const SONARR_URL = 'http://sonarr.test:8989'
+const HEX_KEY = 'a'.repeat(32)
+const AUTOREGISTER = { enable: true, priority: 1 }
+
+// Default handlers shared by every test: identity ping (drives the
+// @requiresInitialization guard's auto-init) + a single quality profile.
+const handlers = [
+  http.get(`${RADARR_URL}/api/v3/system/status`, () => HttpResponse.json({ appName: 'Radarr', version: '4.0.0' })),
+  http.get(`${SONARR_URL}/api/v3/system/status`, () => HttpResponse.json({ appName: 'Sonarr', version: '4.0.0' })),
+  http.get(`${RADARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([{ id: 4 }])),
+  http.get(`${SONARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([{ id: 7 }])),
+]
+
+const server = setupServer(...handlers)
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'bypass' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+function makeRadarr() {
+  return new RadarrServerConnector({
+    url: RADARR_URL,
+    apiKey: HEX_KEY,
+    name: 'My Radarr',
+    source: true,
+    destination: true,
+    autoregister: AUTOREGISTER,
+  })
+}
+
+function makeSonarr() {
+  return new SonarrServerConnector({
+    url: SONARR_URL,
+    apiKey: HEX_KEY,
+    name: 'My Sonarr',
+    source: true,
+    destination: true,
+    autoregister: AUTOREGISTER,
+  })
+}
+
+// The candidate `quality`/`languages` are opaque blobs we forward verbatim, so a
+// schema is the rule-compliant way to read the captured POST body back as typed.
+const CommandBody = z.object({
+  name: z.string(),
+  importMode: z.string(),
+  files: z.array(z.object({
+    path: z.string(),
+    movieId: z.number().optional(),
+    seriesId: z.number().optional(),
+    episodeIds: z.array(z.number()).optional(),
+    downloadId: z.string(),
+    quality: z.unknown(),
+    languages: z.array(z.unknown()),
+    releaseGroup: z.string().optional(),
+  })),
+})
+
+const lookedUpMovie = { tmdbId: 603, title: 'The Matrix', year: 1999, titleSlug: 'the-matrix-603', images: [] }
+const lookedUpSeries = { tvdbId: 81189, title: 'Breaking Bad', year: 2008, titleSlug: 'breaking-bad-81189', images: [] }
+
+describe('RadarrServerConnector.add', () => {
+  test('looks up the movie and POSTs it WITHOUT a search, returning the created id', async () => {
+    let postBody: unknown = null
+    let lookupTerm: string | null = null
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/movie`, () => HttpResponse.json([])),
+      http.get(`${RADARR_URL}/api/v3/movie/lookup`, ({ request }) => {
+        lookupTerm = new URL(request.url).searchParams.get('term')
+        return HttpResponse.json([lookedUpMovie])
+      }),
+      http.post(`${RADARR_URL}/api/v3/movie`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 1, ...lookedUpMovie })
+      }),
+    )
+
+    const radarr = makeRadarr()
+    const id = await radarr.add({ tmdbId: 603, rootFolderPath: '/movies' })
+
+    expect(id).toBe(1)
+    expect<string | null>(lookupTerm).toBe('tmdb:603')
+    expect(postBody).toMatchObject({
+      tmdbId: 603,
+      title: 'The Matrix',
+      qualityProfileId: 4,
+      rootFolderPath: '/movies',
+      monitored: true,
+      addOptions: { searchForMovie: false },
+    })
+  })
+
+  test('is idempotent: returns the existing movie id without POSTing when already in the library', async () => {
+    let posted = false
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/movie`, () => HttpResponse.json([{ id: 99 }])),
+      http.post(`${RADARR_URL}/api/v3/movie`, () => {
+        posted = true
+        return HttpResponse.json({ id: 99 })
+      }),
+    )
+
+    const radarr = makeRadarr()
+    const id = await radarr.add({ tmdbId: 603, rootFolderPath: '/movies' })
+
+    expect(id).toBe(99)
+    expect(posted).toBe(false)
+  })
+
+  test('throws BadRequestError when no tmdbId is given', async () => {
+    const radarr = makeRadarr()
+    await expect(radarr.add({ rootFolderPath: '/movies' })).rejects.toThrow(BadRequestError)
+  })
+
+  test('throws BadRequestError naming the server and id when the lookup is empty', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/movie`, () => HttpResponse.json([])),
+      http.get(`${RADARR_URL}/api/v3/movie/lookup`, () => HttpResponse.json([])),
+    )
+    const radarr = makeRadarr()
+    const promise = radarr.add({ tmdbId: 603, rootFolderPath: '/movies' })
+    await expect(promise).rejects.toThrow(BadRequestError)
+    await expect(promise).rejects.toThrow(/My Radarr/)
+    await expect(promise).rejects.toThrow(/603/)
+  })
+})
+
+describe('RadarrServerConnector.manualImport', () => {
+  test('imports only the file matching params.paths, carrying movieId/downloadId/quality/languages', async () => {
+    let commandBody: unknown = null
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/manualimport`, () => HttpResponse.json([
+        { path: '/downloads/Movie.mkv', quality: { quality: { id: 7 } }, languages: [{ id: 1, name: 'English' }], releaseGroup: 'GRP' },
+        { path: '/downloads/Other.mkv', quality: { quality: { id: 3 } }, languages: [{ id: 2, name: 'French' }], releaseGroup: 'X' },
+      ])),
+      http.post(`${RADARR_URL}/api/v3/command`, async ({ request }) => {
+        commandBody = await request.json()
+        return HttpResponse.json({ id: 1 })
+      }),
+    )
+
+    const radarr = makeRadarr()
+    await radarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Movie.mkv'],
+      target: { kind: 'movie', movieId: 7 },
+      downloadId: 'dl-1',
+    })
+
+    const body = CommandBody.parse(commandBody)
+    expect(body.name).toBe('ManualImport')
+    expect(body.importMode).toBe('move')
+    expect(body.files).toHaveLength(1)
+    expect(body.files[0]).toMatchObject({
+      path: '/downloads/Movie.mkv',
+      movieId: 7,
+      downloadId: 'dl-1',
+      quality: { quality: { id: 7 } },
+      languages: [{ id: 1, name: 'English' }],
+      releaseGroup: 'GRP',
+    })
+  })
+
+  test('throws BadRequestError when given a series target', async () => {
+    const radarr = makeRadarr()
+    await expect(radarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Movie.mkv'],
+      target: { kind: 'series', seriesId: 1 },
+      downloadId: 'dl-1',
+    })).rejects.toThrow(BadRequestError)
+  })
+
+  test('throws BadRequestError when no candidate matches the wanted path', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/manualimport`, () => HttpResponse.json([
+        { path: '/downloads/Other.mkv', quality: {}, languages: [] },
+      ])),
+    )
+    const radarr = makeRadarr()
+    await expect(radarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Movie.mkv'],
+      target: { kind: 'movie', movieId: 7 },
+      downloadId: 'dl-1',
+    })).rejects.toThrow(BadRequestError)
+  })
+})
+
+describe('SonarrServerConnector.add', () => {
+  test('looks up the series and POSTs it WITHOUT a search, returning the created id', async () => {
+    let postBody: unknown = null
+    let lookupTerm: string | null = null
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/series`, () => HttpResponse.json([])),
+      http.get(`${SONARR_URL}/api/v3/series/lookup`, ({ request }) => {
+        lookupTerm = new URL(request.url).searchParams.get('term')
+        return HttpResponse.json([lookedUpSeries])
+      }),
+      http.post(`${SONARR_URL}/api/v3/series`, async ({ request }) => {
+        postBody = await request.json()
+        return HttpResponse.json({ id: 1, ...lookedUpSeries })
+      }),
+    )
+
+    const sonarr = makeSonarr()
+    const id = await sonarr.add({ tvdbId: 81189, rootFolderPath: '/tv' })
+
+    expect(id).toBe(1)
+    expect<string | null>(lookupTerm).toBe('tvdb:81189')
+    expect(postBody).toMatchObject({
+      tvdbId: 81189,
+      title: 'Breaking Bad',
+      qualityProfileId: 7,
+      rootFolderPath: '/tv',
+      monitored: true,
+      seasonFolder: true,
+      addOptions: { monitor: 'all', searchForMissingEpisodes: false },
+    })
+  })
+
+  test('is idempotent: returns the existing series id without POSTing when already in the library', async () => {
+    let posted = false
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/series`, () => HttpResponse.json([{ id: 42 }])),
+      http.post(`${SONARR_URL}/api/v3/series`, () => {
+        posted = true
+        return HttpResponse.json({ id: 42 })
+      }),
+    )
+
+    const sonarr = makeSonarr()
+    const id = await sonarr.add({ tvdbId: 81189, rootFolderPath: '/tv' })
+
+    expect(id).toBe(42)
+    expect(posted).toBe(false)
+  })
+
+  test('throws BadRequestError when no tvdbId is given', async () => {
+    const sonarr = makeSonarr()
+    await expect(sonarr.add({ rootFolderPath: '/tv' })).rejects.toThrow(BadRequestError)
+  })
+})
+
+describe('SonarrServerConnector.manualImport', () => {
+  test('imports the matching file carrying seriesId, episodeIds, downloadId, quality, languages', async () => {
+    let commandBody: unknown = null
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/manualimport`, () => HttpResponse.json([
+        { path: '/downloads/Ep.mkv', quality: { quality: { id: 4 } }, languages: [{ id: 1, name: 'English' }], releaseGroup: 'GRP', episodes: [{ id: 11 }, { id: 12 }] },
+        { path: '/downloads/Other.mkv', quality: {}, languages: [], episodes: [{ id: 99 }] },
+      ])),
+      http.post(`${SONARR_URL}/api/v3/command`, async ({ request }) => {
+        commandBody = await request.json()
+        return HttpResponse.json({ id: 1 })
+      }),
+    )
+
+    const sonarr = makeSonarr()
+    await sonarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Ep.mkv'],
+      target: { kind: 'series', seriesId: 3 },
+      downloadId: 'dl-2',
+    })
+
+    const body = CommandBody.parse(commandBody)
+    expect(body.name).toBe('ManualImport')
+    expect(body.importMode).toBe('move')
+    expect(body.files).toHaveLength(1)
+    expect(body.files[0]).toMatchObject({
+      path: '/downloads/Ep.mkv',
+      seriesId: 3,
+      episodeIds: [11, 12],
+      downloadId: 'dl-2',
+      quality: { quality: { id: 4 } },
+      languages: [{ id: 1, name: 'English' }],
+    })
+  })
+
+  test('throws BadRequestError when given a movie target', async () => {
+    const sonarr = makeSonarr()
+    await expect(sonarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Ep.mkv'],
+      target: { kind: 'movie', movieId: 1 },
+      downloadId: 'dl-2',
+    })).rejects.toThrow(BadRequestError)
+  })
+})
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index 0c986ca..b11cd29 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -4,6 +4,7 @@ import z from 'zod'
 import { logger } from '../../../logger'
 import { requiresDestination, requiresSource } from '../../decorators/requires-capability'
 import { requiresInitialization } from '../../decorators/requires-initialization'
+import { BadRequestError } from '../../errors/BadRequestError'
 import { ServerConnector } from '../base'
 
 const BASENAME_SEPARATOR_REGEX = /[/\\]/
@@ -46,13 +47,26 @@ const JACK_DOWNLOAD_CLIENT_PRIORITY = 50
 
 export type ReleaseKind = 'movie' | 'episode'
 
-export interface AddAndSearchParams {
+export interface AddParams {
   tmdbId?: number
   tvdbId?: number
-  qualityProfileId: number
   rootFolderPath: string
 }
 
+export type ManualImportTarget
+  = | { kind: 'movie', movieId: number }
+    | { kind: 'series', seriesId: number }
+
+export interface ManualImportParams {
+  /** Directory *arr scans for importable files (the downloads completedPath). */
+  folder: string
+  /** Absolute paths of the file(s) we downloaded; only these are imported. */
+  paths: string[]
+  target: ManualImportTarget
+  /** Stub infohash = deriveHash(title,size); recorded in *arr history so the watcher matches it. */
+  downloadId: string
+}
+
 export function basename(path: string): string {
   return path.split(BASENAME_SEPARATOR_REGEX).pop() ?? path
 }
@@ -291,14 +305,32 @@ export abstract class ArrServerConnector extends ServerConnector {
       .map(f => ({ path: f.path, freeSpace: f.freeSpace }))
   }
 
-  /** Add a title to this *arr (monitored) and kick off an automatic search. */
+  /** Add a title to this *arr (monitored) WITHOUT a search; returns the created or existing entity id. */
   @requiresDestination
   @requiresInitialization
-  async addAndSearch(params: AddAndSearchParams): Promise<void> {
-    return this.doAddAndSearch(params)
+  async add(params: AddParams): Promise<number> {
+    return this.doAdd(params)
   }
 
-  protected abstract doAddAndSearch(params: AddAndSearchParams): Promise<void>
+  protected abstract doAdd(params: AddParams): Promise<number>
+
+  /** Import already-downloaded file(s) into this *arr, mapped to `target`. */
+  @requiresDestination
+  @requiresInitialization
+  async manualImport(params: ManualImportParams): Promise<void> {
+    return this.doManualImport(params)
+  }
+
+  protected abstract doManualImport(params: ManualImportParams): Promise<void>
+
+  /** First quality profile id — required to add a title (manual import detects real quality from the file). */
+  protected async resolveQualityProfileId(): Promise<number> {
+    const profiles = await this.arrGet<Array<{ id: number }>>('/api/v3/qualityprofile')
+    const first = Array.isArray(profiles) ? profiles[0] : undefined
+    if (!first)
+      throw new BadRequestError(`No quality profile found on ${this.name}; cannot add a title`)
+    return first.id
+  }
 
   /**
    * Lowercased torrent infohashes (`downloadId`s) that this *arr has finished
diff --git a/apps/backend/src/lib/servers/arr/radarr.ts b/apps/backend/src/lib/servers/arr/radarr.ts
index b00feb4..c4c738b 100644
--- a/apps/backend/src/lib/servers/arr/radarr.ts
+++ b/apps/backend/src/lib/servers/arr/radarr.ts
@@ -1,13 +1,23 @@
 import type { MovieFileResource, MovieResource } from '@jack/schemas/radarr/types'
 import type { AutoRegisterConfig, ConnectorHeadersConfig } from '../../config'
 import type { Release } from '../../release'
-import type { AddAndSearchParams } from './base'
+import type { AddParams, ManualImportParams } from './base'
+import { z } from 'zod'
 import { BadRequestError } from '../../errors/BadRequestError'
 import { normalizeImdbId, ReleaseCategory } from '../../release'
 import { setSpanAttribute, setSpanAttributes } from '../../span-attributes'
 import { withSpan } from '../../tracing'
 import { ArrServerConnector, basename, stripExtension } from './base'
 
+const CreatedId = z.object({ id: z.number().int() })
+
+interface ManualImportCandidate {
+  path?: string
+  quality?: unknown
+  languages?: unknown[]
+  releaseGroup?: string
+}
+
 export class RadarrServerConnector extends ArrServerConnector {
   constructor(config: { url: string, apiKey: string, name: string, source: boolean, destination: boolean, autoregister: AutoRegisterConfig, headers?: ConnectorHeadersConfig }) {
     super({
@@ -153,9 +163,16 @@ export class RadarrServerConnector extends ArrServerConnector {
     return (movie?.movieFile as MovieFileResource | undefined)?.path ?? null
   }
 
-  protected override async doAddAndSearch(params: AddAndSearchParams): Promise<void> {
+  protected override async doAdd(params: AddParams): Promise<number> {
     if (params.tmdbId == null)
       throw new BadRequestError('A tmdbId is required to add a movie to Radarr')
+
+    // Idempotent: reuse the movie if it's already in the library.
+    const existing = await this.arrGet<MovieResource[]>('/api/v3/movie', { tmdbId: String(params.tmdbId) })
+    const found = Array.isArray(existing) ? existing.find(m => m.id != null) : undefined
+    if (found?.id != null)
+      return found.id
+
     const lookup = await this.arrGet<MovieResource[]>('/api/v3/movie/lookup', { term: `tmdb:${params.tmdbId}` })
     const movie = Array.isArray(lookup) ? lookup[0] : undefined
     if (!movie)
@@ -163,16 +180,49 @@ export class RadarrServerConnector extends ArrServerConnector {
 
     const body = {
       ...movie,
-      qualityProfileId: params.qualityProfileId,
+      qualityProfileId: await this.resolveQualityProfileId(),
       rootFolderPath: params.rootFolderPath,
       monitored: true,
       minimumAvailability: 'released',
-      addOptions: { searchForMovie: true },
+      addOptions: { searchForMovie: false },
     }
-    await this.fetch('/api/v3/movie', {
+    const created = await this.fetch('/api/v3/movie', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
-    } as any)
+      schema: CreatedId,
+    })
+    return created.id
+  }
+
+  protected override async doManualImport(params: ManualImportParams): Promise<void> {
+    if (params.target.kind !== 'movie')
+      throw new BadRequestError(`Radarr cannot import a "${params.target.kind}" target`)
+    const { movieId } = params.target
+
+    const candidates = await this.arrGet<ManualImportCandidate[]>('/api/v3/manualimport', {
+      folder: params.folder,
+      movieId: String(movieId),
+      filterExistingFiles: 'false',
+    })
+    const wanted = new Set(params.paths)
+    const files = (Array.isArray(candidates) ? candidates : [])
+      .filter((c): c is ManualImportCandidate & { path: string } => typeof c.path === 'string' && wanted.has(c.path))
+      .map(c => ({
+        path: c.path,
+        movieId,
+        quality: c.quality,
+        languages: c.languages ?? [],
+        releaseGroup: c.releaseGroup ?? '',
+        downloadId: params.downloadId,
+      }))
+    if (files.length === 0)
+      throw new BadRequestError(`Radarr found no importable file for movie ${movieId} in ${params.folder}`)
+
+    await this.fetch('/api/v3/command', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'ManualImport', importMode: 'move', files }),
+    })
   }
 }
diff --git a/apps/backend/src/lib/servers/arr/sonarr.ts b/apps/backend/src/lib/servers/arr/sonarr.ts
index 1014254..6cae646 100644
--- a/apps/backend/src/lib/servers/arr/sonarr.ts
+++ b/apps/backend/src/lib/servers/arr/sonarr.ts
@@ -1,7 +1,8 @@
 import type { EpisodeFileResource, EpisodeResource, SeriesResource } from '@jack/schemas/sonarr/types'
 import type { AutoRegisterConfig, ConnectorHeadersConfig } from '../../config'
 import type { Release } from '../../release'
-import type { AddAndSearchParams } from './base'
+import type { AddParams, ManualImportParams } from './base'
+import { z } from 'zod'
 import { BadRequestError } from '../../errors/BadRequestError'
 import { ReleaseCategory } from '../../release'
 import { setSpanAttributes } from '../../span-attributes'
@@ -10,6 +11,16 @@ import { ArrServerConnector, basename, stripExtension } from './base'
 
 type SeriesWithId = SeriesResource & { id: number }
 
+const CreatedId = z.object({ id: z.number().int() })
+
+interface SonarrManualImportCandidate {
+  path?: string
+  quality?: unknown
+  languages?: unknown[]
+  releaseGroup?: string
+  episodes?: Array<{ id?: number }>
+}
+
 export class SonarrServerConnector extends ArrServerConnector {
   constructor(config: { url: string, apiKey: string, name: string, source: boolean, destination: boolean, autoregister: AutoRegisterConfig, headers?: ConnectorHeadersConfig }) {
     super({
@@ -170,9 +181,14 @@ export class SonarrServerConnector extends ArrServerConnector {
     return bundle?.file?.path ?? null
   }
 
-  protected override async doAddAndSearch(params: AddAndSearchParams): Promise<void> {
+  protected override async doAdd(params: AddParams): Promise<number> {
     if (params.tvdbId == null)
       throw new BadRequestError('A tvdbId is required to add a series to Sonarr')
+
+    const existing = await this.listSeries({ tvdbId: String(params.tvdbId) })
+    if (existing[0]?.id != null)
+      return existing[0].id
+
     const lookup = await this.arrGet<SeriesResource[]>('/api/v3/series/lookup', { term: `tvdb:${params.tvdbId}` })
     const series = Array.isArray(lookup) ? lookup[0] : undefined
     if (!series)
@@ -180,16 +196,51 @@ export class SonarrServerConnector extends ArrServerConnector {
 
     const body = {
       ...series,
-      qualityProfileId: params.qualityProfileId,
+      qualityProfileId: await this.resolveQualityProfileId(),
       rootFolderPath: params.rootFolderPath,
       monitored: true,
       seasonFolder: true,
-      addOptions: { monitor: 'all', searchForMissingEpisodes: true },
+      addOptions: { monitor: 'all', searchForMissingEpisodes: false },
     }
-    await this.fetch('/api/v3/series', {
+    const created = await this.fetch('/api/v3/series', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),
-    } as any)
+      schema: CreatedId,
+    })
+    return created.id
+  }
+
+  protected override async doManualImport(params: ManualImportParams): Promise<void> {
+    if (params.target.kind !== 'series')
+      throw new BadRequestError(`Sonarr cannot import a "${params.target.kind}" target`)
+    const { seriesId } = params.target
+
+    const candidates = await this.arrGet<SonarrManualImportCandidate[]>('/api/v3/manualimport', {
+      folder: params.folder,
+      seriesId: String(seriesId),
+      filterExistingFiles: 'false',
+    })
+    const wanted = new Set(params.paths)
+    const files = (Array.isArray(candidates) ? candidates : [])
+      .filter((c): c is SonarrManualImportCandidate & { path: string } => typeof c.path === 'string' && wanted.has(c.path))
+      .map(c => ({
+        path: c.path,
+        seriesId,
+        episodeIds: (c.episodes ?? []).map(e => e.id).filter((id): id is number => id != null),
+        quality: c.quality,
+        languages: c.languages ?? [],
+        releaseGroup: c.releaseGroup ?? '',
+        downloadId: params.downloadId,
+      }))
+      .filter(f => f.episodeIds.length > 0)
+    if (files.length === 0)
+      throw new BadRequestError(`Sonarr found no importable episode file for series ${seriesId} in ${params.folder}`)
+
+    await this.fetch('/api/v3/command', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'ManualImport', importMode: 'move', files }),
+    })
   }
 }
diff --git a/apps/backend/src/management-app.ts b/apps/backend/src/management-app.ts
index d7c5f53..eafcb1d 100644
--- a/apps/backend/src/management-app.ts
+++ b/apps/backend/src/management-app.ts
@@ -2,6 +2,7 @@ import type { ConnectorManager } from './lib/servers'
 import type { ApiKeysRepository } from './modules/api-keys/api-keys.repository'
 import type { ConfigService } from './modules/config/config.service'
 import type { DownloadsRepository } from './modules/downloads/downloads.repository'
+import type { DownloadsService } from './modules/downloads/downloads.service'
 import { Hono } from 'hono'
 import { secureHeaders } from 'hono/secure-headers'
 import { TmdbClient } from './lib/tmdb/client'
@@ -23,6 +24,7 @@ export function getManagementApp(params: {
   connectors: { servers: ConnectorManager['servers'], peers: ConnectorManager['peers'] }
   configService?: ConfigService
   downloadsRepository?: DownloadsRepository
+  downloadsService?: DownloadsService
   apiKeysRepository?: ApiKeysRepository
   tmdbApiKey?: string
 }) {
@@ -43,7 +45,7 @@ export function getManagementApp(params: {
   app.route('/', getStatusRouter(statusController))
 
   const tmdbClient = params.tmdbApiKey ? new TmdbClient(params.tmdbApiKey) : undefined
-  const catalogController = new CatalogController(params.connectors, tmdbClient)
+  const catalogController = new CatalogController(params.connectors, tmdbClient, params.downloadsService)
   app.route('/catalog', getCatalogRouter(catalogController))
 
   if (params.apiKeysRepository) {
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index f6eebc9..18eb4fa 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -1,10 +1,11 @@
 import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { PeerConnector } from '../../lib/servers/peer'
 import type { TmdbClient, TmdbMediaType, TmdbMetadata } from '../../lib/tmdb/client'
+import type { DownloadsService } from '../downloads/downloads.service'
 import type { CatalogTitle } from './catalog.lib'
 import { BadRequestError } from '../../lib/errors/BadRequestError'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
-import { groupReleasesIntoTitles } from './catalog.lib'
+import { groupReleasesIntoTitles, pickBestRelease } from './catalog.lib'
 
 export interface PeerCatalogResponse {
   peer: { id: string, name: string }
@@ -26,6 +27,7 @@ export interface RequestServerOption {
 }
 
 export interface CatalogRequestInput {
+  peerId: string
   serverId: string
   mediaType: 'movie' | 'tv'
   tmdbId?: number
@@ -37,6 +39,7 @@ export class CatalogController {
   constructor(
     private readonly connectors: { servers: ArrServerConnector[], peers: PeerConnector[] },
     private readonly tmdb?: TmdbClient,
+    private readonly downloads?: DownloadsService,
   ) {}
 
   private requirePeer(peerId: string): PeerConnector {
@@ -87,7 +90,10 @@ export class CatalogController {
     return options.filter((o): o is RequestServerOption => o !== null)
   }
 
-  async requestDownload(input: CatalogRequestInput): Promise<{ ok: true, server: string }> {
+  async requestDownload(input: CatalogRequestInput): Promise<{ ok: true, server: string, started: number }> {
+    if (!this.downloads)
+      throw new BadRequestError('Downloads are not configured on this Jack instance')
+
     const server = this.connectors.servers.find(s => s.id === input.serverId)
     if (!server)
       throw new NotFoundError(`No server found with id "${input.serverId}"`)
@@ -98,16 +104,26 @@ export class CatalogController {
     if (server.type !== expectedType)
       throw new BadRequestError(`Server "${server.name}" cannot handle ${input.mediaType} requests`)
 
-    // Force Jack's dedicated profile so *arr only grabs this release from the Jack
-    // indexer (the profile rejects releases without the Internal flag).
-    const qualityProfileId = await server.ensureJackQualityProfile()
-    await server.addAndSearch({
-      tmdbId: input.tmdbId,
-      tvdbId: input.tvdbId,
-      qualityProfileId,
-      rootFolderPath: input.rootFolderPath,
+    const peer = this.requirePeer(input.peerId)
+
+    if (input.mediaType !== 'movie')
+      throw new BadRequestError('TV requests are not supported yet') // implemented in Phase 2
+
+    if (input.tmdbId == null)
+      throw new BadRequestError('A tmdbId is required for a movie request')
+    const releases = await peer.searchByTmdbId(String(input.tmdbId))
+    const best = pickBestRelease(releases)
+    if (!best)
+      throw new NotFoundError(`Peer "${peer.name}" has no release for tmdbId ${input.tmdbId}`)
+
+    const movieId = await server.add({ tmdbId: input.tmdbId, rootFolderPath: input.rootFolderPath })
+    await this.downloads.startDirectDownload({
+      peerId: peer.id,
+      itemId: best.id,
+      destinationServerName: server.name,
+      importTarget: { kind: 'movie', movieId },
     })
-    return { ok: true, server: server.name }
+    return { ok: true, server: server.name, started: 1 }
   }
 
   async getTmdbStatus(): Promise<TmdbStatus> {
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
index e4c8fde..87d7be1 100644
--- a/apps/backend/src/modules/catalog/catalog.lib.ts
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -80,3 +80,33 @@ export function groupReleasesIntoTitles(releases: Release[]): CatalogTitle[] {
 
   return [...byKey.values()].sort((a, b) => a.displayTitle.localeCompare(b.displayTitle))
 }
+
+/**
+ * Higher resolution wins; ties break to the larger file; full ties break to the
+ * lexicographically lowest release id so the pick is deterministic regardless of
+ * the order the peer returns its catalog in.
+ */
+function isBetterRelease(candidate: Release, current: Release): boolean {
+  const c = candidate.quality?.resolution ?? 0
+  const r = current.quality?.resolution ?? 0
+  if (c !== r)
+    return c > r
+  if (candidate.size !== current.size)
+    return candidate.size > current.size
+  return candidate.id.localeCompare(current.id) < 0
+}
+
+export function pickBestRelease(releases: Release[]): Release | undefined {
+  return releases.reduce<Release | undefined>((best, r) => (!best || isBetterRelease(r, best)) ? r : best, undefined)
+}
+
+export function pickBestPerEpisode(releases: Release[]): Release[] {
+  const byEpisode = new Map<string, Release>()
+  for (const r of releases) {
+    const key = `${r.season ?? 0}:${r.episode ?? 0}`
+    const current = byEpisode.get(key)
+    if (!current || isBetterRelease(r, current))
+      byEpisode.set(key, r)
+  }
+  return [...byEpisode.values()]
+}
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index fd9b69c..faa2c73 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -11,6 +11,7 @@ const tmdbParam = z.object({
 })
 
 const requestBody = z.object({
+  peerId: z.string().min(1),
   serverId: z.string().min(1),
   mediaType: z.enum(['movie', 'tv']),
   tmdbId: z.number().int().optional(),
diff --git a/apps/backend/src/modules/downloads/downloads.repository.ts b/apps/backend/src/modules/downloads/downloads.repository.ts
index 743c86a..74f6c49 100644
--- a/apps/backend/src/modules/downloads/downloads.repository.ts
+++ b/apps/backend/src/modules/downloads/downloads.repository.ts
@@ -1,6 +1,7 @@
 import type { AppDatabase } from '../../database/connection'
 import type { DownloadRow, DownloadStatus, ExpectedBytesSource, NewDownloadRow } from '../../database/schema'
 import type { Release } from '../../lib/release'
+import type { ManualImportTarget } from '../../lib/servers/arr/base'
 import { desc, eq, sql } from 'drizzle-orm'
 import { downloads } from '../../database/schema'
 
@@ -27,6 +28,8 @@ export interface DownloadRecord {
   error: string | null
   qbCategory: string | null
   qbSourceServer: string | null
+  importMode: 'jack_manual' | null
+  importTarget: ManualImportTarget | null
 }
 
 export interface CreateDownloadInput {
@@ -41,6 +44,8 @@ export interface CreateDownloadInput {
   release: Release
   qbCategory?: string | null
   qbSourceServer?: string | null
+  importMode?: 'jack_manual' | null
+  importTarget?: ManualImportTarget | null
 }
 
 function nowIso() {
@@ -71,6 +76,8 @@ function toRecord(row: DownloadRow): DownloadRecord {
     error: row.error,
     qbCategory: row.qbCategory ?? null,
     qbSourceServer: row.qbSourceServer ?? null,
+    importMode: row.importMode ?? null,
+    importTarget: row.importTarget ? (JSON.parse(row.importTarget) as ManualImportTarget) : null,
   }
 }
 
@@ -91,6 +98,8 @@ export class DownloadsRepository {
       releaseJson: JSON.stringify(input.release),
       qbCategory: input.qbCategory ?? null,
       qbSourceServer: input.qbSourceServer ?? null,
+      importMode: input.importMode ?? null,
+      importTarget: input.importTarget ? JSON.stringify(input.importTarget) : null,
       downloadedBytes: 0,
       status: 'downloading',
       startedAt: timestamp,
diff --git a/apps/backend/src/modules/downloads/downloads.service.ts b/apps/backend/src/modules/downloads/downloads.service.ts
index 0e6839c..6ccbc08 100644
--- a/apps/backend/src/modules/downloads/downloads.service.ts
+++ b/apps/backend/src/modules/downloads/downloads.service.ts
@@ -1,5 +1,6 @@
 import type { AppConfig } from '../../lib/config'
 import type { ConnectorManager } from '../../lib/servers'
+import type { ManualImportTarget } from '../../lib/servers/arr/base'
 import type { PeerDownloadProgressEvent } from '../../lib/servers/peer'
 import type { DownloadRecord, DownloadsRepository } from './downloads.repository'
 import { basename, join } from 'node:path'
@@ -59,6 +60,8 @@ export class DownloadsService {
     torrentFilename: string
     qbCategory?: string | null
     qbSourceServer?: string | null
+    importMode?: 'jack_manual' | null
+    importTarget?: ManualImportTarget | null
   }): Promise<CreateDownloadOutcome> {
     const { peerId, itemId, torrentFilename } = input
     const peer = this.peers.find(p => p.id === peerId)
@@ -99,6 +102,8 @@ export class DownloadsService {
       release,
       qbCategory: input.qbCategory ?? null,
       qbSourceServer: input.qbSourceServer ?? null,
+      importMode: input.importMode ?? null,
+      importTarget: input.importTarget ?? null,
     })
 
     return {
@@ -126,6 +131,8 @@ export class DownloadsService {
         error: null,
         qbCategory: input.qbCategory ?? null,
         qbSourceServer: input.qbSourceServer ?? null,
+        importMode: input.importMode ?? null,
+        importTarget: input.importTarget ?? null,
       },
     }
   }
@@ -164,6 +171,45 @@ export class DownloadsService {
     return 'started'
   }
 
+  /**
+   * Catalog direct-download entrypoint: create a jack_manual row bound to a
+   * destination *arr + import target, then drive the download in the background.
+   * Import is pushed later by the ImportWatcher.
+   */
+  async startDirectDownload(input: {
+    peerId: string
+    itemId: string
+    destinationServerName: string
+    importTarget: ManualImportTarget
+  }): Promise<StartQbDownloadResult> {
+    const torrentFilename = `direct-${input.peerId}-${input.itemId}.torrent`.replace(UNSAFE_FILENAME_CHARS, '_')
+    let outcome: CreateDownloadOutcome
+    try {
+      outcome = await this.createDownload({
+        peerId: input.peerId,
+        itemId: input.itemId,
+        torrentFilename,
+        qbSourceServer: input.destinationServerName,
+        importMode: 'jack_manual',
+        importTarget: input.importTarget,
+      })
+    }
+    catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      logger.error({ peerId: input.peerId, itemId: input.itemId, error: message }, 'Failed to create direct download')
+      return 'failed'
+    }
+    if (outcome.kind === 'no-peer')
+      return 'failed'
+    if (outcome.kind === 'duplicate')
+      return 'duplicate'
+    void this.runDownload(outcome.record).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err)
+      logger.error({ itemId: input.itemId, error: message }, 'Direct download failed')
+    })
+    return 'started'
+  }
+
   /** Re-drive stale `downloading` rows from a prior run, resuming from their .part files. */
   async resumeStaleDownloads(): Promise<number> {
     const repo = this.downloadsRepository
diff --git a/apps/backend/src/modules/downloads/import-watcher.ts b/apps/backend/src/modules/downloads/import-watcher.ts
index bec7214..fababf2 100644
--- a/apps/backend/src/modules/downloads/import-watcher.ts
+++ b/apps/backend/src/modules/downloads/import-watcher.ts
@@ -1,5 +1,6 @@
 import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { DownloadsRepository } from './downloads.repository'
+import { dirname } from 'node:path'
 import { logger } from '../../logger'
 import { deriveHash } from '../qbittorrent/qbittorrent.mapper'
 
@@ -13,6 +14,13 @@ import { deriveHash } from '../qbittorrent/qbittorrent.mapper'
  */
 export class ImportWatcher {
   private timer?: ReturnType<typeof setInterval>
+  // Rows we've already pushed a ManualImport for this process (avoids re-POSTing
+  // every tick). Only added on a SUCCESSFUL push (inside the try, after the await),
+  // so a failed trigger is retried next tick. A restart clears the set; re-triggering
+  // is safe — *arr ignores a ManualImport whose file no longer exists at `path`
+  // (already moved/imported), and the row only leaves `import_queued` once the
+  // history hash confirms the import.
+  private readonly manualImportTriggered = new Set<number>()
 
   constructor(
     private readonly repository: DownloadsRepository,
@@ -75,11 +83,28 @@ export class ImportWatcher {
 
       for (const row of rows) {
         const hash = deriveHash(row.release.title, row.releaseSize).toLowerCase()
-        if (!importedIds.has(hash))
+        if (importedIds.has(hash)) {
+          this.repository.markImported(row.id)
+          importedCount++
+          logger.info({ id: row.id, filename: row.filename, server: serverName }, 'Download imported by *arr')
           continue
-        this.repository.markImported(row.id)
-        importedCount++
-        logger.info({ id: row.id, filename: row.filename, server: serverName }, 'Download imported by *arr')
+        }
+        if (row.importMode === 'jack_manual' && row.importTarget && !this.manualImportTriggered.has(row.id)) {
+          try {
+            await connector.manualImport({
+              folder: dirname(row.destPath),
+              paths: [row.destPath],
+              target: row.importTarget,
+              downloadId: deriveHash(row.release.title, row.releaseSize),
+            })
+            this.manualImportTriggered.add(row.id)
+            logger.info({ id: row.id, filename: row.filename, server: serverName }, 'Triggered *arr manual import')
+          }
+          catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            logger.warn({ id: row.id, server: serverName, error: message }, 'Manual import trigger failed; will retry next tick')
+          }
+        }
       }
     }
     return importedCount
diff --git a/apps/ui/app/components/DownloadRequestModal.vue b/apps/ui/app/components/DownloadRequestModal.vue
index ce4728a..a9434ed 100644
--- a/apps/ui/app/components/DownloadRequestModal.vue
+++ b/apps/ui/app/components/DownloadRequestModal.vue
@@ -69,10 +69,6 @@ function onConfirm() {
           />
         </UFormField>
 
-        <p class="text-sm text-muted">
-          Jack downloads use a dedicated profile so *arr only grabs this release from Jack.
-        </p>
-
         <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" :title="error" />
       </div>
     </template>
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index 415354d..d301a98 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -58,6 +58,7 @@ async function onConfirm(payload: CatalogRequestPayload) {
       method: 'POST',
       body: {
         ...payload,
+        peerId: peerId.value,
         mediaType: title.mediaType,
         tmdbId: title.tmdbId,
         tvdbId: title.tvdbId,
@@ -67,7 +68,7 @@ async function onConfirm(payload: CatalogRequestPayload) {
     selected.value = null
     toast.add({
       title: 'Added to your library',
-      description: `"${titleName(title)}" is being searched by your *arr.`,
+      description: `"${titleName(title)}" is downloading from ${peerName.value}.`,
       color: 'success',
       icon: 'i-ph-check-circle',
     })

From 35e0aa0dde73333332f2abf4f2cb126c97dd6005 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 14:26:55 +0200
Subject: [PATCH 11/27] feat(catalog): direct-download whole TV series per
 episode

Add the series branch to requestDownload: add the series without search,
pick the best release per episode (pickBestPerEpisode), and start a direct
download per episode tagged import_target {kind:'series',seriesId}; the
ImportWatcher pushes ManualImport with the candidate episodeIds. Adds a
TV-only 'downloads every episode' hint in the catalog detail UI.
---
 apps/backend/src/__tests__/catalog.test.ts    | 59 ++++++++++++++++++-
 .../src/modules/catalog/catalog.controller.ts | 57 ++++++++++++------
 apps/ui/app/components/CatalogTitleDetail.vue |  3 +
 3 files changed, 97 insertions(+), 22 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index db21da1..ccd7271 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -321,11 +321,15 @@ describe('catalogController.requestDownload', () => {
     }
   }
 
-  function fakePeer(overrides: Partial<{ searchByTmdbId: (tmdbId: string) => Promise<Release[]> }> = {}) {
+  function fakePeer(overrides: Partial<{
+    searchByTmdbId: (tmdbId: string) => Promise<Release[]>
+    searchByTvdbId: (tvdbId: string) => Promise<Release[]>
+  }> = {}) {
     return {
       id: 'peer-1',
       name: 'Friend Jack',
       searchByTmdbId: overrides.searchByTmdbId ?? mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]),
+      searchByTvdbId: overrides.searchByTvdbId ?? mock(async () => [episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 } })]),
     }
   }
 
@@ -390,7 +394,7 @@ describe('catalogController.requestDownload', () => {
     })).rejects.toBeInstanceOf(BadRequestError)
   })
 
-  test('throws BadRequestError for a tv request (not supported until Phase 2)', () => {
+  test('throws BadRequestError when a tv request has no tvdbId', () => {
     const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr' })
     const controller = new CatalogController(makeConnectors([sonarr], [fakePeer()]) as any, undefined, fakeDownloads() as any)
 
@@ -398,7 +402,6 @@ describe('catalogController.requestDownload', () => {
       peerId: 'peer-1',
       serverId: 'sonarr-1',
       mediaType: 'tv',
-      tvdbId: 81189,
       rootFolderPath: '/tv',
     })).rejects.toBeInstanceOf(BadRequestError)
   })
@@ -443,6 +446,56 @@ describe('catalogController.requestDownload', () => {
       importTarget: { kind: 'movie', movieId: 123 },
     })
   })
+
+  test('throws NotFoundError when the peer has no episodes for the tvdbId, and does not add', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => []) })
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]) as any, undefined, fakeDownloads() as any)
+
+    await expect(controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })).rejects.toBeInstanceOf(NotFoundError)
+    expect(sonarr.add).not.toHaveBeenCalled()
+  })
+
+  test('adds the series without search and starts a direct download for the best release per episode', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const ep1a = episode({ id: 'ep:1a', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 720 }, size: 50 })
+    const ep1b = episode({ id: 'ep:1b', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
+    const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1a, ep1b, ep2]) })
+    const downloads = fakeDownloads()
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]) as any, undefined, downloads as any)
+
+    const result = await controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Sonarr', started: 2 })
+    expect(sonarr.add).toHaveBeenCalledTimes(1)
+    expect(sonarr.add).toHaveBeenCalledWith({ tvdbId: 81189, rootFolderPath: '/tv' })
+    expect(downloads.startDirectDownload).toHaveBeenCalledTimes(2)
+    expect(downloads.startDirectDownload).toHaveBeenCalledWith({
+      peerId: 'peer-1',
+      itemId: 'ep:1b',
+      destinationServerName: 'My Sonarr',
+      importTarget: { kind: 'series', seriesId: 55 },
+    })
+    expect(downloads.startDirectDownload).toHaveBeenCalledWith({
+      peerId: 'peer-1',
+      itemId: 'ep:2',
+      destinationServerName: 'My Sonarr',
+      importTarget: { kind: 'series', seriesId: 55 },
+    })
+  })
 })
 
 describe('catalogController.getTmdbStatus', () => {
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index 18eb4fa..9ec5ab1 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -5,7 +5,7 @@ import type { DownloadsService } from '../downloads/downloads.service'
 import type { CatalogTitle } from './catalog.lib'
 import { BadRequestError } from '../../lib/errors/BadRequestError'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
-import { groupReleasesIntoTitles, pickBestRelease } from './catalog.lib'
+import { groupReleasesIntoTitles, pickBestPerEpisode, pickBestRelease } from './catalog.lib'
 
 export interface PeerCatalogResponse {
   peer: { id: string, name: string }
@@ -106,24 +106,43 @@ export class CatalogController {
 
     const peer = this.requirePeer(input.peerId)
 
-    if (input.mediaType !== 'movie')
-      throw new BadRequestError('TV requests are not supported yet') // implemented in Phase 2
-
-    if (input.tmdbId == null)
-      throw new BadRequestError('A tmdbId is required for a movie request')
-    const releases = await peer.searchByTmdbId(String(input.tmdbId))
-    const best = pickBestRelease(releases)
-    if (!best)
-      throw new NotFoundError(`Peer "${peer.name}" has no release for tmdbId ${input.tmdbId}`)
-
-    const movieId = await server.add({ tmdbId: input.tmdbId, rootFolderPath: input.rootFolderPath })
-    await this.downloads.startDirectDownload({
-      peerId: peer.id,
-      itemId: best.id,
-      destinationServerName: server.name,
-      importTarget: { kind: 'movie', movieId },
-    })
-    return { ok: true, server: server.name, started: 1 }
+    if (input.mediaType === 'movie') {
+      if (input.tmdbId == null)
+        throw new BadRequestError('A tmdbId is required for a movie request')
+      const releases = await peer.searchByTmdbId(String(input.tmdbId))
+      const best = pickBestRelease(releases)
+      if (!best)
+        throw new NotFoundError(`Peer "${peer.name}" has no release for tmdbId ${input.tmdbId}`)
+
+      const movieId = await server.add({ tmdbId: input.tmdbId, rootFolderPath: input.rootFolderPath })
+      await this.downloads.startDirectDownload({
+        peerId: peer.id,
+        itemId: best.id,
+        destinationServerName: server.name,
+        importTarget: { kind: 'movie', movieId },
+      })
+      return { ok: true, server: server.name, started: 1 }
+    }
+
+    // --- series (tv): one direct download per best-per-episode release, all bound
+    // to the same series so the watcher imports each file into the right show. ---
+    if (input.tvdbId == null)
+      throw new BadRequestError('A tvdbId is required for a series request')
+    const episodeReleases = await peer.searchByTvdbId(String(input.tvdbId))
+    const best = pickBestPerEpisode(episodeReleases)
+    if (best.length === 0)
+      throw new NotFoundError(`Peer "${peer.name}" has no episodes for tvdbId ${input.tvdbId}`)
+
+    const seriesId = await server.add({ tvdbId: input.tvdbId, rootFolderPath: input.rootFolderPath })
+    for (const release of best) {
+      await this.downloads.startDirectDownload({
+        peerId: peer.id,
+        itemId: release.id,
+        destinationServerName: server.name,
+        importTarget: { kind: 'series', seriesId },
+      })
+    }
+    return { ok: true, server: server.name, started: best.length }
   }
 
   async getTmdbStatus(): Promise<TmdbStatus> {
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index bec75aa..e768913 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -46,6 +46,9 @@ const canRequest = computed(() => props.title.mediaType === 'tv'
     <p class="text-xs text-muted">
       {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} on this peer · {{ formatBytes(title.totalSize) }}
     </p>
+    <p v-if="title.mediaType === 'tv'" class="text-xs text-muted">
+      Downloads every available episode from this peer.
+    </p>
 
     <UTooltip :disabled="canRequest" text="This title has no matching id to request">
       <UButton

From 4bd51f8935a1c052199e96c80b816ccd3c41566d Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 14:33:58 +0200
Subject: [PATCH 12/27] refactor(arr): drop the now-dead Jack custom format and
 quality profile

requestDownload no longer forces a Jack-only quality profile (it uses
direct download + ManualImport), so ensureJackCustomFormat /
ensureJackQualityProfile, their autoregister provisioning branch, the
CreatedResourceId schema, the ManagedRegistrationMeta.profileId field, and
the corresponding dead tests are removed. The torznab Internal-flag tagging
(tag=internal) and the indexer/download-client registration are untouched.
---
 .../backend/src/__tests__/integration.test.ts | 143 ------------------
 apps/backend/src/index.ts                     |   4 -
 apps/backend/src/lib/autoregister.test.ts     |  30 +---
 apps/backend/src/lib/autoregister.ts          |  16 +-
 apps/backend/src/lib/servers/arr/base.ts      | 101 -------------
 5 files changed, 4 insertions(+), 290 deletions(-)

diff --git a/apps/backend/src/__tests__/integration.test.ts b/apps/backend/src/__tests__/integration.test.ts
index a3190e9..40acf77 100644
--- a/apps/backend/src/__tests__/integration.test.ts
+++ b/apps/backend/src/__tests__/integration.test.ts
@@ -558,149 +558,6 @@ describe('Auto-registration', () => {
   })
 })
 
-describe('ensureJackCustomFormat', () => {
-  test('Radarr: POSTs a "Jack" custom format matching the Internal flag (value 32)', async () => {
-    let postBody: any = null
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
-      http.post(`${RADARR_URL}/api/v3/customformat`, async ({ request }) => {
-        postBody = await request.json()
-        return HttpResponse.json({ id: 11, name: 'Jack' })
-      }),
-    )
-
-    const radarr = markInitialized(makeRadarr())
-    const id = await radarr.ensureJackCustomFormat()
-
-    expect(id).toBe(11)
-    expect(postBody).toMatchObject({ name: 'Jack', includeCustomFormatWhenRenaming: false })
-    expect(postBody.specifications).toHaveLength(1)
-    expect(postBody.specifications[0]).toMatchObject({
-      name: 'Internal',
-      implementation: 'IndexerFlagSpecification',
-      negate: false,
-      required: true,
-    })
-    expect(postBody.specifications[0].fields).toEqual([{ name: 'value', value: 32 }])
-  })
-
-  test('Sonarr: uses the Internal flag value 8', async () => {
-    let postBody: any = null
-    server.use(
-      http.get(`${SONARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
-      http.post(`${SONARR_URL}/api/v3/customformat`, async ({ request }) => {
-        postBody = await request.json()
-        return HttpResponse.json({ id: 5, name: 'Jack' })
-      }),
-    )
-
-    const sonarr = markInitialized(makeSonarr())
-    const id = await sonarr.ensureJackCustomFormat()
-
-    expect(id).toBe(5)
-    expect(postBody.specifications[0].fields).toEqual([{ name: 'value', value: 8 }])
-  })
-
-  test('upserts an existing "Jack" custom format with a PUT to /{id}', async () => {
-    let putBody: any = null
-    let posted = false
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([{ id: 9, name: 'Jack' }])),
-      http.post(`${RADARR_URL}/api/v3/customformat`, () => {
-        posted = true
-        return HttpResponse.json({ id: 9, name: 'Jack' })
-      }),
-      http.put(`${RADARR_URL}/api/v3/customformat/9`, async ({ request }) => {
-        putBody = await request.json()
-        return HttpResponse.json({ id: 9, name: 'Jack' })
-      }),
-    )
-
-    const radarr = markInitialized(makeRadarr())
-    const id = await radarr.ensureJackCustomFormat()
-
-    expect(id).toBe(9)
-    expect(posted).toBe(false)
-    expect(putBody).toMatchObject({ id: 9, name: 'Jack' })
-  })
-})
-
-describe('ensureJackQualityProfile', () => {
-  const schemaTemplate = {
-    name: '',
-    upgradeAllowed: false,
-    cutoff: 1,
-    minFormatScore: 0,
-    cutoffFormatScore: 0,
-    items: [
-      { quality: { id: 1, name: 'SDTV' }, allowed: false },
-      { name: 'HD', allowed: false, items: [{ quality: { id: 2, name: 'WEBDL-1080p' }, allowed: false }] },
-    ],
-    formatItems: [
-      { format: 11, name: 'Jack', score: 0 },
-      { format: 12, name: 'Other', score: 0 },
-    ],
-  }
-
-  test('Radarr: ensures the CF then POSTs a "Jack" profile that only scores the Jack flag', async () => {
-    let postBody: any = null
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([])),
-      http.post(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json({ id: 11, name: 'Jack' })),
-      http.get(`${RADARR_URL}/api/v3/qualityprofile/schema`, () => HttpResponse.json(schemaTemplate)),
-      http.get(`${RADARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([])),
-      http.post(`${RADARR_URL}/api/v3/qualityprofile`, async ({ request }) => {
-        postBody = await request.json()
-        return HttpResponse.json({ id: 77, name: 'Jack' })
-      }),
-    )
-
-    const radarr = markInitialized(makeRadarr())
-    const id = await radarr.ensureJackQualityProfile()
-
-    expect(id).toBe(77)
-    expect(postBody).toMatchObject({
-      name: 'Jack',
-      upgradeAllowed: false,
-      minFormatScore: 1,
-      cutoffFormatScore: 1,
-    })
-    // All qualities allowed — recursively, including the nested group.
-    expect(postBody.items[0].allowed).toBe(true)
-    expect(postBody.items[1].allowed).toBe(true)
-    expect(postBody.items[1].items[0].allowed).toBe(true)
-    // Only the Jack format is scored 1; others stay at 0.
-    expect(postBody.formatItems.find((f: any) => f.name === 'Jack').score).toBe(1)
-    expect(postBody.formatItems.find((f: any) => f.name === 'Other').score).toBe(0)
-  })
-
-  test('upserts an existing "Jack" profile with a PUT to /{id}', async () => {
-    let putBody: any = null
-    let posted = false
-    server.use(
-      http.get(`${RADARR_URL}/api/v3/customformat`, () => HttpResponse.json([{ id: 11, name: 'Jack' }])),
-      http.put(`${RADARR_URL}/api/v3/customformat/11`, () => HttpResponse.json({ id: 11, name: 'Jack' })),
-      http.get(`${RADARR_URL}/api/v3/qualityprofile/schema`, () => HttpResponse.json(schemaTemplate)),
-      http.get(`${RADARR_URL}/api/v3/qualityprofile`, () => HttpResponse.json([{ id: 42, name: 'Jack' }])),
-      http.post(`${RADARR_URL}/api/v3/qualityprofile`, () => {
-        posted = true
-        return HttpResponse.json({ id: 42, name: 'Jack' })
-      }),
-      http.put(`${RADARR_URL}/api/v3/qualityprofile/42`, async ({ request }) => {
-        putBody = await request.json()
-        return HttpResponse.json({ id: 42, name: 'Jack' })
-      }),
-    )
-
-    const radarr = markInitialized(makeRadarr())
-    const id = await radarr.ensureJackQualityProfile()
-
-    expect(id).toBe(42)
-    expect(posted).toBe(false)
-    expect(putBody).toMatchObject({ id: 42, name: 'Jack', minFormatScore: 1 })
-  })
-})
-
 describe('Routes mount without peers or sources', () => {
   function createBareApp() {
     return getApp(envs, config, { servers: [], peers: [] })
diff --git a/apps/backend/src/index.ts b/apps/backend/src/index.ts
index a476dd2..4bd272c 100644
--- a/apps/backend/src/index.ts
+++ b/apps/backend/src/index.ts
@@ -119,10 +119,6 @@ for (const dest of registrable) {
         logger.info({ destination: name, downloadClientId: meta.downloadClientId }, 'Registered Jack as qBittorrent download client')
         return
       }
-      if (kind === 'quality profile') {
-        logger.info({ destination: name, profileId: meta.profileId }, 'Registered Jack-only quality profile')
-        return
-      }
       logger.info({ destination: name, categories: meta.categories, downloadClientId: meta.downloadClientId }, 'Registered Jack as Torznab indexer')
     },
     onFailure: logRegistrationFailure,
diff --git a/apps/backend/src/lib/autoregister.test.ts b/apps/backend/src/lib/autoregister.test.ts
index 79ef47b..377a513 100644
--- a/apps/backend/src/lib/autoregister.test.ts
+++ b/apps/backend/src/lib/autoregister.test.ts
@@ -1,7 +1,7 @@
 import type { ManagedRegistrationDeps } from './autoregister'
 import type { ArrServerConnector } from './servers/arr/base'
 import { Database } from 'bun:sqlite'
-import { beforeEach, describe, expect, mock, test } from 'bun:test'
+import { beforeEach, describe, expect, test } from 'bun:test'
 import { drizzle } from 'drizzle-orm/bun-sqlite'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
@@ -21,7 +21,7 @@ describe('registerManagedForDestination', () => {
     service = new ManagedApiKeys(repo)
   })
 
-  function stubDest(over: Partial<{ registerIndexer: () => Promise<void>, registerDownloadClient: () => Promise<number>, ensureJackQualityProfile: () => Promise<number> }> = {}): ArrServerConnector {
+  function stubDest(over: Partial<{ registerIndexer: () => Promise<void>, registerDownloadClient: () => Promise<number> }> = {}): ArrServerConnector {
     return {
       id: 'srv-a',
       name: 'Radarr',
@@ -29,7 +29,6 @@ describe('registerManagedForDestination', () => {
       autoRegister: { enable: true, priority: 1 },
       registerDownloadClient: over.registerDownloadClient ?? (async () => 1),
       registerIndexer: over.registerIndexer ?? (async () => {}),
-      ensureJackQualityProfile: over.ensureJackQualityProfile ?? (async () => 99),
     } as unknown as ArrServerConnector
   }
 
@@ -94,29 +93,4 @@ describe('registerManagedForDestination', () => {
     )
     expect(repo.findByServerId('srv-a').map(r => r.id)).toEqual([old.id])
   })
-
-  test('registers the Jack quality profile and reports it via onSuccess', async () => {
-    const profileCall = mock(async () => 77)
-    const successes: Array<[string, number | undefined]> = []
-    await registerManagedForDestination(
-      stubDest({ ensureJackQualityProfile: profileCall }),
-      { ...deps(), onSuccess: (kind, _name, meta) => successes.push([kind, meta.profileId]) },
-    )
-    expect(profileCall).toHaveBeenCalledTimes(1)
-    expect(successes).toContainEqual(['quality profile', 77])
-  })
-
-  test('a failing quality-profile registration does not gate the managed-key commit', async () => {
-    const old = service.provision('srv-a')
-    const failures: string[] = []
-    await registerManagedForDestination(
-      stubDest({ ensureJackQualityProfile: async () => { throw new Error('qp') } }),
-      { ...deps(), onFailure: kind => failures.push(kind) },
-    )
-    // Download client + indexer both succeeded → still a full commit despite the profile failing.
-    const rows = repo.findByServerId('srv-a')
-    expect(rows).toHaveLength(1)
-    expect(rows[0]!.id).not.toBe(old.id)
-    expect(failures).toContain('quality profile')
-  })
 })
diff --git a/apps/backend/src/lib/autoregister.ts b/apps/backend/src/lib/autoregister.ts
index a0310ce..28987f0 100644
--- a/apps/backend/src/lib/autoregister.ts
+++ b/apps/backend/src/lib/autoregister.ts
@@ -4,7 +4,6 @@ import type { ArrServerConnector } from './servers/arr/base'
 export interface ManagedRegistrationMeta {
   downloadClientId?: number
   categories?: number[]
-  profileId?: number
 }
 
 export interface ManagedRegistrationDeps {
@@ -12,8 +11,8 @@ export interface ManagedRegistrationDeps {
   internalUrl: string
   downloads: boolean
   category: string
-  onSuccess: (kind: 'download client' | 'indexer' | 'quality profile', name: string, meta: ManagedRegistrationMeta) => void
-  onFailure: (kind: 'download client' | 'indexer' | 'quality profile', name: string, err: unknown) => void
+  onSuccess: (kind: 'download client' | 'indexer', name: string, meta: ManagedRegistrationMeta) => void
+  onFailure: (kind: 'download client' | 'indexer', name: string, err: unknown) => void
 }
 
 /**
@@ -67,17 +66,6 @@ export async function registerManagedForDestination(
     deps.onFailure('indexer', dest.name, err)
   }
 
-  // Best-effort: register the Jack-only custom format + quality profile so *arr
-  // won't grab a catalog title from a non-Jack indexer. Independent of the
-  // download client/indexer; its failure must not gate the managed-key commit.
-  try {
-    const profileId = await dest.ensureJackQualityProfile()
-    deps.onSuccess('quality profile', dest.name, { profileId })
-  }
-  catch (err) {
-    deps.onFailure('quality profile', dest.name, err)
-  }
-
   // "Attempted" download = only when downloads is enabled. The indexer is always attempted.
   const allAttemptedOk = (downloads ? downloadDelivered : true) && indexerDelivered
   const anyDelivered = downloadDelivered || indexerDelivered
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index b11cd29..1247fd5 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -34,10 +34,6 @@ export const DestinationServerHealthIssue = z.array(
 // the auto-registered indexer to it.
 const DownloadClientResource = z.object({ id: z.number().int() })
 
-// *arr returns the saved custom format / quality profile on create; we only need
-// its id (to score the format and to force the profile on catalog downloads).
-const CreatedResourceId = z.object({ id: z.number().int() })
-
 // Register the Jack client at *arr's lowest selectable priority (the UI caps it
 // at 50). *arr's general client pool only round-robins among the best-priority
 // group, so a worst-priority Jack client is never picked for real torrents from
@@ -199,103 +195,6 @@ export abstract class ArrServerConnector extends ServerConnector {
     return this.fetch('/api/v3/health', { schema: z.array(DestinationServerHealthIssue) })
   }
 
-  /**
-   * Upsert a custom format named "Jack" that matches *arr's Internal indexer flag
-   * (which jack emits as `tag=internal` on its Torznab items). Returns the format id.
-   */
-  @requiresDestination
-  @requiresInitialization
-  async ensureJackCustomFormat(): Promise<number> {
-    const existingFormats = await this.arrGet<any[]>('/api/v3/customformat')
-    const existing: any = Array.isArray(existingFormats)
-      ? existingFormats.find((cf: any) => cf.name === 'Jack')
-      : null
-
-    const body = {
-      name: 'Jack',
-      includeCustomFormatWhenRenaming: false,
-      specifications: [{
-        name: 'Internal',
-        implementation: 'IndexerFlagSpecification',
-        negate: false,
-        required: true,
-        fields: [{ name: 'value', value: this.internalIndexerFlagValue }],
-      }],
-    }
-
-    if (existing) {
-      await this.fetch(`/api/v3/customformat/${existing.id}`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ ...body, id: existing.id }),
-      } as any)
-      return existing.id as number
-    }
-
-    const created = await this.fetch<typeof CreatedResourceId>('/api/v3/customformat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-      schema: CreatedResourceId,
-    } as any)
-    return created.id
-  }
-
-  /**
-   * Ensure the Jack custom format exists, then upsert a quality profile named
-   * "Jack" that accepts every quality but only scores the Jack flag (minFormatScore
-   * 1), so *arr won't grab a matching release from a non-Jack indexer. Returns the
-   * profile id.
-   */
-  @requiresDestination
-  @requiresInitialization
-  async ensureJackQualityProfile(): Promise<number> {
-    const cfId = await this.ensureJackCustomFormat()
-    const schema = await this.arrGet<any>('/api/v3/qualityprofile/schema')
-
-    // Each item may itself nest an `items` array (quality groups); allow at every level.
-    const allowAll = (items: any[]): any[] =>
-      items.map((item: any) => ({
-        ...item,
-        allowed: true,
-        ...(Array.isArray(item.items) ? { items: allowAll(item.items) } : {}),
-      }))
-
-    const profile = {
-      ...schema,
-      name: 'Jack',
-      // Grab the peer's file once and stop — no chasing "better" Jack releases.
-      upgradeAllowed: false,
-      items: allowAll(Array.isArray(schema?.items) ? schema.items : []),
-      minFormatScore: 1,
-      cutoffFormatScore: 1,
-      formatItems: (Array.isArray(schema?.formatItems) ? schema.formatItems : []).map((fi: any) =>
-        (fi.name === 'Jack' || fi.format === cfId) ? { ...fi, score: 1 } : fi),
-    }
-
-    const existingProfiles = await this.arrGet<any[]>('/api/v3/qualityprofile')
-    const existing: any = Array.isArray(existingProfiles)
-      ? existingProfiles.find((p: any) => p.name === 'Jack')
-      : null
-
-    if (existing) {
-      await this.fetch(`/api/v3/qualityprofile/${existing.id}`, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ ...profile, id: existing.id }),
-      } as any)
-      return existing.id as number
-    }
-
-    const created = await this.fetch<typeof CreatedResourceId>('/api/v3/qualityprofile', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(profile),
-      schema: CreatedResourceId,
-    } as any)
-    return created.id
-  }
-
   @requiresDestination
   @requiresInitialization
   async getRootFolders(): Promise<Array<{ path: string, freeSpace?: number }>> {

From 79e673b51b4d8abe0667af678368ab8039398edf Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 14:43:05 +0200
Subject: [PATCH 13/27] fix(catalog): surface failed direct-download starts in
 requestDownload

startDirectDownload returns 'started'|'duplicate'|'failed' but requestDownload
ignored it and always reported success, leaving a title added to *arr with no
jack_manual row. The movie branch now throws on 'failed'; the series branch
counts only non-failed starts, throws when none started, and returns the real
started count instead of best.length.
---
 apps/backend/src/__tests__/catalog.test.ts    | 52 +++++++++++++++++++
 .../src/modules/catalog/catalog.controller.ts | 13 +++--
 2 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index ccd7271..aa45ccc 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -496,6 +496,58 @@ describe('catalogController.requestDownload', () => {
       importTarget: { kind: 'series', seriesId: 55 },
     })
   })
+
+  test('throws BadRequestError when the movie direct download fails to start', async () => {
+    const radarr = fakeServer({ add: mock(async () => 123) })
+    const peer = fakePeer({ searchByTmdbId: mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]) })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'failed') })
+    const controller = new CatalogController(makeConnectors([radarr], [peer]) as any, undefined, downloads as any)
+
+    await expect(controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      rootFolderPath: '/movies',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
+  test('throws BadRequestError when every episode direct download fails to start', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
+    const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2]) })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'failed') })
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]) as any, undefined, downloads as any)
+
+    await expect(controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })).rejects.toBeInstanceOf(BadRequestError)
+  })
+
+  test('counts only non-failed episode starts when some fail', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
+    const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2]) })
+    let calls = 0
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => (calls++ === 0 ? 'started' : 'failed')) })
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]) as any, undefined, downloads as any)
+
+    const result = await controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Sonarr', started: 1 })
+  })
 })
 
 describe('catalogController.getTmdbStatus', () => {
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index 9ec5ab1..a5291ac 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -115,12 +115,14 @@ export class CatalogController {
         throw new NotFoundError(`Peer "${peer.name}" has no release for tmdbId ${input.tmdbId}`)
 
       const movieId = await server.add({ tmdbId: input.tmdbId, rootFolderPath: input.rootFolderPath })
-      await this.downloads.startDirectDownload({
+      const result = await this.downloads.startDirectDownload({
         peerId: peer.id,
         itemId: best.id,
         destinationServerName: server.name,
         importTarget: { kind: 'movie', movieId },
       })
+      if (result === 'failed')
+        throw new BadRequestError(`Failed to start the download for tmdbId ${input.tmdbId} from peer "${peer.name}"`)
       return { ok: true, server: server.name, started: 1 }
     }
 
@@ -134,15 +136,20 @@ export class CatalogController {
       throw new NotFoundError(`Peer "${peer.name}" has no episodes for tvdbId ${input.tvdbId}`)
 
     const seriesId = await server.add({ tvdbId: input.tvdbId, rootFolderPath: input.rootFolderPath })
+    let started = 0
     for (const release of best) {
-      await this.downloads.startDirectDownload({
+      const result = await this.downloads.startDirectDownload({
         peerId: peer.id,
         itemId: release.id,
         destinationServerName: server.name,
         importTarget: { kind: 'series', seriesId },
       })
+      if (result !== 'failed')
+        started++
     }
-    return { ok: true, server: server.name, started: best.length }
+    if (started === 0)
+      throw new BadRequestError(`Failed to start any episode download for tvdbId ${input.tvdbId} from peer "${peer.name}"`)
+    return { ok: true, server: server.name, started }
   }
 
   async getTmdbStatus(): Promise<TmdbStatus> {

From f5fe87f6e34548ab1871408e77bc7d758ed79641 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 15:37:51 +0200
Subject: [PATCH 14/27] feat(ui): added image fallback for TMDB poster cards

- Implement useFallbackImage composable that cycles through sources when TMDB requests fail under load.
- Refactor CatalogPosterCard with three-state status machine for clearer metadata enrichment and error handling.
- Add lazy-loading via IntersectionObserver to defer metadata fetches until cards approach viewport.
- Remove inline metadata fetching from catalog page in favor of observer-driven lazy pattern.
- Add TMDB API v3 reference documenting authentication, endpoints, and image handling best practices.
---
 .agents/skills/tmdb-api/SKILL.md              | 347 ++++++++++++++++++
 apps/ui/app/components/CatalogPosterCard.vue  |  71 +++-
 apps/ui/app/components/CatalogTitleDetail.vue |  11 +-
 apps/ui/app/composables/useFallbackImage.ts   |  31 ++
 apps/ui/app/pages/catalog/[peerId].vue        |  35 +-
 skills-lock.json                              |  11 +
 6 files changed, 468 insertions(+), 38 deletions(-)
 create mode 100644 .agents/skills/tmdb-api/SKILL.md
 create mode 100644 apps/ui/app/composables/useFallbackImage.ts
 create mode 100644 skills-lock.json

diff --git a/.agents/skills/tmdb-api/SKILL.md b/.agents/skills/tmdb-api/SKILL.md
new file mode 100644
index 0000000..f1e1bda
--- /dev/null
+++ b/.agents/skills/tmdb-api/SKILL.md
@@ -0,0 +1,347 @@
+---
+name: tmdb-api
+description: Use when working with The Movie Database (TMDB) API v3 — fetching movie, TV series, season, episode, or person data; building search or discovery features; handling authentication, ratings, watchlists, or watch providers; using append_to_response to batch requests; or understanding which endpoints exist and what parameters they accept.
+---
+
+# TMDB API v3
+
+TMDB's REST API is versioned at `/3/`. All endpoints require `?api_key=YOUR_KEY` or an `Authorization: Bearer TOKEN` header. Base URL: `https://api.themoviedb.org`.
+
+## Authentication
+
+Three session types exist, each with different write access:
+
+| Type | Creation | Write access |
+|------|----------|--------------|
+| User session | Token → login → session flow | Ratings, watchlist, favorites |
+| Guest session | `GET /3/authentication/guest_session/new` | Ratings only |
+| API key only | None needed | Read-only |
+
+**User session flow:**
+1. `GET /3/authentication/token/new` — get a request token
+2. Redirect user to `https://www.themoviedb.org/authenticate/{request_token}`
+3. `POST /3/authentication/session/new` with `{ "request_token": "..." }` — exchange for session_id
+
+Guest sessions expire after a period of inactivity and cannot access account endpoints.
+
+## Common Parameters
+
+`language` (BCP-47, e.g. `en-US`) applies to most endpoints and affects translated fields like `title`, `overview`, and `tagline`. `page` is 1-based; most paginated endpoints cap at 500 pages.
+
+`append_to_response` accepts a comma-separated list of sub-resources (max 20) and applies **only** to detail endpoints:
+- `GET /3/movie/{movie_id}`
+- `GET /3/tv/{series_id}`
+- `GET /3/tv/{series_id}/season/{season_number}`
+- `GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}`
+- `GET /3/person/{person_id}`
+
+Example: `/3/movie/550?append_to_response=credits,videos,images` returns the movie detail with credits, videos, and images merged into one response, saving two round trips.
+
+## Movies
+
+### Movie Lists
+
+| Endpoint | Description | Extra params |
+|----------|-------------|--------------|
+| `GET /3/movie/popular` | Popularity-ranked | `region` (ISO-3166-1) |
+| `GET /3/movie/top_rated` | Highest rated | `region` |
+| `GET /3/movie/now_playing` | In theatres | `region` |
+| `GET /3/movie/upcoming` | Coming soon | `region` |
+| `GET /3/movie/latest` | Most recently added | — |
+| `GET /3/movie/changes` | Changed movie IDs | `start_date`, `end_date` |
+
+### Movie Detail
+
+`GET /3/movie/{movie_id}` — full metadata including `belongs_to_collection`, `budget`, `revenue`, `runtime`, `release_date`.
+
+### Movie Sub-resources
+
+| Endpoint | Returns |
+|----------|---------|
+| `/3/movie/{id}/credits` | Cast and crew |
+| `/3/movie/{id}/images` | Posters, backdrops, logos |
+| `/3/movie/{id}/videos` | Trailers, clips (YouTube/Vimeo) |
+| `/3/movie/{id}/keywords` | Associated keywords |
+| `/3/movie/{id}/recommendations` | Similar movies TMDB recommends |
+| `/3/movie/{id}/similar` | Same genre/keywords |
+| `/3/movie/{id}/release_dates` | Per-country release dates and certifications |
+| `/3/movie/{id}/watch/providers` | Streaming/rent/buy availability by region |
+| `/3/movie/{id}/alternative_titles` | Title variations by country |
+| `/3/movie/{id}/translations` | Translated metadata |
+| `/3/movie/{id}/reviews` | User reviews |
+| `/3/movie/{id}/lists` | User lists containing this movie |
+| `/3/movie/{id}/account_states` | Auth required — user's rating, watchlist, favorite status |
+| `/3/movie/{id}/rating` | POST/DELETE — add or remove a rating |
+| `/3/movie/{id}/external_ids` | IMDb, Wikidata, Facebook, Instagram, Twitter |
+
+All of the above are also valid values for `append_to_response` on the movie detail endpoint.
+
+### Images
+
+`GET /3/movie/{id}/images` returns three arrays: `backdrops`, `posters`, `logos`. Each image object has `file_path`, `width`, `height`, `vote_average`, and `iso_639_1` (language tag, or `null` for untagged).
+
+To get English images as fallback when querying in another language, add `include_image_language=en,null`. Using only `null` skips English-tagged images, which are often the most abundant.
+
+## TV Series
+
+### TV Lists
+
+| Endpoint | Description | Extra params |
+|----------|-------------|--------------|
+| `GET /3/tv/popular` | Popularity-ranked | — |
+| `GET /3/tv/top_rated` | Highest rated | — |
+| `GET /3/tv/airing_today` | Airing today | `timezone` |
+| `GET /3/tv/on_the_air` | Airing in next 7 days | `timezone` |
+| `GET /3/tv/latest` | Most recently added | — |
+| `GET /3/tv/changes` | Changed series IDs | `start_date`, `end_date` |
+
+TV list endpoints do not accept a `region` parameter (unlike movie lists).
+
+### Series Detail
+
+`GET /3/tv/{series_id}` — includes `number_of_seasons`, `number_of_episodes`, `networks`, `created_by`, `last_air_date`, `next_episode_to_air`, `seasons` (summary array), `type`, and `status`.
+
+### TV Sub-resources
+
+| Endpoint | Returns |
+|----------|---------|
+| `/3/tv/{id}/credits` | Cast/crew for the **latest season only** |
+| `/3/tv/{id}/aggregate_credits` | Cast/crew aggregated across **all seasons** |
+| `/3/tv/{id}/images` | Posters, backdrops, logos |
+| `/3/tv/{id}/videos` | Trailers, clips |
+| `/3/tv/{id}/keywords` | Keywords |
+| `/3/tv/{id}/recommendations` | Recommended series |
+| `/3/tv/{id}/similar` | Similar series |
+| `/3/tv/{id}/content_ratings` | Per-country content ratings (e.g. TV-MA) |
+| `/3/tv/{id}/watch/providers` | Streaming availability by region |
+| `/3/tv/{id}/alternative_titles` | Title variations |
+| `/3/tv/{id}/translations` | Translated metadata |
+| `/3/tv/{id}/reviews` | User reviews |
+| `/3/tv/{id}/external_ids` | IMDb, TVDB, Wikidata, socials |
+| `/3/tv/{id}/account_states` | Auth required — user's rating, watchlist, favorite |
+| `/3/tv/{id}/rating` | POST/DELETE — add or remove a rating |
+| `/3/tv/{id}/episode_groups` | Grouped episode orderings (e.g. DVD order) |
+| `/3/tv/{id}/screened_theatrically` | Episodes that had a theatrical run |
+
+`credits` vs `aggregate_credits`: use `aggregate_credits` when you need the full series cast list. `credits` only covers the latest season, so recurring characters from earlier seasons may be absent.
+
+`aggregate_credits` returns a `roles` array per cast member (one entry per character/season) rather than a flat cast list. Sort client-side by `total_episode_count` to approximate series regulars.
+
+Both `credits` and `aggregate_credits` are valid `append_to_response` values on the series detail endpoint.
+
+### Seasons
+
+`GET /3/tv/{series_id}/season/{season_number}` — full season detail including all episodes.
+
+| Sub-resource | Returns |
+|--------------|---------|
+| `/season/{n}/credits` | Season-level cast/crew |
+| `/season/{n}/aggregate_credits` | Aggregated across the season |
+| `/season/{n}/images` | Season posters |
+| `/season/{n}/videos` | Season trailers |
+| `/season/{n}/translations` | Translated metadata |
+| `/season/{n}/external_ids` | TVDB, TMDB IDs |
+| `/season/{n}/watch/providers` | Season streaming availability |
+
+Season 0 is the specials season when it exists.
+
+### Episodes
+
+`GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number}` — full episode detail.
+
+| Sub-resource | Returns |
+|--------------|---------|
+| `/episode/{n}/credits` | Episode cast/crew (guest stars included) |
+| `/episode/{n}/images` | Still frames |
+| `/episode/{n}/videos` | Clips |
+| `/episode/{n}/translations` | Translated metadata |
+| `/episode/{n}/external_ids` | IMDb, TVDB IDs |
+| `/episode/{n}/rating` | POST/DELETE — episode rating |
+
+## People
+
+`GET /3/person/{person_id}` — biography, birthday, deathday, place of birth, `known_for_department`, `also_known_as`.
+
+| Endpoint | Returns |
+|----------|---------|
+| `/3/person/{id}/movie_credits` | Movies as cast or crew |
+| `/3/person/{id}/tv_credits` | TV series as cast or crew |
+| `/3/person/{id}/combined_credits` | Both, with `media_type` field distinguishing them |
+| `/3/person/{id}/images` | Profile photos |
+| `/3/person/{id}/tagged_images` | Images tagged with this person |
+| `/3/person/{id}/external_ids` | IMDb, TVDB, socials |
+| `/3/person/{id}/translations` | Translated biography |
+| `/3/person/popular` | Popularity-ranked people list |
+| `/3/person/latest` | Most recently added |
+| `/3/person/changes` | Changed person IDs |
+
+All person sub-resources above are valid `append_to_response` values on the person detail endpoint.
+
+## Search
+
+| Endpoint | Searches | Extra params |
+|----------|----------|--------------|
+| `GET /3/search/movie` | Movies | `primary_release_year`, `year`, `region` |
+| `GET /3/search/tv` | TV series | `first_air_date_year`, `year` |
+| `GET /3/search/person` | People | — |
+| `GET /3/search/multi` | Movies, TV, people in one call | — |
+| `GET /3/search/collection` | Movie collections | — |
+| `GET /3/search/company` | Production companies | — |
+| `GET /3/search/keyword` | Keywords | — |
+
+All search endpoints accept `query` (required), `language`, `page`, and `include_adult`.
+
+`/3/search/multi` results include a `media_type` field (`"movie"`, `"tv"`, or `"person"`) to distinguish result types.
+
+## Discover
+
+Discover is a filtered browsing API — not keyword search. Results are sorted and filterable, not relevance-ranked.
+
+### Movie Discover
+
+`GET /3/discover/movie` key parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `sort_by` | `popularity.desc`, `vote_average.desc`, `revenue.desc`, `release_date.desc`, etc. |
+| `with_genres` | Genre IDs — comma = AND, pipe = OR |
+| `with_cast` | Person IDs — comma = AND, pipe = OR |
+| `with_crew` | Person IDs |
+| `with_people` | Cast or crew IDs |
+| `with_companies` | Company IDs |
+| `with_keywords` | Keyword IDs — comma = AND, pipe = OR |
+| `without_genres` | Exclude by genre ID |
+| `without_keywords` | Exclude by keyword ID |
+| `primary_release_year` | Exact year |
+| `primary_release_date.gte` / `.lte` | Date range |
+| `release_date.gte` / `.lte` | Any release type date range |
+| `vote_average.gte` / `.lte` | Score range |
+| `vote_count.gte` / `.lte` | Minimum vote count (use with vote_average filters) |
+| `with_runtime.gte` / `.lte` | Runtime in minutes |
+| `region` | ISO-3166-1 — affects release date filtering |
+| `certification` / `certification_country` | Filter by certification (e.g. R, PG-13) |
+| `with_release_type` | Release type: 1=Premiere, 2=Limited, 3=Theatrical, 4=Digital, 5=Physical, 6=TV |
+| `with_watch_providers` | Provider IDs — use with `watch_region` |
+| `watch_region` | ISO-3166-1 — required for watch provider filtering |
+| `with_watch_monetization_types` | `flatrate`, `free`, `ads`, `rent`, `buy` |
+| `with_original_language` | ISO-639-1 language code |
+| `with_origin_country` | ISO-3166-1 country code |
+| `year` | Alias for `primary_release_year` |
+| `include_adult` | Default false |
+| `include_video` | Include video-only releases, default false |
+
+### TV Discover
+
+`GET /3/discover/tv` — same pattern, with TV-specific parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `sort_by` | `popularity.desc`, `vote_average.desc`, `first_air_date.desc`, etc. |
+| `with_genres` | Genre IDs |
+| `with_networks` | Network ID (integer, not comma-separated) |
+| `with_status` | 0=Returning, 1=Planned, 2=In Production, 3=Ended, 4=Canceled, 5=Pilot |
+| `with_type` | 0=Documentary, 1=News, 2=Miniseries, 3=Reality, 4=Scripted, 5=Talk Show, 6=Video |
+| `first_air_date_year` | Exact first air year |
+| `first_air_date.gte` / `.lte` | Date range |
+| `air_date.gte` / `.lte` | Episode air date range |
+| `timezone` | Used with air date filters |
+| `screened_theatrically` | Boolean — only series with theatrical episodes |
+| `include_null_first_air_dates` | Include series without a first air date |
+
+## Trending
+
+`GET /3/trending/{media_type}/{time_window}` — `media_type` is `movie`, `tv`, `person`, or `all`; `time_window` is `day` or `week`.
+
+## Find by External ID
+
+`GET /3/find/{external_id}?external_source=imdb_id` — look up a TMDB entity by an external identifier.
+
+Supported `external_source` values: `imdb_id`, `tvdb_id`, `freebase_mid`, `freebase_id`, `tvrage_id`, `wikidata_id`, `facebook_id`, `instagram_id`, `twitter_id`.
+
+Returns separate arrays: `movie_results`, `tv_results`, `tv_season_results`, `tv_episode_results`, `person_results`.
+
+## Collections, Networks, Companies, Keywords
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /3/collection/{id}` | Movie collection detail (e.g. Marvel Cinematic Universe) |
+| `GET /3/collection/{id}/images` | Collection images |
+| `GET /3/collection/{id}/translations` | Translated metadata |
+| `GET /3/network/{id}` | Network detail (e.g. HBO) |
+| `GET /3/network/{id}/images` | Network logos |
+| `GET /3/network/{id}/alternative_names` | Network name aliases |
+| `GET /3/company/{id}` | Production company detail |
+| `GET /3/company/{id}/images` | Company logos |
+| `GET /3/company/{id}/alternative_names` | Company name aliases |
+| `GET /3/keyword/{id}` | Keyword detail |
+| `GET /3/keyword/{id}/movies` | Movies tagged with this keyword |
+| `GET /3/credit/{credit_id}` | Cast/crew credit detail by credit ID |
+
+## Account & Watchlist (Auth Required)
+
+All account endpoints require a valid `session_id` query parameter.
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /3/account/{account_id}` | Account details |
+| `POST /3/account/{account_id}/favorite` | Add/remove favorite |
+| `POST /3/account/{account_id}/watchlist` | Add/remove watchlist entry |
+| `GET /3/account/{account_id}/favorite/movies` | Favorite movies |
+| `GET /3/account/{account_id}/favorite/tv` | Favorite TV series |
+| `GET /3/account/{account_id}/watchlist/movies` | Watchlist movies |
+| `GET /3/account/{account_id}/watchlist/tv` | Watchlist TV series |
+| `GET /3/account/{account_id}/rated/movies` | Rated movies |
+| `GET /3/account/{account_id}/rated/tv` | Rated TV series |
+| `GET /3/account/{account_id}/rated/tv/episodes` | Rated episodes |
+| `GET /3/account/{account_id}/lists` | User-created lists |
+
+Guest session ratings use `GET /3/guest_session/{guest_session_id}/rated/movies` (and `/tv`, `/tv/episodes`).
+
+## Lists (v3)
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /3/list` | Create a list |
+| `GET /3/list/{list_id}` | List detail and items |
+| `POST /3/list/{list_id}/add_item` | Add a movie |
+| `POST /3/list/{list_id}/remove_item` | Remove a movie |
+| `POST /3/list/{list_id}/clear` | Remove all items |
+| `DELETE /3/list/{list_id}` | Delete the list |
+| `GET /3/list/{list_id}/item_status` | Check if a movie is in the list |
+
+## Configuration & Reference Data
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /3/configuration` | Image base URLs, available sizes, change keys |
+| `GET /3/configuration/countries` | Country list with ISO codes |
+| `GET /3/configuration/languages` | Language list with ISO codes |
+| `GET /3/configuration/jobs` | Department and job name list |
+| `GET /3/configuration/primary_translations` | Supported translation locales |
+| `GET /3/configuration/timezones` | Timezone list |
+| `GET /3/genre/movie/list` | Movie genre IDs and names |
+| `GET /3/genre/tv/list` | TV genre IDs and names |
+| `GET /3/certification/movie/list` | Movie certifications by country |
+| `GET /3/certification/tv/list` | TV certifications by country |
+| `GET /3/watch/providers/movie` | Available movie streaming providers |
+| `GET /3/watch/providers/tv` | Available TV streaming providers |
+| `GET /3/watch/providers/regions` | Regions where watch providers operate |
+
+## Images
+
+Image URLs are assembled from the configuration endpoint: `secure_base_url + size + file_path`.
+
+Common sizes: `w45`, `w92`, `w154`, `w185`, `w300`, `w342`, `w500`, `w780`, `w1280`, `original`. Not all sizes apply to all image types — use the `poster_sizes`, `backdrop_sizes`, `profile_sizes`, etc. arrays from the configuration endpoint to know what's valid.
+
+## Rate Limits & Errors
+
+TMDB allows roughly 40 requests per second. Exceeding the limit returns `429 Too Many Requests`. No official rate-limit headers are documented; back off and retry on 429.
+
+| Status | Meaning |
+|--------|---------|
+| `401` | Invalid API key or missing authentication |
+| `404` | Resource not found |
+| `422` | Validation error (check request body) |
+| `429` | Rate limit exceeded — back off and retry |
+
+Error responses include a `status_code` (TMDB's internal code) and `status_message` in the JSON body alongside the HTTP status.
diff --git a/apps/ui/app/components/CatalogPosterCard.vue b/apps/ui/app/components/CatalogPosterCard.vue
index 96b3424..f2727ae 100644
--- a/apps/ui/app/components/CatalogPosterCard.vue
+++ b/apps/ui/app/components/CatalogPosterCard.vue
@@ -7,51 +7,98 @@ defineEmits<{ select: [] }>()
 const { load, entryFor } = useCatalogMetadata()
 const entry = computed(() => entryFor(props.title))
 const metadata = computed(() => entry.value?.data ?? props.title.metadata ?? null)
-// Loading until the lookup settles; titles with no tmdbId never load, so they're
-// not "loading" — they just stay on the placeholder.
-const loading = computed(() => props.title.tmdbId != null && (entry.value === null || entry.value.status === 'loading'))
+
+// Three visual states: the lookup is in flight, it finished with nothing (or there
+// was no id to look up), or we have metadata.
+const status = computed<'loading' | 'unavailable' | 'ready'>(() => {
+  if (metadata.value)
+    return 'ready'
+  if (props.title.tmdbId == null)
+    return 'unavailable'
+  return entry.value === null || entry.value.status === 'loading' ? 'loading' : 'unavailable'
+})
 
 const name = computed(() => metadata.value?.title ?? props.title.displayTitle)
-const poster = computed(() => metadata.value?.posterUrl ?? null)
+// Prefer the poster, fall back to the backdrop — both for titles that only have one
+// and for transient TMDB load failures (object-cover crops it to the card shape).
+const { src: poster, onError: onPosterError } = useFallbackImage(() => [
+  metadata.value?.posterUrl,
+  metadata.value?.backdropUrl,
+])
 const year = computed(() => metadata.value?.year ?? null)
 const rating = computed(() => metadata.value?.rating ?? null)
+const typeLabel = computed(() => props.title.mediaType === 'tv' ? 'TV' : 'Movie')
+const mediaIcon = computed(() => props.title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip')
 
-onMounted(() => load(props.title))
+// Enrich only once the card nears the viewport, so off-screen cards don't all
+// fire lookups at once. rootMargin starts the fetch just before it scrolls in.
+const cardRef = ref<HTMLElement | null>(null)
+let observer: IntersectionObserver | null = null
+onMounted(() => {
+  observer = new IntersectionObserver((entries) => {
+    if (!entries.some(entry => entry.isIntersecting))
+      return
+    load(props.title)
+    observer?.disconnect()
+    observer = null
+  }, { rootMargin: '300px' })
+  if (cardRef.value)
+    observer.observe(cardRef.value)
+})
+onBeforeUnmount(() => observer?.disconnect())
 </script>
 
 <template>
   <button
+    ref="cardRef"
     type="button"
     class="group flex flex-col gap-2 text-left focus:outline-none"
     @click="$emit('select')"
   >
     <div class="relative aspect-[2/3] overflow-hidden rounded-lg bg-muted ring-1 ring-default transition group-hover:ring-primary">
+      <!-- No loading="lazy": the IntersectionObserver already defers the poster URL
+           until the card nears the viewport, and native lazy-loading is unreliable
+           inside the panel's internal scroll container (images stay blank until the
+           window scrolls, which it never does here). -->
       <img
         v-if="poster"
         :src="poster"
         :alt="name"
-        loading="lazy"
         class="size-full object-cover"
+        @error="onPosterError"
       >
-      <div v-else class="flex size-full items-center justify-center" :class="{ 'animate-pulse': loading }">
-        <UIcon :name="title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip'" class="size-8 text-dimmed" />
+      <!-- Loading: pulsing surface with a spinner. -->
+      <div v-else-if="status === 'loading'" class="flex size-full animate-pulse items-center justify-center">
+        <UIcon name="i-ph-circle-notch" class="size-7 animate-spin text-dimmed" />
+      </div>
+      <!-- Metadata unavailable: dimmed broken-image mark, no pulse. -->
+      <div v-else-if="status === 'unavailable'" class="flex size-full items-center justify-center text-dimmed">
+        <UIcon name="i-ph-image-broken" class="size-8" />
+      </div>
+      <!-- Metadata present but no poster image: fall back to the media-type icon. -->
+      <div v-else class="flex size-full items-center justify-center">
+        <UIcon :name="mediaIcon" class="size-8 text-dimmed" />
       </div>
       <UBadge
         v-if="rating"
         :label="rating.toFixed(1)"
-        color="neutral"
         variant="solid"
         size="sm"
         icon="i-ph-star-fill"
-        class="absolute right-1.5 top-1.5 bg-default/80 backdrop-blur"
+        class="absolute right-1.5 top-1.5 gap-0.5 bg-black/65 font-semibold text-amber-300 ring-1 ring-white/10 backdrop-blur"
+        :ui="{ leadingIcon: 'text-amber-400' }"
       />
     </div>
     <div class="min-w-0">
       <p class="truncate text-sm font-medium text-default" :title="name">
         {{ name }}
       </p>
-      <p class="text-xs text-muted">
-        <span v-if="year">{{ year }} · </span>{{ title.mediaType === 'tv' ? 'TV' : 'Movie' }}
+      <p v-if="status === 'ready'" class="truncate text-xs text-muted">
+        <span v-if="year">{{ year }} · </span>{{ typeLabel }}
+      </p>
+      <div v-else-if="status === 'loading'" class="mt-1 h-3 w-12 animate-pulse rounded bg-muted" />
+      <p v-else class="truncate text-xs text-dimmed">
+        {{ typeLabel }} · no metadata
       </p>
     </div>
   </button>
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index e768913..3ab8ee9 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -8,6 +8,13 @@ const { load, entryFor } = useCatalogMetadata()
 // Reuse the cache the grid populated; load() is a no-op if the card already fetched it.
 const meta = computed(() => entryFor(props.title)?.data ?? props.title.metadata ?? null)
 const name = computed(() => meta.value?.title ?? props.title.displayTitle)
+// Prefer the wide backdrop, fall back to the poster — covers titles with only one
+// image and transient TMDB load failures (the poster is usually already cached by
+// the card). Null once both fail, so the box is hidden rather than left blank.
+const { src: heroImage, onError: onHeroError } = useFallbackImage(() => [
+  meta.value?.backdropUrl,
+  meta.value?.posterUrl,
+])
 
 onMounted(() => load(props.title))
 const canRequest = computed(() => props.title.mediaType === 'tv'
@@ -17,8 +24,8 @@ const canRequest = computed(() => props.title.mediaType === 'tv'
 
 <template>
   <div class="space-y-4">
-    <div v-if="meta?.backdropUrl" class="aspect-video overflow-hidden rounded-lg bg-muted">
-      <img :src="meta.backdropUrl" :alt="name" class="size-full object-cover">
+    <div v-if="heroImage" class="aspect-video overflow-hidden rounded-lg bg-muted">
+      <img :src="heroImage" :alt="name" class="size-full object-cover" @error="onHeroError">
     </div>
 
     <div class="flex items-baseline gap-2">
diff --git a/apps/ui/app/composables/useFallbackImage.ts b/apps/ui/app/composables/useFallbackImage.ts
new file mode 100644
index 0000000..4a19387
--- /dev/null
+++ b/apps/ui/app/composables/useFallbackImage.ts
@@ -0,0 +1,31 @@
+/**
+ * Renders the first image source that successfully loads, falling back through the
+ * rest on error. TMDB image requests occasionally fail under load (many posters
+ * fetching at once), which otherwise leaves a permanently blank box until a reload
+ * warms the HTTP cache. Falling back to the next candidate — typically an image the
+ * sibling view already cached — keeps artwork on screen; when every source fails,
+ * `src` is null so the caller can show its placeholder instead of a broken image.
+ */
+export function useFallbackImage(sources: () => Array<string | null | undefined>) {
+  const candidates = computed(() => sources().filter((s): s is string => Boolean(s)))
+  const index = ref(0)
+  const exhausted = ref(false)
+
+  const src = computed(() => (exhausted.value ? null : candidates.value[index.value] ?? null))
+
+  function onError(): void {
+    if (index.value < candidates.value.length - 1)
+      index.value += 1
+    else
+      exhausted.value = true
+  }
+
+  // Reset the cursor when the actual list of URLs changes (e.g. the sidebar swaps
+  // to a different title), but not on unrelated reactive churn.
+  watch(() => candidates.value.join('|'), () => {
+    index.value = 0
+    exhausted.value = false
+  })
+
+  return { src, onError }
+}
diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
index d301a98..06018a2 100644
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ b/apps/ui/app/pages/catalog/[peerId].vue
@@ -20,16 +20,6 @@ const titles = computed(() => {
   return typeFilter.value === 'all' ? all : all.filter(t => t.mediaType === typeFilter.value)
 })
 
-// Paginate so only the current page's cards mount — that bounds how many TMDB
-// lookups fire at once (each card fetches its own metadata on mount).
-const PAGE_SIZE = 48
-const page = ref(1)
-const pagedTitles = computed(() => titles.value.slice((page.value - 1) * PAGE_SIZE, page.value * PAGE_SIZE))
-// Jump back to the first page whenever the filter narrows the list.
-watch(typeFilter, () => {
-  page.value = 1
-})
-
 function titleName(title: CatalogTitle): string {
   return entryFor(title)?.data?.title ?? title.metadata?.title ?? title.displayTitle
 }
@@ -119,20 +109,17 @@ async function onConfirm(payload: CatalogRequestPayload) {
         </div>
       </UCard>
 
-      <template v-else>
-        <div class="grid grid-cols-3 gap-4 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 xl:grid-cols-8">
-          <CatalogPosterCard
-            v-for="title in pagedTitles"
-            :key="title.key"
-            :title="title"
-            @select="selected = title"
-          />
-        </div>
-
-        <div v-if="titles.length > PAGE_SIZE" class="mt-6 flex justify-center">
-          <UPagination v-model:page="page" :total="titles.length" :items-per-page="PAGE_SIZE" />
-        </div>
-      </template>
+      <div
+        v-else
+        class="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-4 sm:grid-cols-[repeat(auto-fill,minmax(140px,1fr))] md:grid-cols-[repeat(auto-fill,minmax(160px,1fr))] lg:grid-cols-[repeat(auto-fill,minmax(180px,1fr))] xl:grid-cols-[repeat(auto-fill,minmax(200px,1fr))]"
+      >
+        <CatalogPosterCard
+          v-for="title in titles"
+          :key="title.key"
+          :title="title"
+          @select="selected = title"
+        />
+      </div>
     </template>
   </UDashboardPanel>
 
diff --git a/skills-lock.json b/skills-lock.json
new file mode 100644
index 0000000..ca5c16e
--- /dev/null
+++ b/skills-lock.json
@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "skills": {
+    "tmdb-api": {
+      "source": "ranisalt/skills",
+      "sourceType": "github",
+      "skillPath": "tmdb-api/SKILL.md",
+      "computedHash": "42a19223d669b90c49ddd08e70ed4c72efaafac53f56913c9456a3fc538e6c6f"
+    }
+  }
+}

From 58fde9073b786f27f9c124407ad7b3dd6454a5c0 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 19:39:11 +0200
Subject: [PATCH 15/27] feat(catalog): aggregated GET /catalog with cross-peer
 grouping

---
 apps/backend/src/__tests__/catalog.test.ts    | 156 +++++++++---------
 .../src/modules/catalog/catalog.controller.ts |  35 ++--
 .../src/modules/catalog/catalog.lib.ts        | 113 +++++++++----
 .../src/modules/catalog/catalog.router.ts     |  11 +-
 4 files changed, 178 insertions(+), 137 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index aa45ccc..22e780d 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, mock, test } from 'bun:test'
 import { BadRequestError } from '../lib/errors/BadRequestError'
 import { NotFoundError } from '../lib/errors/NotFoundError'
 import { CatalogController } from '../modules/catalog/catalog.controller'
-import { groupReleasesIntoTitles, pickBestPerEpisode, pickBestRelease } from '../modules/catalog/catalog.lib'
+import { groupReleasesIntoUnifiedTitles, pickBestPerEpisode, pickBestRelease } from '../modules/catalog/catalog.lib'
 
 function movie(overrides: Partial<Release> = {}): Release {
   return {
@@ -27,69 +27,60 @@ function episode(overrides: Partial<Release> = {}): Release {
   }
 }
 
-describe('groupReleasesIntoTitles', () => {
-  test('groups movie + tv releases by their strong ids', () => {
-    const releases: Release[] = [
-      movie({ tmdbId: 603, size: 100 }),
-      movie({ tmdbId: 603, size: 200, quality: { resolution: 1080 } }),
-      movie({ tmdbId: 603, size: 300, quality: { resolution: 2160 } }),
-      episode({ tvdbId: 1396, seriesTitle: 'Breaking Bad', size: 50 }),
-      episode({ tvdbId: 1396, seriesTitle: 'Breaking Bad', size: 60 }),
-    ]
-
-    const titles = groupReleasesIntoTitles(releases)
-
-    expect(titles).toHaveLength(2)
-
-    const movieTitle = titles.find(t => t.mediaType === 'movie')
-    expect(movieTitle).toBeDefined()
-    expect(movieTitle!.tmdbId).toBe(603)
-    expect(movieTitle!.releaseCount).toBe(3)
-    expect(movieTitle!.totalSize).toBe(600)
-
-    const tvTitle = titles.find(t => t.mediaType === 'tv')
-    expect(tvTitle).toBeDefined()
-    expect(tvTitle!.tvdbId).toBe(1396)
-    expect(tvTitle!.releaseCount).toBe(2)
-    expect(tvTitle!.totalSize).toBe(110)
-    expect(tvTitle!.displayTitle).toBe('Breaking Bad')
-  })
-
-  test('collapses id-less movies with the same title into one name-keyed entry', () => {
-    const releases: Release[] = [
-      movie({ title: 'Foo.2024', size: 100 }),
-      movie({ title: 'Foo.2024', size: 200 }),
-    ]
-
-    const titles = groupReleasesIntoTitles(releases)
+describe('groupReleasesIntoUnifiedTitles', () => {
+  test('unifies the same movie across two peers into one title with per-peer buckets', () => {
+    const titles = groupReleasesIntoUnifiedTitles([
+      { peer: { id: 'p1', name: 'Alpha' }, releases: [movie({ tmdbId: 603, size: 100 })] },
+      { peer: { id: 'p2', name: 'Beta' }, releases: [movie({ tmdbId: 603, size: 200 })] },
+    ])
 
     expect(titles).toHaveLength(1)
+    expect(titles[0]!.tmdbId).toBe(603)
     expect(titles[0]!.releaseCount).toBe(2)
     expect(titles[0]!.totalSize).toBe(300)
-    expect(titles[0]!.key).toContain('name:')
+    expect(titles[0]!.peers).toHaveLength(2)
+
+    const alpha = titles[0]!.peers.find(p => p.id === 'p1')!
+    expect(alpha.name).toBe('Alpha')
+    expect(alpha.releaseCount).toBe(1)
+    expect(alpha.totalSize).toBe(100)
+  })
+
+  test('preserves per-release detail in each peer bucket', () => {
+    const titles = groupReleasesIntoUnifiedTitles([
+      { peer: { id: 'p1', name: 'Alpha' }, releases: [
+        episode({ id: 'ep:1', tvdbId: 1396, seriesTitle: 'Breaking Bad', season: 1, episode: 1, size: 50, quality: { resolution: 1080 } }),
+      ] },
+    ])
+
+    const bucket = titles[0]!.peers[0]!
+    expect(bucket.releases).toHaveLength(1)
+    expect(bucket.releases[0]).toMatchObject({
+      id: 'ep:1',
+      filename: 'Show.S01E01.1080p.mkv',
+      size: 50,
+      season: 1,
+      episode: 1,
+      quality: { resolution: 1080 },
+    })
   })
 
-  test('aliases an id-less tv release into the strong-id bucket of the same series', () => {
-    const releases: Release[] = [
-      episode({ seriesTitle: 'Some Show', size: 50 }),
-      episode({ seriesTitle: 'Some Show', tvdbId: 999, size: 60 }),
-    ]
-
-    const titles = groupReleasesIntoTitles(releases)
+  test('collapses an id-less release on one peer into the strong-id bucket from another peer', () => {
+    const titles = groupReleasesIntoUnifiedTitles([
+      { peer: { id: 'p1', name: 'Alpha' }, releases: [episode({ seriesTitle: 'Some Show', size: 50 })] },
+      { peer: { id: 'p2', name: 'Beta' }, releases: [episode({ seriesTitle: 'Some Show', tvdbId: 999, size: 60 })] },
+    ])
 
     expect(titles).toHaveLength(1)
-    expect(titles[0]!.releaseCount).toBe(2)
     expect(titles[0]!.tvdbId).toBe(999)
     expect(titles[0]!.key).toContain('id:999')
+    expect(titles[0]!.peers.map(p => p.id).sort()).toEqual(['p1', 'p2'])
   })
 
-  test('sorts titles by display title', () => {
-    const releases: Release[] = [
-      movie({ title: 'Zebra', tmdbId: 1 }),
-      movie({ title: 'Apple', tmdbId: 2 }),
-    ]
-
-    const titles = groupReleasesIntoTitles(releases)
+  test('sorts unified titles by display title', () => {
+    const titles = groupReleasesIntoUnifiedTitles([
+      { peer: { id: 'p1', name: 'Alpha' }, releases: [movie({ title: 'Zebra', tmdbId: 1 }), movie({ title: 'Apple', tmdbId: 2 })] },
+    ])
 
     expect(titles.map(t => t.displayTitle)).toEqual(['Apple', 'Zebra'])
   })
@@ -133,51 +124,52 @@ describe('pickBestPerEpisode', () => {
   })
 })
 
-describe('catalogController', () => {
+describe('catalogController.getCatalog', () => {
   function makeConnectors(peers: any[]) {
     return { servers: [], peers }
   }
 
-  test('returns the peer and its grouped titles', async () => {
-    const peer = {
-      id: 'peer-1',
-      name: 'Friend Jack',
-      listReleases: async () => [movie({ tmdbId: 603 }), movie({ tmdbId: 603 })],
-    }
-    const controller = new CatalogController(makeConnectors([peer]) as any)
+  test('aggregates the same title across two initialized peers', async () => {
+    const p1 = { id: 'p1', name: 'Alpha', isInitialized: true, listReleases: async () => [movie({ tmdbId: 603, size: 100 })] }
+    const p2 = { id: 'p2', name: 'Beta', isInitialized: true, listReleases: async () => [movie({ tmdbId: 603, size: 200 })] }
+    const controller = new CatalogController(makeConnectors([p1, p2]) as any)
 
-    const result = await controller.getPeerCatalog('peer-1')
+    const result = await controller.getCatalog()
 
-    expect(result.peer).toEqual({ id: 'peer-1', name: 'Friend Jack' })
+    expect(result.peers).toEqual([{ id: 'p1', name: 'Alpha' }, { id: 'p2', name: 'Beta' }])
     expect(result.titles).toHaveLength(1)
     expect(result.titles[0]!.releaseCount).toBe(2)
+    expect(result.titles[0]!.peers).toHaveLength(2)
   })
 
-  test('throws NotFoundError for an unknown peer id', () => {
-    const controller = new CatalogController(makeConnectors([]) as any)
+  test('skips a peer whose listReleases rejects but keeps the rest', async () => {
+    const broken = {
+      id: 'p1',
+      name: 'Broken',
+      isInitialized: true,
+      listReleases: async () => {
+        throw new Error('unreachable')
+      },
+    }
+    const healthy = { id: 'p2', name: 'Healthy', isInitialized: true, listReleases: async () => [movie({ tmdbId: 603 })] }
+    const controller = new CatalogController(makeConnectors([broken, healthy]) as any)
 
-    expect(controller.getPeerCatalog('missing')).rejects.toBeInstanceOf(NotFoundError)
-  })
-})
+    const result = await controller.getCatalog()
 
-describe('catalogController.getPeerCatalog metadata', () => {
-  function makeConnectors(peers: any[]) {
-    return { servers: [], peers }
-  }
+    expect(result.peers).toEqual([{ id: 'p2', name: 'Healthy' }])
+    expect(result.titles).toHaveLength(1)
+  })
 
-  test('returns titles unenriched and makes no TMDB calls', async () => {
-    const getMetadata = mock(async () => ({ title: 'Should not be called' }))
-    const peer = {
-      id: 'peer-1',
-      name: 'Friend Jack',
-      listReleases: async () => [movie({ tmdbId: 603 })],
-    }
-    const controller = new CatalogController(makeConnectors([peer]) as any, { getMetadata } as any)
+  test('does not query uninitialized peers', async () => {
+    const called = mock(async () => [movie({ tmdbId: 603 })])
+    const peer = { id: 'p1', name: 'Offline', isInitialized: false, listReleases: called }
+    const controller = new CatalogController(makeConnectors([peer]) as any)
 
-    const result = await controller.getPeerCatalog('peer-1')
+    const result = await controller.getCatalog()
 
-    expect(result.titles[0]!.metadata).toBeUndefined()
-    expect(getMetadata).not.toHaveBeenCalled()
+    expect(called).not.toHaveBeenCalled()
+    expect(result.peers).toEqual([])
+    expect(result.titles).toEqual([])
   })
 })
 
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index a5291ac..d371b44 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -2,14 +2,15 @@ import type { ArrServerConnector } from '../../lib/servers/arr/base'
 import type { PeerConnector } from '../../lib/servers/peer'
 import type { TmdbClient, TmdbMediaType, TmdbMetadata } from '../../lib/tmdb/client'
 import type { DownloadsService } from '../downloads/downloads.service'
-import type { CatalogTitle } from './catalog.lib'
+import type { PeerReleases, UnifiedCatalogTitle } from './catalog.lib'
 import { BadRequestError } from '../../lib/errors/BadRequestError'
 import { NotFoundError } from '../../lib/errors/NotFoundError'
-import { groupReleasesIntoTitles, pickBestPerEpisode, pickBestRelease } from './catalog.lib'
+import { groupReleasesIntoUnifiedTitles, pickBestPerEpisode, pickBestRelease } from './catalog.lib'
 
-export interface PeerCatalogResponse {
-  peer: { id: string, name: string }
-  titles: CatalogTitle[]
+export interface CatalogResponse {
+  // Peers that responded and contributed to this catalog.
+  peers: Array<{ id: string, name: string }>
+  titles: UnifiedCatalogTitle[]
 }
 
 export interface TmdbStatus {
@@ -49,15 +50,23 @@ export class CatalogController {
     return peer
   }
 
-  async getPeerCatalog(peerId: string): Promise<PeerCatalogResponse> {
-    const peer = this.requirePeer(peerId)
-    const releases = await peer.listReleases()
-    // Return titles immediately, unenriched. TMDB lookups are driven per-title by
-    // the client (see getTitleMetadata) so the catalog renders without waiting on
-    // hundreds of upstream round-trips.
+  async getCatalog(): Promise<CatalogResponse> {
+    // Fan out to every initialized peer. A peer that can't serve its catalog is
+    // skipped (partial results) rather than failing the whole aggregate.
+    const peers = this.connectors.peers.filter(p => p.isInitialized)
+    const results = await Promise.all(peers.map(async (peer): Promise<PeerReleases | null> => {
+      try {
+        const releases = await peer.listReleases()
+        return { peer: { id: peer.id, name: peer.name }, releases }
+      }
+      catch {
+        return null
+      }
+    }))
+    const responded = results.filter((r): r is PeerReleases => r !== null)
     return {
-      peer: { id: peer.id, name: peer.name },
-      titles: groupReleasesIntoTitles(releases),
+      peers: responded.map(r => r.peer),
+      titles: groupReleasesIntoUnifiedTitles(responded),
     }
   }
 
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
index 87d7be1..9fa8837 100644
--- a/apps/backend/src/modules/catalog/catalog.lib.ts
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -2,18 +2,37 @@ import type { Release } from '../../lib/release'
 import type { TmdbMetadata } from '../../lib/tmdb/client'
 import { ReleaseCategory } from '../../lib/release'
 
-export interface CatalogTitle {
-  // Stable grouping key, also used as the client-side list key.
+/** Per-release detail kept for a title within a single peer's bucket. */
+export type CatalogRelease = Pick<Release, 'id' | 'title' | 'filename' | 'size' | 'quality' | 'season' | 'episode'>
+
+/** One peer's contribution to a unified title. */
+export interface CatalogTitlePeer {
+  id: string
+  name: string
+  releaseCount: number
+  totalSize: number
+  releases: CatalogRelease[]
+}
+
+/** A title unified across every peer that carries it. */
+export interface UnifiedCatalogTitle {
   key: string
   mediaType: 'movie' | 'tv'
   tmdbId?: number
   imdbId?: string
   tvdbId?: number
-  // Best display name available pre-TMDB: series title for tv, else the release/scene title.
   displayTitle: string
+  // Totals across every peer that carries this title.
   releaseCount: number
   totalSize: number
   metadata?: TmdbMetadata | null
+  peers: CatalogTitlePeer[]
+}
+
+/** A peer's flat release list, tagged with the peer it came from. */
+export interface PeerReleases {
+  peer: { id: string, name: string }
+  releases: Release[]
 }
 
 function mediaTypeOf(release: Release): 'movie' | 'tv' {
@@ -37,45 +56,71 @@ function nameKey(release: Release): string {
 }
 
 /**
- * Group a peer's flat release list into one entry per movie/series.
+ * Fold every peer's releases into one title per movie/series.
  *
- * Two passes so a title that appears both WITH and WITHOUT an id still collapses:
- * pass 1 records, per fallback name, the strong id key seen for it; pass 2 routes
- * each release to its strong key, else the alias discovered in pass 1, else its name.
+ * Reuses the single-peer grouping keys (strong id key, else the name->id alias from
+ * pass 1, else the name key) but builds the alias map across ALL peers' releases so a
+ * title that is id-less on one peer and id-bearing on another still collapses. Each
+ * title tracks a per-peer bucket with that peer's release detail.
  */
-export function groupReleasesIntoTitles(releases: Release[]): CatalogTitle[] {
+export function groupReleasesIntoUnifiedTitles(peerReleases: PeerReleases[]): UnifiedCatalogTitle[] {
   const nameToStrongKey = new Map<string, string>()
-  for (const release of releases) {
-    const sk = strongKey(release)
-    if (sk && !nameToStrongKey.has(nameKey(release)))
-      nameToStrongKey.set(nameKey(release), sk)
+  for (const { releases } of peerReleases) {
+    for (const release of releases) {
+      const sk = strongKey(release)
+      if (sk && !nameToStrongKey.has(nameKey(release)))
+        nameToStrongKey.set(nameKey(release), sk)
+    }
   }
 
-  const byKey = new Map<string, CatalogTitle>()
-  for (const release of releases) {
-    const key = strongKey(release) ?? nameToStrongKey.get(nameKey(release)) ?? nameKey(release)
+  const keyOf = (release: Release): string =>
+    strongKey(release) ?? nameToStrongKey.get(nameKey(release)) ?? nameKey(release)
+
+  const byKey = new Map<string, UnifiedCatalogTitle>()
+  for (const { peer, releases } of peerReleases) {
+    for (const release of releases) {
+      const key = keyOf(release)
+
+      let title = byKey.get(key)
+      if (!title) {
+        title = {
+          key,
+          mediaType: mediaTypeOf(release),
+          tmdbId: release.tmdbId,
+          imdbId: release.imdbId,
+          tvdbId: release.tvdbId,
+          displayTitle: mediaTypeOf(release) === 'tv' ? (release.seriesTitle ?? release.title) : release.title,
+          releaseCount: 0,
+          totalSize: 0,
+          peers: [],
+        }
+        byKey.set(key, title)
+      }
 
-    const existing = byKey.get(key)
-    if (existing) {
-      existing.releaseCount += 1
-      existing.totalSize += release.size
       // Backfill ids if a later release carries one the first lacked.
-      existing.tmdbId ??= release.tmdbId
-      existing.imdbId ??= release.imdbId
-      existing.tvdbId ??= release.tvdbId
-      continue
-    }
+      title.tmdbId ??= release.tmdbId
+      title.imdbId ??= release.imdbId
+      title.tvdbId ??= release.tvdbId
+      title.releaseCount += 1
+      title.totalSize += release.size
 
-    byKey.set(key, {
-      key,
-      mediaType: mediaTypeOf(release),
-      tmdbId: release.tmdbId,
-      imdbId: release.imdbId,
-      tvdbId: release.tvdbId,
-      displayTitle: mediaTypeOf(release) === 'tv' ? (release.seriesTitle ?? release.title) : release.title,
-      releaseCount: 1,
-      totalSize: release.size,
-    })
+      let bucket = title.peers.find(p => p.id === peer.id)
+      if (!bucket) {
+        bucket = { id: peer.id, name: peer.name, releaseCount: 0, totalSize: 0, releases: [] }
+        title.peers.push(bucket)
+      }
+      bucket.releaseCount += 1
+      bucket.totalSize += release.size
+      bucket.releases.push({
+        id: release.id,
+        title: release.title,
+        filename: release.filename,
+        size: release.size,
+        quality: release.quality,
+        season: release.season,
+        episode: release.episode,
+      })
+    }
   }
 
   return [...byKey.values()].sort((a, b) => a.displayTitle.localeCompare(b.displayTitle))
diff --git a/apps/backend/src/modules/catalog/catalog.router.ts b/apps/backend/src/modules/catalog/catalog.router.ts
index faa2c73..1df3011 100644
--- a/apps/backend/src/modules/catalog/catalog.router.ts
+++ b/apps/backend/src/modules/catalog/catalog.router.ts
@@ -3,8 +3,6 @@ import { Hono } from 'hono'
 import { validator as zValidator } from 'hono-openapi'
 import { z } from 'zod'
 
-const peerParam = z.object({ peerId: z.string().min(1) })
-
 const tmdbParam = z.object({
   mediaType: z.enum(['movie', 'tv']),
   tmdbId: z.coerce.number().int(),
@@ -22,7 +20,7 @@ const requestBody = z.object({
 export function getCatalogRouter(controller: CatalogController) {
   const app = new Hono()
 
-  // Register the static path before `/:peerId` so "tmdb" isn't captured as a peerId.
+  // Register the static path before any future dynamic segment.
   app.get('/tmdb/status', async c => c.json(await controller.getTmdbStatus()))
 
   // Per-title TMDB lookup the catalog grid calls once per visible card.
@@ -31,17 +29,14 @@ export function getCatalogRouter(controller: CatalogController) {
     return c.json(await controller.getTitleMetadata(mediaType, tmdbId))
   })
 
-  // Register before `/:peerId` so "request-options" isn't captured as a peerId.
   app.get('/request-options', async c => c.json({ servers: await controller.getRequestOptions() }))
 
   app.post('/request', zValidator('json', requestBody), async (c) => {
     return c.json(await controller.requestDownload(c.req.valid('json')))
   })
 
-  app.get('/:peerId', zValidator('param', peerParam), async (c) => {
-    const { peerId } = c.req.valid('param')
-    return c.json(await controller.getPeerCatalog(peerId))
-  })
+  // Aggregated catalog across all initialized peers.
+  app.get('/', async c => c.json(await controller.getCatalog()))
 
   return app
 }

From 0db27b95e81be98ca53e8b7302cdfcea895f10cd Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 19:45:05 +0200
Subject: [PATCH 16/27] feat(ui): unified Peer Catalog page with peer picker

---
 apps/ui/app/components/CatalogTitleDetail.vue |   5 +-
 .../app/components/DownloadRequestModal.vue   |  22 ++-
 apps/ui/app/components/PeersSection.vue       |   1 -
 apps/ui/app/layouts/default.vue               |   1 +
 apps/ui/app/pages/catalog/index.vue           | 135 ++++++++++++++++++
 apps/ui/app/pages/index.vue                   |   4 +-
 apps/ui/app/types/management.ts               |  26 ++++
 7 files changed, 186 insertions(+), 8 deletions(-)
 create mode 100644 apps/ui/app/pages/catalog/index.vue

diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index 3ab8ee9..5c2e41b 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -51,10 +51,11 @@ const canRequest = computed(() => props.title.mediaType === 'tv'
     <USeparator />
 
     <p class="text-xs text-muted">
-      {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} on this peer · {{ formatBytes(title.totalSize) }}
+      {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} across
+      {{ title.peers.length }} peer{{ title.peers.length === 1 ? '' : 's' }} · {{ formatBytes(title.totalSize) }}
     </p>
     <p v-if="title.mediaType === 'tv'" class="text-xs text-muted">
-      Downloads every available episode from this peer.
+      Downloads every available episode from the chosen peer.
     </p>
 
     <UTooltip :disabled="canRequest" text="This title has no matching id to request">
diff --git a/apps/ui/app/components/DownloadRequestModal.vue b/apps/ui/app/components/DownloadRequestModal.vue
index a9434ed..703baba 100644
--- a/apps/ui/app/components/DownloadRequestModal.vue
+++ b/apps/ui/app/components/DownloadRequestModal.vue
@@ -17,11 +17,19 @@ const candidates = computed(() =>
 
 // USelect's v-model does not accept null; undefined behaves identically under the
 // `!= null` / `== null` loose checks below, so we use undefined for "unset".
+const peers = computed(() => props.title?.peers ?? [])
+const peerId = ref<string | undefined>(undefined)
 const serverId = ref<string | undefined>(undefined)
 const rootFolderPath = ref<string | undefined>(undefined)
 
 const server = computed(() => candidates.value.find(s => s.id === serverId.value) ?? null)
 
+// Reset to the first peer whenever the title changes, so a multi-peer title always
+// opens on its first peer regardless of a prior selection (matches the AC).
+watch(() => props.title?.key, () => {
+  peerId.value = peers.value[0]?.id
+}, { immediate: true })
+
 watch(candidates, (list) => {
   if (list.length && !list.some(s => s.id === serverId.value))
     serverId.value = list[0]!.id
@@ -31,12 +39,12 @@ watch(server, (s) => {
   rootFolderPath.value = s?.rootFolders[0]?.path ?? undefined
 }, { immediate: true })
 
-const canSubmit = computed(() => Boolean(serverId.value && rootFolderPath.value))
+const canSubmit = computed(() => Boolean(peerId.value && serverId.value && rootFolderPath.value))
 
 function onConfirm() {
-  if (!canSubmit.value || !serverId.value || !rootFolderPath.value)
+  if (!canSubmit.value || !peerId.value || !serverId.value || !rootFolderPath.value)
     return
-  emit('confirm', { serverId: serverId.value, rootFolderPath: rootFolderPath.value })
+  emit('confirm', { peerId: peerId.value, serverId: serverId.value, rootFolderPath: rootFolderPath.value })
 }
 </script>
 
@@ -53,6 +61,14 @@ function onConfirm() {
       </p>
 
       <div v-else class="space-y-4">
+        <UFormField v-if="peers.length > 1" label="Peer">
+          <USelect
+            v-model="peerId"
+            :items="peers.map(p => ({ label: p.name, value: p.id }))"
+            class="w-full"
+          />
+        </UFormField>
+
         <UFormField label="Send to">
           <USelect
             v-model="serverId"
diff --git a/apps/ui/app/components/PeersSection.vue b/apps/ui/app/components/PeersSection.vue
index 4d6b4c3..d6ed9ae 100644
--- a/apps/ui/app/components/PeersSection.vue
+++ b/apps/ui/app/components/PeersSection.vue
@@ -140,7 +140,6 @@ async function confirmDelete() {
           :initialized="peer.initialized"
           :error="peer.initializationError"
           :status="statusBadge(peer)"
-          :to="`/catalog/${peer.id}`"
           @edit="openEdit(peer)"
           @remove="confirmTarget = peer"
         >
diff --git a/apps/ui/app/layouts/default.vue b/apps/ui/app/layouts/default.vue
index c98fd42..4190eb3 100644
--- a/apps/ui/app/layouts/default.vue
+++ b/apps/ui/app/layouts/default.vue
@@ -8,6 +8,7 @@ const { state, logout } = useAuth()
 const items: NavigationMenuItem[] = [
   { label: 'Dashboard', icon: 'i-ph-gauge', to: '/', exact: true },
   { label: 'Downloads', icon: 'i-ph-download-simple', to: '/downloads' },
+  { label: 'Peer Catalog', icon: 'i-ph-film-reel', to: '/catalog' },
   { label: 'Settings', icon: 'i-ph-gear-six', to: '/settings' },
 ]
 
diff --git a/apps/ui/app/pages/catalog/index.vue b/apps/ui/app/pages/catalog/index.vue
new file mode 100644
index 0000000..6e0d212
--- /dev/null
+++ b/apps/ui/app/pages/catalog/index.vue
@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import type { CatalogRequestPayload, CatalogResponse, CatalogTitle } from '~/types/management'
+
+const { request, extractError } = useManagement()
+const { entryFor } = useCatalogMetadata()
+const toast = useToast()
+
+const { data, pending, error } = await useAsyncData(
+  'peer-catalog',
+  () => request<CatalogResponse>('catalog'),
+)
+
+const typeFilter = ref<'all' | 'movie' | 'tv'>('all')
+const titles = computed(() => {
+  const all = data.value?.titles ?? []
+  return typeFilter.value === 'all' ? all : all.filter(t => t.mediaType === typeFilter.value)
+})
+
+function titleName(title: CatalogTitle): string {
+  return entryFor(title)?.data?.title ?? title.metadata?.title ?? title.displayTitle
+}
+
+const selected = ref<CatalogTitle | null>(null)
+
+const requestOpen = ref(false)
+const requestTitle = ref<CatalogTitle | null>(null)
+const requestSubmitting = ref(false)
+const requestError = ref<string | null>(null)
+
+function openRequest() {
+  requestTitle.value = selected.value
+  requestError.value = null
+  requestOpen.value = true
+}
+
+async function onConfirm(payload: CatalogRequestPayload) {
+  const title = requestTitle.value
+  if (!title)
+    return
+  requestSubmitting.value = true
+  requestError.value = null
+  try {
+    await request('catalog/request', {
+      method: 'POST',
+      body: {
+        ...payload,
+        mediaType: title.mediaType,
+        tmdbId: title.tmdbId,
+        tvdbId: title.tvdbId,
+      },
+    })
+    requestOpen.value = false
+    selected.value = null
+    const peerName = title.peers.find(p => p.id === payload.peerId)?.name ?? 'a peer'
+    toast.add({
+      title: 'Added to your library',
+      description: `"${titleName(title)}" is downloading from ${peerName}.`,
+      color: 'success',
+      icon: 'i-ph-check-circle',
+    })
+  }
+  catch (err) {
+    requestError.value = extractError(err, 'Could not request this title.')
+  }
+  finally {
+    requestSubmitting.value = false
+  }
+}
+</script>
+
+<template>
+  <UDashboardPanel id="catalog">
+    <template #header>
+      <UDashboardNavbar title="Peer Catalog" />
+      <UDashboardToolbar>
+        <template #right>
+          <UTabs
+            v-model="typeFilter"
+            size="sm"
+            :items="[{ label: 'All', value: 'all' }, { label: 'Movies', value: 'movie' }, { label: 'TV', value: 'tv' }]"
+            :content="false"
+          />
+        </template>
+      </UDashboardToolbar>
+    </template>
+
+    <template #body>
+      <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load the peer catalog." />
+
+      <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
+        <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
+        Loading...
+      </p>
+
+      <UCard v-else-if="titles.length === 0" variant="subtle">
+        <div class="flex flex-col items-center gap-3 py-6 text-center">
+          <UIcon name="i-ph-film-slate" class="size-8 text-dimmed" />
+          <p class="text-sm text-muted">
+            Nothing to show here.
+          </p>
+        </div>
+      </UCard>
+
+      <div
+        v-else
+        class="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-4 sm:grid-cols-[repeat(auto-fill,minmax(140px,1fr))] md:grid-cols-[repeat(auto-fill,minmax(160px,1fr))] lg:grid-cols-[repeat(auto-fill,minmax(180px,1fr))] xl:grid-cols-[repeat(auto-fill,minmax(200px,1fr))]"
+      >
+        <CatalogPosterCard
+          v-for="title in titles"
+          :key="title.key"
+          :title="title"
+          @select="selected = title"
+        />
+      </div>
+    </template>
+  </UDashboardPanel>
+
+  <USlideover
+    :open="selected !== null"
+    :title="selected ? titleName(selected) : 'Title'"
+    @update:open="(open) => { if (!open) selected = null }"
+  >
+    <template #body>
+      <CatalogTitleDetail v-if="selected" :title="selected" @download="openRequest" />
+    </template>
+  </USlideover>
+
+  <DownloadRequestModal
+    v-model:open="requestOpen"
+    :title="requestTitle"
+    :submitting="requestSubmitting"
+    :error="requestError"
+    @confirm="onConfirm"
+  />
+</template>
diff --git a/apps/ui/app/pages/index.vue b/apps/ui/app/pages/index.vue
index 050d67e..11425ef 100644
--- a/apps/ui/app/pages/index.vue
+++ b/apps/ui/app/pages/index.vue
@@ -132,13 +132,13 @@ function serverRole(server: { source: boolean, destination: boolean }) {
                 No peers yet.
               </p>
               <div v-else class="divide-y divide-default">
-                <NuxtLink v-for="peer in overview.peers.items" :key="peer.id" :to="`/catalog/${peer.id}`" class="flex items-center gap-3 px-4 py-2.5 hover:bg-muted">
+                <div v-for="peer in overview.peers.items" :key="peer.id" class="flex items-center gap-3 px-4 py-2.5">
                   <ConnDot :initialized="peer.initialized" :error="peer.initializationError" />
                   <span class="flex-1 truncate text-sm text-default" :title="peer.name">{{ peer.name }}</span>
                   <span class="text-xs tabular-nums" :class="peer.initialized ? 'text-muted' : 'text-error'">
                     {{ peer.initialized ? (peer.version ?? '—') : 'unreachable' }}
                   </span>
-                </NuxtLink>
+                </div>
               </div>
             </UCard>
 
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index b6a4a27..fa9f803 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -56,6 +56,24 @@ export interface TmdbMetadata {
   genres: string[]
 }
 
+export interface CatalogRelease {
+  id: string
+  title: string
+  filename: string
+  size: number
+  quality?: { name?: string, source?: string, resolution?: number }
+  season?: number
+  episode?: number
+}
+
+export interface CatalogTitlePeer {
+  id: string
+  name: string
+  releaseCount: number
+  totalSize: number
+  releases: CatalogRelease[]
+}
+
 export interface CatalogTitle {
   key: string
   mediaType: 'movie' | 'tv'
@@ -63,9 +81,11 @@ export interface CatalogTitle {
   imdbId?: string
   tvdbId?: number
   displayTitle: string
+  // Totals across every peer that carries this title.
   releaseCount: number
   totalSize: number
   metadata?: TmdbMetadata | null
+  peers: CatalogTitlePeer[]
 }
 
 export interface PeerCatalogResponse {
@@ -73,6 +93,11 @@ export interface PeerCatalogResponse {
   titles: CatalogTitle[]
 }
 
+export interface CatalogResponse {
+  peers: Array<{ id: string, name: string }>
+  titles: CatalogTitle[]
+}
+
 export interface RequestServerOption {
   id: string
   name: string
@@ -82,6 +107,7 @@ export interface RequestServerOption {
 }
 
 export interface CatalogRequestPayload {
+  peerId: string
   serverId: string
   rootFolderPath: string
 }

From c2e9676813e9a05e75c4e79d60e448022852ebb6 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sat, 27 Jun 2026 19:46:55 +0200
Subject: [PATCH 17/27] refactor(ui): remove per-peer catalog page and dead
 type

---
 apps/ui/app/pages/catalog/[peerId].vue | 143 -------------------------
 apps/ui/app/types/management.ts        |   5 -
 2 files changed, 148 deletions(-)
 delete mode 100644 apps/ui/app/pages/catalog/[peerId].vue

diff --git a/apps/ui/app/pages/catalog/[peerId].vue b/apps/ui/app/pages/catalog/[peerId].vue
deleted file mode 100644
index 06018a2..0000000
--- a/apps/ui/app/pages/catalog/[peerId].vue
+++ /dev/null
@@ -1,143 +0,0 @@
-<script setup lang="ts">
-import type { CatalogRequestPayload, CatalogTitle, PeerCatalogResponse } from '~/types/management'
-
-const route = useRoute()
-const peerId = computed(() => String(route.params.peerId))
-const { request, extractError } = useManagement()
-const { entryFor } = useCatalogMetadata()
-const toast = useToast()
-
-const { data, pending, error } = await useAsyncData(
-  `catalog-${peerId.value}`,
-  () => request<PeerCatalogResponse>(`catalog/${peerId.value}`),
-  { watch: [peerId] },
-)
-
-const peerName = computed(() => data.value?.peer.name ?? 'Peer')
-const typeFilter = ref<'all' | 'movie' | 'tv'>('all')
-const titles = computed(() => {
-  const all = data.value?.titles ?? []
-  return typeFilter.value === 'all' ? all : all.filter(t => t.mediaType === typeFilter.value)
-})
-
-function titleName(title: CatalogTitle): string {
-  return entryFor(title)?.data?.title ?? title.metadata?.title ?? title.displayTitle
-}
-
-const selected = ref<CatalogTitle | null>(null)
-
-const requestOpen = ref(false)
-const requestTitle = ref<CatalogTitle | null>(null)
-const requestSubmitting = ref(false)
-const requestError = ref<string | null>(null)
-
-function openRequest() {
-  requestTitle.value = selected.value
-  requestError.value = null
-  requestOpen.value = true
-}
-
-async function onConfirm(payload: CatalogRequestPayload) {
-  const title = requestTitle.value
-  if (!title)
-    return
-  requestSubmitting.value = true
-  requestError.value = null
-  try {
-    await request('catalog/request', {
-      method: 'POST',
-      body: {
-        ...payload,
-        peerId: peerId.value,
-        mediaType: title.mediaType,
-        tmdbId: title.tmdbId,
-        tvdbId: title.tvdbId,
-      },
-    })
-    requestOpen.value = false
-    selected.value = null
-    toast.add({
-      title: 'Added to your library',
-      description: `"${titleName(title)}" is downloading from ${peerName.value}.`,
-      color: 'success',
-      icon: 'i-ph-check-circle',
-    })
-  }
-  catch (err) {
-    requestError.value = extractError(err, 'Could not request this title.')
-  }
-  finally {
-    requestSubmitting.value = false
-  }
-}
-</script>
-
-<template>
-  <UDashboardPanel id="catalog">
-    <template #header>
-      <UDashboardNavbar :title="peerName">
-        <template #leading>
-          <UButton icon="i-ph-arrow-left" color="neutral" variant="ghost" to="/settings" aria-label="Back to settings" />
-        </template>
-      </UDashboardNavbar>
-      <UDashboardToolbar>
-        <template #right>
-          <UTabs
-            v-model="typeFilter"
-            size="sm"
-            :items="[{ label: 'All', value: 'all' }, { label: 'Movies', value: 'movie' }, { label: 'TV', value: 'tv' }]"
-            :content="false"
-          />
-        </template>
-      </UDashboardToolbar>
-    </template>
-
-    <template #body>
-      <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load this peer's catalog." />
-
-      <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
-        <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
-        Loading…
-      </p>
-
-      <UCard v-else-if="titles.length === 0" variant="subtle">
-        <div class="flex flex-col items-center gap-3 py-6 text-center">
-          <UIcon name="i-ph-film-slate" class="size-8 text-dimmed" />
-          <p class="text-sm text-muted">
-            Nothing to show here.
-          </p>
-        </div>
-      </UCard>
-
-      <div
-        v-else
-        class="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-4 sm:grid-cols-[repeat(auto-fill,minmax(140px,1fr))] md:grid-cols-[repeat(auto-fill,minmax(160px,1fr))] lg:grid-cols-[repeat(auto-fill,minmax(180px,1fr))] xl:grid-cols-[repeat(auto-fill,minmax(200px,1fr))]"
-      >
-        <CatalogPosterCard
-          v-for="title in titles"
-          :key="title.key"
-          :title="title"
-          @select="selected = title"
-        />
-      </div>
-    </template>
-  </UDashboardPanel>
-
-  <USlideover
-    :open="selected !== null"
-    :title="selected ? titleName(selected) : 'Title'"
-    @update:open="(open) => { if (!open) selected = null }"
-  >
-    <template #body>
-      <CatalogTitleDetail v-if="selected" :title="selected" @download="openRequest" />
-    </template>
-  </USlideover>
-
-  <DownloadRequestModal
-    v-model:open="requestOpen"
-    :title="requestTitle"
-    :submitting="requestSubmitting"
-    :error="requestError"
-    @confirm="onConfirm"
-  />
-</template>
diff --git a/apps/ui/app/types/management.ts b/apps/ui/app/types/management.ts
index fa9f803..9749c86 100644
--- a/apps/ui/app/types/management.ts
+++ b/apps/ui/app/types/management.ts
@@ -88,11 +88,6 @@ export interface CatalogTitle {
   peers: CatalogTitlePeer[]
 }
 
-export interface PeerCatalogResponse {
-  peer: { id: string, name: string }
-  titles: CatalogTitle[]
-}
-
 export interface CatalogResponse {
   peers: Array<{ id: string, name: string }>
   titles: CatalogTitle[]

From b5cd7c5c370d801504f88648a39513093b3894de Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 09:34:39 +0200
Subject: [PATCH 18/27] feat(ui): add View in Logflix button to catalog title
 detail

---
 apps/ui/app/components/CatalogTitleDetail.vue | 18 ++++++++++++++++++
 apps/ui/public/logflix.svg                    |  9 +++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 apps/ui/public/logflix.svg

diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index 5c2e41b..d9ab2b6 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -20,6 +20,10 @@ onMounted(() => load(props.title))
 const canRequest = computed(() => props.title.mediaType === 'tv'
   ? props.title.tvdbId != null
   : props.title.tmdbId != null)
+// Logflix keys both movies and TV off the TMDB id (e.g. /movie/1301421, /tv/246461).
+const logflixUrl = computed(() => props.title.tmdbId == null
+  ? null
+  : `https://logflix.eu/${props.title.mediaType}/${props.title.tmdbId}`)
 </script>
 
 <template>
@@ -67,5 +71,19 @@ const canRequest = computed(() => props.title.mediaType === 'tv'
         @click="emit('download')"
       />
     </UTooltip>
+
+    <UButton
+      v-if="logflixUrl"
+      :to="logflixUrl"
+      target="_blank"
+      label="View in Logflix"
+      color="neutral"
+      variant="subtle"
+      block
+    >
+      <template #leading>
+        <img src="/logflix.svg" alt="" class="size-4">
+      </template>
+    </UButton>
   </div>
 </template>
diff --git a/apps/ui/public/logflix.svg b/apps/ui/public/logflix.svg
new file mode 100644
index 0000000..d1d6b00
--- /dev/null
+++ b/apps/ui/public/logflix.svg
@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="800" height="800"
+  viewBox="0 0 512 512">
+  <path fill="#f7b239" d="M92.48 73.77a33.72 33.72 0 0 1 55.12-36.6A44.6 44.6 0 0 1 189.74 7.1a44.4 44.4 0 0 1 33.29 14.97A33.8 33.8 0 0 1 254.69 0a33.8 33.8 0 0 1 32.4 24.32A44.5 44.5 0 0 1 322.24 7.1a44.6 44.6 0 0 1 42.15 30.07 33.73 33.73 0 0 1 55.1 36.6 44.54 44.54 0 0 1 28.92 74.44l-67.11 79.86-105.1 29.64-125.3-33.68-60.64-20.21-26.7-55.6a44.53 44.53 0 0 1 28.91-74.44"/>
+  <path fill="#f95428" d="M448.42 148.21H63.14l45 363.79h295.71l45-363.79z"/>
+  <path fill="#f2f2f2" d="M381.56 148.21 352.26 512h-60.11l3.67-121c19.84-12.98 21.4-106.02 3.6-119.28v-.01l3.74-123.5zM216.19 391.02 219.84 512h-60.12l-29.3-363.79h78.42l3.73 123.49.02.01c-17.81 13.26-16.25 106.32 3.6 119.31"/>
+  <path fill="#e09b2d" d="M189.49 73.77a33.72 33.72 0 0 1 55.12-36.6 44.6 44.6 0 0 1 32.14-28.92A33.6 33.6 0 0 0 254.7 0a33.8 33.8 0 0 0-31.66 22.07 44.4 44.4 0 0 0-33.3-14.97 44.6 44.6 0 0 0-42.12 30.07 33.72 33.72 0 0 0-55.12 36.6 44.53 44.53 0 0 0-28.92 74.44h97a44.53 44.53 0 0 1 28.91-74.44"/>
+  <path fill="#e54728" d="M130.43 148.21 159.72 512h-51.58l-45-363.79h.43z"/>
+  <path fill="#f7b239" d="M299.41 271.72a72.6 72.6 0 0 1 29.35 58.39c0 25.49-13.1 47.9-32.95 60.9A72.4 72.4 0 0 1 256 402.86a72.4 72.4 0 0 1-39.8-11.84 72.7 72.7 0 0 1-32.96-60.91 72.7 72.7 0 0 1 29.36-58.4 72.4 72.4 0 0 1 43.4-14.36c16.26 0 31.3 5.35 43.42 14.37"/>
+</svg>

From d24199bdcdecb4e3bbcbd9eb3003c15e9b0908a7 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 10:26:33 +0200
Subject: [PATCH 19/27] feat(ui): add About section with TMDB attribution and
 app version

Adds a Settings > About section: the jack mark plus version (sourced from
package.json via runtimeConfig.public.appVersion) and the TMDB-required
attribution notice and logo, kept visually subordinate to the app mark.
---
 apps/ui/app/pages/settings.vue | 36 ++++++++++++++++++++++++++++++++++
 apps/ui/nuxt.config.ts         |  8 ++++++++
 apps/ui/package.json           |  1 +
 apps/ui/public/tmdb.svg        |  1 +
 4 files changed, 46 insertions(+)
 create mode 100644 apps/ui/public/tmdb.svg

diff --git a/apps/ui/app/pages/settings.vue b/apps/ui/app/pages/settings.vue
index a01697c..856c4b3 100644
--- a/apps/ui/app/pages/settings.vue
+++ b/apps/ui/app/pages/settings.vue
@@ -3,6 +3,7 @@ import type { BadgeProps } from '@nuxt/ui'
 import type { ApiKey, ApiKeyInput, CreatedApiKey, JackConfig } from '~/types/management'
 
 const { request, extractError } = useManagement()
+const version = useRuntimeConfig().public.appVersion
 
 const { data, pending, error, refresh } = await useAsyncData('api-keys', () =>
   request<ApiKey[]>('api-keys'))
@@ -272,6 +273,41 @@ async function confirmRevoke() {
             </UCard>
           </div>
         </SettingsSection>
+
+        <USeparator />
+
+        <!-- About / Credits — also the home for required third-party attribution. -->
+        <SettingsSection
+          title="About"
+          description="What this is, and the data it relies on."
+        >
+          <UCard variant="subtle" :ui="{ body: 'space-y-4' }">
+            <!-- jack's own mark: stated first, in brand color, at full size. -->
+            <div class="flex items-center gap-3">
+              <UIcon name="i-ph-plugs-connected" class="size-7 shrink-0 text-primary" />
+              <div class="min-w-0">
+                <div class="flex items-baseline gap-2">
+                  <span class="text-base font-semibold tracking-tight text-highlighted">jack</span>
+                  <span class="font-mono text-xs text-dimmed">v{{ version }}</span>
+                </div>
+                <p class="text-xs text-muted">
+                  Self-hosted *arr peer bridge
+                </p>
+              </div>
+            </div>
+
+            <USeparator />
+
+            <!-- TMDB attribution — deliberately quieter than the jack mark above:
+                 a smaller logo and muted notice keep it subordinate, per TMDB's terms. -->
+            <div class="flex items-start gap-3">
+              <img src="/tmdb.svg" alt="The Movie Database (TMDB)" class="mt-0.5 h-4 w-auto shrink-0">
+              <p class="text-xs leading-relaxed text-muted">
+                This product uses the TMDB API but is not endorsed or certified by TMDB.
+              </p>
+            </div>
+          </UCard>
+        </SettingsSection>
       </div>
     </template>
   </UDashboardPanel>
diff --git a/apps/ui/nuxt.config.ts b/apps/ui/nuxt.config.ts
index 3984b63..6b545a4 100644
--- a/apps/ui/nuxt.config.ts
+++ b/apps/ui/nuxt.config.ts
@@ -1,4 +1,6 @@
 // https://nuxt.com/docs/api/configuration/nuxt-config
+import pkg from './package.json'
+
 export default defineNuxtConfig({
   compatibilityDate: '2025-01-01',
   devtools: { enabled: false },
@@ -42,5 +44,11 @@ export default defineNuxtConfig({
     // Seals the cookie that holds the management key in cookie mode. MUST be set
     // (>= 32 chars) in production; the default is a clearly-insecure dev value.
     sessionKey: 'dev-insecure-session-key-change-me-please-1234',
+
+    // Browser-exposed: the app version, baked from package.json at build time and
+    // shown in Settings → About.
+    public: {
+      appVersion: pkg.version,
+    },
   },
 })
diff --git a/apps/ui/package.json b/apps/ui/package.json
index 63db74d..2e5d499 100644
--- a/apps/ui/package.json
+++ b/apps/ui/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@jack/ui",
+  "version": "0.1.0",
   "type": "module",
   "private": true,
   "scripts": {
diff --git a/apps/ui/public/tmdb.svg b/apps/ui/public/tmdb.svg
new file mode 100644
index 0000000..4b21ded
--- /dev/null
+++ b/apps/ui/public/tmdb.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 273.42 35.52"><defs><style>.cls-1{fill:url(#linear-gradient);}</style><linearGradient id="linear-gradient" y1="17.76" x2="273.42" y2="17.76" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#90cea1"/><stop offset="0.56" stop-color="#3cbec9"/><stop offset="1" stop-color="#00b3e5"/></linearGradient></defs><title>Asset 3</title><g id="Layer_2" data-name="Layer 2"><g id="Layer_1-2" data-name="Layer 1"><path class="cls-1" d="M191.85,35.37h63.9A17.67,17.67,0,0,0,273.42,17.7h0A17.67,17.67,0,0,0,255.75,0h-63.9A17.67,17.67,0,0,0,174.18,17.7h0A17.67,17.67,0,0,0,191.85,35.37ZM10.1,35.42h7.8V6.92H28V0H0v6.9H10.1Zm28.1,0H46V8.25h.1L55.05,35.4h6L70.3,8.25h.1V35.4h7.8V0H66.45l-8.2,23.1h-.1L50,0H38.2ZM89.14.12h11.7a33.56,33.56,0,0,1,8.08,1,18.52,18.52,0,0,1,6.67,3.08,15.09,15.09,0,0,1,4.53,5.52,18.5,18.5,0,0,1,1.67,8.25,16.91,16.91,0,0,1-1.62,7.58,16.3,16.3,0,0,1-4.38,5.5,19.24,19.24,0,0,1-6.35,3.37,24.53,24.53,0,0,1-7.55,1.15H89.14Zm7.8,28.2h4a21.66,21.66,0,0,0,5-.55A10.58,10.58,0,0,0,110,26a8.73,8.73,0,0,0,2.68-3.35,11.9,11.9,0,0,0,1-5.08,9.87,9.87,0,0,0-1-4.52,9.17,9.17,0,0,0-2.63-3.18A11.61,11.61,0,0,0,106.22,8a17.06,17.06,0,0,0-4.68-.63h-4.6ZM133.09.12h13.2a32.87,32.87,0,0,1,4.63.33,12.66,12.66,0,0,1,4.17,1.3,7.94,7.94,0,0,1,3,2.72,8.34,8.34,0,0,1,1.15,4.65,7.48,7.48,0,0,1-1.67,5,9.13,9.13,0,0,1-4.43,2.82V17a10.28,10.28,0,0,1,3.18,1,8.51,8.51,0,0,1,2.45,1.85,7.79,7.79,0,0,1,1.57,2.62,9.16,9.16,0,0,1,.55,3.2,8.52,8.52,0,0,1-1.2,4.68,9.32,9.32,0,0,1-3.1,3A13.38,13.38,0,0,1,152.32,35a22.5,22.5,0,0,1-4.73.5h-14.5Zm7.8,14.15h5.65a7.65,7.65,0,0,0,1.78-.2,4.78,4.78,0,0,0,1.57-.65,3.43,3.43,0,0,0,1.13-1.2,3.63,3.63,0,0,0,.42-1.8A3.3,3.3,0,0,0,151,8.6a3.42,3.42,0,0,0-1.23-1.13A6.07,6.07,0,0,0,148,6.9a9.9,9.9,0,0,0-1.85-.18h-5.3Zm0,14.65h7a8.27,8.27,0,0,0,1.83-.2,4.67,4.67,0,0,0,1.67-.7,3.93,3.93,0,0,0,1.23-1.3,3.8,3.8,0,0,0,.47-1.95,3.16,3.16,0,0,0-.62-2,4,4,0,0,0-1.58-1.18,8.23,8.23,0,0,0-2-.55,15.12,15.12,0,0,0-2.05-.15h-5.9Z"/></g></g></svg>
\ No newline at end of file

From 02c4c97678e16b1d21a735d430f6388fe194ab3a Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 12:29:15 +0200
Subject: [PATCH 20/27] feat(ui): stable per-peer colors and plug-style
 connection status

Derive a stable accent color per peer from its id (sorted-membership
assignment with a per-id hash fallback), and render it as a dot on
catalog poster peer badges. Reuse it for connection status: ConnDot now
draws a plug icon (shape = status, color = peer identity when given),
and ConnectorCard forwards an optional accent.
---
 apps/ui/app/components/CatalogPosterCard.vue | 51 ++++++++++++++++
 apps/ui/app/components/ConnDot.vue           | 31 +++++++---
 apps/ui/app/components/ConnectorCard.vue     |  5 +-
 apps/ui/app/composables/usePeerColors.ts     | 21 +++++++
 apps/ui/app/utils/peerColor.ts               | 62 ++++++++++++++++++++
 5 files changed, 161 insertions(+), 9 deletions(-)
 create mode 100644 apps/ui/app/composables/usePeerColors.ts
 create mode 100644 apps/ui/app/utils/peerColor.ts

diff --git a/apps/ui/app/components/CatalogPosterCard.vue b/apps/ui/app/components/CatalogPosterCard.vue
index f2727ae..bfd9d17 100644
--- a/apps/ui/app/components/CatalogPosterCard.vue
+++ b/apps/ui/app/components/CatalogPosterCard.vue
@@ -30,6 +30,13 @@ const rating = computed(() => metadata.value?.rating ?? null)
 const typeLabel = computed(() => props.title.mediaType === 'tv' ? 'TV' : 'Movie')
 const mediaIcon = computed(() => props.title.mediaType === 'tv' ? 'i-ph-television' : 'i-ph-film-strip')
 
+// Peer chips along the poster's bottom edge: up to two name badges (CSS-truncated to
+// stay legible, and to shrink rather than overflow on small posters) then a "+N" badge
+// whose tooltip names the rest.
+const visiblePeers = computed(() => props.title.peers.slice(0, 2))
+const hiddenPeers = computed(() => props.title.peers.slice(2))
+const { dotClass } = usePeerColors()
+
 // Enrich only once the card nears the viewport, so off-screen cards don't all
 // fire lookups at once. rootMargin starts the fetch just before it scrolls in.
 const cardRef = ref<HTMLElement | null>(null)
@@ -88,6 +95,50 @@ onBeforeUnmount(() => observer?.disconnect())
         class="absolute right-1.5 top-1.5 gap-0.5 bg-black/65 font-semibold text-amber-300 ring-1 ring-white/10 backdrop-blur"
         :ui="{ leadingIcon: 'text-amber-400' }"
       />
+      <!-- Peers along the bottom, filling right-to-left so the first peer sits at the
+           right edge. -->
+      <div
+        v-if="title.peers.length"
+        class="absolute inset-x-1.5 bottom-1.5 flex justify-end gap-1"
+      >
+        <UTooltip
+          v-for="p in visiblePeers"
+          :key="p.id"
+          :text="`From ${p.name}'s library`"
+        >
+          <UBadge
+            :label="p.name"
+            variant="solid"
+            size="sm"
+            class="min-w-0 max-w-24 bg-black/65 font-medium text-white ring-1 ring-white/10 backdrop-blur"
+          >
+            <template #leading>
+              <span class="size-1.5 shrink-0 rounded-full" :class="dotClass(p.id)" />
+            </template>
+          </UBadge>
+        </UTooltip>
+        <UTooltip v-if="hiddenPeers.length" :ui="{ content: 'h-auto' }">
+          <template #content>
+            <div class="text-xs">
+              <p class="font-medium">
+                Also available from:
+              </p>
+              <ul class="mt-0.5 space-y-0.5">
+                <li v-for="p in hiddenPeers" :key="p.id" class="flex items-center gap-1.5 whitespace-nowrap">
+                  <span class="size-1.5 shrink-0 rounded-full" :class="dotClass(p.id)" />
+                  {{ p.name }}'s library
+                </li>
+              </ul>
+            </div>
+          </template>
+          <UBadge
+            :label="`+${hiddenPeers.length}`"
+            variant="solid"
+            size="sm"
+            class="shrink-0 bg-black/65 font-medium text-white ring-1 ring-white/10 backdrop-blur"
+          />
+        </UTooltip>
+      </div>
     </div>
     <div class="min-w-0">
       <p class="truncate text-sm font-medium text-default" :title="name">
diff --git a/apps/ui/app/components/ConnDot.vue b/apps/ui/app/components/ConnDot.vue
index 94d7f19..e34bd51 100644
--- a/apps/ui/app/components/ConnDot.vue
+++ b/apps/ui/app/components/ConnDot.vue
@@ -2,20 +2,35 @@
 const props = defineProps<{
   initialized: boolean
   error?: string | null
+  // Optional identity color (e.g. a peer's derived text-color class). When set it
+  // overrides the status color: the plug shape carries the status, the color carries
+  // identity. Left unset for connectors, which have no per-entry color.
+  accentClass?: string | null
 }>()
 
-// Connected → success; unreachable (failed to initialize, has an error) → error;
-// still handshaking → warning. A soft halo ring gives the live console a pulse
-// without any custom CSS.
-const dot = computed(() => {
+// Shape conveys status: connected → plugged together, otherwise → unplugged.
+const icon = computed(() => props.initialized ? 'i-ph-plugs-connected' : 'i-ph-plugs')
+
+// Color conveys identity when an accent is given, else falls back to the status color.
+const color = computed(() => {
+  if (props.accentClass)
+    return props.accentClass
   if (props.initialized)
-    return 'bg-success ring-success/20'
+    return 'text-success'
   if (props.error)
-    return 'bg-error ring-error/20'
-  return 'bg-warning ring-warning/20'
+    return 'text-error'
+  return 'text-warning'
 })
+
+// Still handshaking (not initialized, no error yet): pulse to signal it's in progress.
+const connecting = computed(() => !props.initialized && !props.error)
 </script>
 
 <template>
-  <span class="size-2 shrink-0 rounded-full ring-4" :class="dot" :title="error ?? undefined" />
+  <UIcon
+    :name="icon"
+    class="size-4 shrink-0"
+    :class="[color, connecting && 'animate-pulse [animation-duration:0.8s]']"
+    :title="error ?? undefined"
+  />
 </template>
diff --git a/apps/ui/app/components/ConnectorCard.vue b/apps/ui/app/components/ConnectorCard.vue
index 92893e4..72b360d 100644
--- a/apps/ui/app/components/ConnectorCard.vue
+++ b/apps/ui/app/components/ConnectorCard.vue
@@ -8,6 +8,9 @@ defineProps<{
   error?: string | null
   status: { color: BadgeProps['color'], label: string }
   to?: string
+  // Optional identity accent (e.g. a peer's derived text-color class) applied to the
+  // status icon. Left unset for connectors, which have no per-entry color.
+  accentClass?: string | null
 }>()
 defineEmits<{ edit: [], remove: [] }>()
 </script>
@@ -15,7 +18,7 @@ defineEmits<{ edit: [], remove: [] }>()
 <template>
   <UCard variant="subtle" :ui="{ body: 'sm:p-4' }">
     <div class="flex items-center gap-3">
-      <ConnDot :initialized="initialized" :error="error" />
+      <ConnDot :initialized="initialized" :error="error" :accent-class="accentClass" />
       <div class="min-w-0 flex-1">
         <div class="flex items-baseline gap-2">
           <span class="truncate font-medium text-default" :title="name">{{ name }}</span>
diff --git a/apps/ui/app/composables/usePeerColors.ts b/apps/ui/app/composables/usePeerColors.ts
new file mode 100644
index 0000000..6840dae
--- /dev/null
+++ b/apps/ui/app/composables/usePeerColors.ts
@@ -0,0 +1,21 @@
+import type { InjectionKey, Ref } from 'vue'
+import type { PeerColor } from '~/utils/peerColor'
+
+const PEER_COLORS: InjectionKey<Ref<Map<string, PeerColor>>> = Symbol('peer-colors')
+
+/** Provided by a container that knows the full peer set (e.g. the catalog page). */
+export function providePeerColors(colors: Ref<Map<string, PeerColor>>): void {
+  provide(PEER_COLORS, colors)
+}
+
+/**
+ * Resolve a peer's accent classes from the provided color map, falling back to the
+ * per-id hash when no map is in scope (so the components still work standalone).
+ */
+export function usePeerColors() {
+  const colors = inject(PEER_COLORS, null)
+  return {
+    dotClass: (id: string) => colors?.value.get(id)?.dot ?? peerColorClass(id),
+    textClass: (id: string) => colors?.value.get(id)?.text ?? peerColorTextClass(id),
+  }
+}
diff --git a/apps/ui/app/utils/peerColor.ts b/apps/ui/app/utils/peerColor.ts
new file mode 100644
index 0000000..adf0ab0
--- /dev/null
+++ b/apps/ui/app/utils/peerColor.ts
@@ -0,0 +1,62 @@
+// A stable accent color per peer, derived purely from the peer id so it stays the
+// same across server restarts and clients with no persistence. The palette is Nuxt
+// UI's primary colors minus black (too plain), indigo (Jack's own brand color), and
+// green/emerald/rose/red (too close to the connection status green/red). Amber/yellow
+// resemble the connecting status, but that only shows briefly and pulses, so it's fine.
+// Each entry pairs the `bg-`/`text-` class as literals (so Tailwind's scanner emits
+// them) and shares one index, so the filled dot and the icon color never drift.
+// Ordered to step ~5 hues around the wheel rather than spectrally, so peers assigned
+// consecutive slots get visibly different colors instead of neighboring shades.
+const PEER_PALETTE = [
+  { dot: 'bg-orange-500', text: 'text-orange-500' },
+  { dot: 'bg-cyan-500', text: 'text-cyan-500' },
+  { dot: 'bg-fuchsia-500', text: 'text-fuchsia-500' },
+  { dot: 'bg-lime-500', text: 'text-lime-500' },
+  { dot: 'bg-violet-500', text: 'text-violet-500' },
+  { dot: 'bg-amber-500', text: 'text-amber-500' },
+  { dot: 'bg-sky-500', text: 'text-sky-500' },
+  { dot: 'bg-pink-500', text: 'text-pink-500' },
+  { dot: 'bg-teal-500', text: 'text-teal-500' },
+  { dot: 'bg-purple-500', text: 'text-purple-500' },
+  { dot: 'bg-yellow-500', text: 'text-yellow-500' },
+  { dot: 'bg-blue-500', text: 'text-blue-500' },
+] as const
+
+// FNV-1a: small, dependency-free, and well-distributed for short ids.
+function hashId(id: string): number {
+  let h = 2166136261
+  for (let i = 0; i < id.length; i++) {
+    h ^= id.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
+}
+
+export interface PeerColor { dot: string, text: string }
+
+function paletteFor(id: string): PeerColor {
+  return PEER_PALETTE[hashId(id) % PEER_PALETTE.length]!
+}
+
+// Assign palette colors by each peer's position in the sorted, de-duplicated id set.
+// This keeps colors distinct (up to the palette size) and identical across any view
+// that shares the same peer set, instead of risking per-id hash collisions. Stable
+// across restarts; a peer's color only shifts when the set of peers itself changes.
+export function buildPeerColorMap(ids: Iterable<string>): Map<string, PeerColor> {
+  const map = new Map<string, PeerColor>()
+  const unique = [...new Set(ids)].sort()
+  unique.forEach((id, i) => {
+    map.set(id, PEER_PALETTE[i % PEER_PALETTE.length]!)
+  })
+  return map
+}
+
+/** Tailwind background class for a peer's filled accent dot, stable for a given id. */
+export function peerColorClass(id: string): string {
+  return paletteFor(id).dot
+}
+
+/** Tailwind text-color class for a peer's accent (e.g. a status icon), stable for a given id. */
+export function peerColorTextClass(id: string): string {
+  return paletteFor(id).text
+}

From 8c65f9a6988895ac071ef509e7c2fb9d9b369b3f Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 12:29:24 +0200
Subject: [PATCH 21/27] feat(ui): shared settings store with adaptive polling

Centralize peers, servers, and derived peer colors into a single
useState-backed store fetched once per session, so every view stays
consistent and the config endpoints aren't refetched per component. The
store self-polls while any connector is connecting or down (and idles
once everything is connected) via a new reusable usePolling helper, which
also replaces useAutoRefresh's hand-rolled ticker. PeersSection,
ServersSection, and the dashboard now read from the store.
---
 apps/ui/app/components/PeersSection.vue   | 20 +++---
 apps/ui/app/components/ServersSection.vue | 18 +++--
 apps/ui/app/composables/useAutoRefresh.ts | 24 +++----
 apps/ui/app/composables/usePolling.ts     | 48 +++++++++++++
 apps/ui/app/composables/useSettings.ts    | 84 +++++++++++++++++++++++
 apps/ui/app/pages/index.vue               |  6 +-
 6 files changed, 166 insertions(+), 34 deletions(-)
 create mode 100644 apps/ui/app/composables/usePolling.ts
 create mode 100644 apps/ui/app/composables/useSettings.ts

diff --git a/apps/ui/app/components/PeersSection.vue b/apps/ui/app/components/PeersSection.vue
index d6ed9ae..d49beef 100644
--- a/apps/ui/app/components/PeersSection.vue
+++ b/apps/ui/app/components/PeersSection.vue
@@ -3,9 +3,7 @@ import type { BadgeProps } from '@nuxt/ui'
 import type { PeerInput, PeerItem } from '~/types/management'
 
 const { request, extractError } = useManagement()
-
-const { data, pending, error, refresh } = await useAsyncData('peers', () =>
-  request<{ peers: PeerItem[] }>('config/peers'))
+const { settings, pending, error, reload } = useSettings()
 
 const showForm = ref(false)
 const editTarget = ref<PeerItem | null>(null)
@@ -32,7 +30,8 @@ function sortKey(peer: PeerItem) {
     return 1
   return 2
 }
-const peers = computed(() => [...(data.value?.peers ?? [])].sort((a, b) => sortKey(a) - sortKey(b)))
+const peers = computed(() => [...(settings.value?.peers ?? [])].sort((a, b) => sortKey(a) - sortKey(b)))
+const peerTextClass = (id: string) => settings.value?.peerColors.get(id)?.text ?? peerColorTextClass(id)
 const connected = computed(() => peers.value.filter(p => p.initialized).length)
 const unreachable = computed(() => peers.value.filter(p => !p.initialized && p.initializationError).length)
 
@@ -72,7 +71,7 @@ async function submit(input: PeerInput, force = false) {
     else
       await request('config/peers', { method: 'POST', body: input, query })
     showForm.value = false
-    await refresh()
+    await reload()
   }
   catch (err) {
     formError.value = extractError(err, 'Could not save the peer.')
@@ -90,7 +89,7 @@ async function confirmDelete() {
   try {
     await request(`config/peers/${confirmTarget.value.id}`, { method: 'DELETE' })
     confirmTarget.value = null
-    await refresh()
+    await reload()
   }
   catch (err) {
     deleteError.value = extractError(err, 'Could not remove the peer.')
@@ -107,14 +106,14 @@ async function confirmDelete() {
       <UButton label="Add peer" icon="i-ph-plus" @click="openAdd" />
     </template>
 
-    <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load peers." />
+    <UAlert v-if="error && !settings" color="error" variant="soft" icon="i-ph-warning" title="Failed to load peers." />
 
-    <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
+    <p v-else-if="pending && !settings" class="flex items-center gap-2 text-sm text-muted">
       <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
       Loading…
     </p>
 
-    <UCard v-else-if="data && data.peers.length === 0" variant="subtle">
+    <UCard v-else-if="settings && settings.peers.length === 0" variant="subtle">
       <div class="flex flex-col items-center gap-3 py-6 text-center">
         <UIcon name="i-ph-users-three" class="size-8 text-dimmed" />
         <p class="text-sm text-muted">
@@ -124,7 +123,7 @@ async function confirmDelete() {
       </div>
     </UCard>
 
-    <div v-else-if="data" class="space-y-3">
+    <div v-else-if="settings" class="space-y-3">
       <p class="text-xs tabular-nums text-muted">
         {{ connected }} of {{ peers.length }} connected<template v-if="unreachable">
           · <span class="text-error">{{ unreachable }} unreachable</span>
@@ -136,6 +135,7 @@ async function confirmDelete() {
           v-for="peer in peers"
           :key="peer.id"
           :name="peer.name"
+          :accent-class="peerTextClass(peer.id)"
           :url="peer.url"
           :initialized="peer.initialized"
           :error="peer.initializationError"
diff --git a/apps/ui/app/components/ServersSection.vue b/apps/ui/app/components/ServersSection.vue
index aa5c35f..5efd44d 100644
--- a/apps/ui/app/components/ServersSection.vue
+++ b/apps/ui/app/components/ServersSection.vue
@@ -3,9 +3,7 @@ import type { BadgeProps } from '@nuxt/ui'
 import type { ServerInput, ServerItem } from '~/types/management'
 
 const { request, extractError } = useManagement()
-
-const { data, pending, error, refresh } = await useAsyncData('servers', () =>
-  request<{ servers: ServerItem[] }>('config/servers'))
+const { settings, pending, error, reload } = useSettings()
 
 const showForm = ref(false)
 const editTarget = ref<ServerItem | null>(null)
@@ -48,7 +46,7 @@ async function submit(input: ServerInput) {
     else
       await request('config/servers', { method: 'POST', body: input })
     showForm.value = false
-    await refresh()
+    await reload()
   }
   catch (err) {
     formError.value = extractError(err, 'Could not save the server.')
@@ -66,7 +64,7 @@ async function confirmDelete() {
   try {
     await request(`config/servers/${confirmTarget.value.id}`, { method: 'DELETE' })
     confirmTarget.value = null
-    await refresh()
+    await reload()
   }
   catch (err) {
     deleteError.value = extractError(err, 'Could not remove the server.')
@@ -98,7 +96,7 @@ function sortKey(server: ServerItem) {
     return 1
   return 2
 }
-const servers = computed(() => [...(data.value?.servers ?? [])].sort((a, b) => sortKey(a) - sortKey(b)))
+const servers = computed(() => [...(settings.value?.servers ?? [])].sort((a, b) => sortKey(a) - sortKey(b)))
 const connected = computed(() => servers.value.filter(s => s.initialized).length)
 const unreachable = computed(() => servers.value.filter(s => !s.initialized && s.initializationError).length)
 const sources = computed(() => servers.value.filter(s => s.source).length)
@@ -111,14 +109,14 @@ const destinations = computed(() => servers.value.filter(s => s.destination).len
       <UButton label="Add server" icon="i-ph-plus" @click="openAdd" />
     </template>
 
-    <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load servers." />
+    <UAlert v-if="error && !settings" color="error" variant="soft" icon="i-ph-warning" title="Failed to load servers." />
 
-    <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
+    <p v-else-if="pending && !settings" class="flex items-center gap-2 text-sm text-muted">
       <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
       Loading…
     </p>
 
-    <UCard v-else-if="data && data.servers.length === 0" variant="subtle">
+    <UCard v-else-if="settings && settings.servers.length === 0" variant="subtle">
       <div class="flex flex-col items-center gap-3 py-6 text-center">
         <UIcon name="i-ph-hard-drives" class="size-8 text-dimmed" />
         <p class="text-sm text-muted">
@@ -128,7 +126,7 @@ const destinations = computed(() => servers.value.filter(s => s.destination).len
       </div>
     </UCard>
 
-    <div v-else-if="data" class="space-y-3">
+    <div v-else-if="settings" class="space-y-3">
       <p class="text-xs tabular-nums text-muted">
         {{ connected }} of {{ servers.length }} connected<template v-if="unreachable">
           · <span class="text-error">{{ unreachable }} unreachable</span>
diff --git a/apps/ui/app/composables/useAutoRefresh.ts b/apps/ui/app/composables/useAutoRefresh.ts
index e0e25ac..5149ac0 100644
--- a/apps/ui/app/composables/useAutoRefresh.ts
+++ b/apps/ui/app/composables/useAutoRefresh.ts
@@ -40,19 +40,17 @@ export function useAutoRefresh(refresh: () => unknown | Promise<unknown>, defaul
   // means "show me fresher data now", mirroring resume-from-pause.
   watch(intervalMs, () => void refreshNow())
 
-  let ticker: ReturnType<typeof setInterval> | undefined
-  onMounted(() => {
-    ticker = setInterval(() => {
-      if (paused.value)
-        return
-      secondsLeft.value -= 1
-      if (secondsLeft.value <= 0) {
-        resetCountdown()
-        void refresh()
-      }
-    }, 1000)
-  })
-  onUnmounted(() => clearInterval(ticker))
+  // A single 1s ticker drives the countdown and fires the refresh at zero. whenVisible
+  // is off so the countdown keeps running in a background tab, as it always has.
+  usePolling(() => {
+    if (paused.value)
+      return
+    secondsLeft.value -= 1
+    if (secondsLeft.value <= 0) {
+      resetCountdown()
+      void refresh()
+    }
+  }, { intervalMs: 1000, whenVisible: false })
 
   return { REFRESH_OPTIONS, intervalMs, paused, secondsLeft, refreshNow, togglePaused }
 }
diff --git a/apps/ui/app/composables/usePolling.ts b/apps/ui/app/composables/usePolling.ts
new file mode 100644
index 0000000..981c444
--- /dev/null
+++ b/apps/ui/app/composables/usePolling.ts
@@ -0,0 +1,48 @@
+import type { MaybeRefOrGetter } from 'vue'
+
+export interface PollingOptions {
+  /** Tick interval in ms. Reactive — changing it restarts the timer. Default 5000. */
+  intervalMs?: MaybeRefOrGetter<number>
+  /** Only tick while this is true. Reactive — flipping it starts/stops the timer. Default true. */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Skip a tick while the tab is hidden (no point refetching unseen data). Default true. */
+  whenVisible?: boolean
+}
+
+/**
+ * Run `callback` on an interval while enabled, skipping ticks when the tab is hidden.
+ * Client-only, reactive to `enabled`/`intervalMs`, and self-cleaning via `onScopeDispose`
+ * — so it works both inside a component (stops on unmount) and inside a detached
+ * `effectScope` (stops when that scope is disposed).
+ */
+export function usePolling(callback: () => void | Promise<void>, options: PollingOptions = {}) {
+  const { whenVisible = true } = options
+  let timer: ReturnType<typeof setInterval> | undefined
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer)
+      timer = undefined
+    }
+  }
+
+  if (import.meta.client) {
+    watch(
+      () => [toValue(options.enabled ?? true), toValue(options.intervalMs ?? 5000)] as const,
+      ([enabled, ms]) => {
+        stop()
+        if (enabled) {
+          timer = setInterval(() => {
+            if (whenVisible && document.hidden)
+              return
+            void callback()
+          }, ms)
+        }
+      },
+      { immediate: true },
+    )
+    onScopeDispose(stop)
+  }
+
+  return { stop }
+}
diff --git a/apps/ui/app/composables/useSettings.ts b/apps/ui/app/composables/useSettings.ts
new file mode 100644
index 0000000..c1284ff
--- /dev/null
+++ b/apps/ui/app/composables/useSettings.ts
@@ -0,0 +1,84 @@
+import type { Ref } from 'vue'
+import type { PeerItem, ServerItem } from '~/types/management'
+import type { PeerColor } from '~/utils/peerColor'
+
+export interface SettingsState {
+  peers: PeerItem[]
+  servers: ServerItem[]
+  // Distinct, view-consistent colors derived once from the full peer set so callers
+  // don't recompute them on every render. See buildPeerColorMap.
+  peerColors: Map<string, PeerColor>
+}
+
+// How often to re-poll config while a connector is still settling.
+const POLL_MS = 5000
+
+let pollingStarted = false
+
+/**
+ * Poll the config endpoints only while a change is expected — i.e. some connector is
+ * still connecting or is down (and might recover). Once everything is connected there's
+ * nothing to wait on, so polling stops until the next transition. Set up once at module
+ * scope (detached effectScope) so a single poller runs no matter how many components use
+ * the store, independent of any one component's lifecycle.
+ */
+function startAdaptivePolling(settings: Ref<SettingsState | null>, reload: () => Promise<void>) {
+  if (pollingStarted || !import.meta.client)
+    return
+  pollingStarted = true
+
+  effectScope(true).run(() => {
+    const transitioning = computed(() => {
+      const s = settings.value
+      if (!s)
+        return false
+      return s.peers.some(p => !p.initialized) || s.servers.some(srv => !srv.initialized)
+    })
+    usePolling(reload, { intervalMs: POLL_MS, enabled: transitioning })
+  })
+}
+
+/**
+ * Shared connector settings (peers + servers) and their derived peer colors. Backed by
+ * a single `useState` so every view reads the same data and the config endpoints are
+ * fetched once per session. Loads lazily on first use (when the state is still null);
+ * call `reload()` to refetch after a mutation. While any connector is connecting or
+ * down, the store self-polls so a completed handshake/recovery shows without a refresh.
+ */
+export function useSettings() {
+  const { request } = useManagement()
+  const settings = useState<SettingsState | null>('settings', () => null)
+  const pending = useState('settings:pending', () => false)
+  const error = useState<unknown>('settings:error', () => null)
+
+  async function reload() {
+    pending.value = true
+    error.value = null
+    try {
+      const [peersRes, serversRes] = await Promise.all([
+        request<{ peers: PeerItem[] }>('config/peers'),
+        request<{ servers: ServerItem[] }>('config/servers'),
+      ])
+      settings.value = {
+        peers: peersRes.peers,
+        servers: serversRes.servers,
+        peerColors: buildPeerColorMap(peersRes.peers.map(p => p.id)),
+      }
+    }
+    catch (err) {
+      error.value = err
+    }
+    finally {
+      pending.value = false
+    }
+  }
+
+  // Load on first usage. `reload` flips `pending` synchronously before its first await,
+  // so concurrent callers in the same tick won't each kick off a fetch.
+  if (settings.value === null && !pending.value)
+    reload()
+
+  startAdaptivePolling(settings, reload)
+
+  return { settings, pending, error, reload }
+}
diff --git a/apps/ui/app/pages/index.vue b/apps/ui/app/pages/index.vue
index 11425ef..f2bc29d 100644
--- a/apps/ui/app/pages/index.vue
+++ b/apps/ui/app/pages/index.vue
@@ -8,6 +8,10 @@ const { data: overview, pending, error, refresh } = await useAsyncData('overview
 
 const { REFRESH_OPTIONS, intervalMs, paused, secondsLeft, togglePaused } = useAutoRefresh(refresh)
 
+// Peer colors from the shared settings store (single source, consistent across views).
+const { settings } = useSettings()
+const peerTextClass = (id: string) => settings.value?.peerColors.get(id)?.text ?? peerColorTextClass(id)
+
 // Server connection role, shown in the connections grid (e.g. "source · destination").
 function serverRole(server: { source: boolean, destination: boolean }) {
   const roles = []
@@ -133,7 +137,7 @@ function serverRole(server: { source: boolean, destination: boolean }) {
               </p>
               <div v-else class="divide-y divide-default">
                 <div v-for="peer in overview.peers.items" :key="peer.id" class="flex items-center gap-3 px-4 py-2.5">
-                  <ConnDot :initialized="peer.initialized" :error="peer.initializationError" />
+                  <ConnDot :initialized="peer.initialized" :error="peer.initializationError" :accent-class="peerTextClass(peer.id)" />
                   <span class="flex-1 truncate text-sm text-default" :title="peer.name">{{ peer.name }}</span>
                   <span class="text-xs tabular-nums" :class="peer.initialized ? 'text-muted' : 'text-error'">
                     {{ peer.initialized ? (peer.version ?? '—') : 'unreachable' }}

From a9dc73ac73bb5b5c657e021a806e813a9bd5cd8b Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 12:29:38 +0200
Subject: [PATCH 22/27] feat(catalog): instant-load skeletons and per-peer
 download picker

Load the catalog lazily and render poster skeletons so navigation is
instant, and move the filter tabs inline into the navbar. The title
detail now lists each peer as a card (release count, size, available
qualities) with its own Download button that opens the request modal
pre-targeted to that peer; single-peer titles keep a friendlier summary.
Gate the Logflix link on resolved TMDB metadata and move it under the
description, next to the metadata it relates to.
---
 .../components/CatalogPosterCardSkeleton.vue  |  14 ++
 apps/ui/app/components/CatalogTitleDetail.vue | 158 ++++++++++++++----
 .../app/components/DownloadRequestModal.vue   |  11 +-
 apps/ui/app/pages/catalog/index.vue           |  30 ++--
 4 files changed, 164 insertions(+), 49 deletions(-)
 create mode 100644 apps/ui/app/components/CatalogPosterCardSkeleton.vue

diff --git a/apps/ui/app/components/CatalogPosterCardSkeleton.vue b/apps/ui/app/components/CatalogPosterCardSkeleton.vue
new file mode 100644
index 0000000..6b72f8c
--- /dev/null
+++ b/apps/ui/app/components/CatalogPosterCardSkeleton.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// Static placeholder that mirrors CatalogPosterCard's layout so the grid keeps its
+// shape while the catalog request is in flight.
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <div class="aspect-[2/3] animate-pulse rounded-lg bg-muted ring-1 ring-default" />
+    <div class="min-w-0 space-y-1.5">
+      <div class="h-3.5 w-3/4 animate-pulse rounded bg-muted" />
+      <div class="h-3 w-12 animate-pulse rounded bg-muted" />
+    </div>
+  </div>
+</template>
diff --git a/apps/ui/app/components/CatalogTitleDetail.vue b/apps/ui/app/components/CatalogTitleDetail.vue
index d9ab2b6..68b6836 100644
--- a/apps/ui/app/components/CatalogTitleDetail.vue
+++ b/apps/ui/app/components/CatalogTitleDetail.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
-import type { CatalogTitle } from '~/types/management'
+import type { CatalogTitle, CatalogTitlePeer } from '~/types/management'
 
 const props = defineProps<{ title: CatalogTitle }>()
-const emit = defineEmits<{ download: [] }>()
+const emit = defineEmits<{ download: [peerId: string] }>()
 
 const { load, entryFor } = useCatalogMetadata()
 // Reuse the cache the grid populated; load() is a no-op if the card already fetched it.
@@ -17,11 +17,51 @@ const { src: heroImage, onError: onHeroError } = useFallbackImage(() => [
 ])
 
 onMounted(() => load(props.title))
+
+const pluralReleases = (n: number) => `${n} release${n === 1 ? '' : 's'}`
+// A single-peer title gets a friendlier phrasing; otherwise we render a card per peer
+// so the user can pick which one to download from.
+const singlePeer = computed(() => props.title.peers.length === 1 ? props.title.peers[0]! : null)
+const { dotClass } = usePeerColors()
+
+function formatResolution(res?: number): string | null {
+  if (res == null)
+    return null
+  if (res >= 2160)
+    return '4K'
+  if (res >= 1080)
+    return '1080p'
+  if (res >= 720)
+    return '720p'
+  if (res >= 480)
+    return '480p'
+  return `${res}p`
+}
+// Distinct resolution labels a peer carries, best first — the decision-relevant "what
+// quality can I get here" without listing every individual file.
+function peerResolutions(peer: CatalogTitlePeer): string[] {
+  const nums = peer.releases
+    .map(r => r.quality?.resolution)
+    .filter((n): n is number => n != null)
+  const labels = [...new Set(nums)].sort((a, b) => b - a).map(formatResolution)
+  return [...new Set(labels.filter((l): l is string => l != null))]
+}
 const canRequest = computed(() => props.title.mediaType === 'tv'
   ? props.title.tvdbId != null
   : props.title.tmdbId != null)
+// Hover hint on the Download button: explain the disabled state, or for requestable
+// TV titles clarify that the whole series is grabbed.
+const downloadHint = computed(() => {
+  if (!canRequest.value)
+    return 'This title has no matching id to request'
+  if (props.title.mediaType === 'tv')
+    return 'Downloads every available episode of this series.'
+  return null
+})
 // Logflix keys both movies and TV off the TMDB id (e.g. /movie/1301421, /tv/246461).
-const logflixUrl = computed(() => props.title.tmdbId == null
+// Only link out once TMDB metadata actually resolved — a bare id with no data means
+// the title isn't on TMDB, so the Logflix page wouldn't resolve either.
+const logflixUrl = computed(() => props.title.tmdbId == null || meta.value == null
   ? null
   : `https://logflix.eu/${props.title.mediaType}/${props.title.tmdbId}`)
 </script>
@@ -52,38 +92,90 @@ const logflixUrl = computed(() => props.title.tmdbId == null
       No description available.
     </p>
 
-    <USeparator />
+    <UTooltip :disabled="!!logflixUrl" text="No TMDB metadata found for this title." :delay-duration="0">
+      <!-- Wrap in a span so the tooltip still fires while the button is disabled:
+           a native disabled button swallows hover events, so pointer-events-none on it
+           lets them fall through to this trigger. -->
+      <span class="block">
+        <UButton
+          :to="logflixUrl ?? undefined"
+          :target="logflixUrl ? '_blank' : undefined"
+          :disabled="!logflixUrl"
+          :class="logflixUrl ? undefined : 'pointer-events-none'"
+          label="View in Logflix"
+          color="neutral"
+          variant="subtle"
+          block
+        >
+          <template #leading>
+            <img src="/logflix.svg" alt="" class="size-4">
+          </template>
+        </UButton>
+      </span>
+    </UTooltip>
 
-    <p class="text-xs text-muted">
-      {{ title.releaseCount }} release{{ title.releaseCount === 1 ? '' : 's' }} across
-      {{ title.peers.length }} peer{{ title.peers.length === 1 ? '' : 's' }} · {{ formatBytes(title.totalSize) }}
-    </p>
-    <p v-if="title.mediaType === 'tv'" class="text-xs text-muted">
-      Downloads every available episode from the chosen peer.
-    </p>
+    <USeparator />
 
-    <UTooltip :disabled="canRequest" text="This title has no matching id to request">
-      <UButton
-        label="Download"
-        icon="i-ph-download-simple"
-        :disabled="!canRequest"
-        block
-        @click="emit('download')"
-      />
-    </UTooltip>
+    <!-- Single peer: friendly summary line + one Download button. -->
+    <template v-if="singlePeer">
+      <p class="text-xs text-muted">
+        {{ pluralReleases(title.releaseCount) }} available from {{ singlePeer.name }}'s library · {{ formatBytes(title.totalSize) }}
+      </p>
+      <UTooltip :disabled="!downloadHint" :text="downloadHint ?? ''" :delay-duration="0">
+        <!-- Wrap in a span so the tooltip still fires while the button is disabled (see
+             the Logflix button above for why). -->
+        <span class="block">
+          <UButton
+            label="Download"
+            icon="i-ph-download-simple"
+            :disabled="!canRequest"
+            :class="canRequest ? undefined : 'pointer-events-none'"
+            block
+            @click="emit('download', singlePeer.id)"
+          />
+        </span>
+      </UTooltip>
+    </template>
 
-    <UButton
-      v-if="logflixUrl"
-      :to="logflixUrl"
-      target="_blank"
-      label="View in Logflix"
-      color="neutral"
-      variant="subtle"
-      block
-    >
-      <template #leading>
-        <img src="/logflix.svg" alt="" class="size-4">
-      </template>
-    </UButton>
+    <!-- Multiple peers: a card per peer so the user can pick where to download from.
+         The download grabs the whole title (best release per movie / per episode) from
+         the chosen peer, so the choice is the peer, not an individual file. -->
+    <template v-else>
+      <p class="text-xs text-muted">
+        {{ pluralReleases(title.releaseCount) }} across {{ title.peers.length }} peers · {{ formatBytes(title.totalSize) }}
+      </p>
+      <div class="space-y-2">
+        <div
+          v-for="peer in title.peers"
+          :key="peer.id"
+          class="flex items-start justify-between gap-3 rounded-lg p-3 ring-1 ring-default"
+        >
+          <div class="min-w-0 space-y-1.5">
+            <p class="flex items-center gap-1.5 text-sm font-medium text-default">
+              <span class="size-2 shrink-0 rounded-full" :class="dotClass(peer.id)" />
+              <span class="truncate">{{ peer.name }}</span>
+            </p>
+            <p class="text-xs text-muted">
+              {{ pluralReleases(peer.releaseCount) }} · {{ formatBytes(peer.totalSize) }}
+            </p>
+            <div v-if="peerResolutions(peer).length" class="flex flex-wrap gap-1">
+              <UBadge v-for="r in peerResolutions(peer)" :key="r" :label="r" size="sm" color="neutral" variant="soft" />
+            </div>
+          </div>
+          <UTooltip :disabled="!downloadHint" :text="downloadHint ?? ''" :delay-duration="0">
+            <span class="block shrink-0">
+              <UButton
+                label="Download"
+                icon="i-ph-download-simple"
+                size="sm"
+                :disabled="!canRequest"
+                :class="canRequest ? undefined : 'pointer-events-none'"
+                @click="emit('download', peer.id)"
+              />
+            </span>
+          </UTooltip>
+        </div>
+      </div>
+    </template>
   </div>
 </template>
diff --git a/apps/ui/app/components/DownloadRequestModal.vue b/apps/ui/app/components/DownloadRequestModal.vue
index 703baba..8629500 100644
--- a/apps/ui/app/components/DownloadRequestModal.vue
+++ b/apps/ui/app/components/DownloadRequestModal.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { CatalogRequestPayload, CatalogTitle, RequestServerOption } from '~/types/management'
 
-const props = defineProps<{ open: boolean, title: CatalogTitle | null, submitting?: boolean, error?: string | null }>()
+const props = defineProps<{ open: boolean, title: CatalogTitle | null, submitting?: boolean, error?: string | null, lockedPeerId?: string }>()
 const emit = defineEmits<{ 'update:open': [boolean], 'confirm': [CatalogRequestPayload] }>()
 
 // Codebase convention (see settings.vue) is a computed get/set bridge for v-model,
@@ -24,10 +24,11 @@ const rootFolderPath = ref<string | undefined>(undefined)
 
 const server = computed(() => candidates.value.find(s => s.id === serverId.value) ?? null)
 
-// Reset to the first peer whenever the title changes, so a multi-peer title always
+// Honor a peer picked from the detail view's per-peer cards (lockedPeerId); otherwise
+// reset to the first peer whenever the title changes, so a multi-peer title always
 // opens on its first peer regardless of a prior selection (matches the AC).
-watch(() => props.title?.key, () => {
-  peerId.value = peers.value[0]?.id
+watch([() => props.title?.key, () => props.lockedPeerId], () => {
+  peerId.value = props.lockedPeerId ?? peers.value[0]?.id
 }, { immediate: true })
 
 watch(candidates, (list) => {
@@ -61,7 +62,7 @@ function onConfirm() {
       </p>
 
       <div v-else class="space-y-4">
-        <UFormField v-if="peers.length > 1" label="Peer">
+        <UFormField v-if="peers.length > 1 && !lockedPeerId" label="Peer">
           <USelect
             v-model="peerId"
             :items="peers.map(p => ({ label: p.name, value: p.id }))"
diff --git a/apps/ui/app/pages/catalog/index.vue b/apps/ui/app/pages/catalog/index.vue
index 6e0d212..590644e 100644
--- a/apps/ui/app/pages/catalog/index.vue
+++ b/apps/ui/app/pages/catalog/index.vue
@@ -5,11 +5,18 @@ const { request, extractError } = useManagement()
 const { entryFor } = useCatalogMetadata()
 const toast = useToast()
 
-const { data, pending, error } = await useAsyncData(
+// Lazy (no top-level await) so navigation into the page is instant; the grid shows
+// skeletons until the catalog request resolves.
+const { data, pending, error } = useLazyAsyncData(
   'peer-catalog',
   () => request<CatalogResponse>('catalog'),
 )
 
+// Distinct, view-consistent peer colors from the shared settings store. Provided so
+// the poster badges and detail cards resolve the same color for a given peer.
+const { settings } = useSettings()
+providePeerColors(computed(() => settings.value?.peerColors ?? new Map()))
+
 const typeFilter = ref<'all' | 'movie' | 'tv'>('all')
 const titles = computed(() => {
   const all = data.value?.titles ?? []
@@ -24,11 +31,13 @@ const selected = ref<CatalogTitle | null>(null)
 
 const requestOpen = ref(false)
 const requestTitle = ref<CatalogTitle | null>(null)
+const requestPeerId = ref<string | undefined>(undefined)
 const requestSubmitting = ref(false)
 const requestError = ref<string | null>(null)
 
-function openRequest() {
+function openRequest(peerId: string) {
   requestTitle.value = selected.value
+  requestPeerId.value = peerId
   requestError.value = null
   requestOpen.value = true
 }
@@ -71,8 +80,7 @@ async function onConfirm(payload: CatalogRequestPayload) {
 <template>
   <UDashboardPanel id="catalog">
     <template #header>
-      <UDashboardNavbar title="Peer Catalog" />
-      <UDashboardToolbar>
+      <UDashboardNavbar title="Peer Catalog">
         <template #right>
           <UTabs
             v-model="typeFilter"
@@ -81,18 +89,13 @@ async function onConfirm(payload: CatalogRequestPayload) {
             :content="false"
           />
         </template>
-      </UDashboardToolbar>
+      </UDashboardNavbar>
     </template>
 
     <template #body>
       <UAlert v-if="error" color="error" variant="soft" icon="i-ph-warning" title="Failed to load the peer catalog." />
 
-      <p v-else-if="pending" class="flex items-center gap-2 text-sm text-muted">
-        <UIcon name="i-ph-circle-notch" class="size-4 animate-spin" />
-        Loading...
-      </p>
-
-      <UCard v-else-if="titles.length === 0" variant="subtle">
+      <UCard v-else-if="!pending && titles.length === 0" variant="subtle">
         <div class="flex flex-col items-center gap-3 py-6 text-center">
           <UIcon name="i-ph-film-slate" class="size-8 text-dimmed" />
           <p class="text-sm text-muted">
@@ -105,8 +108,12 @@ async function onConfirm(payload: CatalogRequestPayload) {
         v-else
         class="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-4 sm:grid-cols-[repeat(auto-fill,minmax(140px,1fr))] md:grid-cols-[repeat(auto-fill,minmax(160px,1fr))] lg:grid-cols-[repeat(auto-fill,minmax(180px,1fr))] xl:grid-cols-[repeat(auto-fill,minmax(200px,1fr))]"
       >
+        <template v-if="pending">
+          <CatalogPosterCardSkeleton v-for="n in 18" :key="n" />
+        </template>
         <CatalogPosterCard
           v-for="title in titles"
+          v-else
           :key="title.key"
           :title="title"
           @select="selected = title"
@@ -128,6 +135,7 @@ async function onConfirm(payload: CatalogRequestPayload) {
   <DownloadRequestModal
     v-model:open="requestOpen"
     :title="requestTitle"
+    :locked-peer-id="requestPeerId"
     :submitting="requestSubmitting"
     :error="requestError"
     @confirm="onConfirm"

From f4ef958bc852d2168772ac26a789f3b90364600b Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 13:13:35 +0200
Subject: [PATCH 23/27] chore(ui): reorder package metadata

---
 apps/ui/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/ui/package.json b/apps/ui/package.json
index 2e5d499..8a4f4d8 100644
--- a/apps/ui/package.json
+++ b/apps/ui/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@jack/ui",
-  "version": "0.1.0",
   "type": "module",
+  "version": "0.1.0",
   "private": true,
   "scripts": {
     "dev": "nuxt dev",

From 9645f3f859126e822f2b1419b053b0c2e56a3696 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 13:47:48 +0200
Subject: [PATCH 24/27] fix(catalog): report duplicate direct downloads
 accurately

---
 apps/backend/src/__tests__/catalog.test.ts    | 58 +++++++++++++++++++
 .../src/modules/catalog/catalog.controller.ts | 10 +++-
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 22e780d..bd909d9 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -439,6 +439,23 @@ describe('catalogController.requestDownload', () => {
     })
   })
 
+  test('reports zero starts when a duplicate movie direct download is already active', async () => {
+    const radarr = fakeServer({ add: mock(async () => 123) })
+    const peer = fakePeer({ searchByTmdbId: mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]) })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'duplicate') })
+    const controller = new CatalogController(makeConnectors([radarr], [peer]), undefined, downloads)
+
+    const result = await controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'radarr-1',
+      mediaType: 'movie',
+      tmdbId: 603,
+      rootFolderPath: '/movies',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Radarr', started: 0 })
+  })
+
   test('throws NotFoundError when the peer has no episodes for the tvdbId, and does not add', async () => {
     const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
     const peer = fakePeer({ searchByTvdbId: mock(async () => []) })
@@ -540,6 +557,47 @@ describe('catalogController.requestDownload', () => {
 
     expect(result).toEqual({ ok: true, server: 'My Sonarr', started: 1 })
   })
+
+  test('counts only newly started episode downloads when duplicates and failures are mixed', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
+    const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
+    const ep3 = episode({ id: 'ep:3', tvdbId: 81189, season: 1, episode: 3, quality: { resolution: 720 }, size: 30 })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2, ep3]) })
+    const outcomes = ['started', 'duplicate', 'failed'] as const
+    let call = 0
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => outcomes[call++] ?? 'failed') })
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]), undefined, downloads)
+
+    const result = await controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Sonarr', started: 1 })
+  })
+
+  test('reports zero starts when every episode direct download is duplicate', async () => {
+    const sonarr = fakeServer({ id: 'sonarr-1', name: 'My Sonarr', type: 'sonarr', add: mock(async () => 55) })
+    const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
+    const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
+    const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2]) })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'duplicate') })
+    const controller = new CatalogController(makeConnectors([sonarr], [peer]), undefined, downloads)
+
+    const result = await controller.requestDownload({
+      peerId: 'peer-1',
+      serverId: 'sonarr-1',
+      mediaType: 'tv',
+      tvdbId: 81189,
+      rootFolderPath: '/tv',
+    })
+
+    expect(result).toEqual({ ok: true, server: 'My Sonarr', started: 0 })
+  })
 })
 
 describe('catalogController.getTmdbStatus', () => {
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index d371b44..164b562 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -132,6 +132,8 @@ export class CatalogController {
       })
       if (result === 'failed')
         throw new BadRequestError(`Failed to start the download for tmdbId ${input.tmdbId} from peer "${peer.name}"`)
+      if (result === 'duplicate')
+        return { ok: true, server: server.name, started: 0 }
       return { ok: true, server: server.name, started: 1 }
     }
 
@@ -146,6 +148,7 @@ export class CatalogController {
 
     const seriesId = await server.add({ tvdbId: input.tvdbId, rootFolderPath: input.rootFolderPath })
     let started = 0
+    let accepted = 0
     for (const release of best) {
       const result = await this.downloads.startDirectDownload({
         peerId: peer.id,
@@ -153,10 +156,13 @@ export class CatalogController {
         destinationServerName: server.name,
         importTarget: { kind: 'series', seriesId },
       })
-      if (result !== 'failed')
+      if (result === 'failed')
+        continue
+      accepted++
+      if (result === 'started')
         started++
     }
-    if (started === 0)
+    if (accepted === 0)
       throw new BadRequestError(`Failed to start any episode download for tvdbId ${input.tvdbId} from peer "${peer.name}"`)
     return { ok: true, server: server.name, started }
   }

From 5f3d75cdd33afacf5429374cda29ccfc0e6d06a6 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 13:50:19 +0200
Subject: [PATCH 25/27] fix(catalog): avoid ambiguous grouping and retry
 metadata

---
 apps/backend/src/__tests__/catalog.test.ts    | 29 ++++++++
 .../src/modules/catalog/catalog.lib.ts        | 21 ++++--
 .../composables/useCatalogMetadata.test.ts    | 67 +++++++++++++++++++
 apps/ui/app/composables/useCatalogMetadata.ts |  7 +-
 4 files changed, 118 insertions(+), 6 deletions(-)
 create mode 100644 apps/ui/app/composables/useCatalogMetadata.test.ts

diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index bd909d9..09ce90e 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -77,6 +77,24 @@ describe('groupReleasesIntoUnifiedTitles', () => {
     expect(titles[0]!.peers.map(p => p.id).sort()).toEqual(['p1', 'p2'])
   })
 
+  test('does not alias id-less same-name releases when strong ids are ambiguous', () => {
+    const titles = groupReleasesIntoUnifiedTitles([
+      { peer: { id: 'p1', name: 'Alpha' }, releases: [movie({ title: 'The Thing', tmdbId: 1091 })] },
+      { peer: { id: 'p2', name: 'Beta' }, releases: [movie({ title: 'The Thing', tmdbId: 609 })] },
+      { peer: { id: 'p3', name: 'Gamma' }, releases: [movie({ title: 'The Thing' })] },
+    ])
+
+    const strongIds = titles
+      .map(title => title.tmdbId)
+      .filter((tmdbId): tmdbId is number => tmdbId != null)
+      .sort((a, b) => a - b)
+    const idLess = titles.find(title => title.key === 'movie:name:the thing')
+
+    expect(strongIds).toEqual([609, 1091])
+    expect(idLess?.releaseCount).toBe(1)
+    expect(idLess?.tmdbId).toBeUndefined()
+  })
+
   test('sorts unified titles by display title', () => {
     const titles = groupReleasesIntoUnifiedTitles([
       { peer: { id: 'p1', name: 'Alpha' }, releases: [movie({ title: 'Zebra', tmdbId: 1 }), movie({ title: 'Apple', tmdbId: 2 })] },
@@ -122,6 +140,17 @@ describe('pickBestPerEpisode', () => {
     expect(best).toContain(s1e2)
     expect(best).not.toContain(s1e1Sd)
   })
+
+  test('keeps unnumbered episode releases separate instead of collapsing them to one slot', () => {
+    const first = episode({ id: 'unparsed:1', tvdbId: 81189, title: 'Show.Special.A', filename: 'Show.Special.A.mkv', quality: { resolution: 720 } })
+    const second = episode({ id: 'unparsed:2', tvdbId: 81189, title: 'Show.Special.B', filename: 'Show.Special.B.mkv', quality: { resolution: 1080 } })
+
+    const best = pickBestPerEpisode([first, second])
+
+    expect(best).toHaveLength(2)
+    expect(best).toContain(first)
+    expect(best).toContain(second)
+  })
 })
 
 describe('catalogController.getCatalog', () => {
diff --git a/apps/backend/src/modules/catalog/catalog.lib.ts b/apps/backend/src/modules/catalog/catalog.lib.ts
index 9fa8837..e00c0c4 100644
--- a/apps/backend/src/modules/catalog/catalog.lib.ts
+++ b/apps/backend/src/modules/catalog/catalog.lib.ts
@@ -64,15 +64,28 @@ function nameKey(release: Release): string {
  * title tracks a per-peer bucket with that peer's release detail.
  */
 export function groupReleasesIntoUnifiedTitles(peerReleases: PeerReleases[]): UnifiedCatalogTitle[] {
-  const nameToStrongKey = new Map<string, string>()
+  const strongKeysByName = new Map<string, Set<string>>()
   for (const { releases } of peerReleases) {
     for (const release of releases) {
       const sk = strongKey(release)
-      if (sk && !nameToStrongKey.has(nameKey(release)))
-        nameToStrongKey.set(nameKey(release), sk)
+      if (!sk)
+        continue
+      const nk = nameKey(release)
+      const keys = strongKeysByName.get(nk) ?? new Set<string>()
+      keys.add(sk)
+      strongKeysByName.set(nk, keys)
     }
   }
 
+  const nameToStrongKey = new Map<string, string>()
+  for (const [nk, keys] of strongKeysByName) {
+    if (keys.size !== 1)
+      continue
+    const key = keys.values().next().value
+    if (typeof key === 'string')
+      nameToStrongKey.set(nk, key)
+  }
+
   const keyOf = (release: Release): string =>
     strongKey(release) ?? nameToStrongKey.get(nameKey(release)) ?? nameKey(release)
 
@@ -148,7 +161,7 @@ export function pickBestRelease(releases: Release[]): Release | undefined {
 export function pickBestPerEpisode(releases: Release[]): Release[] {
   const byEpisode = new Map<string, Release>()
   for (const r of releases) {
-    const key = `${r.season ?? 0}:${r.episode ?? 0}`
+    const key = r.season != null && r.episode != null ? `${r.season}:${r.episode}` : `unparsed:${r.id}`
     const current = byEpisode.get(key)
     if (!current || isBetterRelease(r, current))
       byEpisode.set(key, r)
diff --git a/apps/ui/app/composables/useCatalogMetadata.test.ts b/apps/ui/app/composables/useCatalogMetadata.test.ts
new file mode 100644
index 0000000..f51ccb7
--- /dev/null
+++ b/apps/ui/app/composables/useCatalogMetadata.test.ts
@@ -0,0 +1,67 @@
+import type { CatalogTitle, TmdbMetadata } from '~/types/management'
+import { describe, expect, test } from 'bun:test'
+import { useCatalogMetadata } from './useCatalogMetadata'
+
+type StateRef<T> = { value: T }
+type ManagementStub = { request: <T>(path: string) => Promise<T> }
+
+type NuxtComposableGlobals = typeof globalThis & {
+  useManagement: () => ManagementStub
+  useState: <T>(key: string, init: () => T) => StateRef<T>
+}
+
+const globals = globalThis as NuxtComposableGlobals
+const states = new Map<string, StateRef<unknown>>()
+
+globals.useState = <T>(key: string, init: () => T): StateRef<T> => {
+  const existing = states.get(key)
+  if (existing) {
+    // The test stub stores one stable state type per Nuxt key, matching useState's contract.
+    return existing as StateRef<T>
+  }
+  const created = { value: init() } satisfies StateRef<T>
+  states.set(key, created)
+  return created
+}
+
+describe('useCatalogMetadata', () => {
+  test('retries a metadata lookup after a transient error entry', async () => {
+    states.clear()
+    const metadata = {
+      tmdbId: 603,
+      title: 'The Matrix',
+      overview: 'A hacker learns the truth.',
+      year: 1999,
+      rating: 8.2,
+      posterUrl: 'https://image.tmdb.org/t/p/w500/poster.jpg',
+      backdropUrl: null,
+      genres: ['Action'],
+    } satisfies TmdbMetadata
+    const title = {
+      key: 'movie:id:603',
+      mediaType: 'movie',
+      tmdbId: 603,
+      displayTitle: 'The Matrix',
+      releaseCount: 1,
+      totalSize: 100,
+      peers: [],
+    } satisfies CatalogTitle
+    let calls = 0
+    globals.useManagement = () => ({
+      request: async <T>() => {
+        calls++
+        if (calls === 1)
+          throw new Error('tmdb unavailable')
+        // load() asks for TmdbMetadata | null; the generic mirrors Nuxt's request helper.
+        return metadata as T
+      },
+    })
+    const { load, entryFor } = useCatalogMetadata()
+
+    await load(title)
+    await load(title)
+
+    expect(calls).toBe(2)
+    expect(entryFor(title)).toEqual({ status: 'loaded', data: metadata })
+  })
+})
diff --git a/apps/ui/app/composables/useCatalogMetadata.ts b/apps/ui/app/composables/useCatalogMetadata.ts
index bb9eb6d..bddee0d 100644
--- a/apps/ui/app/composables/useCatalogMetadata.ts
+++ b/apps/ui/app/composables/useCatalogMetadata.ts
@@ -29,8 +29,11 @@ export function useCatalogMetadata() {
 
   async function load(title: CatalogTitle): Promise<void> {
     const key = keyFor(title)
-    // No id to look up, or already loading/loaded — don't refetch.
-    if (!key || cache.value[key])
+    if (!key)
+      return
+    const existing = cache.value[key]
+    // No id to look up, or already loading/loaded — don't refetch. Error entries retry.
+    if (existing?.status === 'loading' || existing?.status === 'loaded')
       return
     cache.value[key] = { status: 'loading', data: null }
     try {

From a134d65890f85e00774bc8e206aa63a8befa5842 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 14:01:31 +0200
Subject: [PATCH 26/27] fix(downloads): track manual import completion

---
 .../backend/drizzle/0009_bumpy_ozymandias.sql |   2 +
 apps/backend/drizzle/meta/0009_snapshot.json  | 350 ++++++++++++++++++
 apps/backend/drizzle/meta/_journal.json       |   7 +
 apps/backend/src/__tests__/catalog.test.ts    |  19 +-
 apps/backend/src/__tests__/database.test.ts   |  10 +-
 .../src/__tests__/downloads-service.test.ts   |  19 +-
 .../src/__tests__/import-watcher.test.ts      | 137 ++++++-
 .../src/__tests__/qbittorrent-api.test.ts     |   2 +
 .../src/__tests__/qbittorrent-mapper.test.ts  |   2 +
 apps/backend/src/database/schema.ts           |   2 +
 .../lib/servers/arr/arr-add-import.test.ts    |  41 +-
 apps/backend/src/lib/servers/arr/base.ts      |  38 +-
 apps/backend/src/lib/servers/arr/radarr.ts    |   6 +-
 apps/backend/src/lib/servers/arr/sonarr.ts    |  39 +-
 .../src/modules/catalog/catalog.controller.ts |   2 +
 .../modules/downloads/downloads.repository.ts |  15 +
 .../modules/downloads/downloads.service.ts    |   7 +
 .../src/modules/downloads/import-watcher.ts   | 123 +++---
 .../qbittorrent/qbittorrent.controller.ts     |   5 +-
 .../composables/useCatalogMetadata.test.ts    |   4 +-
 20 files changed, 741 insertions(+), 89 deletions(-)
 create mode 100644 apps/backend/drizzle/0009_bumpy_ozymandias.sql
 create mode 100644 apps/backend/drizzle/meta/0009_snapshot.json

diff --git a/apps/backend/drizzle/0009_bumpy_ozymandias.sql b/apps/backend/drizzle/0009_bumpy_ozymandias.sql
new file mode 100644
index 0000000..e42c843
--- /dev/null
+++ b/apps/backend/drizzle/0009_bumpy_ozymandias.sql
@@ -0,0 +1,2 @@
+ALTER TABLE `downloads` ADD `source_server_id` text;--> statement-breakpoint
+ALTER TABLE `downloads` ADD `manual_import_command_id` integer;
\ No newline at end of file
diff --git a/apps/backend/drizzle/meta/0009_snapshot.json b/apps/backend/drizzle/meta/0009_snapshot.json
new file mode 100644
index 0000000..6b9dec0
--- /dev/null
+++ b/apps/backend/drizzle/meta/0009_snapshot.json
@@ -0,0 +1,350 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "868c8329-4d5e-4af6-bbca-e9380502b247",
+  "prevId": "364866ab-f386-439e-af39-505eada0b51e",
+  "tables": {
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "downloads": {
+      "name": "downloads",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "torrent_filename": {
+          "name": "torrent_filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "peer_id": {
+          "name": "peer_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "peer_name": {
+          "name": "peer_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "filename": {
+          "name": "filename",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "dest_path": {
+          "name": "dest_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "part_path": {
+          "name": "part_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "release_size": {
+          "name": "release_size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "release_json": {
+          "name": "release_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expected_bytes": {
+          "name": "expected_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expected_bytes_source": {
+          "name": "expected_bytes_source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expected_bytes_mismatch": {
+          "name": "expected_bytes_mismatch",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        },
+        "downloaded_bytes": {
+          "name": "downloaded_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "attempts": {
+          "name": "attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "completed_at": {
+          "name": "completed_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "qb_category": {
+          "name": "qb_category",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "qb_source_server": {
+          "name": "qb_source_server",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "source_server_id": {
+          "name": "source_server_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "import_mode": {
+          "name": "import_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "import_target": {
+          "name": "import_target",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "manual_import_command_id": {
+          "name": "manual_import_command_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "downloads_status_idx": {
+          "name": "downloads_status_idx",
+          "columns": [
+            "status"
+          ],
+          "isUnique": false
+        },
+        "downloads_updated_at_idx": {
+          "name": "downloads_updated_at_idx",
+          "columns": [
+            "updated_at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {
+        "downloads_status_check": {
+          "name": "downloads_status_check",
+          "value": "\"downloads\".\"status\" in ('downloading', 'import_queued', 'imported', 'failed')"
+        },
+        "downloads_expected_bytes_source_check": {
+          "name": "downloads_expected_bytes_source_check",
+          "value": "\"downloads\".\"expected_bytes_source\" is null or \"downloads\".\"expected_bytes_source\" in ('content_length', 'content_range', 'release_size')"
+        }
+      }
+    },
+    "managed_keys": {
+      "name": "managed_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "server_id": {
+          "name": "server_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "managed_keys_key_hash_unique": {
+          "name": "managed_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/apps/backend/drizzle/meta/_journal.json b/apps/backend/drizzle/meta/_journal.json
index 7f8f9b4..040233b 100644
--- a/apps/backend/drizzle/meta/_journal.json
+++ b/apps/backend/drizzle/meta/_journal.json
@@ -64,6 +64,13 @@
       "when": 1782561669632,
       "tag": "0008_typical_rocket_racer",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1782647842534,
+      "tag": "0009_bumpy_ozymandias",
+      "breakpoints": true
     }
   ]
 }
diff --git a/apps/backend/src/__tests__/catalog.test.ts b/apps/backend/src/__tests__/catalog.test.ts
index 09ce90e..eef0c04 100644
--- a/apps/backend/src/__tests__/catalog.test.ts
+++ b/apps/backend/src/__tests__/catalog.test.ts
@@ -1,4 +1,5 @@
 import type { Release } from '../lib/release'
+import type { DownloadsService, StartQbDownloadResult } from '../modules/downloads/downloads.service'
 import { describe, expect, mock, test } from 'bun:test'
 import { BadRequestError } from '../lib/errors/BadRequestError'
 import { NotFoundError } from '../lib/errors/NotFoundError'
@@ -354,10 +355,11 @@ describe('catalogController.requestDownload', () => {
     }
   }
 
-  function fakeDownloads(overrides: Partial<{ startDirectDownload: (input: any) => Promise<string> }> = {}) {
-    return {
-      startDirectDownload: overrides.startDirectDownload ?? mock(async () => 'started'),
+  function fakeDownloads(overrides: Partial<{ startDirectDownload: (input: unknown) => Promise<StartQbDownloadResult> }> = {}): DownloadsService {
+    const testDouble = {
+      startDirectDownload: overrides.startDirectDownload ?? mock(async () => 'started' as const),
     }
+    return testDouble as unknown as DownloadsService
   }
 
   function makeConnectors(servers: any[], peers: any[] = []) {
@@ -464,6 +466,7 @@ describe('catalogController.requestDownload', () => {
       peerId: 'peer-1',
       itemId: 'rel:best',
       destinationServerName: 'My Radarr',
+      destinationServerId: 'radarr-1',
       importTarget: { kind: 'movie', movieId: 123 },
     })
   })
@@ -471,7 +474,7 @@ describe('catalogController.requestDownload', () => {
   test('reports zero starts when a duplicate movie direct download is already active', async () => {
     const radarr = fakeServer({ add: mock(async () => 123) })
     const peer = fakePeer({ searchByTmdbId: mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]) })
-    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'duplicate') })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async (): Promise<StartQbDownloadResult> => 'duplicate') })
     const controller = new CatalogController(makeConnectors([radarr], [peer]), undefined, downloads)
 
     const result = await controller.requestDownload({
@@ -525,12 +528,14 @@ describe('catalogController.requestDownload', () => {
       peerId: 'peer-1',
       itemId: 'ep:1b',
       destinationServerName: 'My Sonarr',
+      destinationServerId: 'sonarr-1',
       importTarget: { kind: 'series', seriesId: 55 },
     })
     expect(downloads.startDirectDownload).toHaveBeenCalledWith({
       peerId: 'peer-1',
       itemId: 'ep:2',
       destinationServerName: 'My Sonarr',
+      destinationServerId: 'sonarr-1',
       importTarget: { kind: 'series', seriesId: 55 },
     })
   })
@@ -538,7 +543,7 @@ describe('catalogController.requestDownload', () => {
   test('throws BadRequestError when the movie direct download fails to start', async () => {
     const radarr = fakeServer({ add: mock(async () => 123) })
     const peer = fakePeer({ searchByTmdbId: mock(async () => [movie({ id: 'rel:1', tmdbId: 603, quality: { resolution: 1080 } })]) })
-    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'failed') })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async (): Promise<StartQbDownloadResult> => 'failed') })
     const controller = new CatalogController(makeConnectors([radarr], [peer]) as any, undefined, downloads as any)
 
     await expect(controller.requestDownload({
@@ -555,7 +560,7 @@ describe('catalogController.requestDownload', () => {
     const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
     const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
     const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2]) })
-    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'failed') })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async (): Promise<StartQbDownloadResult> => 'failed') })
     const controller = new CatalogController(makeConnectors([sonarr], [peer]) as any, undefined, downloads as any)
 
     await expect(controller.requestDownload({
@@ -614,7 +619,7 @@ describe('catalogController.requestDownload', () => {
     const ep1 = episode({ id: 'ep:1', tvdbId: 81189, season: 1, episode: 1, quality: { resolution: 1080 }, size: 60 })
     const ep2 = episode({ id: 'ep:2', tvdbId: 81189, season: 1, episode: 2, quality: { resolution: 720 }, size: 40 })
     const peer = fakePeer({ searchByTvdbId: mock(async () => [ep1, ep2]) })
-    const downloads = fakeDownloads({ startDirectDownload: mock(async () => 'duplicate') })
+    const downloads = fakeDownloads({ startDirectDownload: mock(async (): Promise<StartQbDownloadResult> => 'duplicate') })
     const controller = new CatalogController(makeConnectors([sonarr], [peer]), undefined, downloads)
 
     const result = await controller.requestDownload({
diff --git a/apps/backend/src/__tests__/database.test.ts b/apps/backend/src/__tests__/database.test.ts
index 1ae17c3..1366cb5 100644
--- a/apps/backend/src/__tests__/database.test.ts
+++ b/apps/backend/src/__tests__/database.test.ts
@@ -203,7 +203,7 @@ describe('DownloadsRepository', () => {
     handle.close()
   })
 
-  test('persists qbCategory and qbSourceServer round-trip; defaults to null', async () => {
+  test('persists qB source and manual import command fields round-trip; defaults to null', async () => {
     const handle = await openDatabase({ appConfigPath: join(tempDir, 'config.jsonc') })
     const repository = new DownloadsRepository(handle.db)
 
@@ -219,12 +219,18 @@ describe('DownloadsRepository', () => {
       release,
       qbCategory: 'jack-abc12345',
       qbSourceServer: 'My Radarr',
+      sourceServerId: 'radarr-1',
+      manualImportCommandId: 77,
     })
 
     expect(withQb.qbCategory).toBe('jack-abc12345')
     expect(withQb.qbSourceServer).toBe('My Radarr')
+    expect(withQb.sourceServerId).toBe('radarr-1')
+    expect(withQb.manualImportCommandId).toBe(77)
     expect(repository.get(withQb.id)?.qbCategory).toBe('jack-abc12345')
     expect(repository.get(withQb.id)?.qbSourceServer).toBe('My Radarr')
+    expect(repository.get(withQb.id)?.sourceServerId).toBe('radarr-1')
+    expect(repository.get(withQb.id)?.manualImportCommandId).toBe(77)
 
     const withoutQb = repository.create({
       torrentFilename: 'second.torrent',
@@ -240,6 +246,8 @@ describe('DownloadsRepository', () => {
 
     expect(withoutQb.qbCategory).toBeNull()
     expect(withoutQb.qbSourceServer).toBeNull()
+    expect(withoutQb.sourceServerId).toBeNull()
+    expect(withoutQb.manualImportCommandId).toBeNull()
     handle.close()
   })
 
diff --git a/apps/backend/src/__tests__/downloads-service.test.ts b/apps/backend/src/__tests__/downloads-service.test.ts
index 3810d20..96e5fb6 100644
--- a/apps/backend/src/__tests__/downloads-service.test.ts
+++ b/apps/backend/src/__tests__/downloads-service.test.ts
@@ -77,7 +77,7 @@ describe('DownloadsService download progress persistence', () => {
     })
     const service = new DownloadsService(downloadsConfig(), { peers: [peer as any] }, repository)
 
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
     await waitForStatus(repository, 'import_queued')
 
     expect(calls).toHaveLength(1)
@@ -101,7 +101,7 @@ describe('DownloadsService download progress persistence', () => {
     } })
     const service = new DownloadsService(downloadsConfig(), { peers: [peer as any] }, repository)
 
-    const result = await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    const result = await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
 
     expect(result).toBe('failed')
     expect(repository.list()).toHaveLength(0)
@@ -118,7 +118,7 @@ describe('DownloadsService download progress persistence', () => {
     } })
     const service = new DownloadsService(downloadsConfig(), { peers: [peer as any] }, repository)
 
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
     await waitForStatus(repository, 'failed')
 
     expect(calls).toBe(1) // 404 is permanent — no retry
@@ -141,7 +141,7 @@ describe('DownloadsService download progress persistence', () => {
     })
     const service = new DownloadsService(downloadsConfig(), { peers: [peer as any] }, repository)
 
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
     await waitForStatus(repository, 'import_queued')
 
     expect(calls).toBe(2)
@@ -167,7 +167,7 @@ describe('DownloadsService download progress persistence', () => {
     })
     const service = new DownloadsService(downloadsConfig(), { peers: [peer as any] }, repository)
 
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
     await waitForStatus(repository, 'import_queued')
 
     expect(resetSpy).toHaveBeenCalledTimes(1)
@@ -197,8 +197,8 @@ describe('DownloadsService download progress persistence', () => {
     }
     const service = new DownloadsService(downloadsConfig({ maxConcurrentDownloads: 1 }), { peers: [peer as any] }, repository)
 
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
-    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:2', qbCategory: 'jack-x', qbSourceServer: 'My Radarr' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:1', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
+    await service.startQbDownload({ peerId: 'peer-1', itemId: 'movie:2', qbCategory: 'jack-x', qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
     for (let i = 0; i < 100 && repository.list().filter(d => d.status === 'import_queued').length < 2; i++)
       await Bun.sleep(10)
 
@@ -288,6 +288,7 @@ describe('DownloadsService download progress persistence', () => {
       itemId: 'movie:1',
       qbCategory: 'jack-x',
       qbSourceServer: 'My Radarr',
+      sourceServerId: 'radarr-1',
     })
 
     expect(result).toBe('started')
@@ -298,6 +299,7 @@ describe('DownloadsService download progress persistence', () => {
     expect(rows[0]?.status).toBe('import_queued')
     expect(rows[0]?.qbCategory).toBe('jack-x')
     expect(rows[0]?.qbSourceServer).toBe('My Radarr')
+    expect(rows[0]?.sourceServerId).toBe('radarr-1')
     handle.close()
   })
 
@@ -312,6 +314,7 @@ describe('DownloadsService download progress persistence', () => {
       itemId: 'movie:1',
       qbCategory: 'jack-x',
       qbSourceServer: 'My Radarr',
+      sourceServerId: 'radarr-1',
     })
 
     expect(result).toBe('failed')
@@ -328,6 +331,7 @@ describe('DownloadsService download progress persistence', () => {
       peerId: 'peer-1',
       itemId: 'movie:1',
       destinationServerName: 'My Radarr',
+      destinationServerId: 'radarr-1',
       importTarget: { kind: 'movie', movieId: 42 },
     })
 
@@ -338,6 +342,7 @@ describe('DownloadsService download progress persistence', () => {
     expect(rows).toHaveLength(1)
     expect(rows[0]?.status).toBe('import_queued')
     expect(rows[0]?.qbSourceServer).toBe('My Radarr')
+    expect(rows[0]?.sourceServerId).toBe('radarr-1')
     expect(rows[0]?.importMode).toBe('jack_manual')
     expect(rows[0]?.importTarget).toEqual({ kind: 'movie', movieId: 42 })
     handle.close()
diff --git a/apps/backend/src/__tests__/import-watcher.test.ts b/apps/backend/src/__tests__/import-watcher.test.ts
index f62f72d..1ee12c0 100644
--- a/apps/backend/src/__tests__/import-watcher.test.ts
+++ b/apps/backend/src/__tests__/import-watcher.test.ts
@@ -1,3 +1,4 @@
+import type { ArrServerConnector, ManualImportParams } from '../lib/servers/arr/base'
 import type { DownloadsRepository } from '../modules/downloads/downloads.repository'
 import { dirname } from 'node:path'
 import { Database } from 'bun:sqlite'
@@ -5,6 +6,7 @@ import { describe, expect, mock, test } from 'bun:test'
 import { drizzle } from 'drizzle-orm/bun-sqlite'
 import { runMigrations } from '../database/connection'
 import * as schema from '../database/schema'
+import { PermanentManualImportError } from '../lib/servers/arr/base'
 import { DownloadsRepository as Repo } from '../modules/downloads/downloads.repository'
 import { ImportWatcher } from '../modules/downloads/import-watcher'
 import { deriveHash } from '../modules/qbittorrent/qbittorrent.mapper'
@@ -115,20 +117,22 @@ function manualRow(repo: DownloadsRepository, qbSourceServer: string) {
   return row
 }
 
-function manualServer(name: string, importedHashes: string[], manualImport: (params: unknown) => Promise<void>, opts: { initialized?: boolean } = {}) {
+function manualServer(name: string, importedHashes: string[], manualImport: (params: ManualImportParams) => Promise<number>, opts: { initialized?: boolean } = {}): ArrServerConnector {
   return {
+    id: name,
     name,
     isInitialized: opts.initialized ?? true,
     recentlyImportedDownloadIds: async () => new Set(importedHashes.map(h => h.toLowerCase())),
     manualImport,
-  } as any
+    manualImportCommandStatus: async () => ({ state: 'pending' as const }),
+  } as unknown as ArrServerConnector
 }
 
 describe('ImportWatcher jack_manual trigger', () => {
   test('pushes manualImport once across two ticks while the hash is absent from history', async () => {
     const repo = makeRepo()
     const row = manualRow(repo, 'My Radarr')
-    const manualImport = mock(async () => {})
+    const manualImport = mock(async () => 101)
     const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
 
     await watcher.tick()
@@ -140,6 +144,7 @@ describe('ImportWatcher jack_manual trigger', () => {
       paths: [row.destPath],
       target: { kind: 'movie', movieId: 42 },
       downloadId: HASH,
+      release,
     })
     expect(repo.get(row.id)?.status).toBe('import_queued')
   })
@@ -147,7 +152,7 @@ describe('ImportWatcher jack_manual trigger', () => {
   test('marks the row imported (and skips the push) once the hash appears in *arr history', async () => {
     const repo = makeRepo()
     const row = manualRow(repo, 'My Radarr')
-    const manualImport = mock(async () => {})
+    const manualImport = mock(async () => 102)
     const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [HASH], manualImport)] }, 1000)
 
     expect(await watcher.tick()).toBe(1)
@@ -155,17 +160,17 @@ describe('ImportWatcher jack_manual trigger', () => {
     expect(manualImport).not.toHaveBeenCalled()
   })
 
-  test('re-triggers after a restart (a fresh watcher with an empty triggered set)', async () => {
+  test('does not re-trigger after a restart once the manual import command id is persisted', async () => {
     const repo = makeRepo()
     manualRow(repo, 'My Radarr')
-    const manualImport = mock(async () => {})
+    const manualImport = mock(async () => 103)
     const first = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
     await first.tick()
     expect(manualImport).toHaveBeenCalledTimes(1)
 
     const second = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
     await second.tick()
-    expect(manualImport).toHaveBeenCalledTimes(2)
+    expect(manualImport).toHaveBeenCalledTimes(1)
   })
 
   test('retries on the next tick when the manual-import push throws', async () => {
@@ -176,6 +181,7 @@ describe('ImportWatcher jack_manual trigger', () => {
       calls++
       if (calls === 1)
         throw new Error('arr down')
+      return 104
     })
     const watcher = new ImportWatcher(repo, { servers: [manualServer('My Radarr', [], manualImport)] }, 1000)
 
@@ -184,3 +190,120 @@ describe('ImportWatcher jack_manual trigger', () => {
     expect(manualImport).toHaveBeenCalledTimes(2)
   })
 })
+
+type TestManualImportCommandState
+  = | { state: 'pending' }
+    | { state: 'completed' }
+    | { state: 'failed', error: string }
+
+interface ImportWatcherServer {
+  id: string
+  name: string
+  isInitialized: boolean
+  recentlyImportedDownloadIds: () => Promise<Set<string>>
+  manualImport: (params: ManualImportParams) => Promise<number>
+  manualImportCommandStatus: (commandId: number) => Promise<TestManualImportCommandState>
+}
+
+function watcherWithServers(repo: DownloadsRepository, servers: ImportWatcherServer[]) {
+  // Test fakes implement only the ArrServerConnector surface that ImportWatcher calls.
+  return new ImportWatcher(repo, { servers: servers as unknown as ArrServerConnector[] }, 1000)
+}
+
+function manualImportRow(repo: DownloadsRepository, input: { qbSourceServer: string, sourceServerId: string }) {
+  const row = repo.create({
+    torrentFilename: 't.torrent',
+    peerId: 'peer-1',
+    peerName: 'Friend',
+    itemId: 'movie:1',
+    filename: release.filename,
+    destPath: '/tmp/movies/x.mkv',
+    partPath: '/tmp/movies/x.mkv.part',
+    releaseSize: release.size,
+    release,
+    qbSourceServer: input.qbSourceServer,
+    sourceServerId: input.sourceServerId,
+    importMode: 'jack_manual',
+    importTarget: { kind: 'movie', movieId: 42 },
+  })
+  repo.markImportQueued(row.id)
+  return row
+}
+
+describe('ImportWatcher tracked manual imports', () => {
+  test('resolves queued rows by stable server id after a destination rename', async () => {
+    const repo = makeRepo()
+    const row = manualImportRow(repo, { qbSourceServer: 'Old Radarr', sourceServerId: 'radarr-1' })
+    const server: ImportWatcherServer = {
+      id: 'radarr-1',
+      name: 'New Radarr',
+      isInitialized: true,
+      recentlyImportedDownloadIds: async () => new Set(),
+      manualImport: async () => 41,
+      manualImportCommandStatus: async () => ({ state: 'pending' }),
+    }
+    const watcher = watcherWithServers(repo, [server])
+
+    await watcher.tick()
+
+    expect(repo.get(row.id)?.manualImportCommandId).toBe(41)
+  })
+
+  test('marks a manual import row imported when the tracked command completes', async () => {
+    const repo = makeRepo()
+    const row = manualImportRow(repo, { qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
+    const server: ImportWatcherServer = {
+      id: 'radarr-1',
+      name: 'My Radarr',
+      isInitialized: true,
+      recentlyImportedDownloadIds: async () => new Set(),
+      manualImport: async () => 42,
+      manualImportCommandStatus: async () => ({ state: 'completed' }),
+    }
+    const watcher = watcherWithServers(repo, [server])
+
+    await watcher.tick()
+    await watcher.tick()
+
+    expect(repo.get(row.id)?.status).toBe('imported')
+  })
+
+  test('marks a manual import row failed when the tracked command fails', async () => {
+    const repo = makeRepo()
+    const row = manualImportRow(repo, { qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
+    const server: ImportWatcherServer = {
+      id: 'radarr-1',
+      name: 'My Radarr',
+      isInitialized: true,
+      recentlyImportedDownloadIds: async () => new Set(),
+      manualImport: async () => 43,
+      manualImportCommandStatus: async () => ({ state: 'failed', error: 'manual import rejected' }),
+    }
+    const watcher = watcherWithServers(repo, [server])
+
+    await watcher.tick()
+    await watcher.tick()
+
+    expect(repo.get(row.id)).toMatchObject({ status: 'failed', error: 'manual import rejected' })
+  })
+
+  test('marks a manual import row failed when the connector reports a permanent import error', async () => {
+    const repo = makeRepo()
+    const row = manualImportRow(repo, { qbSourceServer: 'My Radarr', sourceServerId: 'radarr-1' })
+    const server: ImportWatcherServer = {
+      id: 'radarr-1',
+      name: 'My Radarr',
+      isInitialized: true,
+      recentlyImportedDownloadIds: async () => new Set(),
+      manualImport: async () => {
+        throw new PermanentManualImportError('episode ids could not be resolved')
+      },
+      manualImportCommandStatus: async () => ({ state: 'pending' }),
+    }
+    const watcher = watcherWithServers(repo, [server])
+
+    await watcher.tick()
+
+    expect(repo.get(row.id)).toMatchObject({ status: 'failed', error: 'episode ids could not be resolved' })
+  })
+})
diff --git a/apps/backend/src/__tests__/qbittorrent-api.test.ts b/apps/backend/src/__tests__/qbittorrent-api.test.ts
index c142f7f..98a0521 100644
--- a/apps/backend/src/__tests__/qbittorrent-api.test.ts
+++ b/apps/backend/src/__tests__/qbittorrent-api.test.ts
@@ -67,6 +67,7 @@ function seedDownload(repository: DownloadsRepository, category: string) {
     release: { id: 'conn:movie:42', title: 'Big Buck Bunny', filename: 'Big Buck Bunny (2008).mkv', category: 2000, size: 10 } as any,
     qbCategory: category,
     qbSourceServer: 'My Radarr',
+    sourceServerId: 'abc12345',
   })
 }
 
@@ -220,6 +221,7 @@ describe('qBittorrent add/delete/setCategory', () => {
     expect(calls[0].itemId).toBe('conn:movie:42')
     expect(calls[0].qbCategory).toBe('jack-abc12345')
     expect(calls[0].qbSourceServer).toBe('My Radarr')
+    expect(calls[0].sourceServerId).toBe('abc12345')
   })
 
   test('add returns 503 when startQbDownload fails so *arr retries promptly', async () => {
diff --git a/apps/backend/src/__tests__/qbittorrent-mapper.test.ts b/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
index d88be65..7d37c25 100644
--- a/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
+++ b/apps/backend/src/__tests__/qbittorrent-mapper.test.ts
@@ -26,8 +26,10 @@ function baseRecord(overrides: Partial<DownloadRecord> = {}): DownloadRecord {
     error: null,
     qbCategory: 'jack-abc12345',
     qbSourceServer: 'My Radarr',
+    sourceServerId: 'abc12345',
     importMode: null,
     importTarget: null,
+    manualImportCommandId: null,
     ...overrides,
   }
 }
diff --git a/apps/backend/src/database/schema.ts b/apps/backend/src/database/schema.ts
index c94ef1a..d808f92 100644
--- a/apps/backend/src/database/schema.ts
+++ b/apps/backend/src/database/schema.ts
@@ -33,11 +33,13 @@ export const downloads = sqliteTable('downloads', {
   // download (→ *arr-pull import, no jack push). Null for blackhole-added rows.
   qbCategory: text('qb_category'),
   qbSourceServer: text('qb_source_server'),
+  sourceServerId: text('source_server_id'),
   // Direct catalog downloads: 'jack_manual' means the import watcher must push an
   // explicit *arr ManualImport (vs. null = qB/blackhole, where *arr imports itself).
   importMode: text('import_mode').$type<'jack_manual' | null>(),
   // JSON ManualImportTarget: {"kind":"movie","movieId":N} | {"kind":"series","seriesId":N}.
   importTarget: text('import_target'),
+  manualImportCommandId: integer('manual_import_command_id'),
 }, t => [
   check('downloads_status_check', sql`${t.status} in ('downloading', 'import_queued', 'imported', 'failed')`),
   check('downloads_expected_bytes_source_check', sql`${t.expectedBytesSource} is null or ${t.expectedBytesSource} in ('content_length', 'content_range', 'release_size')`),
diff --git a/apps/backend/src/lib/servers/arr/arr-add-import.test.ts b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
index 41c854b..0ea6565 100644
--- a/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
+++ b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
@@ -149,7 +149,7 @@ describe('RadarrServerConnector.manualImport', () => {
     )
 
     const radarr = makeRadarr()
-    await radarr.manualImport({
+    const commandId = await radarr.manualImport({
       folder: '/downloads',
       paths: ['/downloads/Movie.mkv'],
       target: { kind: 'movie', movieId: 7 },
@@ -157,6 +157,7 @@ describe('RadarrServerConnector.manualImport', () => {
     })
 
     const body = CommandBody.parse(commandBody)
+    expect(commandId).toBe(1)
     expect(body.name).toBe('ManualImport')
     expect(body.importMode).toBe('move')
     expect(body.files).toHaveLength(1)
@@ -266,7 +267,8 @@ describe('SonarrServerConnector.manualImport', () => {
     )
 
     const sonarr = makeSonarr()
-    await sonarr.manualImport({
+
+    const commandId = await sonarr.manualImport({
       folder: '/downloads',
       paths: ['/downloads/Ep.mkv'],
       target: { kind: 'series', seriesId: 3 },
@@ -274,6 +276,7 @@ describe('SonarrServerConnector.manualImport', () => {
     })
 
     const body = CommandBody.parse(commandBody)
+    expect(commandId).toBe(1)
     expect(body.name).toBe('ManualImport')
     expect(body.importMode).toBe('move')
     expect(body.files).toHaveLength(1)
@@ -287,6 +290,40 @@ describe('SonarrServerConnector.manualImport', () => {
     })
   })
 
+  test('falls back to release season and episode when Sonarr cannot parse episode ids', async () => {
+    let commandBody: unknown = null
+    server.use(
+      http.get(`${SONARR_URL}/api/v3/manualimport`, () => HttpResponse.json([
+        { path: '/downloads/Ep.mkv', quality: { quality: { id: 4 } }, languages: [{ id: 1, name: 'English' }], releaseGroup: 'GRP', episodes: [] },
+      ])),
+      http.get(`${SONARR_URL}/api/v3/episode`, () => HttpResponse.json([
+        { id: 22, seasonNumber: 1, episodeNumber: 2 },
+      ])),
+      http.post(`${SONARR_URL}/api/v3/command`, async ({ request }) => {
+        commandBody = await request.json()
+        return HttpResponse.json({ id: 2 })
+      }),
+    )
+
+    const sonarr = makeSonarr()
+    const commandId = await sonarr.manualImport({
+      folder: '/downloads',
+      paths: ['/downloads/Ep.mkv'],
+      target: { kind: 'series', seriesId: 3 },
+      downloadId: 'dl-2',
+      release: { season: 1, episode: 2 },
+    })
+
+    const body = CommandBody.parse(commandBody)
+    expect(commandId).toBe(2)
+    expect(body.files[0]).toMatchObject({
+      path: '/downloads/Ep.mkv',
+      seriesId: 3,
+      episodeIds: [22],
+      downloadId: 'dl-2',
+    })
+  })
+
   test('throws BadRequestError when given a movie target', async () => {
     const sonarr = makeSonarr()
     await expect(sonarr.manualImport({
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index 1247fd5..2f6591d 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -33,6 +33,11 @@ export const DestinationServerHealthIssue = z.array(
 // *arr returns the saved download client on create; we only need its id to bind
 // the auto-registered indexer to it.
 const DownloadClientResource = z.object({ id: z.number().int() })
+const CommandResource = z.object({
+  id: z.number().int().optional(),
+  status: z.string().nullable().optional(),
+  message: z.string().nullable().optional(),
+})
 
 // Register the Jack client at *arr's lowest selectable priority (the UI caps it
 // at 50). *arr's general client pool only round-robins among the best-priority
@@ -61,6 +66,20 @@ export interface ManualImportParams {
   target: ManualImportTarget
   /** Stub infohash = deriveHash(title,size); recorded in *arr history so the watcher matches it. */
   downloadId: string
+  /** Original release numbering, used as a Sonarr fallback when filename parsing omits episode ids. */
+  release?: Pick<Release, 'season' | 'episode'>
+}
+
+export type ManualImportCommandState
+  = | { state: 'pending' }
+    | { state: 'completed' }
+    | { state: 'failed', error: string }
+
+export class PermanentManualImportError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PermanentManualImportError'
+  }
 }
 
 export function basename(path: string): string {
@@ -216,11 +235,26 @@ export abstract class ArrServerConnector extends ServerConnector {
   /** Import already-downloaded file(s) into this *arr, mapped to `target`. */
   @requiresDestination
   @requiresInitialization
-  async manualImport(params: ManualImportParams): Promise<void> {
+  async manualImport(params: ManualImportParams): Promise<number> {
     return this.doManualImport(params)
   }
 
-  protected abstract doManualImport(params: ManualImportParams): Promise<void>
+  protected abstract doManualImport(params: ManualImportParams): Promise<number>
+
+  /** Current state for a previously accepted ManualImport command. */
+  @requiresDestination
+  @requiresInitialization
+  async manualImportCommandStatus(commandId: number): Promise<ManualImportCommandState> {
+    const command = await this.fetch(`/api/v3/command/${commandId}`, { method: 'GET', schema: CommandResource })
+    const status = command.status?.toLowerCase()
+    if (status === 'completed')
+      return { state: 'completed' }
+    if (status === 'failed' || status === 'aborted' || status === 'cancelled') {
+      const message = command.message ?? `Manual import command ${commandId} ${status}`
+      return { state: 'failed', error: message }
+    }
+    return { state: 'pending' }
+  }
 
   /** First quality profile id — required to add a title (manual import detects real quality from the file). */
   protected async resolveQualityProfileId(): Promise<number> {
diff --git a/apps/backend/src/lib/servers/arr/radarr.ts b/apps/backend/src/lib/servers/arr/radarr.ts
index c4c738b..63876df 100644
--- a/apps/backend/src/lib/servers/arr/radarr.ts
+++ b/apps/backend/src/lib/servers/arr/radarr.ts
@@ -195,7 +195,7 @@ export class RadarrServerConnector extends ArrServerConnector {
     return created.id
   }
 
-  protected override async doManualImport(params: ManualImportParams): Promise<void> {
+  protected override async doManualImport(params: ManualImportParams): Promise<number> {
     if (params.target.kind !== 'movie')
       throw new BadRequestError(`Radarr cannot import a "${params.target.kind}" target`)
     const { movieId } = params.target
@@ -219,10 +219,12 @@ export class RadarrServerConnector extends ArrServerConnector {
     if (files.length === 0)
       throw new BadRequestError(`Radarr found no importable file for movie ${movieId} in ${params.folder}`)
 
-    await this.fetch('/api/v3/command', {
+    const command = await this.fetch('/api/v3/command', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name: 'ManualImport', importMode: 'move', files }),
+      schema: CreatedId,
     })
+    return command.id
   }
 }
diff --git a/apps/backend/src/lib/servers/arr/sonarr.ts b/apps/backend/src/lib/servers/arr/sonarr.ts
index 6cae646..8da820f 100644
--- a/apps/backend/src/lib/servers/arr/sonarr.ts
+++ b/apps/backend/src/lib/servers/arr/sonarr.ts
@@ -7,7 +7,7 @@ import { BadRequestError } from '../../errors/BadRequestError'
 import { ReleaseCategory } from '../../release'
 import { setSpanAttributes } from '../../span-attributes'
 import { withSpan } from '../../tracing'
-import { ArrServerConnector, basename, stripExtension } from './base'
+import { ArrServerConnector, basename, PermanentManualImportError, stripExtension } from './base'
 
 type SeriesWithId = SeriesResource & { id: number }
 
@@ -90,6 +90,16 @@ export class SonarrServerConnector extends ArrServerConnector {
     return Array.isArray(episodes) ? episodes : []
   }
 
+  private async episodeIdsFromRelease(seriesId: number, release: ManualImportParams['release']): Promise<number[]> {
+    if (release?.season == null || release.episode == null)
+      return []
+    const episodes = await this.listEpisodes(seriesId)
+    return episodes
+      .filter(e => e.seasonNumber === release.season && e.episodeNumber === release.episode)
+      .map(e => e.id)
+      .filter((id): id is number => id != null)
+  }
+
   private async releasesForSeries(series: SeriesWithId, filter?: (e: EpisodeResource) => boolean): Promise<Release[]> {
     const episodes = await this.listEpisodes(series.id)
     return episodes
@@ -211,7 +221,7 @@ export class SonarrServerConnector extends ArrServerConnector {
     return created.id
   }
 
-  protected override async doManualImport(params: ManualImportParams): Promise<void> {
+  protected override async doManualImport(params: ManualImportParams): Promise<number> {
     if (params.target.kind !== 'series')
       throw new BadRequestError(`Sonarr cannot import a "${params.target.kind}" target`)
     const { seriesId } = params.target
@@ -222,25 +232,34 @@ export class SonarrServerConnector extends ArrServerConnector {
       filterExistingFiles: 'false',
     })
     const wanted = new Set(params.paths)
-    const files = (Array.isArray(candidates) ? candidates : [])
+    const matches = (Array.isArray(candidates) ? candidates : [])
       .filter((c): c is SonarrManualImportCandidate & { path: string } => typeof c.path === 'string' && wanted.has(c.path))
-      .map(c => ({
+    if (matches.length === 0)
+      throw new BadRequestError(`Sonarr found no importable episode file for series ${seriesId} in ${params.folder}`)
+
+    const fallbackEpisodeIds = await this.episodeIdsFromRelease(seriesId, params.release)
+    const files = matches.map((c) => {
+      const parsedEpisodeIds = (c.episodes ?? []).map(e => e.id).filter((id): id is number => id != null)
+      const episodeIds = parsedEpisodeIds.length > 0 ? parsedEpisodeIds : fallbackEpisodeIds
+      if (episodeIds.length === 0)
+        throw new PermanentManualImportError(`Sonarr could not resolve episode ids for ${c.path}`)
+      return {
         path: c.path,
         seriesId,
-        episodeIds: (c.episodes ?? []).map(e => e.id).filter((id): id is number => id != null),
+        episodeIds,
         quality: c.quality,
         languages: c.languages ?? [],
         releaseGroup: c.releaseGroup ?? '',
         downloadId: params.downloadId,
-      }))
-      .filter(f => f.episodeIds.length > 0)
-    if (files.length === 0)
-      throw new BadRequestError(`Sonarr found no importable episode file for series ${seriesId} in ${params.folder}`)
+      }
+    })
 
-    await this.fetch('/api/v3/command', {
+    const command = await this.fetch('/api/v3/command', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name: 'ManualImport', importMode: 'move', files }),
+      schema: CreatedId,
     })
+    return command.id
   }
 }
diff --git a/apps/backend/src/modules/catalog/catalog.controller.ts b/apps/backend/src/modules/catalog/catalog.controller.ts
index 164b562..be0163c 100644
--- a/apps/backend/src/modules/catalog/catalog.controller.ts
+++ b/apps/backend/src/modules/catalog/catalog.controller.ts
@@ -128,6 +128,7 @@ export class CatalogController {
         peerId: peer.id,
         itemId: best.id,
         destinationServerName: server.name,
+        destinationServerId: server.id,
         importTarget: { kind: 'movie', movieId },
       })
       if (result === 'failed')
@@ -153,6 +154,7 @@ export class CatalogController {
       const result = await this.downloads.startDirectDownload({
         peerId: peer.id,
         itemId: release.id,
+        destinationServerId: server.id,
         destinationServerName: server.name,
         importTarget: { kind: 'series', seriesId },
       })
diff --git a/apps/backend/src/modules/downloads/downloads.repository.ts b/apps/backend/src/modules/downloads/downloads.repository.ts
index 74f6c49..d976d14 100644
--- a/apps/backend/src/modules/downloads/downloads.repository.ts
+++ b/apps/backend/src/modules/downloads/downloads.repository.ts
@@ -28,8 +28,10 @@ export interface DownloadRecord {
   error: string | null
   qbCategory: string | null
   qbSourceServer: string | null
+  sourceServerId: string | null
   importMode: 'jack_manual' | null
   importTarget: ManualImportTarget | null
+  manualImportCommandId: number | null
 }
 
 export interface CreateDownloadInput {
@@ -44,8 +46,10 @@ export interface CreateDownloadInput {
   release: Release
   qbCategory?: string | null
   qbSourceServer?: string | null
+  sourceServerId?: string | null
   importMode?: 'jack_manual' | null
   importTarget?: ManualImportTarget | null
+  manualImportCommandId?: number | null
 }
 
 function nowIso() {
@@ -76,8 +80,10 @@ function toRecord(row: DownloadRow): DownloadRecord {
     error: row.error,
     qbCategory: row.qbCategory ?? null,
     qbSourceServer: row.qbSourceServer ?? null,
+    sourceServerId: row.sourceServerId ?? null,
     importMode: row.importMode ?? null,
     importTarget: row.importTarget ? (JSON.parse(row.importTarget) as ManualImportTarget) : null,
+    manualImportCommandId: row.manualImportCommandId ?? null,
   }
 }
 
@@ -98,8 +104,10 @@ export class DownloadsRepository {
       releaseJson: JSON.stringify(input.release),
       qbCategory: input.qbCategory ?? null,
       qbSourceServer: input.qbSourceServer ?? null,
+      sourceServerId: input.sourceServerId ?? null,
       importMode: input.importMode ?? null,
       importTarget: input.importTarget ? JSON.stringify(input.importTarget) : null,
+      manualImportCommandId: input.manualImportCommandId ?? null,
       downloadedBytes: 0,
       status: 'downloading',
       startedAt: timestamp,
@@ -161,6 +169,13 @@ export class DownloadsRepository {
       .run()
   }
 
+  setManualImportCommand(id: number, commandId: number): void {
+    this.db.update(downloads)
+      .set({ manualImportCommandId: commandId, updatedAt: nowIso() })
+      .where(eq(downloads.id, id))
+      .run()
+  }
+
   markFailed(id: number, error: string): void {
     this.db.update(downloads)
       .set({ status: 'failed', error, updatedAt: nowIso() })
diff --git a/apps/backend/src/modules/downloads/downloads.service.ts b/apps/backend/src/modules/downloads/downloads.service.ts
index 6ccbc08..3f1dd0f 100644
--- a/apps/backend/src/modules/downloads/downloads.service.ts
+++ b/apps/backend/src/modules/downloads/downloads.service.ts
@@ -60,6 +60,7 @@ export class DownloadsService {
     torrentFilename: string
     qbCategory?: string | null
     qbSourceServer?: string | null
+    sourceServerId?: string | null
     importMode?: 'jack_manual' | null
     importTarget?: ManualImportTarget | null
   }): Promise<CreateDownloadOutcome> {
@@ -102,6 +103,7 @@ export class DownloadsService {
       release,
       qbCategory: input.qbCategory ?? null,
       qbSourceServer: input.qbSourceServer ?? null,
+      sourceServerId: input.sourceServerId ?? null,
       importMode: input.importMode ?? null,
       importTarget: input.importTarget ?? null,
     })
@@ -131,8 +133,10 @@ export class DownloadsService {
         error: null,
         qbCategory: input.qbCategory ?? null,
         qbSourceServer: input.qbSourceServer ?? null,
+        sourceServerId: input.sourceServerId ?? null,
         importMode: input.importMode ?? null,
         importTarget: input.importTarget ?? null,
+        manualImportCommandId: null,
       },
     }
   }
@@ -146,6 +150,7 @@ export class DownloadsService {
     itemId: string
     qbCategory: string
     qbSourceServer: string
+    sourceServerId: string
   }): Promise<StartQbDownloadResult> {
     // qB-added downloads have no on-disk stub, but createDownload + the row still
     // need a stable filename.
@@ -180,6 +185,7 @@ export class DownloadsService {
     peerId: string
     itemId: string
     destinationServerName: string
+    destinationServerId: string
     importTarget: ManualImportTarget
   }): Promise<StartQbDownloadResult> {
     const torrentFilename = `direct-${input.peerId}-${input.itemId}.torrent`.replace(UNSAFE_FILENAME_CHARS, '_')
@@ -190,6 +196,7 @@ export class DownloadsService {
         itemId: input.itemId,
         torrentFilename,
         qbSourceServer: input.destinationServerName,
+        sourceServerId: input.destinationServerId,
         importMode: 'jack_manual',
         importTarget: input.importTarget,
       })
diff --git a/apps/backend/src/modules/downloads/import-watcher.ts b/apps/backend/src/modules/downloads/import-watcher.ts
index fababf2..966ec2b 100644
--- a/apps/backend/src/modules/downloads/import-watcher.ts
+++ b/apps/backend/src/modules/downloads/import-watcher.ts
@@ -1,6 +1,7 @@
 import type { ArrServerConnector } from '../../lib/servers/arr/base'
-import type { DownloadsRepository } from './downloads.repository'
+import type { DownloadRecord, DownloadsRepository } from './downloads.repository'
 import { dirname } from 'node:path'
+import { PermanentManualImportError } from '../../lib/servers/arr/base'
 import { logger } from '../../logger'
 import { deriveHash } from '../qbittorrent/qbittorrent.mapper'
 
@@ -14,13 +15,6 @@ import { deriveHash } from '../qbittorrent/qbittorrent.mapper'
  */
 export class ImportWatcher {
   private timer?: ReturnType<typeof setInterval>
-  // Rows we've already pushed a ManualImport for this process (avoids re-POSTing
-  // every tick). Only added on a SUCCESSFUL push (inside the try, after the await),
-  // so a failed trigger is retried next tick. A restart clears the set; re-triggering
-  // is safe — *arr ignores a ManualImport whose file no longer exists at `path`
-  // (already moved/imported), and the row only leaves `import_queued` once the
-  // history hash confirms the import.
-  private readonly manualImportTriggered = new Set<number>()
 
   constructor(
     private readonly repository: DownloadsRepository,
@@ -30,6 +24,15 @@ export class ImportWatcher {
     private readonly intervalMs: number,
   ) {}
 
+  private connectorFor(row: DownloadRecord): ArrServerConnector | undefined {
+    if (row.sourceServerId) {
+      const byId = this.connectorManager.servers.find(s => s.id === row.sourceServerId)
+      if (byId)
+        return byId
+    }
+    return row.qbSourceServer ? this.connectorManager.servers.find(s => s.name === row.qbSourceServer) : undefined
+  }
+
   start(): void {
     if (this.timer)
       return
@@ -52,59 +55,85 @@ export class ImportWatcher {
 
   /** One reconciliation pass. Returns how many downloads it marked imported. */
   async tick(): Promise<number> {
-    // Only qB-added downloads (qbSourceServer set) are imported by an *arr we can
-    // poll; blackhole rows have no server to ask, so they're left as-is.
-    const queued = this.repository.listByStatus('import_queued').filter(r => r.qbSourceServer)
+    // Only rows with an owning destination can be reconciled; blackhole rows have
+    // no server to poll, so they're left as-is.
+    const queued = this.repository.listByStatus('import_queued').filter(r => r.sourceServerId || r.qbSourceServer)
     if (queued.length === 0)
       return 0
 
-    const byServer = new Map<string, typeof queued>()
-    for (const row of queued) {
-      const group = byServer.get(row.qbSourceServer!) ?? []
-      group.push(row)
-      byServer.set(row.qbSourceServer!, group)
-    }
-
+    const importedIdsByConnector = new Map<string, Set<string>>()
+    const skippedConnectors = new Set<string>()
     let importedCount = 0
-    for (const [serverName, rows] of byServer) {
-      const connector = this.connectorManager.servers.find(s => s.name === serverName)
+
+    for (const row of queued) {
+      const connector = this.connectorFor(row)
       if (!connector || !connector.isInitialized)
         continue
 
-      let importedIds: Set<string>
-      try {
-        importedIds = await connector.recentlyImportedDownloadIds()
+      if (!importedIdsByConnector.has(connector.id) && !skippedConnectors.has(connector.id)) {
+        try {
+          importedIdsByConnector.set(connector.id, await connector.recentlyImportedDownloadIds())
+        }
+        catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          skippedConnectors.add(connector.id)
+          logger.warn({ server: connector.name, error: message }, 'Could not read import history; will retry next tick')
+        }
       }
-      catch (err) {
-        const message = err instanceof Error ? err.message : String(err)
-        logger.warn({ server: serverName, error: message }, 'Could not read import history; will retry next tick')
+      const importedIds = importedIdsByConnector.get(connector.id)
+      if (!importedIds)
+        continue
+
+      const hash = deriveHash(row.release.title, row.releaseSize).toLowerCase()
+      if (importedIds.has(hash)) {
+        this.repository.markImported(row.id)
+        importedCount++
+        logger.info({ id: row.id, filename: row.filename, server: connector.name }, 'Download imported by *arr')
         continue
       }
 
-      for (const row of rows) {
-        const hash = deriveHash(row.release.title, row.releaseSize).toLowerCase()
-        if (importedIds.has(hash)) {
-          this.repository.markImported(row.id)
-          importedCount++
-          logger.info({ id: row.id, filename: row.filename, server: serverName }, 'Download imported by *arr')
-          continue
-        }
-        if (row.importMode === 'jack_manual' && row.importTarget && !this.manualImportTriggered.has(row.id)) {
-          try {
-            await connector.manualImport({
-              folder: dirname(row.destPath),
-              paths: [row.destPath],
-              target: row.importTarget,
-              downloadId: deriveHash(row.release.title, row.releaseSize),
-            })
-            this.manualImportTriggered.add(row.id)
-            logger.info({ id: row.id, filename: row.filename, server: serverName }, 'Triggered *arr manual import')
+      if (row.importMode !== 'jack_manual' || !row.importTarget)
+        continue
+
+      if (row.manualImportCommandId != null) {
+        try {
+          const status = await connector.manualImportCommandStatus(row.manualImportCommandId)
+          if (status.state === 'completed') {
+            this.repository.markImported(row.id)
+            importedCount++
+            logger.info({ id: row.id, filename: row.filename, server: connector.name, commandId: row.manualImportCommandId }, 'Manual import command completed')
           }
-          catch (err) {
-            const message = err instanceof Error ? err.message : String(err)
-            logger.warn({ id: row.id, server: serverName, error: message }, 'Manual import trigger failed; will retry next tick')
+          else if (status.state === 'failed') {
+            this.repository.markFailed(row.id, status.error)
+            logger.warn({ id: row.id, server: connector.name, commandId: row.manualImportCommandId, error: status.error }, 'Manual import command failed')
           }
         }
+        catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          logger.warn({ id: row.id, server: connector.name, commandId: row.manualImportCommandId, error: message }, 'Could not read manual import command status; will retry next tick')
+        }
+        continue
+      }
+
+      try {
+        const commandId = await connector.manualImport({
+          folder: dirname(row.destPath),
+          paths: [row.destPath],
+          target: row.importTarget,
+          downloadId: deriveHash(row.release.title, row.releaseSize),
+          release: row.release,
+        })
+        this.repository.setManualImportCommand(row.id, commandId)
+        logger.info({ id: row.id, filename: row.filename, server: connector.name, commandId }, 'Triggered *arr manual import')
+      }
+      catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        if (err instanceof PermanentManualImportError) {
+          this.repository.markFailed(row.id, message)
+          logger.warn({ id: row.id, server: connector.name, error: message }, 'Manual import cannot be retried')
+          continue
+        }
+        logger.warn({ id: row.id, server: connector.name, error: message }, 'Manual import trigger failed; will retry next tick')
       }
     }
     return importedCount
diff --git a/apps/backend/src/modules/qbittorrent/qbittorrent.controller.ts b/apps/backend/src/modules/qbittorrent/qbittorrent.controller.ts
index 1102776..c97e431 100644
--- a/apps/backend/src/modules/qbittorrent/qbittorrent.controller.ts
+++ b/apps/backend/src/modules/qbittorrent/qbittorrent.controller.ts
@@ -178,6 +178,7 @@ export class QbittorrentController {
         itemId: stub.itemId,
         qbCategory: category,
         qbSourceServer: input.session.serverName,
+        sourceServerId: input.session.serverId,
       })
       if (result === 'failed')
         return 'failed'
@@ -214,7 +215,7 @@ export class QbittorrentController {
   // shared release yields the SAME infohash across servers, an unscoped delete
   // could remove another server's (or a blackhole) row.
   async deleteTorrents(session: QbSession, hashesParam: string, deleteFiles: boolean): Promise<void> {
-    const mine = (r: DownloadRecord) => r.qbSourceServer === session.serverName
+    const mine = (r: DownloadRecord) => r.sourceServerId ? r.sourceServerId === session.serverId : r.qbSourceServer === session.serverName
     const records = hashesParam === 'all'
       ? this.deps.repository.list().filter(mine)
       : hashesParam.split('|').flatMap(h => this.findAllByHash(h)).filter(mine)
@@ -230,7 +231,7 @@ export class QbittorrentController {
   setCategory(session: QbSession, hashes: string[], category: string): void {
     for (const hash of hashes) {
       for (const record of this.findAllByHash(hash)) {
-        if (record.qbSourceServer === session.serverName)
+        if (record.sourceServerId ? record.sourceServerId === session.serverId : record.qbSourceServer === session.serverName)
           this.deps.repository.setQbCategory(record.id, category)
       }
     }
diff --git a/apps/ui/app/composables/useCatalogMetadata.test.ts b/apps/ui/app/composables/useCatalogMetadata.test.ts
index f51ccb7..c9fbe57 100644
--- a/apps/ui/app/composables/useCatalogMetadata.test.ts
+++ b/apps/ui/app/composables/useCatalogMetadata.test.ts
@@ -2,8 +2,8 @@ import type { CatalogTitle, TmdbMetadata } from '~/types/management'
 import { describe, expect, test } from 'bun:test'
 import { useCatalogMetadata } from './useCatalogMetadata'
 
-type StateRef<T> = { value: T }
-type ManagementStub = { request: <T>(path: string) => Promise<T> }
+interface StateRef<T> { value: T }
+interface ManagementStub { request: <T>(path: string) => Promise<T> }
 
 type NuxtComposableGlobals = typeof globalThis & {
   useManagement: () => ManagementStub

From 4a67231482124bc465a237f5cf04bff72c053e52 Mon Sep 17 00:00:00 2001
From: Roz <rogerio.j.munhoz@gmail.com>
Date: Sun, 28 Jun 2026 14:17:17 +0200
Subject: [PATCH 27/27] fix(arr): fail rows on pruned manual-import commands

A persistent status-read failure for a stored manualImportCommandId left
the import row stuck forever: the watcher logged and retried the same
vanished command id every tick. Treat a 404 from the command endpoint as
terminal and return a failed state so the watcher marks the row failed,
while transient errors still throw and retry.
---
 .../lib/servers/arr/arr-add-import.test.ts    | 35 +++++++++++++++++++
 apps/backend/src/lib/servers/arr/base.ts      | 16 ++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/apps/backend/src/lib/servers/arr/arr-add-import.test.ts b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
index 0ea6565..50ed5c0 100644
--- a/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
+++ b/apps/backend/src/lib/servers/arr/arr-add-import.test.ts
@@ -334,3 +334,38 @@ describe('SonarrServerConnector.manualImport', () => {
     })).rejects.toThrow(BadRequestError)
   })
 })
+
+describe('manualImportCommandStatus', () => {
+  test('reports completed/failed/pending from the command status', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/command/1`, () => HttpResponse.json({ id: 1, status: 'completed' })),
+      http.get(`${RADARR_URL}/api/v3/command/2`, () => HttpResponse.json({ id: 2, status: 'failed', message: 'boom' })),
+      http.get(`${RADARR_URL}/api/v3/command/3`, () => HttpResponse.json({ id: 3, status: 'started' })),
+    )
+    const radarr = makeRadarr()
+    expect(await radarr.manualImportCommandStatus(1)).toEqual({ state: 'completed' })
+    expect(await radarr.manualImportCommandStatus(2)).toEqual({ state: 'failed', error: 'boom' })
+    expect(await radarr.manualImportCommandStatus(3)).toEqual({ state: 'pending' })
+  })
+
+  // A pruned command record (404) is terminal, not transient: returning `failed`
+  // lets the watcher fail the row instead of polling a vanished id forever.
+  test('returns failed when the command record was pruned (404)', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/command/9`, () => new HttpResponse(null, { status: 404 })),
+    )
+    const radarr = makeRadarr()
+    const status = await radarr.manualImportCommandStatus(9)
+    expect(status.state).toBe('failed')
+    expect(status).toMatchObject({ error: expect.stringContaining('no longer exists') })
+  })
+
+  // A transient failure (5xx, timeout) must keep throwing so the watcher retries.
+  test('rethrows non-404 errors so the watcher retries next tick', async () => {
+    server.use(
+      http.get(`${RADARR_URL}/api/v3/command/8`, () => new HttpResponse(null, { status: 503 })),
+    )
+    const radarr = makeRadarr()
+    await expect(radarr.manualImportCommandStatus(8)).rejects.toThrow()
+  })
+})
diff --git a/apps/backend/src/lib/servers/arr/base.ts b/apps/backend/src/lib/servers/arr/base.ts
index 2f6591d..fe30cd3 100644
--- a/apps/backend/src/lib/servers/arr/base.ts
+++ b/apps/backend/src/lib/servers/arr/base.ts
@@ -5,6 +5,7 @@ import { logger } from '../../../logger'
 import { requiresDestination, requiresSource } from '../../decorators/requires-capability'
 import { requiresInitialization } from '../../decorators/requires-initialization'
 import { BadRequestError } from '../../errors/BadRequestError'
+import { FetchError } from '../../errors/FetchError'
 import { ServerConnector } from '../base'
 
 const BASENAME_SEPARATOR_REGEX = /[/\\]/
@@ -245,7 +246,20 @@ export abstract class ArrServerConnector extends ServerConnector {
   @requiresDestination
   @requiresInitialization
   async manualImportCommandStatus(commandId: number): Promise<ManualImportCommandState> {
-    const command = await this.fetch(`/api/v3/command/${commandId}`, { method: 'GET', schema: CommandResource })
+    let command: z.infer<typeof CommandResource>
+    try {
+      command = await this.fetch(`/api/v3/command/${commandId}`, { method: 'GET', schema: CommandResource })
+    }
+    catch (err) {
+      // *arr prunes command records after a while, so a 404 means this command is
+      // gone for good. Treat it as terminal (rather than re-throwing every tick) so
+      // the watcher fails the row instead of polling a vanished command id forever.
+      // A real success is already caught earlier by the import-history match, so we
+      // only reach here when the file never imported.
+      if (err instanceof FetchError && err.response.status === 404)
+        return { state: 'failed', error: `Manual import command ${commandId} no longer exists on ${this.name}` }
+      throw err
+    }
     const status = command.status?.toLowerCase()
     if (status === 'completed')
       return { state: 'completed' }