release: v0.3.2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
feat: merge crop-dimension-trace into dev
2026-06-13 15:32:33 +00:00 · 2026-06-13 15:32:27 +00:00 · 2026-06-13 15:30:14 +00:00 · 2026-06-13 15:20:54 +00:00 · 2026-06-13 14:54:02 +00:00 · 2026-06-13 14:53:56 +00:00
35 changed files with 6019 additions and 470 deletions
@@ -0,0 +1,81 @@
+name: Bug Report
+description: Something isn't working as expected
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, check the [Troubleshooting wiki](https://github.com/sudolulo/winnow/wiki/Troubleshooting) and [existing issues](https://github.com/sudolulo/winnow/issues).
+
+  - type: dropdown
+    id: image-tag
+    attributes:
+      label: Image tag
+      description: Which winnow image are you running?
+      options:
+        - ":latest (NVIDIA CUDA)"
+        - ":rocm (AMD)"
+        - ":intel (Intel Arc / iGPU)"
+        - ":cpu (CPU only)"
+        - "Local install (uv)"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: winnow version
+      description: Output of `docker inspect ghcr.io/sudolulo/winnow:<tag> | grep org.opencontainers.image.version` or the version in `pyproject.toml`.
+      placeholder: "0.2.13"
+    validations:
+      required: true
+
+  - type: input
+    id: immich-version
+    attributes:
+      label: Immich version
+      placeholder: "v1.110.0"
+    validations:
+      required: false
+
+  - type: input
+    id: frigate-version
+    attributes:
+      label: Frigate version
+      placeholder: "0.16.0"
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Paste logs from `docker logs winnow` or `winnow.log`. Set `VERBOSE=true` for more detail.
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: compose
+    attributes:
+      label: Relevant compose / env config
+      description: Paste your `services.winnow` block. Redact your API key.
+      render: yaml
+    validations:
+      required: false
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or help request
+    url: https://github.com/sudolulo/winnow/discussions
+    about: Ask questions and get help in GitHub Discussions
+  - name: Wiki / Documentation
+    url: https://github.com/sudolulo/winnow/wiki
+    about: Setup, troubleshooting, and FAQ
@@ -0,0 +1,36 @@
+name: Feature Request
+description: Suggest an improvement or new capability
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or limitation you're running into.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like winnow to do? New env var, different behaviour, etc.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you've tried or other approaches you considered.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I checked existing issues and this hasn't been requested before.
+          required: true
@@ -0,0 +1,26 @@
+## What does this PR do?
+
+<!-- One or two sentences. -->
+
+## Why?
+
+<!-- Link to the issue this addresses, or explain the motivation if there isn't one. -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of the meaningful changes. -->
+
+-
+
+## Testing
+
+<!-- How did you verify this works? New tests added? Manual test steps? -->
+
+## Checklist
+
+- [ ] Targets the `dev` branch (not `main`)
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check` passes
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated
@@ -6,9 +6,19 @@ on:
    paths-ignore:
      - "**.md"
      - "docs/**"
+      - ".github/ISSUE_TEMPLATE/**"
+      - ".github/PULL_REQUEST_TEMPLATE.md"
      - ".github/workflows/release.yml"
      - ".github/workflows/lint.yml"
      - ".github/dependabot.yml"
+      - "uv.lock"
+      - "uv-cpu.lock"
+      - "uv-rocm.lock"
+      - "uv-intel.lock"
+
+concurrency:
+  group: docker-${{ github.ref }}
+  cancel-in-progress: true

 env:
  REGISTRY: ghcr.io
@@ -32,18 +42,18 @@ jobs:
    steps:
      - name: Free up disk space
        run: |
-          sudo rm -rf /usr/share/dotnet
-          sudo rm -rf /opt/ghc
-          sudo rm -rf "/usr/local/share/boost"
-          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
-          echo "Disk space freed."
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h

      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up QEMU
        if: matrix.platform == 'linux/arm64'
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
@@ -57,7 +67,7 @@ jobs:

      - name: Build and push by digest
        id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
@@ -127,8 +137,15 @@ jobs:
        run: |
          docker buildx imagetools inspect ${{ steps.tags.outputs.tags }}

+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
  build-cpu:
-    name: Build CPU-only (amd64)
+    name: Build CPU (amd64 + arm64)
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -137,15 +154,18 @@ jobs:
    steps:
      - name: Free up disk space
        run: |
-          sudo rm -rf /usr/share/dotnet
-          sudo rm -rf /opt/ghc
-          sudo rm -rf "/usr/local/share/boost"
-          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
-          echo "Disk space freed."
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h

      - name: Checkout repository
        uses: actions/checkout@v6

+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

@@ -166,14 +186,14 @@ jobs:
          fi

      - name: Build and push CPU image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
-          platforms: linux/amd64
+          platforms: linux/amd64,linux/arm64
          build-args: VARIANT=cpu
-          cache-from: type=gha,scope=linux/amd64-cpu
-          cache-to: type=gha,mode=max,scope=linux/amd64-cpu
+          cache-from: type=gha,scope=cpu
+          cache-to: type=gha,mode=max,scope=cpu
          github-token: ${{ secrets.GITHUB_TOKEN }}
          push: true
          tags: ${{ steps.cpu-tag.outputs.tag }}
@@ -181,3 +201,134 @@ jobs:
      - name: Inspect CPU image
        run: |
          docker buildx imagetools inspect ${{ steps.cpu-tag.outputs.tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-rocm:
+    name: Build ROCm / AMD GPU (amd64)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine ROCm image tag
+        id: rocm-tag
+        run: |
+          if [ "${{ github.ref_name }}" = "dev" ]; then
+            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev-rocm" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:rocm" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push ROCm image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          build-args: VARIANT=rocm
+          cache-from: type=gha,scope=linux/amd64-rocm
+          cache-to: type=gha,mode=max,scope=linux/amd64-rocm
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push: true
+          tags: ${{ steps.rocm-tag.outputs.tag }}
+
+      - name: Inspect ROCm image
+        run: |
+          docker buildx imagetools inspect ${{ steps.rocm-tag.outputs.tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build-intel:
+    name: Build Intel GPU (amd64)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          sudo rm -rf /opt/hostedtoolcache/CodeQL /usr/share/swift
+          sudo rm -rf "/usr/local/share/boost" "$AGENT_TOOLSDIRECTORY"
+          docker system prune -af
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine Intel image tag
+        id: intel-tag
+        run: |
+          if [ "${{ github.ref_name }}" = "dev" ]; then
+            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:dev-intel" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:intel" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push Intel image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          build-args: VARIANT=intel
+          cache-from: type=gha,scope=linux/amd64-intel
+          cache-to: type=gha,mode=max,scope=linux/amd64-intel
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push: true
+          tags: ${{ steps.intel-tag.outputs.tag }}
+
+      - name: Inspect Intel image
+        run: |
+          docker buildx imagetools inspect ${{ steps.intel-tag.outputs.tag }}
+
+      - name: Ensure package is public
+        run: |
+          gh api -X PATCH /user/packages/container/winnow \
+            -f visibility=public || true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -15,11 +15,13 @@ concurrency:

 jobs:
  release:
-    name: Create GitHub Release & Build Image
+    name: Create GitHub Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
-      packages: write
+    outputs:
+      tag: ${{ steps.tag.outputs.TAG }}
+      version: ${{ steps.tag.outputs.VERSION }}
    steps:
      - name: Free up disk space
        run: |
@@ -37,14 +39,28 @@ jobs:
      - name: Install uv
        uses: astral-sh/setup-uv@v7

-      - name: Ensure uv.lock is current
-        run: uv lock
+      - name: Set up Python
+        run: uv python install 3.13

-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+      - name: Verify release branch
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ "${{ github.ref_name }}" != "main" ]; then
+            echo "::error::Releases must be dispatched from main (current: ${{ github.ref_name }})"
+            exit 1
+          fi

-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+      - name: Ensure lockfiles are current
+        run: |
+          cp pyproject.toml _pyproject_orig.toml
+          for variant in cpu rocm intel; do
+            cp pyproject-${variant}.toml pyproject.toml
+            uv lock
+            cp uv.lock uv-${variant}.lock
+          done
+          cp _pyproject_orig.toml pyproject.toml
+          uv lock
+          rm _pyproject_orig.toml

      - name: Resolve tag name
        id: tag
@@ -111,6 +127,30 @@ jobs:
              prerelease: false,
            });

+  build-gpu:
+    name: Build GPU image
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf "/usr/local/share/boost"
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          echo "Disk space freed."
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
      - name: Log in to GHCR
        uses: docker/login-action@v4
        with:
@@ -118,15 +158,157 @@ jobs:
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
+      - name: Build and push GPU image (latest)
+        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64
          push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          build-args: VERSION=${{ needs.release.outputs.version }}
+          cache-from: type=gha,scope=release-gpu
+          cache-to: type=gha,mode=max,scope=release-gpu
          tags: |
            ghcr.io/sudolulo/winnow:latest
-            ghcr.io/sudolulo/winnow:${{ steps.tag.outputs.TAG }}
+            ghcr.io/sudolulo/winnow:${{ needs.release.outputs.tag }}
+
+  build-cpu:
+    name: Build CPU image
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf "/usr/local/share/boost"
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          echo "Disk space freed."
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push CPU image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            VARIANT=cpu
+            VERSION=${{ needs.release.outputs.version }}
+          cache-from: type=gha,scope=release-cpu
+          cache-to: type=gha,mode=max,scope=release-cpu
+          tags: |
+            ghcr.io/sudolulo/winnow:cpu
+            ghcr.io/sudolulo/winnow:${{ needs.release.outputs.tag }}-cpu
+
+  build-rocm:
+    name: Build ROCm image
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf "/usr/local/share/boost"
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          echo "Disk space freed."
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push ROCm image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          push: true
+          build-args: |
+            VARIANT=rocm
+            VERSION=${{ needs.release.outputs.version }}
+          cache-from: type=gha,scope=release-rocm
+          cache-to: type=gha,mode=max,scope=release-rocm
+          tags: |
+            ghcr.io/sudolulo/winnow:rocm
+            ghcr.io/sudolulo/winnow:${{ needs.release.outputs.tag }}-rocm
+
+  build-intel:
+    name: Build Intel image
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf "/usr/local/share/boost"
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          echo "Disk space freed."
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Intel image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64
+          push: true
+          build-args: |
+            VARIANT=intel
+            VERSION=${{ needs.release.outputs.version }}
+          cache-from: type=gha,scope=release-intel
+          cache-to: type=gha,mode=max,scope=release-intel
+          tags: |
+            ghcr.io/sudolulo/winnow:intel
+            ghcr.io/sudolulo/winnow:${{ needs.release.outputs.tag }}-intel
@@ -1,10 +1,15 @@
 # .github/workflows/update-lockfile.yml
-name: Update uv.lock
+name: Update lockfiles

 on:
  push:
+    branches:
+      - '**'
    paths:
      - 'pyproject.toml'
+      - 'pyproject-cpu.toml'
+      - 'pyproject-rocm.toml'
+      - 'pyproject-intel.toml'
  workflow_dispatch:

 jobs:
@@ -30,24 +35,32 @@ jobs:
      - name: Set up Python
        run: uv python install 3.13

-      - name: Regenerate lockfile
-        run: uv lock
+      - name: Regenerate all lockfiles
+        run: |
+          cp pyproject.toml _pyproject_orig.toml
+          for variant in cpu rocm intel; do
+            cp pyproject-${variant}.toml pyproject.toml
+            uv lock
+            cp uv.lock uv-${variant}.lock
+          done
+          cp _pyproject_orig.toml pyproject.toml
+          uv lock
+          rm _pyproject_orig.toml

      - name: Check for changes
        id: diff
        run: |
-          if git diff --quiet uv.lock; then
+          if git diff --quiet uv.lock uv-cpu.lock uv-rocm.lock uv-intel.lock; then
            echo "changed=false" >> "$GITHUB_OUTPUT"
          else
            echo "changed=true" >> "$GITHUB_OUTPUT"
          fi

-      - name: Commit and push updated lockfile
+      - name: Commit and push updated lockfiles
        if: steps.diff.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add uv.lock
-          git commit -m "chore: update uv.lock"
+          git add uv.lock uv-cpu.lock uv-rocm.lock uv-intel.lock
+          git commit -m "chore: update lockfiles"
          git push
-
@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [0.3.2] - 2026-06-13
+
+### Added
+
+- **Crop dimension tracing**: winnow now records the pixel dimensions (width × height) of each face crop at upload time in the tracker (`crop_dims` field). Run `TRACE_CROP_SIZE=3848 winnow` to look up which Immich asset produced a crop with that pixel dimension — output includes person name, asset ID, Immich URL, blur score, and the Frigate filename. Useful for tracing low-quality or unexpected images visible in Frigate back to their source.
+
+## [0.3.1] - 2026-06-13
+
+### Fixed
+
+- **Lint**: split overly long line in `quality.py` (`E501`, 146 → ≤120 chars).
+- **CI — lockfile update workflow**: added `branches: ['**']` filter to `on.push` so tag pushes no longer trigger the job; tag checkouts land in detached HEAD and the subsequent `git push` had no branch target.
+- **CI — release workflow**: split four Docker image builds into parallel jobs (`build-gpu`, `build-cpu`, `build-rocm`, `build-intel`), each with its own runner. Previously all four ran in a single job; building the GPU and CPU multi-platform images exhausted disk, causing ROCm and Intel builds to be cancelled.
+
+## [0.3.0] - 2026-06-13
+
+### Added
+
+- **`get_tracked_frigate_filenames()`** — new upload-tracker function that returns the set of Frigate filenames currently mapped for a person. Used internally as a reconciliation baseline when the Frigate GET endpoint is unreachable; also available to callers that need the mapped filename set without a count.
+- **Community scaffolding**: `CONTRIBUTING.md`, `SECURITY.md`, GitHub issue templates (bug report, feature request), and pull request template.
+- **OCI image labels**: `org.opencontainers.image.*` labels added to the runtime stage of the Dockerfile so image metadata is surfaced by container registries.
+- **Additional tracker tests**: coverage added for `get_tracked_frigate_filenames` and for `get_lowest_quality_mapped_file` with the `exclude` parameter.
+
+### Fixed
+
+- **Quality score scale mismatch (USE_FULL_RESOLUTION=true)**: the time-spread quality-score fallback called `assess_quality` on the full-resolution download, while the embedding path always scores on preview thumbnails. Laplacian variance scales with image resolution, so the two paths produced incomparable scores for people with mixed-mode files. The fallback now caps the image at 1440 px before scoring to match the thumbnail scale.
+- **assess_quality failure left file permanently unreplaceable**: if `assess_quality` raised an exception (e.g. an RGBA image with an unsupported channel count), `score_map` kept `None` and `mark_uploaded(score=None)` skipped writing the score. The uploaded file was then permanently invisible to `get_lowest_quality_mapped_file` because it had no entry in `scores{}`. The fallback now converts the image to RGB before scoring and stores `0.0` on any exception, so every uploaded file is eligible for future quality replacement.
+- **Uploads during Frigate GET outage never mapped**: when `GET /api/faces` failed at upload start, the reconciliation guard (`_snapshot is not None`) correctly skipped the post-upload diff — but uploads that succeeded during the outage were never recorded in `frigate_files`, causing `get_tracked_frigate_file_count` to permanently under-report and Frigate to eventually exceed `MAX_AUTO_IMAGES`. The code now uses the tracker's mapped filenames as a pre-upload baseline when the live snapshot is unavailable, so reconciliation proceeds normally (the `>target` guard handles concurrent external uploads as before).
+- **Freed quality-replacement slot could be filled by a worse image**: when a replacement delete succeeded but the subsequent upload failed all retries, `effective_count` stayed decremented and the next file in the iteration uploaded unconditionally — it could have a lower quality score than the file that was deleted. A `min_quality_score_for_slot` variable now records the deleted file's score on a successful delete; any candidate that doesn't beat that floor is skipped until the slot is filled by a qualifying image or the run ends.
+- **CI multi-arch and lockfile bot**: hardened the build workflow — lockfile-update bot no longer races against Docker publish on the same push event; CPU image now builds for both `linux/amd64` and `linux/arm64`; `paths-ignore` prevents documentation-only pushes from triggering image builds.
+- **README pipeline diagram updated**: step 8 now explicitly documents the quality-replacement decision tree (`below cap → upload`, `at cap + enabled → swap if better`, `at cap + disabled → skip`).
+
+## [0.2.13] - 2026-06-13
+
+### Added
+
+- **Quality replacement**: when a person is at `MAX_AUTO_IMAGES`, winnow now checks each new candidate against the lowest-quality image already in Frigate and swaps it in if the new image scores higher. Only images winnow uploaded (tracked in `frigate_files`) are ever replaced — files added manually through Frigate's UI are left untouched permanently. Enabled by default; set `QUALITY_REPLACEMENT=false` to revert to the previous behaviour of skipping people at cap.
+- **Frigate filename mapping**: each successful upload now records the mapping from Frigate's assigned filename to the originating Immich asset ID and face confidence score in the tracker (`frigate_files` field). This is the foundation for quality replacement and future management of the Frigate training set.
+- **`QUALITY_REPLACEMENT` env var** (default `true`): controls whether at-cap people are eligible for quality replacement. When disabled, people at `MAX_AUTO_IMAGES` are skipped as before.
+- **NOTICES file**: third-party attribution for if_curator (MIT, Copyright © 2026 Sebastian) added to satisfy upstream license requirements.
+
+## [0.2.12] - 2026-06-13
+
+### Added
+
+- **ROCm (AMD GPU) support**: new `:rocm` image tag. InsightFace runs via `ROCmExecutionProvider`; SigLIP runs via PyTorch ROCm 6.3 (ROCm builds expose `torch.cuda.is_available() == True`, so the existing CUDA path is reused automatically). Requires `/dev/kfd` and `/dev/dri` device passthrough plus `video` and `render` group membership — see `compose.yml` for the snippet.
+- **Intel GPU support**: new `:intel` image tag. InsightFace runs via `OpenVINOExecutionProvider` from `onnxruntime-openvino`. By default OpenVINO targets CPU (no device passthrough needed); set `OPENVINO_DEVICE=GPU` to target Intel Arc discrete or integrated graphics. Intel's GPU compute runtime (Level Zero + OpenCL ICD) is installed automatically from Intel's official graphics repo in the image — no manual package installation required. SigLIP uses CPU inference for now (Intel Extension for PyTorch has no Python 3.13 wheels yet; the `torch.xpu` path is wired and will activate automatically when they ship).
+- **`OPENVINO_DEVICE` env var**: controls the OpenVINO execution provider device for the `:intel` variant. `CPU` (default) requires no device passthrough. `GPU` targets Intel Arc discrete and integrated graphics via Level Zero.
+- **AMD and Intel device passthrough snippets in `compose.yml`**: documented as commented-out alternatives to the NVIDIA `deploy:` block.
+- **`:rocm` and `:intel` CI jobs**: `docker-publish.yml` now builds and pushes `:rocm` / `:dev-rocm` and `:intel` / `:dev-intel` alongside `:latest` and `:cpu`. `release.yml` builds all four variants on tag push.
+
+### Fixed
+
+- **Interactive custom-count prompt firing for all choices**: in the no-embedding fallback path of the strategy selector, `IntPrompt.ask` was inside a dict literal and evaluated eagerly — users selecting Standard (30) or Broad (100) were still prompted to enter a custom image count. Each choice is now handled in a dedicated branch.
+
+## [0.2.11] - 2026-06-12
+
+### Fixed
+
+- **GPU broken on x86_64 Linux**: `insightface` 1.0.1 (pulled in by the 0.2.10 lock update) added a hard dependency on the CPU `onnxruntime` package. Combined with an incorrect `override-dependencies` entry introduced in 0.2.10, both `onnxruntime` (CPU) and `onnxruntime-gpu` were being installed into the same venv. The CPU package landed last and overwrote the GPU one, causing `CUDAExecutionProvider` to disappear from the provider list even when a GPU was present. Fixed by declaring `onnxruntime` and `onnxruntime-gpu` as conflicting packages in uv's resolver, ensuring only the correct one is installed per platform.
+- **OOM crash on large person libraries (CPU mode)**: All candidate thumbnails were downloaded into a single in-memory dict before any processing began. At ~5 MB per decoded preview image, a person with 472 candidates would accumulate ~2.4 GB of thumbnail data alone, exhausting a 4 GB container memory limit. Thumbnails are now downloaded and processed in batches of 32, with each image released immediately after embedding. Peak in-flight thumbnail memory is now bounded to ~256 MB regardless of candidate pool size. GPU users also benefit from lower host RAM pressure and faster time-to-first-result on large libraries.
+
 ## [0.2.10] - 2026-06-12

 ### Added
@@ -0,0 +1,41 @@
+# Contributing to winnow
+
+Bug reports, feature requests, and pull requests are all welcome.
+
+## Before You Start
+
+- Check [existing issues](https://github.com/sudolulo/winnow/issues) to avoid duplicates.
+- For large changes, open an issue first to discuss the approach.
+- All PRs target the `dev` branch — never `main` directly.
+
+## Development Setup
+
+Requires Python 3.13+ and [uv](https://astral.sh/uv).
+
+```bash
+git clone https://github.com/sudolulo/winnow.git
+cd winnow
+git checkout dev
+uv sync
+```
+
+## Running Tests and Lint
+
+```bash
+uv run pytest          # run the test suite
+uv run ruff check      # lint
+uv run ruff check --fix  # auto-fix lint issues
+```
+
+CI runs both on every push and PR to `main` and `dev`. PRs must pass before merging.
+
+## Pull Request Guidelines
+
+- One logical change per PR.
+- If you add behaviour, add a test for it.
+- Keep the `CHANGELOG.md` entry in the `[Unreleased]` section updated.
+- Commit messages should be plain English describing what changed and why.
+
+## License
+
+By submitting a contribution you agree that your work will be released under the project's [AGPLv3+ license](LICENSE).
@@ -1,13 +1,19 @@
 # ── Base images ───────────────────────────────────────────────────────────────
-#   amd64 + gpu:  NVIDIA CUDA 13.3 + cuDNN (GPU acceleration when available)
-#   amd64 + cpu:  Ubuntu 22.04 (CPU-only, ~2 GB smaller image)
-#   arm64:        Ubuntu 24.04 (CPU-only; no CUDA wheels on ARM)
+#   amd64 + gpu:   NVIDIA CUDA 13.3 + cuDNN (GPU acceleration via NVIDIA Container Toolkit)
+#   amd64 + rocm:  Ubuntu 22.04 (AMD GPU via ROCm — pass /dev/kfd and /dev/dri)
+#   amd64 + intel: Ubuntu 22.04 (Intel Arc / iGPU via OpenVINO — pass /dev/dri)
+#   amd64 + cpu:   Ubuntu 22.04 (CPU-only, ~2 GB smaller image)
+#   arm64:         Ubuntu 24.04 (CPU-only; no CUDA/ROCm wheels on ARM)

 ARG VARIANT=gpu

 FROM --platform=$BUILDPLATFORM nvidia/cuda:13.3.0-cudnn-runtime-ubuntu22.04 AS base-amd64-gpu
+FROM ubuntu:22.04 AS base-amd64-rocm
+FROM ubuntu:22.04 AS base-amd64-intel
 FROM ubuntu:22.04 AS base-amd64-cpu
 FROM ubuntu:24.04 AS base-arm64-gpu
+FROM ubuntu:24.04 AS base-arm64-rocm
+FROM ubuntu:24.04 AS base-arm64-intel
 FROM ubuntu:24.04 AS base-arm64-cpu

 # ── Build stage ───────────────────────────────────────────────────────────────
@@ -35,11 +41,15 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh \

 WORKDIR /app

-# For cpu variant, swap in the CPU-only pyproject and lockfile before syncing.
-COPY pyproject.toml uv.lock pyproject-cpu.toml uv-cpu.lock ./
+# Swap in the variant-specific pyproject and lockfile before syncing.
+COPY pyproject.toml uv.lock pyproject-cpu.toml uv-cpu.lock \
+     pyproject-rocm.toml uv-rocm.lock pyproject-intel.toml uv-intel.lock ./
 RUN if [ "$VARIANT" = "cpu" ]; then \
-        cp pyproject-cpu.toml pyproject.toml && \
-        cp uv-cpu.lock uv.lock; \
+        cp pyproject-cpu.toml pyproject.toml && cp uv-cpu.lock uv.lock; \
+    elif [ "$VARIANT" = "rocm" ]; then \
+        cp pyproject-rocm.toml pyproject.toml && cp uv-rocm.lock uv.lock; \
+    elif [ "$VARIANT" = "intel" ]; then \
+        cp pyproject-intel.toml pyproject.toml && cp uv-intel.lock uv.lock; \
    fi && \
    uv sync --frozen --no-dev \
    && uv cache clean
@@ -55,6 +65,12 @@ RUN chmod +x /app/entrypoint.sh
 FROM base-${TARGETARCH}-${VARIANT} AS runtime

 ARG VARIANT=gpu
+ARG VERSION=dev
+LABEL org.opencontainers.image.title="winnow" \
+      org.opencontainers.image.description="Selects diverse, high-quality photos from Immich as training data for Frigate face recognition and object classification." \
+      org.opencontainers.image.source="https://github.com/sudolulo/winnow" \
+      org.opencontainers.image.licenses="AGPL-3.0-or-later" \
+      org.opencontainers.image.version="${VERSION}"
 ENV DEBIAN_FRONTEND=noninteractive

 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -72,11 +88,32 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=build /app /app
 COPY --from=build /usr/local/bin/uv /usr/local/bin/uv

-# Register every nvidia pip-package lib/ directory with ldconfig so that
-# onnxruntime-gpu and torch can find libcudnn, libcublas, libcufft, etc.
-# without a hand-maintained LD_LIBRARY_PATH. Skipped silently on cpu builds.
-RUN find /app/.venv/lib/python3.*/site-packages/nvidia -type d -name "lib" \
-        2>/dev/null > /etc/ld.so.conf.d/nvidia-pip.conf && ldconfig || true
+# NVIDIA: register pip-installed nvidia lib/ dirs with ldconfig so onnxruntime-gpu
+# and torch can find libcudnn, libcublas, etc. Skipped silently on other variants.
+RUN if [ "$VARIANT" = "gpu" ]; then \
+        find /app/.venv/lib/python3.*/site-packages/nvidia -type d -name "lib" \
+            2>/dev/null > /etc/ld.so.conf.d/nvidia-pip.conf && ldconfig || true; \
+    fi
+# Intel: install GPU compute runtime so OpenVINO EP can target Intel Arc / iGPU.
+# onnxruntime-openvino bundles OpenVINO itself; only the userspace GPU driver
+# (OpenCL ICD + Level Zero) is needed from the OS.
+# These packages aren't in Ubuntu 22.04 main, so this block adds Intel's
+# official GPU repo first, then installs. libze-intel-gpu1 was renamed to
+# level-zero in Intel's repo.
+RUN if [ "$VARIANT" = "intel" ]; then \
+        apt-get update \
+        && apt-get install -y --no-install-recommends curl gnupg \
+        && curl -fsSL https://repositories.intel.com/graphics/intel-graphics.key \
+           | gpg --dearmor > /usr/share/keyrings/intel-graphics.gpg \
+        && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] \
+https://repositories.intel.com/graphics/ubuntu jammy flex" \
+           > /etc/apt/sources.list.d/intel-graphics.list \
+        && apt-get update \
+        && apt-get install -y --no-install-recommends \
+               intel-opencl-icd intel-level-zero-gpu level-zero \
+        && apt-get remove -y --autoremove curl gnupg \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi

 RUN groupadd -g 568 apps && useradd -u 568 -g apps -m -s /bin/bash appuser \
    && mkdir -p /models/.insightface /models/huggingface \
@@ -0,0 +1,23 @@
+winnow incorporates portions of if_curator (https://github.com/ds-sebastian/if_curator).
+
+    MIT License
+
+    Copyright (c) 2026 Sebastian
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
@@ -1,31 +1,17 @@
 # winnow

-[![Docker](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml) [![Test](https://github.com/sudolulo/winnow/actions/workflows/test.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/test.yml) [![Immich](https://img.shields.io/badge/Immich-v1.106%2B-blueviolet)](https://immich.app) [![Frigate](https://img.shields.io/badge/Frigate-Ready-brightgreen)](https://frigate.video)
+[![Docker](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/docker-publish.yml) [![Test](https://github.com/sudolulo/winnow/actions/workflows/test.yml/badge.svg)](https://github.com/sudolulo/winnow/actions/workflows/test.yml) [![GitHub release](https://img.shields.io/github/v/release/sudolulo/winnow)](https://github.com/sudolulo/winnow/releases/latest) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Immich](https://img.shields.io/badge/Immich-v1.106%2B-blueviolet)](https://immich.app) [![Frigate](https://img.shields.io/badge/Frigate-Ready-brightgreen)](https://frigate.video)

 **Docs:** [Setup](https://github.com/sudolulo/winnow/wiki/Setup) · [Troubleshooting](https://github.com/sudolulo/winnow/wiki/Troubleshooting) · [FAQ](https://github.com/sudolulo/winnow/wiki/FAQ)

-`winnow` pulls photos of people and objects from your [Immich](https://immich.app) library, selects the most diverse and highest-quality subset using AI embeddings, and delivers them as training data for [Frigate](https://frigate.video)'s face recognition and object classification models.
+`winnow` pulls photos from your [Immich](https://immich.app) library, selects the most diverse and highest-quality subset using AI embeddings, and delivers them as training data for [Frigate](https://frigate.video)'s face recognition and object classification models.

-It runs fully headless in Docker, is configured entirely through environment variables, and can run on a schedule — no interactive prompts, no manual steps.
-
---
-
-## The Problem
-
-Frigate's face recognition model (ArcFace) and object classifier are only as good as the training data you give them. The instinct is to feed them as many photos as possible, but volume is not what matters — **diversity is**.
-
-If you upload 100 photos from the same week, the model learns the lighting in your living room and the jacket you wore that month. It struggles the moment anything changes. What you actually want is a spread: different years, different lighting conditions, different angles, different contexts.
-
-This is especially true for people who have never been to your property, or who visit rarely — family members, friends, anyone Frigate has never seen in person. Live detections alone will never build a reliable model for these people. Your photo library already has the data; winnow finds and delivers the right subset of it.
-
-Finding that spread manually across a library of thousands of photos is not practical. `winnow` does it automatically.
+Frigate's face recognition is only as good as its training data — and the key quality metric is **diversity**, not volume. A hundred photos from the same week teach the model one lighting condition. What you need is a spread: different years, different angles, different lighting, different contexts. Your photo library already has that data. winnow finds and delivers the right subset automatically.

 ---

 ## How It Works

-For each person (or object) you configure, the tool runs this pipeline:
-
 ```
 Immich library
      │
@@ -33,79 +19,59 @@ Immich library
 1. Fetch all assets tagged with this person
      │
      ▼
-2. Filter by recency (configurable years window)
+2. Filter by recency (YEARS_FILTER) and skip already-uploaded
+   and rejected assets (persistent tracker in CACHE_DIR)
      │
      ▼
-3. Skip already-uploaded assets (persistent tracker)
-      │
-      ▼
-4. Quality filter — reject:
+3. Quality filter — download preview thumbnails and reject:
   • Blurry images (Laplacian variance)
-   • Grayscale / infrared (channel similarity check)
+   • Grayscale / infrared (channel similarity)
   • Over- or underexposed
   • Low detection confidence
   • Face crops below minimum pixel size
      │
      ▼
-5. Compute embeddings for remaining candidates
-   • Faces   → InsightFace (ArcFace / Buffalo_L)
-   • Objects → SigLIP (Vision Transformer)
+4. Compute embeddings from the same preview thumbnails
+   • Faces   → InsightFace (ArcFace / Buffalo_L)  → 512-dim vector
+   • Objects → SigLIP (Vision Transformer)         → 768-dim vector
      │
      ▼
-6. Diversity selection
-   • K-Medoids clustering to find natural groupings
-   • Farthest Point Sampling (FPS) to pick maximally spread representatives
-   • Hard example weighting — unusual angles, partial occlusions,
-     and low-confidence detections are biased toward selection
-   • Auto mode: keeps selecting until marginal diversity drops off
+5. Diversity selection
+   • K-Medoids clustering → one representative per natural group
+   • Farthest Point Sampling → fill remaining slots with maximally spread picks
+   • Hard example weighting — unusual angles and low-confidence detections
+     are biased toward selection, since those are where models tend to fail
+   • Auto mode: stops when similarity to the existing set exceeds a threshold
+     (20 % of median pairwise distance for faces, 10 % for objects)
      │
      ▼
-7. Crop and export
-   • Face mode: aligned 112×112 crops (ArcFace standard input),
-     uploaded directly to Frigate's face training API
-   • Object mode: YOLO-detected crops saved to disk
+6. Download full-resolution originals from Immich
+      │
+      ▼
+7. Crop and process
+   • Face mode: EXIF-corrected, landmark-aligned 112×112 crop (ArcFace format)
+   • Object mode: YOLOv9c detection → one crop per matched instance
+      │
+      ▼
+8. Deliver
+   • Face mode: upload crops to Frigate's face registration API
+     ↳ below MAX_AUTO_IMAGES — upload freely
+     ↳ at cap + QUALITY_REPLACEMENT=true — swap the lowest-scoring tracked
+       image if the new candidate scores higher; manually added files are
+       never touched
+     ↳ at cap + QUALITY_REPLACEMENT=false — skip this person
+   • Object mode: save crops to disk → place into your Frigate data directory
 ```

-Uploaded asset IDs are recorded so the same image is never uploaded twice, even across runs weeks apart.
-
---
-
-## Note on Crop Quality
-
-winnow works well, but no automated pipeline is perfect. Occasionally a bad crop will slip through quality filtering — a partial face, someone in the background, a blurry frame. After a run it's worth a quick review in Frigate's face management UI to remove anything that doesn't belong.
-
-Issues and feedback welcome via [GitHub Issues](https://github.com/sudolulo/winnow/issues).
+Uploaded and rejected asset IDs are persisted across runs. The same image is never processed twice; Frigate rejections are permanently skipped unless `RETRY_REJECTED=true`.

 ---

 ## Modes

-### Face Mode (default)
+**Face mode** (default) — extracts face crops using Immich's bounding box metadata, applies EXIF orientation correction, and aligns them to ArcFace's standard 112×112 format using 5-point facial landmarks. Crops are uploaded directly to Frigate's face registration API.

-Extracts face crops using Immich's bounding box metadata, scales them to the source image resolution, applies EXIF orientation correction, then either aligns them to the standard ArcFace 112×112 format using 5-point facial landmarks or falls back to a margin-padded bounding box crop.
-
-Crops are uploaded directly to Frigate's face registration API (`POST /api/faces/{name}/register`). After each successful upload the asset ID is marked in the tracker so future runs skip it.
-
-### Object Mode
-
-Runs each full image through YOLOv9c to detect instances of a target class (dog, cat, car, etc.), then crops each detection and saves it to the output directory. Frigate has no API for uploading object training images, so the crops are saved for you to place into your Frigate data directory manually.
-
---
-
-## Diversity Selection in Detail
-
-The core of the tool is the embedding-based selection. Rather than picking images at random or evenly across time, it computes a vector embedding for each candidate image that encodes what the face or object actually looks like — the angle, lighting, expression, background context.
-
-It then:
-
-1. **Clusters** those embeddings using K-Medoids to find natural groups (e.g. "holiday photos", "outdoor summer shots", "indoor low light")
-2. **Selects one representative** from each cluster — the most central image in each group
-3. **Fills remaining slots** using Farthest Point Sampling, iteratively picking whichever image is most different from everything already selected
-4. **Weights toward hard examples** — images with unusual angles, partial occlusions, or borderline detection confidence are more likely to be picked, because those edge cases are where models fail
-
-In **Auto mode**, there is no fixed limit. The tool keeps selecting until the most-different remaining image is already close to something already in the set — at that point adding more would be redundant. This is capped at `MAX_AUTO_IMAGES` (default 80) as a safety limit.
-
-If the embedding model is unavailable, the tool falls back to **time spread**: evenly distributing picks across the date range of your photos.
+**Object mode** — runs each full-resolution image through YOLOv9c to detect instances of a target class (dog, cat, car, etc.), crops each detection, and saves it to the output directory. Frigate has no API for uploading object training data; place the crops into your Frigate data directory manually.

 ---

@@ -113,22 +79,25 @@ If the embedding model is unavailable, the tool falls back to **time spread**: e

 ### Image Tags

-| Tag | Arch | GPU | Notes |
-| :-- | :-- | :-- | :-- |
-| `:latest` | amd64 + arm64 | CUDA 13.3 (amd64) | Requires NVIDIA Container Toolkit on amd64 |
-| `:cpu` | amd64 | None | ~2 GB smaller; use if you have no NVIDIA GPU |
+| Tag | Arch | Acceleration |
+| :-- | :-- | :-- |
+| `:latest` | amd64 + arm64 | NVIDIA CUDA 13.3 (amd64) · requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) |
+| `:rocm` | amd64 | AMD ROCm · pass `/dev/kfd` + `/dev/dri` |
+| `:intel` | amd64 | Intel Arc / iGPU via OpenVINO · pass `/dev/dri`, set `OPENVINO_DEVICE=GPU` |
+| `:cpu` | amd64 + arm64 | CPU only · ~2 GB smaller · no GPU required |

 ### Quick Start

+**NVIDIA:**
 ```yaml
 services:
  winnow:
-    image: ghcr.io/sudolulo/winnow:latest   # or :cpu for CPU-only amd64
+    image: ghcr.io/sudolulo/winnow:latest
    environment:
      - IMMICH_URL=http://192.168.1.10:2283
      - API_KEY=your-immich-api-key
      - FRIGATE_URL=http://192.168.1.10:5000
-      - CRON_SCHEDULE=0 3 * * 0   # Every Sunday at 3 AM
+      - CRON_SCHEDULE=0 3 * * 0
    volumes:
      - /path/to/models:/models
      - /path/to/cache:/app/.if_cache
@@ -142,11 +111,31 @@ services:
              capabilities: [gpu]
 ```

-> **CPU users (`:cpu` tag):** remove the `deploy.resources` block — no NVIDIA runtime needed.
+**AMD (`:rocm`):** use `image: ghcr.io/sudolulo/winnow:rocm` and replace the `deploy:` block with:
+```yaml
+    devices:
+      - /dev/kfd
+      - /dev/dri
+    group_add:
+      - video
+      - render
+```

-See [compose.yml](compose.yml) for the full annotated example.
+**Intel (`:intel`):** use `image: ghcr.io/sudolulo/winnow:intel` and replace the `deploy:` block with:
+```yaml
+    devices:
+      - /dev/dri
+    group_add:
+      - render
+    environment:
+      - OPENVINO_DEVICE=GPU   # omit to run OpenVINO inference on CPU (default)
+```

-### Scheduling Behaviour
+**CPU (`:cpu`):** use `image: ghcr.io/sudolulo/winnow:cpu`, remove the `deploy:` block, and add `mem_limit: 2g` to prevent OOM on large libraries.
+
+See [compose.yml](compose.yml) for the full annotated example with all options.
+
+### Scheduling

 `CRON_SCHEDULE` controls container lifetime:

@@ -156,69 +145,75 @@ See [compose.yml](compose.yml) for the full annotated example.
 | *(empty string)* | Stay alive, run nothing — trigger manually with `docker exec -it winnow winnow` |
 | Cron expression | Run on startup, then repeat on schedule |

-In scheduled mode the process (and loaded models) stays resident between runs. In manual mode the container idles indefinitely with `sleep infinity` — useful when you want to trigger runs interactively on demand without pulling a new container each time.
-
-The first run after a fresh install downloads the embedding models (~1-2 GB). Subsequent runs use the cached models from the mounted volume and start immediately.
+In scheduled mode the process (and loaded models) stays resident between runs. The first run after a fresh install downloads the embedding models (~1–2 GB); subsequent runs use the cached models from the mounted volume.

 ---

 ## Environment Variables

-### Mode & Strategy
-
-| Variable | Default | Description |
-| :--- | :--- | :--- |
-| `AUTO_MODE` | *(auto)* | Force non-interactive mode even in a terminal; auto-detected otherwise (no TTY = auto) |
-| `VERBOSE` | `false` | Set to `true` to enable DEBUG-level console output (the log file is always DEBUG) |
-| `TRAINING_MODE` | `face` | `face` — upload crops to Frigate API; `object` — save crops to disk |
-| `STRATEGY` | `auto` | `auto` (adaptive), `standard` (30 images), `broad` (100 images) |
-| `LIMIT` | *(unset)* | Exact image count — overrides `STRATEGY` |
-| `OBJECT_CLASS` | `dog` | Target class for object mode (any YOLO class: `dog`, `cat`, `car`, etc.) |
-
-### People Filtering
-
-| Variable | Default | Description |
-| :--- | :--- | :--- |
-| `ONLY_PEOPLE` | *(unset)* | Comma-separated whitelist — only these people are processed |
-| `SKIP_PEOPLE` | *(unset)* | Comma-separated list of people to skip |
-| `MIN_FACE_COUNT` | `0` | Skip people with fewer than N tagged assets in Immich |
-| `YEARS_FILTER` | `10` | Ignore images older than N years |
-
 ### Connection

 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `IMMICH_URL` | *(required)* | Full URL to your Immich instance |
 | `API_KEY` | *(required)* | Immich API key |
-| `FRIGATE_URL` | *(unset)* | Frigate URL — required for face upload; omit to skip upload |
+| `FRIGATE_URL` | *(unset)* | Frigate URL — required for face upload; omit to skip |
+
+### Mode & Strategy
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `TRAINING_MODE` | `face` | `face` — upload crops to Frigate; `object` — save crops to disk |
+| `STRATEGY` | `auto` | `auto` (embedding-based adaptive), `standard` (30 images), `broad` (100 images) |
+| `LIMIT` | *(unset)* | Exact image count — overrides `STRATEGY` |
+| `OBJECT_CLASS` | `dog` | Target class for object mode (any YOLO class: `dog`, `cat`, `car`, etc.) |
+| `AUTO_MODE` | *(auto)* | Force non-interactive mode in a terminal; auto-detected otherwise |
+| `VERBOSE` | `false` | Enable DEBUG-level console output (log file is always DEBUG) |
+
+### People Filtering
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `ONLY_PEOPLE` | *(unset)* | Comma-separated whitelist — process only these people |
+| `SKIP_PEOPLE` | *(unset)* | Comma-separated list — skip these people |
+| `MIN_FACE_COUNT` | `0` | Skip people with fewer than N tagged assets in Immich |
+| `YEARS_FILTER` | `10` | Ignore images older than N years |

 ### Image Quality

 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `MIN_FACE_WIDTH` | `50` | Minimum face crop width in pixels |
-| `FACE_MARGIN` | `0.15` | Padding added around the bounding box crop (fraction of face size) |
+| `FACE_MARGIN` | `0.15` | Padding around bounding box crop (fraction of face size) |
 | `ENABLE_FACE_ALIGNMENT` | `true` | Align to ArcFace 112×112 format using facial landmarks |
 | `USE_FULL_RESOLUTION` | `true` | Download full-resolution originals rather than preview thumbnails |
 | `MIN_CONFIDENCE` | `0.7` | Minimum Immich face detection confidence |
 | `BLUR_THRESHOLD` | `100.0` | Laplacian variance threshold — lower accepts more blur |
-| `MAX_AUTO_IMAGES` | `80` | Maximum images in auto-diversity mode |
+| `MAX_AUTO_IMAGES` | `80` | Maximum training images per person in Frigate |
+| `QUALITY_REPLACEMENT` | `true` | When at cap, swap the lowest-scoring tracked image for a better candidate. Never touches manually added Frigate files. Set `false` to skip people already at cap |

-### Caching & Models
+### GPU & Models

 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `FORCE_CPU` | `false` | Disable GPU — fall back to CPU for embedding computation |
+| `FORCE_CPU` | `false` | Disable GPU — fall back to CPU for all inference |
+| `OPENVINO_DEVICE` | `CPU` | Intel variant only: set `GPU` to use Arc or iGPU; default runs on CPU |
 | `ENABLE_CACHE` | `true` | Cache computed embeddings to disk (speeds up re-runs on the same library) |
 | `CACHE_DIR` | `.if_cache` | Path for embedding cache and upload tracker files |
-| `HF_HOME` | *(system)* | HuggingFace model cache location (SigLIP) |
-| `INSIGHTFACE_HOME` | *(system)* | InsightFace model cache location (Buffalo_L) |
+| `HF_HOME` | *(system)* | HuggingFace model cache path (SigLIP) |
+| `INSIGHTFACE_HOME` | *(system)* | InsightFace model cache path (Buffalo_L) |
+
+### Output
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `OUTPUT_DIR` | `./frigate_train` | Directory for object-mode crops and the `winnow.log` file. In Docker, set this via the volume mount instead. |

 ### Tracker Overrides *(one-shot — remove after use)*

 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `DRY_RUN` | `false` | Show what would be selected and uploaded without doing it |
+| `DRY_RUN` | `false` | Preview selection without downloading or uploading |
 | `RETRY_REJECTED` | `false` | Re-attempt assets previously rejected by Frigate |
 | `RESET_PERSON` | *(unset)* | Clear upload and rejection history for one person by name |

@@ -226,7 +221,7 @@ The first run after a fresh install downloads the embedding models (~1-2 GB). Su

 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `CRON_SCHEDULE` | *(unset)* | Unset = run once and exit; empty = stay alive for manual `docker exec`; cron expression = scheduled |
+| `CRON_SCHEDULE` | *(unset)* | Unset = run once and exit; empty = stay alive; cron expression = scheduled |

 ---

@@ -239,16 +234,26 @@ uv sync
 uv run winnow
 ```

-Requires Python 3.13+ and [uv](https://astral.sh/uv/). An NVIDIA GPU is strongly recommended — CPU mode works but embedding computation is significantly slower.
+Requires Python 3.13+ and [uv](https://astral.sh/uv). An NVIDIA, AMD, or Intel GPU is recommended — CPU mode works but embedding computation is slower.
+
+When run with a terminal attached, winnow starts an interactive session: select which people to process and choose a strategy (auto, standard, broad, or a custom count) per person. Without a TTY — Docker, cron, or `AUTO_MODE=true` — it processes all people automatically using the configured defaults.

 ---

 ## Requirements

 - **Immich** v1.106+
- **Frigate** v0.16+ (face mode only — object mode has no Frigate API dependency)
- **NVIDIA GPU** recommended (CUDA 12.x)
- **Python 3.13+**
+- **Frigate** v0.16+ (face mode only — object mode has no Frigate dependency)
+- **GPU** recommended: NVIDIA (CUDA), AMD (ROCm), or Intel (Arc / iGPU via OpenVINO)
+- **Python** 3.13+
+
+---
+
+## Getting Help
+
+- **[GitHub Discussions](https://github.com/sudolulo/winnow/discussions)** — questions, setup help, and general discussion
+- **[Wiki](https://github.com/sudolulo/winnow/wiki)** — setup guide, troubleshooting, and FAQ
+- **[Issues](https://github.com/sudolulo/winnow/issues)** — bugs and feature requests only

 ---

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release is supported with security fixes.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Email **holden@arch.fyi** with:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof of concept
+- Any suggested fix, if you have one
+
+You will receive an acknowledgement within 48 hours. If the vulnerability is confirmed, a fix will be released as soon as possible and you will be credited in the changelog unless you prefer otherwise.
@@ -38,6 +38,7 @@ services:

      # ── Caching & Models ──────────────────────────────────────────────────
      # - FORCE_CPU=true              # Disable GPU, fall back to CPU
+      # - OPENVINO_DEVICE=GPU         # Intel variant only: use Arc/iGPU instead of CPU (default: CPU)
      # - ENABLE_CACHE=false          # Disable embedding cache (default: true)
      - CACHE_DIR=/app/.if_cache
      - HF_HOME=/models/huggingface
@@ -63,6 +64,9 @@ services:
      - /path/to/winnow/cache:/app/.if_cache
      - /path/to/winnow/output:/app/frigate_train
    restart: unless-stopped
+
+    # ── GPU device passthrough ─────────────────────────────────────────────────
+    # NVIDIA (default — requires nvidia-container-toolkit):
    deploy:
      resources:
        reservations:
@@ -70,3 +74,18 @@ services:
            - driver: nvidia
              count: all
              capabilities: [gpu]
+    #
+    # AMD ROCm — replace the deploy block above with:
+    #   devices:
+    #     - /dev/kfd
+    #     - /dev/dri
+    #   group_add:
+    #     - video
+    #     - render
+    #
+    # Intel Arc / iGPU — replace the deploy block above with:
+    #   devices:
+    #     - /dev/dri
+    #   group_add:
+    #     - render
+    #   Also set: OPENVINO_DEVICE=GPU in the environment section above.
@@ -1,6 +1,6 @@
 [project]
 name = "winnow"
-version = "0.2.10"
+version = "0.2.13"
 description = "Immich to Frigate training sets"
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.13"
@@ -25,7 +25,7 @@ dependencies = [
    "rich>=14.2.0",
    "torch>=2.12.0",
    "torchvision>=0.27.0",
-    "transformers>=4.57.6",
+    "transformers>=5.12.0",
    "ultralytics>=8.4.66",
 ]

@@ -0,0 +1,103 @@
+[project]
+name = "winnow"
+version = "0.2.13"
+description = "Immich to Frigate training sets"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.13"
+authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
+keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface", "insightface"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "croniter>=5.0.2",
+    "insightface>=0.7.3",
+    "numpy>=2.2.6",
+    "onnxruntime-openvino>=1.20.0",
+    "opencv-python-headless>=4.12.0.88",
+    "pillow>=12.1.0",
+    "python-dotenv>=1.2.1",
+    "requests>=2.32.5",
+    "rich>=14.2.0",
+    "torch>=2.12.0",
+    "torchvision>=0.27.0",
+    "transformers>=5.12.0",
+    "ultralytics>=8.4.66",
+]
+
+[project.scripts]
+winnow = "winnow.cli:main"
+
+[project.urls]
+Repository = "https://github.com/sudolulo/winnow"
+
+[tool.uv]
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+        { package = "onnxruntime-openvino" },
+    ],
+]
+required-environments = [
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+torchvision = [
+    { index = "pytorch-cpu", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.15.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["winnow"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.deptry]
+pep621_dev_dependency_groups = ["dev"]
+
+[tool.deptry.package_module_name_map]
+pillow = "PIL"
+opencv-python-headless = "cv2"
+python-dotenv = "dotenv"
+insightface = "insightface"
+numpy = "numpy"
+onnxruntime-openvino = "onnxruntime"
+requests = "requests"
+rich = "rich"
+torch = "torch"
+transformers = "transformers"
+ultralytics = "ultralytics"
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["onnxruntime-openvino"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
@@ -0,0 +1,103 @@
+[project]
+name = "winnow"
+version = "0.2.13"
+description = "Immich to Frigate training sets"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.13"
+authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
+keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface", "insightface"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "croniter>=5.0.2",
+    "insightface>=0.7.3",
+    "numpy>=2.2.6",
+    "onnxruntime-rocm>=1.16.0",
+    "opencv-python-headless>=4.12.0.88",
+    "pillow>=12.1.0",
+    "python-dotenv>=1.2.1",
+    "requests>=2.32.5",
+    "rich>=14.2.0",
+    "torch>=2.5.0",
+    "torchvision>=0.20.0",
+    "transformers>=5.12.0",
+    "ultralytics>=8.4.66",
+]
+
+[project.scripts]
+winnow = "winnow.cli:main"
+
+[project.urls]
+Repository = "https://github.com/sudolulo/winnow"
+
+[tool.uv]
+index-strategy = "unsafe-best-match"
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+        { package = "onnxruntime-rocm" },
+    ],
+]
+required-environments = [
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-rocm63", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+torchvision = [
+    { index = "pytorch-rocm63", marker = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-rocm63"
+url = "https://download.pytorch.org/whl/rocm6.3"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.15.17",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["winnow"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.deptry]
+pep621_dev_dependency_groups = ["dev"]
+
+[tool.deptry.package_module_name_map]
+pillow = "PIL"
+opencv-python-headless = "cv2"
+python-dotenv = "dotenv"
+insightface = "insightface"
+numpy = "numpy"
+onnxruntime-rocm = "onnxruntime"
+requests = "requests"
+rich = "rich"
+torch = "torch"
+transformers = "transformers"
+ultralytics = "ultralytics"
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["onnxruntime-rocm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
@@ -1,7 +1,7 @@
 [project]
 name = "winnow"
-version = "0.2.10"
-description = "Immich to Frigate training sets"
+version = "0.3.2"
+description = "Selects diverse, high-quality photos from Immich as training data for Frigate face recognition and object classification."
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.13"
 authors = [{ name = "Holden Salomon", email = "holden@arch.fyi" }]
@@ -9,6 +9,7 @@ keywords = ["immich", "frigate", "face-recognition", "training-data", "arcface",
 classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
    "Programming Language :: Python :: 3.13",
    "Topic :: Scientific/Engineering :: Image Recognition",
@@ -28,7 +29,7 @@ dependencies = [
    "rich>=14.2.0",
    "torch>=2.12.0",
    "torchvision>=0.27.0",
-    "transformers>=4.57.6",
+    "transformers>=5.12.0",
    "ultralytics>=8.4.66",
 ]

@@ -37,9 +38,16 @@ winnow = "winnow.cli:main"

 [project.urls]
 Repository = "https://github.com/sudolulo/winnow"
+Changelog = "https://github.com/sudolulo/winnow/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/sudolulo/winnow/wiki"

 [tool.uv]
-override-dependencies = ["onnxruntime>=1.23.2"]
+conflicts = [
+    [
+        { package = "onnxruntime" },
+        { package = "onnxruntime-gpu" },
+    ],
+]
 required-environments = [
    "sys_platform == 'linux' and platform_machine == 'x86_64'",
    "sys_platform == 'linux' and platform_machine == 'aarch64'",
@@ -22,6 +22,7 @@ def test_config_loads_defaults(monkeypatch):
    assert cfg.BLUR_THRESHOLD == 100.0
    assert cfg.MIN_CONFIDENCE == 0.7
    assert cfg.MAX_AUTO_IMAGES == 80
+    assert cfg.QUALITY_REPLACEMENT is True
    assert cfg.FACE_MARGIN == 0.15
    assert cfg.USE_FULL_RESOLUTION is True
    assert cfg.ENABLE_FACE_ALIGNMENT is True
@@ -39,6 +40,7 @@ def test_config_env_overrides(monkeypatch):
    monkeypatch.setenv("BLUR_THRESHOLD", "50.0")
    monkeypatch.setenv("MIN_CONFIDENCE", "0.9")
    monkeypatch.setenv("MAX_AUTO_IMAGES", "40")
+    monkeypatch.setenv("QUALITY_REPLACEMENT", "false")
    monkeypatch.setenv("FACE_MARGIN", "0.2")
    monkeypatch.setenv("USE_FULL_RESOLUTION", "false")
    monkeypatch.setenv("ENABLE_FACE_ALIGNMENT", "false")
@@ -54,6 +56,7 @@ def test_config_env_overrides(monkeypatch):
    assert cfg.BLUR_THRESHOLD == 50.0
    assert cfg.MIN_CONFIDENCE == 0.9
    assert cfg.MAX_AUTO_IMAGES == 40
+    assert cfg.QUALITY_REPLACEMENT is False
    assert cfg.FACE_MARGIN == 0.2
    assert cfg.USE_FULL_RESOLUTION is False
    assert cfg.ENABLE_FACE_ALIGNMENT is False
@@ -134,6 +134,16 @@ def test_assess_quality_passes_good_image():
    img = _noisy_color_image()
    result = assess_quality(img, face_bbox=(10, 10, 110, 110), confidence=0.9)
    assert result.passed
+    assert result.blur_score is not None
+    assert result.blur_score > 0
+
+
+def test_assess_quality_blur_score_is_low_for_flat_image():
+    from winnow.quality import assess_quality
+    flat = _rgb_image(128, 128, 128)
+    result = assess_quality(flat)
+    assert result.blur_score is not None
+    assert result.blur_score < 1.0


 def test_assess_quality_collects_multiple_failures():
@@ -69,3 +69,152 @@ def test_duplicate_marks_are_idempotent():
    mark_uploaded("dup", person_name="Alice")
    mark_uploaded("dup", person_name="Alice")
    assert filter_already_uploaded(["dup", "new"]) == ["new"]
+
+
+# ── frigate_files mapping ─────────────────────────────────────────────────────
+
+def test_record_and_remove_frigate_file():
+    from winnow.upload_tracker import get_person_summary, record_frigate_file, remove_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a1")
+    assert "Alice-1000.webp" in get_person_summary()["Alice"]["frigate_files"]
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    assert "Alice-1000.webp" not in get_person_summary()["Alice"]["frigate_files"]
+
+
+def test_remove_nonexistent_frigate_file_is_safe():
+    from winnow.upload_tracker import remove_frigate_file
+    # Should not raise even if the file was never recorded
+    remove_frigate_file("Alice", "Alice-ghost.webp")
+
+
+def test_remove_frigate_file_does_not_unmark_asset():
+    """Deleting a Frigate file should not re-expose the source asset for upload."""
+    from winnow.upload_tracker import (
+        filter_already_uploaded,
+        mark_uploaded,
+        record_frigate_file,
+        remove_frigate_file,
+    )
+    mark_uploaded("asset-a1", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a1")
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    # Asset must still be excluded — it was deliberately replaced, not lost
+    assert filter_already_uploaded(["asset-a1"]) == []
+
+
+def test_get_tracked_frigate_file_count_zero_when_empty():
+    from winnow.upload_tracker import get_tracked_frigate_file_count
+    assert get_tracked_frigate_file_count("Alice") == 0
+
+
+def test_get_tracked_frigate_file_count_counts_only_mapped():
+    """Only files explicitly recorded via record_frigate_file count toward the cap."""
+    from winnow.upload_tracker import get_tracked_frigate_file_count, mark_uploaded, record_frigate_file
+    mark_uploaded("asset-a", person_name="Alice")
+    mark_uploaded("asset-b", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    # asset-b is uploaded but not yet mapped — does not count
+    assert get_tracked_frigate_file_count("Alice") == 1
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    assert get_tracked_frigate_file_count("Alice") == 2
+
+
+def test_get_lowest_quality_mapped_file_none_when_empty():
+    from winnow.upload_tracker import get_lowest_quality_mapped_file
+    assert get_lowest_quality_mapped_file("Alice") is None
+
+
+def test_get_lowest_quality_mapped_file_returns_lowest():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-hi", person_name="Alice", score=0.95)
+    mark_uploaded("asset-lo", person_name="Alice", score=0.71)
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-hi")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-lo")
+    result = get_lowest_quality_mapped_file("Alice")
+    assert result is not None
+    frigate_filename, asset_id, score = result
+    assert frigate_filename == "Alice-1001.webp"
+    assert asset_id == "asset-lo"
+    assert score == pytest.approx(0.71, abs=0.001)
+
+
+def test_get_lowest_quality_mapped_file_skips_unscored():
+    """Files mapped without a score should not be returned as candidates."""
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-scored", person_name="Alice", score=0.85)
+    mark_uploaded("asset-noscr", person_name="Alice")
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-scored")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-noscr")
+    result = get_lowest_quality_mapped_file("Alice")
+    assert result is not None
+    assert result[1] == "asset-scored"  # only scored file is a candidate
+
+
+# ── get_tracked_frigate_filenames ─────────────────────────────────────────────
+
+def test_get_tracked_frigate_filenames_empty():
+    from winnow.upload_tracker import get_tracked_frigate_filenames
+    assert get_tracked_frigate_filenames("Alice") == set()
+
+
+def test_get_tracked_frigate_filenames_returns_mapped():
+    from winnow.upload_tracker import get_tracked_frigate_filenames, record_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1000.webp", "Alice-1001.webp"}
+
+
+def test_get_tracked_frigate_filenames_excludes_removed():
+    from winnow.upload_tracker import (
+        get_tracked_frigate_filenames,
+        record_frigate_file,
+        remove_frigate_file,
+    )
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Alice", "Alice-1001.webp", "asset-b")
+    remove_frigate_file("Alice", "Alice-1000.webp")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1001.webp"}
+
+
+def test_get_tracked_frigate_filenames_isolated_by_person():
+    from winnow.upload_tracker import get_tracked_frigate_filenames, record_frigate_file
+    record_frigate_file("Alice", "Alice-1000.webp", "asset-a")
+    record_frigate_file("Bob", "Bob-2000.webp", "asset-b")
+    assert get_tracked_frigate_filenames("Alice") == {"Alice-1000.webp"}
+    assert get_tracked_frigate_filenames("Bob") == {"Bob-2000.webp"}
+
+
+# ── get_lowest_quality_mapped_file with exclude ───────────────────────────────
+
+def test_get_lowest_quality_exclude_skips_specified_file():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-lo", person_name="Alice", score=0.10)
+    mark_uploaded("asset-hi", person_name="Alice", score=0.90)
+    record_frigate_file("Alice", "Alice-lo.webp", "asset-lo")
+    record_frigate_file("Alice", "Alice-hi.webp", "asset-hi")
+    result = get_lowest_quality_mapped_file("Alice", exclude={"Alice-lo.webp"})
+    assert result is not None
+    assert result[1] == "asset-hi"  # lo was excluded; hi is returned
+
+
+def test_get_lowest_quality_exclude_all_returns_none():
+    from winnow.upload_tracker import (
+        get_lowest_quality_mapped_file,
+        mark_uploaded,
+        record_frigate_file,
+    )
+    mark_uploaded("asset-a", person_name="Alice", score=0.50)
+    record_frigate_file("Alice", "Alice-a.webp", "asset-a")
+    assert get_lowest_quality_mapped_file("Alice", exclude={"Alice-a.webp"}) is None
@@ -1724,7 +1724,7 @@ wheels = [

 [[package]]
 name = "transformers"
-version = "5.11.0"
+version = "5.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "huggingface-hub" },
@@ -1737,9 +1737,9 @@ dependencies = [
    { name = "tqdm" },
    { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/4a/2ee05f9a06bb2dd34cac951548553738a826762fb7adfa7ce256daeaeac8/transformers-5.11.0.tar.gz", hash = "sha256:1dbecade5b8a09bdf3e9e8fdfc9d312cb9eccf5a201080dc894b373f0f3eb5f4", size = 8874363, upload-time = "2026-06-10T16:31:52.441Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/0c/f9/4552e2ba55db1c943aea0d4c09a32e9cbe5445b9eabe9856900de503dc8f/transformers-5.12.0.tar.gz", hash = "sha256:f0cf42ae1464c2eb41e7e0e66d7fd4b66145f48af17093b4cc0b2e9781faa7f4", size = 8923020, upload-time = "2026-06-12T14:39:20.43Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/9b/40/30fdefda9b8aff8d36054dbb37d8e1464cc1130c29623403c3c2147bdee1/transformers-5.11.0-py3-none-any.whl", hash = "sha256:06d0a34eab529955f8e704b530663c7d6bd6f9c7a9e47a05cddb4a44e7b6566b", size = 11094597, upload-time = "2026-06-10T16:31:49.08Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/1f/d385913c38e900d23b728a4188fee625f2fccb306aeebc59be9d91404a5a/transformers-5.12.0-py3-none-any.whl", hash = "sha256:500be9eb644ede81c3103eee7687fc36d05dd75d1c76686c3820b26396fe7c7c", size = 11150246, upload-time = "2026-06-12T14:39:17.009Z" },
 ]

 [[package]]
@@ -1832,7 +1832,7 @@ wheels = [

 [[package]]
 name = "winnow"
-version = "0.2.9"
+version = "0.2.13"
 source = { editable = "." }
 dependencies = [
    { name = "croniter" },
@@ -1873,7 +1873,7 @@ requires-dist = [
    { name = "torch", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'", specifier = ">=2.12.0", index = "https://download.pytorch.org/whl/cpu" },
    { name = "torchvision", marker = "platform_machine != 'x86_64' or sys_platform != 'linux'", specifier = ">=0.27.0" },
    { name = "torchvision", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'", specifier = ">=0.27.0", index = "https://download.pytorch.org/whl/cpu" },
-    { name = "transformers", specifier = ">=4.57.6" },
+    { name = "transformers", specifier = ">=5.12.0" },
    { name = "ultralytics", specifier = ">=8.4.66" },
 ]

@@ -12,17 +12,53 @@ from .executor import execute_jobs, upload_to_frigate
 from .immich_api import get_people
 from .jobs import _show_preview, auto_configure, interactive_configure
 from .log_config import console, setup_logging
-from .upload_tracker import get_person_summary, reset_person
+from .upload_tracker import find_by_crop_dimension, get_person_summary, reset_person

 logger = logging.getLogger(__name__)


+def _handle_trace_crop(size_str: str) -> None:
+    """Print tracker records whose crop dimension matches the given pixel size and exit."""
+    try:
+        size = int(size_str)
+    except ValueError:
+        rprint(f"[bold red]TRACE_CROP_SIZE must be an integer, got: {size_str!r}[/bold red]")
+        sys.exit(1)
+
+    immich_url = os.environ.get("IMMICH_URL", "").rstrip("/")
+    matches = find_by_crop_dimension(size)
+    if not matches:
+        rprint(f"[yellow]No crops with dimension {size}px found in tracker.[/yellow]")
+        rprint("[dim]Note: crop dimensions are only recorded for uploads made after this feature was added.[/dim]")
+        sys.exit(0)
+
+    rprint(f"\n[bold]Crops matching dimension {size}px:[/bold] ({len(matches)} found)\n")
+    for m in matches:
+        rprint(f"  [bold cyan]{m['person']}[/bold cyan]")
+        rprint(f"    Dimensions:   {m['width']}×{m['height']}px")
+        rprint(f"    Asset ID:     {m['asset_id']}")
+        if immich_url:
+            rprint(f"    Immich URL:   {immich_url}/photos/{m['asset_id']}")
+        blur = m.get("blur_score")
+        rprint(f"    Blur score:   {blur:.1f}" if blur is not None else "    Blur score:   unknown")
+        if m.get("frigate_filename"):
+            rprint(f"    Frigate file: {m['frigate_filename']}")
+        else:
+            rprint("    Frigate file: [dim]unmapped (reconciliation race)[/dim]")
+        rprint()
+    sys.exit(0)
+
+
 def main() -> None:
    """Entry point for winnow CLI."""
    try:
        verbose = os.environ.get("VERBOSE", "").lower() in ("true", "1", "yes")
        setup_logging(verbose=verbose)

+        trace_size = os.environ.get("TRACE_CROP_SIZE", "").strip()
+        if trace_size:
+            _handle_trace_crop(trace_size)
+
        console.print(r"""
    [bold blue]winnow[/bold blue]
    [dim]Immich -> Frigate Training Data Curator[/dim]
@@ -30,6 +30,7 @@ class _Config:
    BLUR_THRESHOLD: float = 100.0
    MIN_CONFIDENCE: float = 0.7
    MAX_AUTO_IMAGES: int = 80
+    QUALITY_REPLACEMENT: bool = True

    # People filtering
    MIN_FACE_COUNT: int = 0
@@ -60,6 +61,7 @@ class _Config:
        self.BLUR_THRESHOLD = float(os.getenv("BLUR_THRESHOLD", "100.0"))
        self.MIN_CONFIDENCE = float(os.getenv("MIN_CONFIDENCE", "0.7"))
        self.MAX_AUTO_IMAGES = int(os.getenv("MAX_AUTO_IMAGES", "80"))
+        self.QUALITY_REPLACEMENT = os.getenv("QUALITY_REPLACEMENT", "true").lower() in ("true", "1", "yes")
        self.FACE_MARGIN = float(os.getenv("FACE_MARGIN", "0.15"))
        self.USE_FULL_RESOLUTION = os.getenv("USE_FULL_RESOLUTION", "true").lower() in ("true", "1", "yes")
        self.ENABLE_FACE_ALIGNMENT = os.getenv("ENABLE_FACE_ALIGNMENT", "true").lower() in ("true", "1", "yes")
@@ -203,64 +203,72 @@ def _select_by_embedding(
    else:
        candidates = assets

-    # --- Phase 1: Concurrent thumbnail download ---
+    # --- Phases 1-4: Batched download → quality filter → crop → embed ---
+    # Process in bounded batches so at most _BATCH decoded images live in RAM
+    # at once. With 472 candidates each thumbnail is ~3-8 MB decoded; loading
+    # all at once easily exhausts a 4 GB container limit on CPU.
    from concurrent.futures import ThreadPoolExecutor, as_completed

-    thumbnail_map: dict[str, Image.Image] = {}
-    with ThreadPoolExecutor(max_workers=8) as pool:
-        futures = {pool.submit(_fetch_thumbnail, a["id"]): a for a in candidates}
-        for i, future in enumerate(as_completed(futures)):
-            if progress_callback:
-                progress_callback(i, len(candidates))
-            asset = futures[future]
-            try:
-                img = future.result()
-                if img is not None:
-                    thumbnail_map[asset["id"]] = img
-            except Exception:
-                continue
-
-    # --- Phase 2-4: Quality filter → Crop → Embed ---
+    _BATCH = 32
    embeddings, valid_candidates, confidence_scores = [], [], []
    quality_filtered = 0
+    processed = 0

-    for asset in candidates:
-        img = thumbnail_map.get(asset["id"])
-        if img is None:
-            continue
+    for batch_start in range(0, len(candidates), _BATCH):
+        batch = candidates[batch_start : batch_start + _BATCH]

-        confidence = _get_face_confidence(asset, person_id=person_id)
+        # Download this batch concurrently
+        batch_images: dict[str, Image.Image] = {}
+        with ThreadPoolExecutor(max_workers=min(8, len(batch))) as pool:
+            futures = {pool.submit(_fetch_thumbnail, a["id"]): a for a in batch}
+            for future in as_completed(futures):
+                asset = futures[future]
+                try:
+                    img = future.result()
+                    if img is not None:
+                        batch_images[asset["id"]] = img
+                except Exception as e:
+                    logger.debug(f"Failed to fetch thumbnail for {asset['id']}: {e}")
+                    continue

-        # Quality gate: filter before expensive embedding computation
-        if entity_type == "face":
-            face_bbox = _get_face_bbox(asset, person_id=person_id)
-            quality = assess_quality(
-                img,
-                face_bbox=face_bbox,
-                confidence=confidence,
-                blur_threshold=Config.BLUR_THRESHOLD,
-                min_face_px=Config.MIN_FACE_WIDTH,
-                min_confidence=Config.MIN_CONFIDENCE,
-            )
-            if not quality.passed:
-                quality_filtered += 1
-                logger.debug(f"Quality filtered {asset['id']}: {quality.reason}")
+        # Process each image; batch_images goes out of scope after this loop,
+        # bounding peak thumbnail memory to _BATCH images per iteration.
+        for asset in batch:
+            img = batch_images.get(asset["id"])
+            processed += 1
+            if progress_callback:
+                progress_callback(processed, len(candidates))
+            if img is None:
                continue

-            # Crop the target person's face before embedding
-            face_crop = _crop_face_from_thumbnail(img, asset, person_id=person_id)
-            embed_img = face_crop if face_crop is not None else img
-        else:
-            embed_img = img
+            confidence = _get_face_confidence(asset, person_id=person_id)

-        emb = get_embedding(embed_img, entity_type, asset_id=asset["id"])
-        if emb is not None:
-            embeddings.append(emb)
-            valid_candidates.append(asset)
-            confidence_scores.append(confidence)
+            if entity_type == "face":
+                face_bbox = _get_face_bbox(asset, person_id=person_id)
+                quality = assess_quality(
+                    img,
+                    face_bbox=face_bbox,
+                    confidence=confidence,
+                    blur_threshold=Config.BLUR_THRESHOLD,
+                    min_face_px=Config.MIN_FACE_WIDTH,
+                    min_confidence=Config.MIN_CONFIDENCE,
+                )
+                if not quality.passed:
+                    quality_filtered += 1
+                    logger.debug(f"Quality filtered {asset['id']}: {quality.reason}")
+                    continue

-    if progress_callback:
-        progress_callback(len(candidates), len(candidates))
+                asset["quality_score"] = quality.blur_score
+                face_crop = _crop_face_from_thumbnail(img, asset, person_id=person_id)
+                embed_img = face_crop if face_crop is not None else img
+            else:
+                embed_img = img
+
+            emb = get_embedding(embed_img, entity_type, asset_id=asset["id"])
+            if emb is not None:
+                embeddings.append(emb)
+                valid_candidates.append(asset)
+                confidence_scores.append(confidence)

    if quality_filtered > 0:
        logger.info(f"Quality filtering removed {quality_filtered} images.")
@@ -85,15 +85,16 @@ def get_insightface_app():
        return _insightface_app
    _insightface_loaded = True

-    # Preload CUDA/cuDNN DLLs BEFORE any ORT InferenceSession is created
-    _preload_cuda_libs()
-
    ctx_id = -1
    insightface_home = os.environ.get("INSIGHTFACE_HOME", os.path.expanduser("~/.insightface"))
    try:
        import onnxruntime as ort
        from insightface.app import FaceAnalysis

+        # Preload CUDA/cuDNN DLLs before any ORT InferenceSession is created.
+        # Silently no-ops on ROCm/Intel builds where preload_dlls() is absent.
+        _preload_cuda_libs()
+
        # Disk cache check — lets the user know whether a download is coming
        buffalo_path = Path(insightface_home) / "models" / "buffalo_l"
        if buffalo_path.exists() and any(buffalo_path.iterdir()):
@@ -110,18 +111,35 @@ def get_insightface_app():
            "ROCmExecutionProvider",
            "MPSExecutionProvider",
            "CoreMLExecutionProvider",
+            "OpenVINOExecutionProvider",
        }
        has_gpu_provider = bool(gpu_providers & set(providers))
        ctx_id = -1 if _is_force_cpu() else (0 if has_gpu_provider else -1)

+        # For OpenVINO EP, inject device_type from env var (default CPU; set GPU for Intel Arc/iGPU)
+        has_openvino = "OpenVINOExecutionProvider" in providers
+        if has_openvino:
+            openvino_device = os.getenv("OPENVINO_DEVICE", "CPU")
+            providers = [
+                ("OpenVINOExecutionProvider", {"device_type": openvino_device})
+                if p == "OpenVINOExecutionProvider" else p
+                for p in providers
+            ]
+            logger.debug(f"OpenVINO EP: device_type={openvino_device}")
+
        if not has_gpu_provider and not _is_force_cpu():
            logger.warning(
                "No GPU execution provider found — running InsightFace on CPU. "
-                "If you have an NVIDIA GPU, ensure the NVIDIA Container Toolkit is "
-                "installed and the container has GPU access (deploy.resources in compose)."
+                "Ensure the container has GPU access and the correct variant image is used "
+                "(gpu for NVIDIA, rocm for AMD, intel for Intel Arc/iGPU)."
            )

-        device_str = "GPU" if ctx_id >= 0 else "CPU"
+        if ctx_id < 0:
+            device_str = "CPU"
+        elif has_openvino:
+            device_str = f"OpenVINO ({os.getenv('OPENVINO_DEVICE', 'CPU')})"
+        else:
+            device_str = "GPU"
        logger.info(f"InsightFace Buffalo_L: loading into memory on {device_str}...")

        t0 = time.time()
@@ -223,11 +241,14 @@ def get_siglip_model():

        _siglip_model.eval()

-        # Move to GPU if available
+        # Move to GPU if available (ROCm builds expose torch.cuda.is_available() == True)
        if not _is_force_cpu():
            if torch.cuda.is_available():
                _siglip_model = _siglip_model.cuda()
                device_name = "CUDA GPU"
+            elif hasattr(torch, "xpu") and torch.xpu.is_available():
+                _siglip_model = _siglip_model.to("xpu")
+                device_name = "Intel XPU"
            elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
                _siglip_model = _siglip_model.to("mps")
                device_name = "Apple MPS"
@@ -3,6 +3,7 @@
 import logging
 import os
 import shutil
+import time
 from io import BytesIO
 from urllib.parse import quote

@@ -12,14 +13,86 @@ from rich import print as rprint
 from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn

 from .config import Config, get_headers
+from .frigate_api import delete_frigate_person_files, get_frigate_person_files
 from .image_processing import process_face_mode, process_full_mode, process_object_mode
 from .immich_api import fetch_face_data, fetch_full_image
 from .log_config import console
-from .upload_tracker import mark_rejected, mark_uploaded
+from .quality import assess_quality
+from .upload_tracker import (
+    get_lowest_quality_mapped_file,
+    get_tracked_frigate_file_count,
+    get_tracked_frigate_filenames,
+    mark_rejected,
+    mark_uploaded,
+    record_frigate_file,
+    remove_frigate_file,
+)

 logger = logging.getLogger(__name__)


+def _reconcile_frigate_mappings(
+    person_name: str,
+    known_files_before: set[str],
+    uploaded: list[tuple[str, str | None]],
+) -> None:
+    """Map Frigate filenames to asset IDs after a batch of uploads.
+
+    Polls until all expected new files appear in the Frigate API, then maps
+    them to asset IDs by filename timestamp order (Frigate processes the
+    upload queue in FIFO order, so earlier uploads get earlier timestamps).
+
+    KNOWN LIMITATION — race condition with external uploads:
+    If another client uploads a face file for this person concurrently, the
+    count of new files will exceed `len(uploaded)` and we bail out entirely
+    (the "> target" branch). That's safe — we never record a wrong mapping —
+    but those uploads become permanently unmapped (they won't be eligible for
+    quality replacement). The right fix is a Frigate API that returns the
+    filename in the upload response, removing the need for any post-upload
+    diffing. Until then, the external-upload guard keeps mappings correct at
+    the cost of occasionally missing them when another client is active.
+    """
+    target = len(uploaded)
+    current_files: set[str] = set()
+
+    for delay in (1, 2, 4, 8):
+        time.sleep(delay)
+        fresh = get_frigate_person_files(person_name)
+        if fresh is None:
+            logger.warning(
+                f"{person_name}: Frigate API unreachable during mapping reconciliation"
+                " — quality replacement won't target these files"
+            )
+            return
+        current_files = set(fresh)
+        if len(current_files - known_files_before) >= target:
+            break
+
+    new_files = current_files - known_files_before
+
+    if len(new_files) == target:
+        def _ts(fname: str) -> float:
+            try:
+                return float(fname.rsplit("_", 1)[-1].replace(".webp", ""))
+            except (ValueError, IndexError):
+                return 0.0
+
+        for (fname, asset_id), frigate_file in zip(uploaded, sorted(new_files, key=_ts)):
+            if asset_id:
+                record_frigate_file(person_name, frigate_file, asset_id)
+        logger.debug(f"{person_name}: batch-mapped {target} Frigate file(s)")
+    elif len(new_files) > target:
+        logger.info(
+            f"{person_name}: {len(new_files)} new Frigate files for {target} uploads"
+            " (external upload detected) — skipping file mapping"
+        )
+    else:
+        logger.warning(
+            f"{person_name}: only {len(new_files)} of {target} expected Frigate files"
+            " appeared after reconciliation — mapping skipped"
+        )
+
+
 def _enrich_asset_with_face_data(asset: dict, person: dict) -> dict:
    """Enrich an asset dict with face bounding box data from the Immich faces API.

@@ -97,9 +170,10 @@ def execute_jobs(jobs: list[dict]) -> None:
                shutil.rmtree(person_dir)
            os.makedirs(person_dir, exist_ok=True)

-            # Track filename → asset_id and filename → confidence score
+            # Track filename → asset_id, filename → confidence score, filename → crop dims
            asset_map: dict[str, str] = {}
            score_map: dict[str, float | None] = {}
+            dims_map: dict[str, tuple[int, int]] = {}

            count = 0
            for asset in assets:
@@ -134,7 +208,24 @@ def execute_jobs(jobs: list[dict]) -> None:
                            # Record which asset produced which output file
                            filename = f"{count}.jpg"
                            asset_map[filename] = asset["id"]
-                            score_map[filename] = asset.get("face_confidence")
+                            score_map[filename] = asset.get("quality_score")
+                            if mode == "face" and isinstance(saved, tuple):
+                                dims_map[filename] = saved
+                            # Time-spread path: compute blur score from the downloaded
+                            # image. Cap at 1440px so the scale matches the preview
+                            # thumbnails the embedding path uses for scoring — Laplacian
+                            # variance grows with resolution, making full-res and
+                            # thumbnail scores incomparable if left uncapped.
+                            if mode == "face" and score_map[filename] is None:
+                                try:
+                                    score_img = img.convert("RGB") if img.mode != "RGB" else img
+                                    if score_img.width > 1440 or score_img.height > 1440:
+                                        score_img = score_img.copy()
+                                        score_img.thumbnail((1440, 1440), Image.LANCZOS)
+                                    score_map[filename] = assess_quality(score_img).blur_score
+                                except Exception as exc:
+                                    logger.debug(f"Quality score fallback for {asset['id']}: {exc}")
+                                    score_map[filename] = 0.0  # unknown quality — treat as lowest
                            # Also record object-mode variant filenames
                            if mode == "object":
                                for f in sorted(os.listdir(person_dir)):
@@ -156,6 +247,7 @@ def execute_jobs(jobs: list[dict]) -> None:
            # Store maps on the job so upload_to_frigate can use them
            job["asset_map"] = asset_map
            job["score_map"] = score_map
+            job["dims_map"] = dims_map

            progress.remove_task(job_task)

@@ -236,6 +328,7 @@ def upload_to_frigate(jobs: list[dict]) -> None:

            asset_map = filename_to_asset_id.get(name, {})
            score_map = job.get("score_map", {})
+            dims_map = job.get("dims_map", {})
            person_files = sorted(asset_map.keys())

            if not person_files:
@@ -246,8 +339,80 @@ def upload_to_frigate(jobs: list[dict]) -> None:
            person_uploaded = 0
            person_failed = 0

+            # Snapshot live Frigate files for post-upload reconciliation diff only.
+            # effective_count is sourced from the tracker (mapped files) so that
+            # manually-added Frigate files don't consume winnow's managed quota.
+            _snapshot = get_frigate_person_files(name)
+            if _snapshot is None:
+                # Frigate GET is down; fall back to the tracker's mapped filenames
+                # as the pre-upload baseline. reconciliation will still work unless
+                # there are concurrent manual uploads (handled by >target guard).
+                logger.warning(
+                    f"{name}: Frigate API unreachable at upload start"
+                    " — using tracker baseline for post-upload reconciliation"
+                )
+                known_frigate_files_at_start: set[str] = get_tracked_frigate_filenames(name)
+            else:
+                known_frigate_files_at_start: set[str] = set(_snapshot)
+            effective_count = get_tracked_frigate_file_count(name)
+            quality_replacement = job.get("config", {}).get("quality_replacement", False)
+            actually_uploaded: list[tuple[str, str | None]] = []
+            failed_deletes: set[str] = set()
+            min_quality_score_for_slot: float | None = None
+
            for fname in person_files:
                fpath = os.path.join(person_dir, fname)
+
+                # If a previous replacement delete succeeded but that upload failed,
+                # require the next candidate to beat the deleted file's score so the
+                # freed slot isn't filled with something worse than what we removed.
+                if min_quality_score_for_slot is not None:
+                    file_score = score_map.get(fname)
+                    if file_score is None or file_score <= min_quality_score_for_slot:
+                        score_str = f"{file_score:.3f}" if file_score is not None else "N/A"
+                        progress.console.print(
+                            f"    [dim]⏭  {fname}: score {score_str} ≤ freed slot floor"
+                            f" {min_quality_score_for_slot:.3f}, skipping[/dim]"
+                        )
+                        progress.advance(upload_task)
+                        continue
+
+                at_cap = effective_count >= Config.MAX_AUTO_IMAGES
+                if at_cap:
+                    if not quality_replacement:
+                        progress.console.print(f"    [dim]⏭  {fname}: at cap, quality replacement disabled[/dim]")
+                        progress.advance(upload_task)
+                        continue
+                    new_score = score_map.get(fname)
+                    if new_score is None:
+                        progress.console.print(f"    [dim]⏭  {fname}: no confidence score, skipping replacement[/dim]")
+                        progress.advance(upload_task)
+                        continue
+                    worst = get_lowest_quality_mapped_file(name, exclude=failed_deletes)
+                    if worst is None or new_score <= worst[2]:
+                        worst_score_str = f"{worst[2]:.3f}" if worst is not None else "N/A"
+                        progress.console.print(
+                            f"    [dim]⏭  {fname}: score {new_score:.3f} ≤ worst mapped"
+                            f" {worst_score_str}, skipping[/dim]"
+                        )
+                        progress.advance(upload_task)
+                        continue
+                    # Delete the worst mapped file to make room for the better one
+                    worst_frigate_file, _worst_asset_id, worst_score = worst
+                    progress.console.print(
+                        f"    🔄 {fname}: score {new_score:.3f} > {worst_score:.3f},"
+                        f" replacing {worst_frigate_file}"
+                    )
+                    if delete_frigate_person_files(name, [worst_frigate_file]):
+                        remove_frigate_file(name, worst_frigate_file)
+                        effective_count -= 1
+                        min_quality_score_for_slot = worst_score
+                    else:
+                        logger.warning(f"Failed to delete {worst_frigate_file} for {name}, skipping replacement")
+                        failed_deletes.add(worst_frigate_file)
+                        progress.advance(upload_task)
+                        continue
+
                for attempt in range(1, max_retries + 1):
                    try:
                        with open(fpath, "rb") as f:
@@ -259,11 +424,18 @@ def upload_to_frigate(jobs: list[dict]) -> None:
                        if resp.status_code == 200:
                            uploaded += 1
                            person_uploaded += 1
+                            effective_count += 1
+                            min_quality_score_for_slot = None

-                            # Mark this asset as uploaded so it's skipped on future runs
                            asset_id = asset_map.get(fname)
                            if asset_id:
-                                mark_uploaded(asset_id, person_name=name, score=score_map.get(fname))
+                                mark_uploaded(
+                                    asset_id,
+                                    person_name=name,
+                                    score=score_map.get(fname),
+                                    crop_dims=dims_map.get(fname),
+                                )
+                                actually_uploaded.append((fname, asset_id))

                            break
                        else:
@@ -320,6 +492,16 @@ def upload_to_frigate(jobs: list[dict]) -> None:

                progress.advance(upload_task)

+            if min_quality_score_for_slot is not None:
+                logger.warning(
+                    f"{name}: freed replacement slot (floor {min_quality_score_for_slot:.3f})"
+                    " was not filled this run — will be available next run"
+                )
+
+            # Batch-map Frigate filenames to asset IDs now that all uploads are done.
+            if actually_uploaded:
+                _reconcile_frigate_mappings(name, known_frigate_files_at_start, actually_uploaded)
+
            # Per-person summary
            if person_failed == 0:
                progress.console.print(
@@ -8,26 +8,78 @@ import requests
 logger = logging.getLogger(__name__)


-def get_frigate_face_counts() -> dict[str, int] | None:
-    """Return {person_name: training_image_count} from Frigate's train directory.
-
-    Returns None if FRIGATE_URL is not set or the API is unreachable, so callers
-    can distinguish "API unavailable" from "person has 0 images."
-    """
+def _get_faces_data() -> dict | None:
+    """Fetch raw GET /api/faces response. Returns None if unavailable."""
    frigate_url = os.environ.get("FRIGATE_URL", "").rstrip("/")
    if not frigate_url:
        return None
    try:
        resp = requests.get(f"{frigate_url}/api/faces", timeout=10)
        resp.raise_for_status()
-        data = resp.json()
-        # Response: {person_name: [file, ...], "train": [...], ...}
-        # "train" is a flat pending list, not a person — skip it.
-        return {
-            name: len(files)
-            for name, files in data.items()
-            if name != "train" and isinstance(files, list)
-        }
+        return resp.json()
    except Exception as e:
-        logger.warning(f"Could not query Frigate face counts: {e}")
+        logger.warning(f"Could not query Frigate faces API: {e}")
        return None
+
+
+def get_frigate_face_counts() -> dict[str, int] | None:
+    """Return {person_name: training_image_count} from Frigate's train directory.
+
+    Returns None if FRIGATE_URL is not set or the API is unreachable, so callers
+    can distinguish "API unavailable" from "person has 0 images."
+    """
+    data = _get_faces_data()
+    if data is None:
+        return None
+    # Response: {person_name: [file, ...], "train": [...], ...}
+    # "train" is a flat pending list, not a person — skip it.
+    return {
+        name: len(files)
+        for name, files in data.items()
+        if name != "train" and isinstance(files, list)
+    }
+
+
+def get_frigate_person_files(person_name: str) -> list[str] | None:
+    """Return the list of training filenames for a person in Frigate.
+
+    Returns None if the API is unreachable. Returns an empty list if the
+    person exists but has no training images yet.
+    """
+    data = _get_faces_data()
+    if data is None:
+        return None
+    files = data.get(person_name)
+    return files if isinstance(files, list) else []
+
+
+def delete_frigate_person_files(person_name: str, filenames: list[str]) -> bool:
+    """Delete specific training files for a person from Frigate.
+
+    Uses POST /api/faces/{name}/delete with body {"ids": [filename, ...]}.
+    Returns True on success, False if unreachable or the request fails.
+    """
+    frigate_url = os.environ.get("FRIGATE_URL", "").rstrip("/")
+    if not frigate_url or not filenames:
+        return False
+    from urllib.parse import quote
+    encoded = quote(person_name, safe="")
+    try:
+        resp = requests.post(
+            f"{frigate_url}/api/faces/{encoded}/delete",
+            json={"ids": filenames},
+            timeout=10,
+        )
+        if resp.ok:
+            logger.debug(f"Deleted {len(filenames)} Frigate file(s) for {person_name}")
+            return True
+        if resp.status_code == 404:
+            # File already absent — stale tracker entry. Return True so the caller
+            # removes it from the tracker and frees the slot cleanly.
+            logger.warning(f"Frigate file(s) not found for {person_name} (stale tracker entry?): {filenames}")
+            return True
+        logger.warning(f"Frigate delete returned {resp.status_code} for {person_name}")
+        return False
+    except Exception as e:
+        logger.warning(f"Failed to delete Frigate files for {person_name}: {e}")
+        return False
@@ -69,9 +69,10 @@ def process_face_mode(
    output_dir: str,
    count: int,
    min_width: int | None = None,
-) -> bool:
+) -> tuple[int, int] | None:
    """Crop face based on Immich metadata and save to output directory.

+    Returns (width, height) of the saved crop, or None if no crop was saved.
    If face alignment is enabled and landmarks are available, produces
    an aligned 112x112 crop. Otherwise falls back to bounding box crop
    with configurable margin.
@@ -90,7 +91,7 @@ def process_face_mode(

    if not face_info:
        logger.debug(f"No face info for {person.get('name')} in asset {asset.get('id')}")
-        return False
+        return None

    img_w, img_h = img.size
    meta_w = face_info.get("imageWidth") or img_w
@@ -106,7 +107,7 @@ def process_face_mode(
    face_w, face_h = x2 - x1, y2 - y1
    if face_w < min_width or face_h < min_width:
        logger.debug(f"Face too small ({face_w:.1f}x{face_h:.1f})")
-        return False
+        return None

    # Try face alignment if enabled and landmarks available
    if Config.ENABLE_FACE_ALIGNMENT:
@@ -117,7 +118,7 @@ def process_face_mode(
            aligned = align_face(img, scaled_landmarks)
            if aligned is not None:
                _save_jpeg(aligned, os.path.join(output_dir, f"{count}.jpg"))
-                return True
+                return aligned.size

    # Fall back to bounding box crop with configurable margin
    margin = Config.FACE_MARGIN
@@ -131,7 +132,7 @@ def process_face_mode(

    face_crop = img.crop(crop_box)
    _save_jpeg(face_crop, os.path.join(output_dir, f"{count}.jpg"))
-    return True
+    return face_crop.size


 def process_object_mode(
@@ -144,7 +145,14 @@ def process_object_mode(
    try:
        model = get_yolo_model()
        target_class = config.get("object_class", "dog")
-        device = "cpu" if os.getenv("FORCE_CPU", "").lower() in ("true", "1", "yes") else None
+        import torch
+
+        if os.getenv("FORCE_CPU", "").lower() in ("true", "1", "yes"):
+            device = "cpu"
+        elif hasattr(torch, "xpu") and torch.xpu.is_available():
+            device = "xpu"
+        else:
+            device = None  # YOLO auto-selects (CUDA/ROCm/CPU)

        results = model(img, verbose=False, device=device)

@@ -58,8 +58,11 @@ def _get_strategy_choice(has_embedding: bool, entity_type: str) -> tuple[int | s
    rprint("  [bold]4.[/bold] Skip")

    choice = Prompt.ask("Choice", choices=["1", "2", "3", "4"], default="1")
-    limits = {"1": 30, "2": 100, "3": IntPrompt.ask("Enter number of images", default=30)}
-    return limits.get(choice, 0), "time" if choice != "4" else "skip"
+    if choice == "4":
+        return 0, "skip"
+    if choice == "3":
+        return IntPrompt.ask("Enter number of images", default=30), "time"
+    return {"1": 30, "2": 100}.get(choice, 30), "time"


 def _resolve_strategy(strategy: str, has_embedding: bool) -> tuple[int | str, str]:
@@ -136,7 +139,7 @@ def _configure_person(person: dict, people: list[dict]) -> dict | None:
    mode_choice = Prompt.ask("Choice", choices=["1", "2"], default="1")
    entity_type = "face" if mode_choice == "1" else "object"

-    config = {"name": name, "mode": entity_type}
+    config = {"name": name, "mode": entity_type, "quality_replacement": Config.QUALITY_REPLACEMENT}
    if entity_type == "object":
        config["object_class"] = Prompt.ask("Enter Object Class (e.g. dog, cat, car)", default="dog")

@@ -280,34 +283,41 @@ def auto_configure(people: list[dict]) -> list[dict]:
            rprint(f"  [dim]Skipping {name} (0 new images after dedup).[/dim]")
            continue

-        # Enforce MAX_AUTO_IMAGES as a lifetime cap per person.
-        # Priority: live Frigate count → last cached Frigate count → local uploaded count.
+        # Enforce MAX_AUTO_IMAGES against the tracked file count only.
+        # Manually-added Frigate files are invisible to this cap so users can
+        # curate their own files without shrinking winnow's managed quota.
        person_summary = upload_summary.get(name, {})
-        if frigate_counts is not None:
-            already_uploaded = frigate_counts.get(name, 0)
-        else:
-            fc = person_summary.get("frigate_count")
-            already_uploaded = fc if fc is not None else person_summary.get("uploaded", 0)
+        already_uploaded = len(person_summary.get("frigate_files", {}))
        capacity = Config.MAX_AUTO_IMAGES - already_uploaded
        if capacity <= 0:
+            if not Config.QUALITY_REPLACEMENT:
+                rprint(
+                    f"  [dim]Skipping {name} (at cap:"
+                    f" {already_uploaded}/{Config.MAX_AUTO_IMAGES}, quality replacement disabled).[/dim]"
+                )
+                continue
            rprint(
-                f"  [dim]Skipping {name} (at lifetime cap:"
-                f" {already_uploaded}/{Config.MAX_AUTO_IMAGES} trained).[/dim]"
+                f"  [cyan]{name}: at cap ({already_uploaded}/{Config.MAX_AUTO_IMAGES}),"
+                f" checking for quality improvements...[/cyan]"
            )
-            continue
+            quality_replacement_only = True
+        else:
+            quality_replacement_only = False
+
+        config["quality_replacement"] = quality_replacement_only or Config.QUALITY_REPLACEMENT

        has_embedding = is_embedding_available(entity_type)
        limit, selection_mode = _resolve_strategy(strategy, has_embedding)

-        # Cap selection to remaining capacity.
-        # For auto mode with partial training, keep "auto" so adaptive stopping
-        # still runs — just trim the result to the remaining capacity afterward.
+        # Cap selection to remaining capacity (no cap when replacement-only — executor
+        # decides per-image whether to swap; any candidate could be an improvement).
        auto_cap = None
-        if limit == "auto":
-            if already_uploaded > 0:
-                auto_cap = capacity
-        else:
-            limit = min(limit, capacity)
+        if not quality_replacement_only:
+            if limit == "auto":
+                if already_uploaded > 0:
+                    auto_cap = capacity
+            else:
+                limit = min(limit, capacity)

        if selection_mode == "skip":
            continue
@@ -20,6 +20,7 @@ class QualityResult:

    passed: bool
    reasons: list[str] = field(default_factory=list)
+    blur_score: float | None = None

    @property
    def reason(self) -> str:
@@ -113,9 +114,15 @@ def assess_quality(
    img_np = np.asarray(img)
    reasons = []

-    # Run all checks, collect failures
+    # Compute laplacian variance once (used by check_blur and stored as blur_score)
+    gray = cv2.cvtColor(img_np, cv2.COLOR_RGB2GRAY) if img_np.ndim == 3 else img_np
+    blur_score = float(cv2.Laplacian(gray, cv2.CV_64F).var())
+
    checks = [
-        check_blur(img_np, blur_threshold),
+        (
+            blur_score >= blur_threshold,
+            f"Blurry (laplacian={blur_score:.1f}, threshold={blur_threshold})" if blur_score < blur_threshold else "",
+        ),
        check_grayscale(img_np),
        check_exposure(img_np),
        check_confidence(confidence, min_confidence),
@@ -129,5 +136,5 @@ def assess_quality(
        if not passed:
            reasons.append(reason)

-    return QualityResult(passed=len(reasons) == 0, reasons=reasons)
+    return QualityResult(passed=len(reasons) == 0, reasons=reasons, blur_score=blur_score)

@@ -11,10 +11,15 @@ Both are excluded from future candidate pools. To reset:

 by_person schema (frigate_uploaded_ids.json):
  {
-    "asset_ids":    ["immich-id-1", ...],   # all assets we attempted to upload
-    "scores":       {"immich-id-1": 0.953}, # Immich face confidence at upload time
-    "frigate_count": 42                     # last known Frigate training image count
+    "asset_ids":     ["immich-id-1", ...],                    # all assets we attempted to upload
+    "scores":        {"immich-id-1": 450.3},                   # Laplacian blur variance at upload time
+    "frigate_files": {"PersonName-123.webp": "immich-id-1"},  # Frigate filename → asset ID
+    "crop_dims":     {"immich-id-1": [640, 480]},             # crop pixel dimensions at upload time
+    "frigate_count": 42                                       # last known Frigate training image count
  }
+
+frigate_files only contains files winnow uploaded — files added manually through
+Frigate's UI are never mapped here and are never touched by quality replacement.
 """

 import json
@@ -72,13 +77,21 @@ def _get_ids(entry: list | dict) -> list[str]:
 def _migrate_entry(entry: list | dict) -> dict:
    """Ensure by_person entry is in the current dict format."""
    if isinstance(entry, list):
-        return {"asset_ids": sorted(entry), "scores": {}}
+        return {"asset_ids": sorted(entry), "scores": {}, "frigate_files": {}, "crop_dims": {}}
    entry.setdefault("asset_ids", [])
    entry.setdefault("scores", {})
+    entry.setdefault("frigate_files", {})
+    entry.setdefault("crop_dims", {})
    return entry


-def _mark(filename: str, asset_id: str, person_name: str | None, score: float | None = None) -> None:
+def _mark(
+    filename: str,
+    asset_id: str,
+    person_name: str | None,
+    score: float | None = None,
+    crop_dims: tuple[int, int] | None = None,
+) -> None:
    data = _load(filename)
    flat_key = _flat_key(filename)
    flat = set(data.get(flat_key, []))
@@ -92,6 +105,8 @@ def _mark(filename: str, asset_id: str, person_name: str | None, score: float |
        entry["asset_ids"] = sorted(ids)
        if score is not None:
            entry["scores"][asset_id] = round(score, 4)
+        if crop_dims is not None:
+            entry["crop_dims"][asset_id] = [crop_dims[0], crop_dims[1]]
        by_person[person_name] = entry
    _save(filename, data)

@@ -106,8 +121,13 @@ def load_rejected_ids() -> set[str]:
    return _load_flat(REJECT_TRACKER_FILE)


-def mark_uploaded(asset_id: str, person_name: str | None = None, score: float | None = None) -> None:
-    _mark(UPLOAD_TRACKER_FILE, asset_id, person_name, score=score)
+def mark_uploaded(
+    asset_id: str,
+    person_name: str | None = None,
+    score: float | None = None,
+    crop_dims: tuple[int, int] | None = None,
+) -> None:
+    _mark(UPLOAD_TRACKER_FILE, asset_id, person_name, score=score, crop_dims=crop_dims)
    logger.debug(f"Marked {asset_id} as uploaded ({person_name})")


@@ -116,6 +136,104 @@ def mark_rejected(asset_id: str, person_name: str | None = None) -> None:
    logger.debug(f"Marked {asset_id} as rejected ({person_name})")


+def record_frigate_file(person_name: str, frigate_filename: str, asset_id: str) -> None:
+    """Record the mapping from a Frigate training filename to an Immich asset ID."""
+    data = _load(UPLOAD_TRACKER_FILE)
+    by_person = data.setdefault("by_person", {})
+    entry = _migrate_entry(by_person.get(person_name, {}))
+    entry["frigate_files"][frigate_filename] = asset_id
+    by_person[person_name] = entry
+    _save(UPLOAD_TRACKER_FILE, data)
+    logger.debug(f"Mapped Frigate file {frigate_filename} → {asset_id} ({person_name})")
+
+
+def remove_frigate_file(person_name: str, frigate_filename: str) -> None:
+    """Remove a Frigate filename from the mapping after it has been deleted.
+
+    Does NOT unmark the source asset_id — the deletion was deliberate and
+    we don't want to re-upload the inferior image on the next run.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    by_person = data.get("by_person", {})
+    entry = _migrate_entry(by_person.get(person_name, {}))
+    entry["frigate_files"].pop(frigate_filename, None)
+    by_person[person_name] = entry
+    _save(UPLOAD_TRACKER_FILE, data)
+    logger.debug(f"Removed Frigate file mapping {frigate_filename} ({person_name})")
+
+
+def get_tracked_frigate_file_count(person_name: str) -> int:
+    """Return the number of Frigate training files winnow has mapped for this person.
+
+    Used as the cap baseline so that manually-added Frigate files do not
+    consume slots from winnow's managed quota.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    return len(entry["frigate_files"])
+
+
+def get_tracked_frigate_filenames(person_name: str) -> set[str]:
+    """Return the set of Frigate filenames currently mapped in the tracker for a person.
+
+    Used as a pre-upload baseline when the Frigate GET API is unreachable at
+    upload start, so reconciliation can still identify newly uploaded files.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    return set(entry["frigate_files"].keys())
+
+
+def get_lowest_quality_mapped_file(
+    person_name: str, exclude: set[str] | None = None
+) -> tuple[str, str, float] | None:
+    """Return (frigate_filename, asset_id, score) for the mapped file with the lowest
+    quality score, or None if no mapped files with known scores exist.
+
+    Pass `exclude` to skip files that failed to delete this run without removing
+    them from the tracker — they remain candidates on the next run.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    entry = _migrate_entry(data.get("by_person", {}).get(person_name, {}))
+    frigate_files = entry.get("frigate_files", {})
+    scores = entry.get("scores", {})
+    candidates = [
+        (frigate_filename, asset_id, scores[asset_id])
+        for frigate_filename, asset_id in frigate_files.items()
+        if asset_id in scores and (exclude is None or frigate_filename not in exclude)
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda x: x[2])
+
+
+def find_by_crop_dimension(size: int) -> list[dict]:
+    """Return all tracked crops whose width or height matches `size` pixels.
+
+    Returns a list of dicts: {person, asset_id, width, height, blur_score, frigate_filename}.
+    frigate_filename is None when the Frigate mapping was lost to a reconciliation race.
+    """
+    data = _load(UPLOAD_TRACKER_FILE)
+    results = []
+    for person_name, raw_entry in data.get("by_person", {}).items():
+        entry = _migrate_entry(raw_entry)
+        scores = entry.get("scores", {})
+        frigate_files = entry.get("frigate_files", {})
+        asset_to_frigate = {v: k for k, v in frigate_files.items()}
+        for asset_id, dims in entry.get("crop_dims", {}).items():
+            w, h = dims[0], dims[1]
+            if w == size or h == size:
+                results.append({
+                    "person": person_name,
+                    "asset_id": asset_id,
+                    "width": w,
+                    "height": h,
+                    "blur_score": scores.get(asset_id),
+                    "frigate_filename": asset_to_frigate.get(asset_id),
+                })
+    return results
+
+
 def update_frigate_count(person_name: str, count: int) -> None:
    """Record Frigate's authoritative training image count for a person."""
    data = _load(UPLOAD_TRACKER_FILE)
@@ -143,7 +261,7 @@ def reset_person(person_name: str) -> None:


 def get_person_summary() -> dict[str, dict]:
-    """Return {person_name: {uploaded, rejected, frigate_count, scores}} for display/capacity."""
+    """Return {person_name: {uploaded, rejected, frigate_count, scores, frigate_files}} for display/capacity."""
    uploaded_data = _load(UPLOAD_TRACKER_FILE).get("by_person", {})
    rejected_data = _load(REJECT_TRACKER_FILE).get("by_person", {})
    names = set(uploaded_data) | set(rejected_data)
@@ -156,6 +274,7 @@ def get_person_summary() -> dict[str, dict]:
            "rejected": len(_get_ids(r_entry)),
            "frigate_count": u_entry.get("frigate_count") if isinstance(u_entry, dict) else None,
            "scores": u_entry.get("scores", {}) if isinstance(u_entry, dict) else {},
+            "frigate_files": u_entry.get("frigate_files", {}) if isinstance(u_entry, dict) else {},
        }
    return result