Removes the now saved profiling code

Phase 1 -- Eliminate JSON round-trip in document exporter

Replace json.loads(serializers.serialize("json", qs)) with
serializers.serialize("python", qs) to skip the intermediate
JSON string allocation and parse step. Use DjangoJSONEncoder
in check_and_write_json() to handle native Python types
(datetime, Decimal, UUID) the Python serializer returns.

Measured on 200 documents + 200 CustomFieldInstances:
  - Memory delta:  1,410 KiB → 527 KiB  (−63%)
  - Peak memory:   1,500 KiB → 530 KiB  (−65%)
  - Wall time:       0.54s  → 0.36s    (−34%)
  - JSON output: identical (byte-for-byte, 345 KB)

Phase 2 -- Batched QuerySet serialization in document exporter

Add serialize_queryset_batched() helper that uses QuerySet.iterator()
and itertools.islice to stream records in configurable chunks, bounding
peak memory during serialization to batch_size * avg_record_size rather
than loading the entire QuerySet at once.

Replace the single-call serializers.serialize("python", qs) in dump()
with list(chain.from_iterable(serialize_queryset_batched(qs, batch_size))).
Add --batch-size CLI argument (default 500).

Measured on 2,000 documents + 2,000 CustomFieldInstances:
  Phase 1 baseline (full queryset, no iterator):
    Peak: 9,293 KiB  |  Time: 4.33s

  Phase 2 batch=2000 (iterator, 1 batch):
    Peak: 7,716 KiB  |  Time: 4.20s  (−17% peak vs Phase 1)

  Phase 2 batch=500 (iterator, 4 batches -- default):
    Peak: 6,980 KiB  |  Time: 4.28s  (−25% peak vs Phase 1)

  Phase 2 batch=100 (iterator, 20 batches):
    Peak: 6,776 KiB  |  Time: 4.30s  (−27% peak vs Phase 1)

Peak memory falls as batch_size decreases. Wall time is within noise
(batching overhead negligible). Output is byte-for-byte identical across
all batch sizes and approaches.

The primary gain is that Django's queryset cache is bypassed (iterator()),
preventing the ORM from holding all model instances in memory after fetch.
Smaller batches reduce the per-batch model-instance peak further.

.github/workflows/ci-backend.yml

@@ -35,18 +35,18 @@ jobs:
       fail-fast: false
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Start containers
         run: |
           docker compose --file docker/compose/docker-compose.ci-test.yml pull --quiet
           docker compose --file docker/compose/docker-compose.ci-test.yml up --detach
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: "${{ matrix.python-version }}"
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true
@@ -83,13 +83,13 @@ jobs:
             pytest
       - name: Upload test results to Codecov
         if: always()
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v5.5.2
         with:
           flags: backend-python-${{ matrix.python-version }}
           files: junit.xml
           report_type: test_results
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v5.5.2
         with:
           flags: backend-python-${{ matrix.python-version }}
           files: coverage.xml
@@ -106,14 +106,14 @@ jobs:
       DEFAULT_PYTHON: "3.12"
     steps:
       - name: Checkout
-        uses: actions/checkout@v6.0.1
+        uses: actions/checkout@v6.0.2
       - name: Set up Python
         id: setup-python
         uses: actions/setup-python@v6.2.0
         with:
           python-version: "${{ env.DEFAULT_PYTHON }}"
       - name: Install uv
-        uses: astral-sh/setup-uv@v7.2.1
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true

.github/workflows/ci-docker.yml

@@ -41,7 +41,7 @@ jobs:
       ref-name: ${{ steps.ref.outputs.name }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v6.0.1
+        uses: actions/checkout@v6.0.2
       - name: Determine ref name
         id: ref
         run: |
@@ -130,7 +130,7 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@v6.18.0
+        uses: docker/build-push-action@v6.19.2
         with:
           context: .
           file: ./Dockerfile
@@ -152,7 +152,7 @@ jobs:
           touch "/tmp/digests/${digest#sha256:}"
       - name: Upload digest
         if: steps.check-push.outputs.should-push == 'true'
-        uses: actions/upload-artifact@v6.0.0
+        uses: actions/upload-artifact@v7.0.0
         with:
           name: digests-${{ matrix.arch }}
           path: /tmp/digests/*
@@ -168,7 +168,7 @@ jobs:
       packages: write
     steps:
       - name: Download digests
-        uses: actions/download-artifact@v7.0.0
+        uses: actions/download-artifact@v8.0.0
         with:
           path: /tmp/digests
           pattern: digests-*

.github/workflows/ci-docs.yml

@@ -33,16 +33,16 @@ jobs:
     name: Build Documentation
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/configure-pages@v5
+      - uses: actions/configure-pages@v5.0.0
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true
@@ -58,7 +58,7 @@ jobs:
             --frozen \
             zensical build --clean
       - name: Upload GitHub Pages artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v4.0.0
         with:
           path: site
           name: github-pages-${{ github.run_id }}-${{ github.run_attempt }}
@@ -72,7 +72,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy GitHub Pages
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4.0.5
         id: deployment
         with:
           artifact_name: github-pages-${{ github.run_id }}-${{ github.run_attempt }}

.github/workflows/ci-frontend.yml

@@ -22,20 +22,20 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
         id: cache-frontend-deps
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store
@@ -49,19 +49,19 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store
@@ -83,19 +83,19 @@ jobs:
         shard-count: [4]
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store
@@ -107,13 +107,13 @@ jobs:
         run: cd src-ui && pnpm run test --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
       - name: Upload test results to Codecov
         if: always()
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v5.5.2
         with:
           flags: frontend-node-${{ matrix.node-version }}
           directory: src-ui/
           report_type: test_results
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v5.5.2
         with:
           flags: frontend-node-${{ matrix.node-version }}
           directory: src-ui/coverage/
@@ -133,19 +133,19 @@ jobs:
         shard-count: [2]
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store
@@ -163,19 +163,19 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store

.github/workflows/ci-release.yml

@@ -28,14 +28,14 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       # ---- Frontend Build ----
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
@@ -47,11 +47,11 @@ jobs:
       # ---- Backend Setup ----
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true
@@ -118,7 +118,7 @@ jobs:
           sudo chown -R 1000:1000 paperless-ngx/
           tar -cJf paperless-ngx.tar.xz paperless-ngx/
       - name: Upload release artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7.0.0
         with:
           name: release
           path: dist/paperless-ngx.tar.xz
@@ -133,7 +133,7 @@ jobs:
       version: ${{ steps.get-version.outputs.version }}
     steps:
       - name: Download release artifact
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8.0.0
         with:
           name: release
           path: ./
@@ -148,7 +148,7 @@ jobs:
           fi
       - name: Create release and changelog
         id: create-release
-        uses: release-drafter/release-drafter@v6
+        uses: release-drafter/release-drafter@v6.2.0
         with:
           name: Paperless-ngx ${{ steps.get-version.outputs.version }}
           tag: ${{ steps.get-version.outputs.version }}
@@ -159,7 +159,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Upload release archive
-        uses: shogo82148/actions-upload-release-asset@v1
+        uses: shogo82148/actions-upload-release-asset@v1.9.2
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           upload_url: ${{ steps.create-release.outputs.upload_url }}
@@ -176,16 +176,16 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
         with:
           ref: main
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v6.2.0
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true
@@ -218,7 +218,7 @@ jobs:
           git commit -am "Changelog ${{ needs.publish-release.outputs.version }} - GHA"
           git push origin ${{ needs.publish-release.outputs.version }}-changelog
       - name: Create pull request
-        uses: actions/github-script@v8
+        uses: actions/github-script@v8.0.0
         with:
           script: |
             const { repo, owner } = context.repo;

.github/workflows/codeql-analysis.yml

@@ -34,10 +34,10 @@ jobs:
         # Learn more about CodeQL language support at https://git.io/codeql-language-support
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@v4.32.5
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -45,4 +45,4 @@ jobs:
           # Prefix the list here with "+" to use these queries and those in the config file.
           # queries: ./path/to/local/query, your-org/your-repo/queries@main
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@v4.32.5

.github/workflows/crowdin.yml

@@ -13,11 +13,11 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
         with:
           token: ${{ secrets.PNGX_BOT_PAT }}
       - name: crowdin action
-        uses: crowdin/github-action@v2
+        uses: crowdin/github-action@v2.15.0
         with:
           upload_translations: false
           download_translations: true

.github/workflows/pr-bot.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
       - name: Label PR by file path or branch name
         # see .github/labeler.yml for the labeler config
-        uses: actions/labeler@v6
+        uses: actions/labeler@v6.0.1
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Label by size
@@ -26,7 +26,7 @@ jobs:
           fail_if_xl: 'false'
           excluded_files: /\.lock$/ /\.txt$/ ^src-ui/pnpm-lock\.yaml$ ^src-ui/messages\.xlf$ ^src/locale/en_US/LC_MESSAGES/django\.po$
       - name: Label by PR title
-        uses: actions/github-script@v8
+        uses: actions/github-script@v8.0.0
         with:
           script: |
             const pr = context.payload.pull_request;
@@ -52,7 +52,7 @@ jobs:
             }
       - name: Label bot-generated PRs
         if: ${{ contains(github.actor, 'dependabot') || contains(github.actor, 'crowdin-bot') }}
-        uses: actions/github-script@v8
+        uses: actions/github-script@v8.0.0
         with:
           script: |
             const pr = context.payload.pull_request;
@@ -77,7 +77,7 @@ jobs:
             }
       - name: Welcome comment
         if: ${{ !contains(github.actor, 'bot') }}
-        uses: actions/github-script@v8
+        uses: actions/github-script@v8.0.0
         with:
           script: |
             const pr = context.payload.pull_request;

.github/workflows/project-actions.yml

@@ -19,6 +19,6 @@ jobs:
     if: github.event_name == 'pull_request_target' && (github.event.action == 'opened' || github.event.action == 'reopened') && github.event.pull_request.user.login != 'dependabot'
     steps:
       - name: Label PR with release-drafter
-        uses: release-drafter/release-drafter@v6
+        uses: release-drafter/release-drafter@v6.2.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/repo-maintenance.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.repository_owner == 'paperless-ngx'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/stale@v10
+      - uses: actions/stale@v10.2.0
         with:
           days-before-stale: 7
           days-before-close: 14
@@ -37,7 +37,7 @@ jobs:
     if: github.repository_owner == 'paperless-ngx'
     runs-on: ubuntu-24.04
     steps:
-      - uses: dessant/lock-threads@v6
+      - uses: dessant/lock-threads@v6.0.0
         with:
           issue-inactive-days: '30'
           pr-inactive-days: '30'
@@ -57,7 +57,7 @@ jobs:
     if: github.repository_owner == 'paperless-ngx'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@v8.0.0
         with:
           script: |
             function sleep(ms) {
@@ -114,7 +114,7 @@ jobs:
     if: github.repository_owner == 'paperless-ngx'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@v8.0.0
         with:
           script: |
             function sleep(ms) {
@@ -206,7 +206,7 @@ jobs:
     if: github.repository_owner == 'paperless-ngx'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/github-script@v8
+      - uses: actions/github-script@v8.0.0
         with:
           script: |
             function sleep(ms) {

.github/workflows/translate-strings.yml

@@ -11,7 +11,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
         env:
           GH_REF: ${{ github.ref }} # sonar rule:githubactions:S7630 - avoid injection
         with:
@@ -19,13 +19,13 @@ jobs:
           ref: ${{ env.GH_REF }}
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v6.2.0
       - name: Install system dependencies
         run: |
           sudo apt-get update -qq
           sudo apt-get install -qq --no-install-recommends gettext
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v7.3.1
         with:
           enable-cache: true
       - name: Install backend python dependencies
@@ -36,18 +36,18 @@ jobs:
       - name: Generate backend translation strings
         run: cd src/ && uv run manage.py makemessages -l en_US -i "samples*"
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v4.2.0
         with:
           version: 10
       - name: Use Node.js 24
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.2.0
         with:
           node-version: 24.x
           cache: 'pnpm'
           cache-dependency-path: 'src-ui/pnpm-lock.yaml'
       - name: Cache frontend dependencies
         id: cache-frontend-deps
-        uses: actions/cache@v5
+        uses: actions/cache@v5.0.3
         with:
           path: |
             ~/.pnpm-store
@@ -63,7 +63,7 @@ jobs:
           cd src-ui
           pnpm run ng extract-i18n
       - name: Commit changes
-        uses: stefanzweifel/git-auto-commit-action@v7
+        uses: stefanzweifel/git-auto-commit-action@v7.1.0
         with:
           file_pattern: 'src-ui/messages.xlf src/locale/en_US/LC_MESSAGES/django.po'
           commit_message: "Auto translate strings"

Dockerfile

@@ -30,7 +30,7 @@ RUN set -eux \
 # Purpose: Installs s6-overlay and rootfs
 # Comments:
 #  - Don't leave anything extra in here either
-FROM ghcr.io/astral-sh/uv:0.10.5-python3.12-trixie-slim AS s6-overlay-base
+FROM ghcr.io/astral-sh/uv:0.10.7-python3.12-trixie-slim AS s6-overlay-base
 
 WORKDIR /usr/src/s6
 
@@ -45,7 +45,7 @@ ENV \
 ARG TARGETARCH
 ARG TARGETVARIANT
 # Lock this version
-ARG S6_OVERLAY_VERSION=3.2.1.0
+ARG S6_OVERLAY_VERSION=3.2.2.0
 
 ARG S6_BUILD_TIME_PKGS="curl \
                         xz-utils"

docker/compose/docker-compose.ci-test.yml

@@ -4,7 +4,7 @@
 # correct networking for the tests
 services:
   gotenberg:
-    image: docker.io/gotenberg/gotenberg:8.26
+    image: docker.io/gotenberg/gotenberg:8.27
     hostname: gotenberg
     container_name: gotenberg
     network_mode: host

docker/compose/docker-compose.mariadb-tika.yml

@@ -72,7 +72,7 @@ services:
       PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
       PAPERLESS_TIKA_ENDPOINT: http://tika:9998
   gotenberg:
-    image: docker.io/gotenberg/gotenberg:8.26
+    image: docker.io/gotenberg/gotenberg:8.27
     restart: unless-stopped
     # The gotenberg chromium route is used to convert .eml files. We do not
     # want to allow external content like tracking pixels or even javascript.

docker/compose/docker-compose.postgres-tika.yml

@@ -66,7 +66,7 @@ services:
       PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
       PAPERLESS_TIKA_ENDPOINT: http://tika:9998
   gotenberg:
-    image: docker.io/gotenberg/gotenberg:8.26
+    image: docker.io/gotenberg/gotenberg:8.27
     restart: unless-stopped
     # The gotenberg chromium route is used to convert .eml files. We do not
     # want to allow external content like tracking pixels or even javascript.

docker/compose/docker-compose.sqlite-tika.yml

@@ -55,7 +55,7 @@ services:
       PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
       PAPERLESS_TIKA_ENDPOINT: http://tika:9998
   gotenberg:
-    image: docker.io/gotenberg/gotenberg:8.26
+    image: docker.io/gotenberg/gotenberg:8.27
     restart: unless-stopped
     # The gotenberg chromium route is used to convert .eml files. We do not
     # want to allow external content like tracking pixels or even javascript.

docs/advanced_usage.md

@@ -332,7 +332,6 @@ Paperless provides the following variables for use within filenames:
 -   `{{ owner_username }}`: Username of document owner, if any, or "none"
 -   `{{ original_name }}`: Document original filename, minus the extension, if any, or "none"
 -   `{{ doc_pk }}`: The paperless identifier (primary key) for the document.
--   `{{ version_label }}`: The document version label or "none" if not explicitly set.
 
 !!! warning
 

docs/usage.md

@@ -616,9 +616,8 @@ applied. You can use the following placeholders in the template with any trigger
 -   `{{added_day}}`: added day
 -   `{{added_time}}`: added time in HH:MM format
 -   `{{original_filename}}`: original file name without extension
--   `{{filename}}`: current file name without extension
+-   `{{filename}}`: current file name without extension (for "added" workflows this may not be final yet, you can use `{{original_filename}}`)
 -   `{{doc_title}}`: current document title (cannot be used in title assignment)
--   `{{version_label}}`: the document version label (empty if not explicitly set)
 
 The following placeholders are only available for "added" or "updated" triggers
 

pyproject.toml

@@ -111,6 +111,7 @@ docs = [
 testing = [
   "daphne",
   "factory-boy~=3.3.1",
+  "faker~=40.5.1",
   "imagehash",
   "pytest~=9.0.0",
   "pytest-cov~=7.0.0",
@@ -304,6 +305,7 @@ markers = [
   "greenmail: Tests requiring Greenmail service",
   "date_parsing: Tests which cover date parsing from content or filename",
   "management: Tests which cover management commands/functionality",
+  "profiling: Benchmarks that profile and compare implementation performance",
 ]
 
 [tool.pytest_env]

src-ui/messages.xlf

@@ -5,14 +5,14 @@
       <trans-unit id="ngb.alert.close" datatype="html">
         <source>Close</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/alert/alert.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/alert/alert.ts</context>
           <context context-type="linenumber">50</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.carousel.slide-number" datatype="html">
         <source> Slide <x id="INTERPOLATION" equiv-text="ueryList&lt;NgbSli"/> of <x id="INTERPOLATION_1" equiv-text="EventSource = N"/> </source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/carousel/carousel.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/carousel/carousel.ts</context>
           <context context-type="linenumber">131,135</context>
         </context-group>
         <note priority="1" from="description">Currently selected slide number read by screen reader</note>
@@ -20,114 +20,114 @@
       <trans-unit id="ngb.carousel.previous" datatype="html">
         <source>Previous</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/carousel/carousel.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/carousel/carousel.ts</context>
           <context context-type="linenumber">159,162</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.carousel.next" datatype="html">
         <source>Next</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/carousel/carousel.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/carousel/carousel.ts</context>
           <context context-type="linenumber">202,203</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.datepicker.select-month" datatype="html">
         <source>Select month</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
           <context context-type="linenumber">91</context>
         </context-group>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
           <context context-type="linenumber">91</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.datepicker.select-year" datatype="html">
         <source>Select year</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
           <context context-type="linenumber">91</context>
         </context-group>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation-select.ts</context>
           <context context-type="linenumber">91</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.datepicker.previous-month" datatype="html">
         <source>Previous month</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation.ts</context>
           <context context-type="linenumber">83,85</context>
         </context-group>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation.ts</context>
           <context context-type="linenumber">112</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.datepicker.next-month" datatype="html">
         <source>Next month</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation.ts</context>
           <context context-type="linenumber">112</context>
         </context-group>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/datepicker/datepicker-navigation.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/datepicker/datepicker-navigation.ts</context>
           <context context-type="linenumber">112</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.first" datatype="html">
         <source>««</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.previous" datatype="html">
         <source>«</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.next" datatype="html">
         <source>»</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.last" datatype="html">
         <source>»»</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.first-aria" datatype="html">
         <source>First</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.previous-aria" datatype="html">
         <source>Previous</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.next-aria" datatype="html">
         <source>Next</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.pagination.last-aria" datatype="html">
         <source>Last</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/pagination/pagination-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/pagination/pagination-config.ts</context>
           <context context-type="linenumber">20</context>
         </context-group>
       </trans-unit>
@@ -135,105 +135,105 @@
         <source><x id="INTERPOLATION" equiv-text="barConfig);
 	pu"/></source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/progressbar/progressbar.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/progressbar/progressbar.ts</context>
           <context context-type="linenumber">41,42</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.HH" datatype="html">
         <source>HH</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.hours" datatype="html">
         <source>Hours</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.MM" datatype="html">
         <source>MM</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.minutes" datatype="html">
         <source>Minutes</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.increment-hours" datatype="html">
         <source>Increment hours</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.decrement-hours" datatype="html">
         <source>Decrement hours</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.increment-minutes" datatype="html">
         <source>Increment minutes</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.decrement-minutes" datatype="html">
         <source>Decrement minutes</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.SS" datatype="html">
         <source>SS</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.seconds" datatype="html">
         <source>Seconds</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.increment-seconds" datatype="html">
         <source>Increment seconds</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.decrement-seconds" datatype="html">
         <source>Decrement seconds</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.timepicker.PM" datatype="html">
         <source><x id="INTERPOLATION"/></source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/timepicker/timepicker-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/timepicker/timepicker-config.ts</context>
           <context context-type="linenumber">21</context>
         </context-group>
       </trans-unit>
       <trans-unit id="ngb.toast.close-aria" datatype="html">
         <source>Close</source>
         <context-group purpose="location">
-          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.1.3_@angular+core@21.1.3_@angular+_1ede04b1f6b65fa8e34a28e44afe1de9/node_modules/src/toast/toast-config.ts</context>
+          <context context-type="sourcefile">node_modules/.pnpm/@ng-bootstrap+ng-bootstrap@20.0.0_@angular+common@21.2.0_@angular+core@21.2.0_@angular+_fdecb2f5429dfeda6301fd300107de5b/node_modules/src/toast/toast-config.ts</context>
           <context context-type="linenumber">54</context>
         </context-group>
       </trans-unit>
@@ -1238,8 +1238,8 @@
           <context context-type="linenumber">82</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="8035757452478567832" datatype="html">
-        <source>Update existing document</source>
+      <trans-unit id="7860582931776068318" datatype="html">
+        <source>Add document version</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/admin/settings/settings.component.html</context>
           <context context-type="linenumber">280</context>
@@ -8411,8 +8411,8 @@
           <context context-type="linenumber">832</context>
         </context-group>
       </trans-unit>
-      <trans-unit id="6390006284731990222" datatype="html">
-        <source>This operation will permanently rotate the original version of <x id="PH" equiv-text="this.list.selected.size"/> document(s).</source>
+      <trans-unit id="5203024009814367559" datatype="html">
+        <source>This operation will add rotated versions of the <x id="PH" equiv-text="this.list.selected.size"/> document(s).</source>
         <context-group purpose="location">
           <context context-type="sourcefile">src/app/components/document-list/bulk-editor/bulk-editor.component.ts</context>
           <context context-type="linenumber">833</context>

src-ui/package.json

@@ -11,17 +11,17 @@
   },
   "private": true,
   "dependencies": {
-    "@angular/cdk": "^21.1.3",
-    "@angular/common": "~21.1.3",
-    "@angular/compiler": "~21.1.3",
-    "@angular/core": "~21.1.3",
-    "@angular/forms": "~21.1.3",
-    "@angular/localize": "~21.1.3",
-    "@angular/platform-browser": "~21.1.3",
-    "@angular/platform-browser-dynamic": "~21.1.3",
-    "@angular/router": "~21.1.3",
+    "@angular/cdk": "^21.2.0",
+    "@angular/common": "~21.2.0",
+    "@angular/compiler": "~21.2.0",
+    "@angular/core": "~21.2.0",
+    "@angular/forms": "~21.2.0",
+    "@angular/localize": "~21.2.0",
+    "@angular/platform-browser": "~21.2.0",
+    "@angular/platform-browser-dynamic": "~21.2.0",
+    "@angular/router": "~21.2.0",
     "@ng-bootstrap/ng-bootstrap": "^20.0.0",
-    "@ng-select/ng-select": "^21.2.0",
+    "@ng-select/ng-select": "^21.4.1",
     "@ngneat/dirty-check-forms": "^3.0.3",
     "@popperjs/core": "^2.11.8",
     "bootstrap": "^5.3.8",
@@ -37,25 +37,25 @@
     "tslib": "^2.8.1",
     "utif": "^3.1.0",
     "uuid": "^13.0.0",
-    "zone.js": "^0.16.0"
+    "zone.js": "^0.16.1"
   },
   "devDependencies": {
     "@angular-builders/custom-webpack": "^21.0.3",
     "@angular-builders/jest": "^21.0.3",
-    "@angular-devkit/core": "^21.1.3",
-    "@angular-devkit/schematics": "^21.1.3",
+    "@angular-devkit/core": "^21.2.0",
+    "@angular-devkit/schematics": "^21.2.0",
     "@angular-eslint/builder": "21.2.0",
     "@angular-eslint/eslint-plugin": "21.2.0",
     "@angular-eslint/eslint-plugin-template": "21.2.0",
     "@angular-eslint/schematics": "21.2.0",
     "@angular-eslint/template-parser": "21.2.0",
-    "@angular/build": "^21.1.3",
-    "@angular/cli": "~21.1.3",
-    "@angular/compiler-cli": "~21.1.3",
+    "@angular/build": "^21.2.0",
+    "@angular/cli": "~21.2.0",
+    "@angular/compiler-cli": "~21.2.0",
     "@codecov/webpack-plugin": "^1.9.1",
     "@playwright/test": "^1.58.2",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.2.1",
+    "@types/node": "^25.3.3",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "@typescript-eslint/utils": "^8.54.0",
@@ -63,12 +63,12 @@
     "jest": "30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-junit": "^16.0.0",
-    "jest-preset-angular": "^16.0.0",
+    "jest-preset-angular": "^16.1.1",
     "jest-websocket-mock": "^2.5.0",
     "prettier-plugin-organize-imports": "^4.3.0",
     "ts-node": "~10.9.1",
     "typescript": "^5.9.3",
-    "webpack": "^5.105.0"
+    "webpack": "^5.105.3"
   },
   "packageManager": "pnpm@10.17.1",
   "pnpm": {

src-ui/src/app/components/admin/settings/settings.component.html

@@ -277,7 +277,7 @@
               <div class="col">
                 <select class="form-select" formControlName="pdfEditorDefaultEditMode">
                   <option [ngValue]="PdfEditorEditMode.Create" i18n>Create new document(s)</option>
-                  <option [ngValue]="PdfEditorEditMode.Update" i18n>Update existing document</option>
+                  <option [ngValue]="PdfEditorEditMode.Update" i18n>Add document version</option>
                 </select>
               </div>
             </div>

src-ui/src/app/components/common/pdf-editor/pdf-editor.component.html

@@ -84,7 +84,7 @@
       <input type="radio" class="btn-check" [(ngModel)]="editMode" [value]="PdfEditorEditMode.Update" id="editModeUpdate" name="editmode" [disabled]="hasSplit()">
       <label for="editModeUpdate" class="btn btn-outline-primary btn-sm">
         <i-bs name="pencil"></i-bs>
-        <span class="form-check-label ms-2" i18n>Update existing document</span>
+        <span class="form-check-label ms-2" i18n>Add document version</span>
       </label>
     </div>
     @if (editMode === PdfEditorEditMode.Create) {

src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts

@@ -830,7 +830,7 @@ export class BulkEditorComponent
     })
     const rotateDialog = modal.componentInstance as RotateConfirmDialogComponent
     rotateDialog.title = $localize`Rotate confirm`
-    rotateDialog.messageBold = $localize`This operation will permanently rotate the original version of ${this.list.selected.size} document(s).`
+    rotateDialog.messageBold = $localize`This operation will add rotated versions of the ${this.list.selected.size} document(s).`
     rotateDialog.btnClass = 'btn-danger'
     rotateDialog.btnCaption = $localize`Proceed`
     rotateDialog.documentID = Array.from(this.list.selected)[0]

src/documents/consumer.py

@@ -43,6 +43,7 @@ from documents.plugins.helpers import ProgressManager
 from documents.plugins.helpers import ProgressStatusOptions
 from documents.signals import document_consumption_finished
 from documents.signals import document_consumption_started
+from documents.signals import document_updated
 from documents.signals.handlers import run_workflows
 from documents.templating.workflows import parse_w_workflow_placeholders
 from documents.utils import copy_basic_file_stats
@@ -646,6 +647,12 @@ class ConsumerPlugin(
                 # This triggers things like file renaming
                 document.save()
 
+                if document.root_document_id:
+                    document_updated.send(
+                        sender=self.__class__,
+                        document=document.root_document,
+                    )
+
                 # Delete the file only if it was successfully consumed
                 self.log.debug(f"Deleting original file {self.input_doc.original_file}")
                 self.input_doc.original_file.unlink()
@@ -715,17 +722,6 @@ class ConsumerPlugin(
             else None
         )
 
-        version_index = (
-            0
-            if self.input_doc.root_document_id is None
-            else (
-                Document.objects.filter(
-                    root_document_id=self.input_doc.root_document_id,
-                ).count()
-                + 1
-            )
-        )
-
         return parse_w_workflow_placeholders(
             title,
             correspondent_name,
@@ -734,8 +730,6 @@ class ConsumerPlugin(
             local_added,
             self.filename,
             self.filename,
-            version_label=self.metadata.version_label,
-            version_index=version_index,
         )
 
     def _store(

src/documents/management/commands/base.py

@@ -6,11 +6,14 @@ Provides automatic progress bar and multiprocessing support with minimal boilerp
 
 from __future__ import annotations
 
+import logging
 import os
+from collections.abc import Callable
 from collections.abc import Iterable
 from collections.abc import Sized
 from concurrent.futures import ProcessPoolExecutor
 from concurrent.futures import as_completed
+from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 from typing import Any
@@ -22,7 +25,11 @@ from django import db
 from django.core.management import CommandError
 from django.db.models import QuerySet
 from django_rich.management import RichCommand
+from rich import box
 from rich.console import Console
+from rich.console import Group
+from rich.console import RenderableType
+from rich.live import Live
 from rich.progress import BarColumn
 from rich.progress import MofNCompleteColumn
 from rich.progress import Progress
@@ -30,11 +37,11 @@ from rich.progress import SpinnerColumn
 from rich.progress import TextColumn
 from rich.progress import TimeElapsedColumn
 from rich.progress import TimeRemainingColumn
+from rich.table import Table
+from rich.text import Text
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
     from collections.abc import Generator
-    from collections.abc import Iterable
     from collections.abc import Sequence
 
     from django.core.management import CommandParser
@@ -43,6 +50,78 @@ T = TypeVar("T")
 R = TypeVar("R")
 
 
+@dataclass(slots=True, frozen=True)
+class _BufferedRecord:
+    level: int
+    name: str
+    message: str
+
+
+class BufferingLogHandler(logging.Handler):
+    """Captures log records during a command run for deferred rendering.
+
+    Attach to a logger before a long operation and call ``render()``
+    afterwards to emit the buffered records via Rich, optionally filtered
+    by minimum level.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._records: list[_BufferedRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self._records.append(
+            _BufferedRecord(
+                level=record.levelno,
+                name=record.name,
+                message=self.format(record),
+            ),
+        )
+
+    def render(
+        self,
+        console: Console,
+        *,
+        min_level: int = logging.DEBUG,
+        title: str = "Log Output",
+    ) -> None:
+        records = [r for r in self._records if r.level >= min_level]
+        if not records:
+            return
+
+        table = Table(
+            title=title,
+            show_header=True,
+            header_style="bold",
+            show_lines=False,
+            box=box.SIMPLE,
+        )
+        table.add_column("Level", style="bold", width=8)
+        table.add_column("Logger", style="dim")
+        table.add_column("Message", no_wrap=False)
+
+        _level_styles: dict[int, str] = {
+            logging.DEBUG: "dim",
+            logging.INFO: "cyan",
+            logging.WARNING: "yellow",
+            logging.ERROR: "red",
+            logging.CRITICAL: "bold red",
+        }
+
+        for record in records:
+            style = _level_styles.get(record.level, "")
+            table.add_row(
+                Text(logging.getLevelName(record.level), style=style),
+                record.name,
+                record.message,
+            )
+
+        console.print(table)
+
+    def clear(self) -> None:
+        self._records.clear()
+
+
 @dataclass(frozen=True, slots=True)
 class ProcessResult(Generic[T, R]):
     """
@@ -91,6 +170,23 @@ class PaperlessCommand(RichCommand):
                 for result in self.process_parallel(process_doc, ids):
                     if result.error:
                         self.console.print(f"[red]Failed: {result.error}[/red]")
+
+        class Command(PaperlessCommand):
+            help = "Import documents with live stats"
+
+            def handle(self, *args, **options):
+                stats = ImportStats()
+
+                def render_stats() -> Table:
+                    ...  # build Rich Table from stats
+
+                for item in self.track_with_stats(
+                    items,
+                    description="Importing...",
+                    stats_renderer=render_stats,
+                ):
+                    result = import_item(item)
+                    stats.imported += 1
     """
 
     supports_progress_bar: ClassVar[bool] = True
@@ -128,13 +224,11 @@ class PaperlessCommand(RichCommand):
         This is called by Django's command infrastructure after argument parsing
         but before handle(). We use it to set instance attributes from options.
         """
-        # Set progress bar state
         if self.supports_progress_bar:
             self.no_progress_bar = options.get("no_progress_bar", False)
         else:
             self.no_progress_bar = True
 
-        # Set multiprocessing state
         if self.supports_multiprocessing:
             self.process_count = options.get("processes", 1)
             if self.process_count < 1:
@@ -144,9 +238,69 @@ class PaperlessCommand(RichCommand):
 
         return super().execute(*args, **options)
 
+    @contextmanager
+    def buffered_logging(
+        self,
+        *logger_names: str,
+        level: int = logging.DEBUG,
+    ) -> Generator[BufferingLogHandler, None, None]:
+        """Context manager that captures log output from named loggers.
+
+        Installs a ``BufferingLogHandler`` on each named logger for the
+        duration of the block, suppressing propagation to avoid interleaving
+        with the Rich live display. The handler is removed on exit regardless
+        of whether an exception occurred.
+
+        Usage::
+
+            with self.buffered_logging("paperless", "documents") as log_buf:
+                # ... run progress loop ...
+            if options["verbose"]:
+                log_buf.render(self.console)
+        """
+        handler = BufferingLogHandler()
+        handler.setFormatter(logging.Formatter("%(message)s"))
+
+        loggers: list[logging.Logger] = []
+        original_propagate: dict[str, bool] = {}
+
+        for name in logger_names:
+            log = logging.getLogger(name)
+            log.addHandler(handler)
+            original_propagate[name] = log.propagate
+            log.propagate = False
+            loggers.append(log)
+
+        try:
+            yield handler
+        finally:
+            for log in loggers:
+                log.removeHandler(handler)
+                log.propagate = original_propagate[log.name]
+
+    @staticmethod
+    def _progress_columns() -> tuple[Any, ...]:
+        """
+        Return the standard set of progress bar columns.
+
+        Extracted so both _create_progress (standalone) and track_with_stats
+        (inside Live) use identical column configuration without duplication.
+        """
+        return (
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            TimeRemainingColumn(),
+        )
+
     def _create_progress(self, description: str) -> Progress:
         """
-        Create a configured Progress instance.
+        Create a standalone Progress instance with its own stderr Console.
+
+        Use this for track(). For track_with_stats(), Progress is created
+        directly inside a Live context instead.
 
         Progress output is directed to stderr to match the convention that
         progress bars are transient UI feedback, not command output. This
@@ -161,12 +315,7 @@ class PaperlessCommand(RichCommand):
             A Progress instance configured with appropriate columns.
         """
         return Progress(
-            SpinnerColumn(),
-            TextColumn("[progress.description]{task.description}"),
-            BarColumn(),
-            MofNCompleteColumn(),
-            TimeElapsedColumn(),
-            TimeRemainingColumn(),
+            *self._progress_columns(),
             console=Console(stderr=True),
             transient=False,
         )
@@ -222,7 +371,6 @@ class PaperlessCommand(RichCommand):
             yield from iterable
             return
 
-        # Attempt to determine total if not provided
         if total is None:
             total = self._get_iterable_length(iterable)
 
@@ -232,6 +380,87 @@ class PaperlessCommand(RichCommand):
                 yield item
                 progress.advance(task_id)
 
+    def track_with_stats(
+        self,
+        iterable: Iterable[T],
+        *,
+        description: str = "Processing...",
+        stats_renderer: Callable[[], RenderableType],
+        total: int | None = None,
+    ) -> Generator[T, None, None]:
+        """
+        Iterate over items with a progress bar and a live-updating stats display.
+
+        The progress bar and stats renderable are combined in a single Live
+        context, so the stats panel re-renders in place below the progress bar
+        after each item is processed.
+
+        Respects --no-progress-bar flag. When disabled, yields items without
+        any display (stats are still updated by the caller's loop body, so
+        they will be accurate for any post-loop summary the caller prints).
+
+        Args:
+            iterable: The items to iterate over.
+            description: Text to display alongside the progress bar.
+            stats_renderer: Zero-argument callable that returns a Rich
+                renderable. Called after each item to refresh the display.
+                The caller typically closes over a mutable dataclass and
+                rebuilds a Table from it on each call.
+            total: Total number of items. If None, attempts to determine
+                automatically via .count() (for querysets) or len().
+
+        Yields:
+            Items from the iterable.
+
+        Example:
+            @dataclass
+            class Stats:
+                processed: int = 0
+                failed: int = 0
+
+            stats = Stats()
+
+            def render_stats() -> Table:
+                table = Table(box=None)
+                table.add_column("Processed")
+                table.add_column("Failed")
+                table.add_row(str(stats.processed), str(stats.failed))
+                return table
+
+            for item in self.track_with_stats(
+                items,
+                description="Importing...",
+                stats_renderer=render_stats,
+            ):
+                try:
+                    import_item(item)
+                    stats.processed += 1
+                except Exception:
+                    stats.failed += 1
+        """
+        if self.no_progress_bar:
+            yield from iterable
+            return
+
+        if total is None:
+            total = self._get_iterable_length(iterable)
+
+        stderr_console = Console(stderr=True)
+
+        # Progress is created without its own console so Live controls rendering.
+        progress = Progress(*self._progress_columns())
+        task_id = progress.add_task(description, total=total)
+
+        with Live(
+            Group(progress, stats_renderer()),
+            console=stderr_console,
+            refresh_per_second=4,
+        ) as live:
+            for item in iterable:
+                yield item
+                progress.advance(task_id)
+                live.update(Group(progress, stats_renderer()))
+
     def process_parallel(
         self,
         fn: Callable[[T], R],
@@ -269,7 +498,7 @@ class PaperlessCommand(RichCommand):
         total = len(items)
 
         if self.process_count == 1:
-            # Sequential execution in main process - critical for testing
+            # Sequential execution in main process - critical for testing, so we don't fork in fork, etc
             yield from self._process_sequential(fn, items, description, total)
         else:
             # Parallel execution with ProcessPoolExecutor
@@ -298,6 +527,7 @@ class PaperlessCommand(RichCommand):
         total: int,
     ) -> Generator[ProcessResult[T, R], None, None]:
         """Process items in parallel using ProcessPoolExecutor."""
+
         # Close database connections before forking - required for PostgreSQL
         db.connections.close_all()
 

src/documents/management/commands/document_exporter.py

@@ -3,6 +3,8 @@ import json
 import os
 import shutil
 import tempfile
+from itertools import chain
+from itertools import islice
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -19,6 +21,7 @@ from django.contrib.contenttypes.models import ContentType
 from django.core import serializers
 from django.core.management.base import BaseCommand
 from django.core.management.base import CommandError
+from django.core.serializers.json import DjangoJSONEncoder
 from django.db import transaction
 from django.utils import timezone
 from filelock import FileLock
@@ -26,6 +29,8 @@ from guardian.models import GroupObjectPermission
 from guardian.models import UserObjectPermission
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
+
     from django.db.models import QuerySet
 
 if settings.AUDIT_LOG_ENABLED:
@@ -60,6 +65,22 @@ from paperless_mail.models import MailAccount
 from paperless_mail.models import MailRule
 
 
+def serialize_queryset_batched(
+    queryset: "QuerySet",
+    *,
+    batch_size: int = 500,
+) -> "Generator[list[dict], None, None]":
+    """Yield batches of serialized records from a QuerySet.
+
+    Each batch is a list of dicts in Django's Python serialization format.
+    Uses QuerySet.iterator() to avoid loading the full queryset into memory,
+    and islice to collect chunk-sized batches serialized in a single call.
+    """
+    iterator = queryset.iterator(chunk_size=batch_size)
+    while chunk := list(islice(iterator, batch_size)):
+        yield serializers.serialize("python", chunk)
+
+
 class Command(CryptMixin, BaseCommand):
     help = (
         "Decrypt and rename all files in our collection into a given target "
@@ -186,6 +207,17 @@ class Command(CryptMixin, BaseCommand):
             help="If provided, is used to encrypt sensitive data in the export",
         )
 
+        parser.add_argument(
+            "--batch-size",
+            type=int,
+            default=500,
+            help=(
+                "Number of records to process per batch during serialization. "
+                "Lower values reduce peak memory usage; higher values improve "
+                "throughput. Default: 500."
+            ),
+        )
+
     def handle(self, *args, **options) -> None:
         self.target = Path(options["target"]).resolve()
         self.split_manifest: bool = options["split_manifest"]
@@ -200,6 +232,7 @@ class Command(CryptMixin, BaseCommand):
         self.data_only: bool = options["data_only"]
         self.no_progress_bar: bool = options["no_progress_bar"]
         self.passphrase: str | None = options.get("passphrase")
+        self.batch_size: int = options["batch_size"]
 
         self.files_in_export_dir: set[Path] = set()
         self.exported_files: set[str] = set()
@@ -294,8 +327,13 @@ class Command(CryptMixin, BaseCommand):
 
             # Build an overall manifest
             for key, object_query in manifest_key_to_object_query.items():
-                manifest_dict[key] = json.loads(
-                    serializers.serialize("json", object_query),
+                manifest_dict[key] = list(
+                    chain.from_iterable(
+                        serialize_queryset_batched(
+                            object_query,
+                            batch_size=self.batch_size,
+                        ),
+                    ),
                 )
 
             self.encrypt_secret_fields(manifest_dict)
@@ -512,14 +550,24 @@ class Command(CryptMixin, BaseCommand):
             self.files_in_export_dir.remove(target)
             if self.compare_json:
                 target_checksum = hashlib.md5(target.read_bytes()).hexdigest()
-                src_str = json.dumps(content, indent=2, ensure_ascii=False)
+                src_str = json.dumps(
+                    content,
+                    cls=DjangoJSONEncoder,
+                    indent=2,
+                    ensure_ascii=False,
+                )
                 src_checksum = hashlib.md5(src_str.encode("utf-8")).hexdigest()
                 if src_checksum == target_checksum:
                     perform_write = False
 
         if perform_write:
             target.write_text(
-                json.dumps(content, indent=2, ensure_ascii=False),
+                json.dumps(
+                    content,
+                    cls=DjangoJSONEncoder,
+                    indent=2,
+                    ensure_ascii=False,
+                ),
                 encoding="utf-8",
             )
 

src/documents/management/commands/document_index.py

@@ -1,22 +1,25 @@
-from django.core.management import BaseCommand
 from django.db import transaction
 
-from documents.management.commands.mixins import ProgressBarMixin
+from documents.management.commands.base import PaperlessCommand
 from documents.tasks import index_optimize
 from documents.tasks import index_reindex
 
 
-class Command(ProgressBarMixin, BaseCommand):
+class Command(PaperlessCommand):
     help = "Manages the document index."
 
     def add_arguments(self, parser):
+        super().add_arguments(parser)
         parser.add_argument("command", choices=["reindex", "optimize"])
-        self.add_argument_progress_bar_mixin(parser)
 
     def handle(self, *args, **options):
-        self.handle_progress_bar_mixin(**options)
         with transaction.atomic():
             if options["command"] == "reindex":
-                index_reindex(progress_bar_disable=self.no_progress_bar)
+                index_reindex(
+                    iter_wrapper=lambda docs: self.track(
+                        docs,
+                        description="Indexing documents...",
+                    ),
+                )
             elif options["command"] == "optimize":
                 index_optimize()

src/documents/management/commands/document_llmindex.py

@@ -1,22 +1,22 @@
-from django.core.management import BaseCommand
-from django.db import transaction
+from typing import Any
 
-from documents.management.commands.mixins import ProgressBarMixin
+from documents.management.commands.base import PaperlessCommand
 from documents.tasks import llmindex_index
 
 
-class Command(ProgressBarMixin, BaseCommand):
+class Command(PaperlessCommand):
     help = "Manages the LLM-based vector index for Paperless."
 
-    def add_arguments(self, parser):
+    def add_arguments(self, parser: Any) -> None:
+        super().add_arguments(parser)
         parser.add_argument("command", choices=["rebuild", "update"])
-        self.add_argument_progress_bar_mixin(parser)
 
-    def handle(self, *args, **options):
-        self.handle_progress_bar_mixin(**options)
-        with transaction.atomic():
-            llmindex_index(
-                progress_bar_disable=self.no_progress_bar,
-                rebuild=options["command"] == "rebuild",
-                scheduled=False,
-            )
+    def handle(self, *args: Any, **options: Any) -> None:
+        llmindex_index(
+            rebuild=options["command"] == "rebuild",
+            scheduled=False,
+            iter_wrapper=lambda docs: self.track(
+                docs,
+                description="Indexing documents...",
+            ),
+        )

src/documents/management/commands/document_retagger.py

@@ -1,4 +1,12 @@
+from __future__ import annotations
+
 import logging
+from dataclasses import dataclass
+from dataclasses import field
+from typing import TYPE_CHECKING
+
+from rich.table import Table
+from rich.text import Text
 
 from documents.classifier import load_classifier
 from documents.management.commands.base import PaperlessCommand
@@ -8,9 +16,162 @@ from documents.signals.handlers import set_document_type
 from documents.signals.handlers import set_storage_path
 from documents.signals.handlers import set_tags
 
+if TYPE_CHECKING:
+    from rich.console import RenderableType
+
+    from documents.models import Correspondent
+    from documents.models import DocumentType
+    from documents.models import StoragePath
+    from documents.models import Tag
+
 logger = logging.getLogger("paperless.management.retagger")
 
 
+@dataclass(slots=True)
+class RetaggerStats:
+    """Cumulative counters updated as the retagger processes documents.
+
+    Mutable by design -- fields are incremented in the processing loop.
+    slots=True reduces per-instance memory overhead and speeds attribute access.
+    """
+
+    correspondents: int = 0
+    document_types: int = 0
+    tags_added: int = 0
+    tags_removed: int = 0
+    storage_paths: int = 0
+    documents_processed: int = 0
+
+
+@dataclass(slots=True)
+class DocumentSuggestion:
+    """Buffered classifier suggestions for a single document (suggest mode only).
+
+    Mutable by design -- fields are assigned incrementally as each setter runs.
+    """
+
+    document: Document
+    correspondent: Correspondent | None = None
+    document_type: DocumentType | None = None
+    tags_to_add: frozenset[Tag] = field(default_factory=frozenset)
+    tags_to_remove: frozenset[Tag] = field(default_factory=frozenset)
+    storage_path: StoragePath | None = None
+
+    @property
+    def has_suggestions(self) -> bool:
+        return bool(
+            self.correspondent is not None
+            or self.document_type is not None
+            or self.tags_to_add
+            or self.tags_to_remove
+            or self.storage_path is not None,
+        )
+
+
+def _build_stats_table(stats: RetaggerStats, *, suggest: bool) -> Table:
+    """
+    Build the live-updating stats table shown below the progress bar.
+
+    In suggest mode the labels read "would set / would add" to make clear
+    that nothing has been written to the database.
+    """
+    table = Table(box=None, padding=(0, 2), show_header=True, header_style="bold")
+
+    table.add_column("Documents")
+    table.add_column("Correspondents")
+    table.add_column("Doc Types")
+    table.add_column("Tags (+)")
+    table.add_column("Tags (-)")
+    table.add_column("Storage Paths")
+
+    verb = "would set" if suggest else "set"
+
+    table.add_row(
+        str(stats.documents_processed),
+        f"{stats.correspondents} {verb}",
+        f"{stats.document_types} {verb}",
+        f"+{stats.tags_added}",
+        f"-{stats.tags_removed}",
+        f"{stats.storage_paths} {verb}",
+    )
+
+    return table
+
+
+def _build_suggestion_table(
+    suggestions: list[DocumentSuggestion],
+    base_url: str | None,
+) -> Table:
+    """
+    Build the final suggestion table printed after the progress bar completes.
+
+    Only documents with at least one suggestion are included.
+    """
+    table = Table(
+        title="Suggested Changes",
+        show_header=True,
+        header_style="bold cyan",
+        show_lines=True,
+    )
+
+    table.add_column("Document", style="bold", no_wrap=False, min_width=20)
+    table.add_column("Correspondent")
+    table.add_column("Doc Type")
+    table.add_column("Tags")
+    table.add_column("Storage Path")
+
+    for suggestion in suggestions:
+        if not suggestion.has_suggestions:
+            continue
+
+        doc = suggestion.document
+
+        if base_url:
+            doc_cell = Text()
+            doc_cell.append(str(doc))
+            doc_cell.append(f"\n{base_url}/documents/{doc.pk}", style="dim")
+        else:
+            doc_cell = Text(f"{doc} [{doc.pk}]")
+
+        tag_parts: list[str] = []
+        for tag in sorted(suggestion.tags_to_add, key=lambda t: t.name):
+            tag_parts.append(f"[green]+{tag.name}[/green]")
+        for tag in sorted(suggestion.tags_to_remove, key=lambda t: t.name):
+            tag_parts.append(f"[red]-{tag.name}[/red]")
+        tag_cell = Text.from_markup(", ".join(tag_parts)) if tag_parts else Text("-")
+
+        table.add_row(
+            doc_cell,
+            str(suggestion.correspondent) if suggestion.correspondent else "-",
+            str(suggestion.document_type) if suggestion.document_type else "-",
+            tag_cell,
+            str(suggestion.storage_path) if suggestion.storage_path else "-",
+        )
+
+    return table
+
+
+def _build_summary_table(stats: RetaggerStats) -> Table:
+    """Build the final applied-changes summary table."""
+    table = Table(
+        title="Retagger Summary",
+        show_header=True,
+        header_style="bold cyan",
+    )
+
+    table.add_column("Metric", style="bold")
+    table.add_column("Count", justify="right")
+
+    table.add_row("Documents processed", str(stats.documents_processed))
+    table.add_row("Correspondents set", str(stats.correspondents))
+    table.add_row("Document types set", str(stats.document_types))
+    table.add_row("Tags added", str(stats.tags_added))
+    table.add_row("Tags removed", str(stats.tags_removed))
+    table.add_row("Storage paths set", str(stats.storage_paths))
+
+    return table
+
+
 class Command(PaperlessCommand):
     help = (
         "Using the current classification model, assigns correspondents, tags "
@@ -19,7 +180,7 @@ class Command(PaperlessCommand):
         "modified) after their initial import."
     )
 
-    def add_arguments(self, parser):
+    def add_arguments(self, parser) -> None:
         super().add_arguments(parser)
         parser.add_argument("-c", "--correspondent", default=False, action="store_true")
         parser.add_argument("-T", "--tags", default=False, action="store_true")
@@ -31,9 +192,9 @@ class Command(PaperlessCommand):
             default=False,
             action="store_true",
             help=(
-                "By default this command won't try to assign a correspondent "
-                "if more than one matches the document. Use this flag if "
-                "you'd rather it just pick the first one it finds."
+                "By default this command will not try to assign a correspondent "
+                "if more than one matches the document. Use this flag to pick "
+                "the first match instead."
             ),
         )
         parser.add_argument(
@@ -42,91 +203,140 @@ class Command(PaperlessCommand):
             default=False,
             action="store_true",
             help=(
-                "If set, the document retagger will overwrite any previously "
-                "set correspondent, document and remove correspondents, types "
-                "and tags that do not match anymore due to changed rules."
+                "Overwrite any previously set correspondent, document type, and "
+                "remove tags that no longer match due to changed rules."
             ),
         )
         parser.add_argument(
             "--suggest",
             default=False,
             action="store_true",
-            help="Return the suggestion, don't change anything.",
+            help="Show what would be changed without applying anything.",
         )
         parser.add_argument(
             "--base-url",
-            help="The base URL to use to build the link to the documents.",
+            help="Base URL used to build document links in suggest output.",
         )
         parser.add_argument(
             "--id-range",
-            help="A range of document ids on which the retagging should be applied.",
+            help="Restrict retagging to documents within this ID range (inclusive).",
             nargs=2,
             type=int,
         )
 
-    def handle(self, *args, **options):
+    def handle(self, *args, **options) -> None:
+        suggest: bool = options["suggest"]
+        overwrite: bool = options["overwrite"]
+        use_first: bool = options["use_first"]
+        base_url: str | None = options["base_url"]
+
+        do_correspondent: bool = options["correspondent"]
+        do_document_type: bool = options["document_type"]
+        do_tags: bool = options["tags"]
+        do_storage_path: bool = options["storage_path"]
+
+        if not any([do_correspondent, do_document_type, do_tags, do_storage_path]):
+            self.console.print(
+                "[yellow]No classifier targets specified. "
+                "Use -c, -T, -t, or -s to select what to retag.[/yellow]",
+            )
+            return
+
         if options["inbox_only"]:
             queryset = Document.objects.filter(tags__is_inbox_tag=True)
         else:
             queryset = Document.objects.all()
 
         if options["id_range"]:
-            queryset = queryset.filter(
-                id__range=(options["id_range"][0], options["id_range"][1]),
-            )
+            lo, hi = options["id_range"]
+            queryset = queryset.filter(id__range=(lo, hi))
 
         documents = queryset.distinct()
-
         classifier = load_classifier()
 
-        for document in self.track(documents, description="Retagging..."):
-            if options["correspondent"]:
-                set_correspondent(
-                    sender=None,
-                    document=document,
-                    classifier=classifier,
-                    replace=options["overwrite"],
-                    use_first=options["use_first"],
-                    suggest=options["suggest"],
-                    base_url=options["base_url"],
-                    stdout=self.stdout,
-                    style_func=self.style,
-                )
+        stats = RetaggerStats()
+        suggestions: list[DocumentSuggestion] = []
 
-            if options["document_type"]:
-                set_document_type(
-                    sender=None,
-                    document=document,
-                    classifier=classifier,
-                    replace=options["overwrite"],
-                    use_first=options["use_first"],
-                    suggest=options["suggest"],
-                    base_url=options["base_url"],
-                    stdout=self.stdout,
-                    style_func=self.style,
-                )
+        def render_stats() -> RenderableType:
+            return _build_stats_table(stats, suggest=suggest)
 
-            if options["tags"]:
-                set_tags(
-                    sender=None,
-                    document=document,
-                    classifier=classifier,
-                    replace=options["overwrite"],
-                    suggest=options["suggest"],
-                    base_url=options["base_url"],
-                    stdout=self.stdout,
-                    style_func=self.style,
-                )
+        with self.buffered_logging(
+            "paperless",
+            "paperless.handlers",
+            "documents",
+        ) as log_buf:
+            for document in self.track_with_stats(
+                documents,
+                description="Retagging...",
+                stats_renderer=render_stats,
+            ):
+                suggestion = DocumentSuggestion(document=document)
 
-            if options["storage_path"]:
-                set_storage_path(
-                    sender=None,
-                    document=document,
-                    classifier=classifier,
-                    replace=options["overwrite"],
-                    use_first=options["use_first"],
-                    suggest=options["suggest"],
-                    base_url=options["base_url"],
-                    stdout=self.stdout,
-                    style_func=self.style,
-                )
+                if do_correspondent:
+                    correspondent = set_correspondent(
+                        None,
+                        document,
+                        classifier=classifier,
+                        replace=overwrite,
+                        use_first=use_first,
+                        dry_run=suggest,
+                    )
+                    if correspondent is not None:
+                        stats.correspondents += 1
+                        suggestion.correspondent = correspondent
+
+                if do_document_type:
+                    document_type = set_document_type(
+                        None,
+                        document,
+                        classifier=classifier,
+                        replace=overwrite,
+                        use_first=use_first,
+                        dry_run=suggest,
+                    )
+                    if document_type is not None:
+                        stats.document_types += 1
+                        suggestion.document_type = document_type
+
+                if do_tags:
+                    tags_to_add, tags_to_remove = set_tags(
+                        None,
+                        document,
+                        classifier=classifier,
+                        replace=overwrite,
+                        dry_run=suggest,
+                    )
+                    stats.tags_added += len(tags_to_add)
+                    stats.tags_removed += len(tags_to_remove)
+                    suggestion.tags_to_add = frozenset(tags_to_add)
+                    suggestion.tags_to_remove = frozenset(tags_to_remove)
+
+                if do_storage_path:
+                    storage_path = set_storage_path(
+                        None,
+                        document,
+                        classifier=classifier,
+                        replace=overwrite,
+                        use_first=use_first,
+                        dry_run=suggest,
+                    )
+                    if storage_path is not None:
+                        stats.storage_paths += 1
+                        suggestion.storage_path = storage_path
+
+                stats.documents_processed += 1
+
+                if suggest:
+                    suggestions.append(suggestion)
+
+        # Post-loop output
+        if suggest:
+            visible = [s for s in suggestions if s.has_suggestions]
+            if visible:
+                self.console.print(_build_suggestion_table(visible, base_url))
+            else:
+                self.console.print("[green]No changes suggested.[/green]")
+        else:
+            self.console.print(_build_summary_table(stats))
+
+        log_buf.render(self.console, min_level=logging.INFO, title="Retagger Log")

src/documents/management/commands/document_sanity_checker.py

@@ -1,17 +1,117 @@
-from django.core.management.base import BaseCommand
+"""Management command to check the document archive for issues."""
 
-from documents.management.commands.mixins import ProgressBarMixin
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from documents.management.commands.base import PaperlessCommand
+from documents.models import Document
+from documents.sanity_checker import SanityCheckMessages
 from documents.sanity_checker import check_sanity
 
+_LEVEL_STYLE: dict[int, tuple[str, str]] = {
+    logging.ERROR: ("bold red", "ERROR"),
+    logging.WARNING: ("yellow", "WARN"),
+    logging.INFO: ("dim", "INFO"),
+}
 
-class Command(ProgressBarMixin, BaseCommand):
+
+class Command(PaperlessCommand):
     help = "This command checks your document archive for issues."
 
-    def add_arguments(self, parser):
-        self.add_argument_progress_bar_mixin(parser)
+    def _render_results(self, messages: SanityCheckMessages) -> None:
+        """Render sanity check results as a Rich table."""
 
-    def handle(self, *args, **options):
-        self.handle_progress_bar_mixin(**options)
-        messages = check_sanity(progress=self.use_progress_bar, scheduled=False)
+        if (
+            not messages.has_error
+            and not messages.has_warning
+            and not messages.has_info
+        ):
+            self.console.print(
+                Panel(
+                    "[green]No issues detected.[/green]",
+                    title="Sanity Check",
+                    border_style="green",
+                ),
+            )
+            return
 
-        messages.log_messages()
+        # Build a lookup for document titles
+        doc_pks = [pk for pk in messages.document_pks() if pk is not None]
+        titles: dict[int, str] = {}
+        if doc_pks:
+            titles = dict(
+                Document.global_objects.filter(pk__in=doc_pks)
+                .only("pk", "title")
+                .values_list("pk", "title"),
+            )
+
+        table = Table(
+            title="Sanity Check Results",
+            show_lines=True,
+            title_style="bold",
+        )
+        table.add_column("Level", width=7, no_wrap=True)
+        table.add_column("Document", min_width=20)
+        table.add_column("Issue", ratio=1)
+
+        for doc_pk, doc_messages in messages.iter_messages():
+            if doc_pk is not None:
+                title = titles.get(doc_pk, "Unknown")
+                doc_label = f"#{doc_pk} {title}"
+            else:
+                doc_label = "(global)"
+
+            for msg in doc_messages:
+                style, label = _LEVEL_STYLE.get(
+                    msg["level"],
+                    ("dim", "INFO"),
+                )
+                table.add_row(
+                    Text(label, style=style),
+                    Text(doc_label),
+                    Text(str(msg["message"])),
+                )
+
+        self.console.print(table)
+
+        parts: list[str] = []
+
+        if messages.document_error_count:
+            parts.append(
+                f"{messages.document_error_count} document(s) with [bold red]errors[/bold red]",
+            )
+        if messages.document_warning_count:
+            parts.append(
+                f"{messages.document_warning_count} document(s) with [yellow]warnings[/yellow]",
+            )
+        if messages.document_info_count:
+            parts.append(f"{messages.document_info_count} document(s) with infos")
+        if messages.global_warning_count:
+            parts.append(
+                f"{messages.global_warning_count} global [yellow]warning(s)[/yellow]",
+            )
+
+        if parts:
+            if len(parts) > 1:
+                summary = ", ".join(parts[:-1]) + " and " + parts[-1]
+            else:
+                summary = parts[0]
+            self.console.print(f"\nFound {summary}.")
+        else:
+            self.console.print("\nNo issues found.")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        messages = check_sanity(
+            scheduled=False,
+            iter_wrapper=lambda docs: self.track(
+                docs,
+                description="Checking documents...",
+            ),
+        )
+        self._render_results(messages)

src/documents/migrations/0001_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.7 on 2026-01-15 22:08
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import datetime
 
@@ -21,6 +21,207 @@ class Migration(migrations.Migration):
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    replaces = [
+        ("documents", "0001_initial"),
+        ("documents", "0002_auto_20151226_1316"),
+        ("documents", "0003_sender"),
+        ("documents", "0004_auto_20160114_1844"),
+        (
+            "documents",
+            "0004_auto_20160114_1844_squashed_0011_auto_20160303_1929",
+        ),
+        ("documents", "0005_auto_20160123_0313"),
+        ("documents", "0006_auto_20160123_0430"),
+        ("documents", "0007_auto_20160126_2114"),
+        ("documents", "0008_document_file_type"),
+        ("documents", "0009_auto_20160214_0040"),
+        ("documents", "0010_log"),
+        ("documents", "0011_auto_20160303_1929"),
+        ("documents", "0012_auto_20160305_0040"),
+        ("documents", "0013_auto_20160325_2111"),
+        ("documents", "0014_document_checksum"),
+        ("documents", "0015_add_insensitive_to_match"),
+        (
+            "documents",
+            "0015_add_insensitive_to_match_squashed_0018_auto_20170715_1712",
+        ),
+        ("documents", "0016_auto_20170325_1558"),
+        ("documents", "0017_auto_20170512_0507"),
+        ("documents", "0018_auto_20170715_1712"),
+        ("documents", "0019_add_consumer_user"),
+        ("documents", "0020_document_added"),
+        ("documents", "0021_document_storage_type"),
+        ("documents", "0022_auto_20181007_1420"),
+        ("documents", "0023_document_current_filename"),
+        ("documents", "1000_update_paperless_all"),
+        ("documents", "1001_auto_20201109_1636"),
+        ("documents", "1002_auto_20201111_1105"),
+        ("documents", "1003_mime_types"),
+        ("documents", "1004_sanity_check_schedule"),
+        ("documents", "1005_checksums"),
+        ("documents", "1006_auto_20201208_2209"),
+        (
+            "documents",
+            "1006_auto_20201208_2209_squashed_1011_auto_20210101_2340",
+        ),
+        ("documents", "1007_savedview_savedviewfilterrule"),
+        ("documents", "1008_auto_20201216_1736"),
+        ("documents", "1009_auto_20201216_2005"),
+        ("documents", "1010_auto_20210101_2159"),
+        ("documents", "1011_auto_20210101_2340"),
+        ("documents", "1012_fix_archive_files"),
+        ("documents", "1013_migrate_tag_colour"),
+        ("documents", "1014_auto_20210228_1614"),
+        ("documents", "1015_remove_null_characters"),
+        ("documents", "1016_auto_20210317_1351"),
+        (
+            "documents",
+            "1016_auto_20210317_1351_squashed_1020_merge_20220518_1839",
+        ),
+        ("documents", "1017_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1018_alter_savedviewfilterrule_value"),
+        ("documents", "1019_storagepath_document_storage_path"),
+        ("documents", "1019_uisettings"),
+        ("documents", "1020_merge_20220518_1839"),
+        ("documents", "1021_webp_thumbnail_conversion"),
+        ("documents", "1022_paperlesstask"),
+        (
+            "documents",
+            "1022_paperlesstask_squashed_1036_alter_savedviewfilterrule_rule_type",
+        ),
+        ("documents", "1023_add_comments"),
+        ("documents", "1024_document_original_filename"),
+        ("documents", "1025_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1026_transition_to_celery"),
+        (
+            "documents",
+            "1027_remove_paperlesstask_attempted_task_and_more",
+        ),
+        (
+            "documents",
+            "1028_remove_paperlesstask_task_args_and_more",
+        ),
+        ("documents", "1029_alter_document_archive_serial_number"),
+        ("documents", "1030_alter_paperlesstask_task_file_name"),
+        (
+            "documents",
+            "1031_remove_savedview_user_correspondent_owner_and_more",
+        ),
+        (
+            "documents",
+            "1032_alter_correspondent_matching_algorithm_and_more",
+        ),
+        (
+            "documents",
+            "1033_alter_documenttype_options_alter_tag_options_and_more",
+        ),
+        ("documents", "1034_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1035_rename_comment_note"),
+        ("documents", "1036_alter_savedviewfilterrule_rule_type"),
+        ("documents", "1037_webp_encrypted_thumbnail_conversion"),
+        ("documents", "1038_sharelink"),
+        ("documents", "1039_consumptiontemplate"),
+        (
+            "documents",
+            "1040_customfield_customfieldinstance_and_more",
+        ),
+        ("documents", "1041_alter_consumptiontemplate_sources"),
+        (
+            "documents",
+            "1042_consumptiontemplate_assign_custom_fields_and_more",
+        ),
+        ("documents", "1043_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1044_workflow_workflowaction_workflowtrigger_and_more",
+        ),
+        (
+            "documents",
+            "1045_alter_customfieldinstance_value_monetary",
+        ),
+        (
+            "documents",
+            "1045_alter_customfieldinstance_value_monetary_squashed_1049_document_deleted_at_document_restored_at",
+        ),
+        (
+            "documents",
+            "1046_workflowaction_remove_all_correspondents_and_more",
+        ),
+        ("documents", "1047_savedview_display_mode_and_more"),
+        ("documents", "1048_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1049_document_deleted_at_document_restored_at",
+        ),
+        ("documents", "1050_customfield_extra_data_and_more"),
+        (
+            "documents",
+            "1051_alter_correspondent_owner_alter_document_owner_and_more",
+        ),
+        ("documents", "1052_document_transaction_id"),
+        ("documents", "1053_document_page_count"),
+        (
+            "documents",
+            "1054_customfieldinstance_value_monetary_amount_and_more",
+        ),
+        ("documents", "1055_alter_storagepath_path"),
+        (
+            "documents",
+            "1056_customfieldinstance_deleted_at_and_more",
+        ),
+        ("documents", "1057_paperlesstask_owner"),
+        (
+            "documents",
+            "1058_workflowtrigger_schedule_date_custom_field_and_more",
+        ),
+        (
+            "documents",
+            "1059_workflowactionemail_workflowactionwebhook_and_more",
+        ),
+        (
+            "documents",
+            "1060_alter_customfieldinstance_value_select",
+        ),
+        ("documents", "1061_workflowactionwebhook_as_json"),
+        ("documents", "1062_alter_savedviewfilterrule_rule_type"),
+        (
+            "documents",
+            "1063_paperlesstask_type_alter_paperlesstask_task_name_and_more",
+        ),
+        ("documents", "1064_delete_log"),
+        (
+            "documents",
+            "1065_workflowaction_assign_custom_fields_values",
+        ),
+        (
+            "documents",
+            "1066_alter_workflowtrigger_schedule_offset_days",
+        ),
+        ("documents", "1067_alter_document_created"),
+        ("documents", "1068_alter_document_created"),
+        (
+            "documents",
+            "1069_workflowtrigger_filter_has_storage_path_and_more",
+        ),
+        (
+            "documents",
+            "1070_customfieldinstance_value_long_text_and_more",
+        ),
+        (
+            "documents",
+            "1071_tag_tn_ancestors_count_tag_tn_ancestors_pks_and_more",
+        ),
+        (
+            "documents",
+            "1072_workflowtrigger_filter_custom_field_query_and_more",
+        ),
+        ("documents", "1073_migrate_workflow_title_jinja"),
+        (
+            "documents",
+            "1074_workflowrun_deleted_at_workflowrun_restored_at_and_more",
+        ),
+    ]
+
     operations = [
         migrations.CreateModel(
             name="WorkflowActionEmail",
@@ -185,70 +386,6 @@ class Migration(migrations.Migration):
                 "abstract": False,
             },
         ),
-        migrations.CreateModel(
-            name="CustomField",
-            fields=[
-                (
-                    "id",
-                    models.AutoField(
-                        auto_created=True,
-                        primary_key=True,
-                        serialize=False,
-                        verbose_name="ID",
-                    ),
-                ),
-                (
-                    "created",
-                    models.DateTimeField(
-                        db_index=True,
-                        default=django.utils.timezone.now,
-                        editable=False,
-                        verbose_name="created",
-                    ),
-                ),
-                ("name", models.CharField(max_length=128)),
-                (
-                    "data_type",
-                    models.CharField(
-                        choices=[
-                            ("string", "String"),
-                            ("url", "URL"),
-                            ("date", "Date"),
-                            ("boolean", "Boolean"),
-                            ("integer", "Integer"),
-                            ("float", "Float"),
-                            ("monetary", "Monetary"),
-                            ("documentlink", "Document Link"),
-                            ("select", "Select"),
-                            ("longtext", "Long Text"),
-                        ],
-                        editable=False,
-                        max_length=50,
-                        verbose_name="data type",
-                    ),
-                ),
-                (
-                    "extra_data",
-                    models.JSONField(
-                        blank=True,
-                        help_text="Extra data for the custom field, such as select options",
-                        null=True,
-                        verbose_name="extra data",
-                    ),
-                ),
-            ],
-            options={
-                "verbose_name": "custom field",
-                "verbose_name_plural": "custom fields",
-                "ordering": ("created",),
-                "constraints": [
-                    models.UniqueConstraint(
-                        fields=("name",),
-                        name="documents_customfield_unique_name",
-                    ),
-                ],
-            },
-        ),
         migrations.CreateModel(
             name="DocumentType",
             fields=[
@@ -733,17 +870,6 @@ class Migration(migrations.Migration):
                         verbose_name="correspondent",
                     ),
                 ),
-                (
-                    "owner",
-                    models.ForeignKey(
-                        blank=True,
-                        default=None,
-                        null=True,
-                        on_delete=django.db.models.deletion.SET_NULL,
-                        to=settings.AUTH_USER_MODEL,
-                        verbose_name="owner",
-                    ),
-                ),
                 (
                     "document_type",
                     models.ForeignKey(
@@ -767,12 +893,14 @@ class Migration(migrations.Migration):
                     ),
                 ),
                 (
-                    "tags",
-                    models.ManyToManyField(
+                    "owner",
+                    models.ForeignKey(
                         blank=True,
-                        related_name="documents",
-                        to="documents.tag",
-                        verbose_name="tags",
+                        default=None,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        to=settings.AUTH_USER_MODEL,
+                        verbose_name="owner",
                     ),
                 ),
             ],
@@ -782,6 +910,140 @@ class Migration(migrations.Migration):
                 "ordering": ("-created",),
             },
         ),
+        migrations.AddField(
+            model_name="document",
+            name="tags",
+            field=models.ManyToManyField(
+                blank=True,
+                related_name="documents",
+                to="documents.tag",
+                verbose_name="tags",
+            ),
+        ),
+        migrations.CreateModel(
+            name="Note",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("deleted_at", models.DateTimeField(blank=True, null=True)),
+                ("restored_at", models.DateTimeField(blank=True, null=True)),
+                ("transaction_id", models.UUIDField(blank=True, null=True)),
+                (
+                    "note",
+                    models.TextField(
+                        blank=True,
+                        help_text="Note for the document",
+                        verbose_name="content",
+                    ),
+                ),
+                (
+                    "created",
+                    models.DateTimeField(
+                        db_index=True,
+                        default=django.utils.timezone.now,
+                        verbose_name="created",
+                    ),
+                ),
+                (
+                    "document",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="notes",
+                        to="documents.document",
+                        verbose_name="document",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="notes",
+                        to=settings.AUTH_USER_MODEL,
+                        verbose_name="user",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "note",
+                "verbose_name_plural": "notes",
+                "ordering": ("created",),
+            },
+        ),
+        migrations.CreateModel(
+            name="CustomField",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "created",
+                    models.DateTimeField(
+                        db_index=True,
+                        default=django.utils.timezone.now,
+                        editable=False,
+                        verbose_name="created",
+                    ),
+                ),
+                ("name", models.CharField(max_length=128)),
+                (
+                    "data_type",
+                    models.CharField(
+                        choices=[
+                            ("string", "String"),
+                            ("url", "URL"),
+                            ("date", "Date"),
+                            ("boolean", "Boolean"),
+                            ("integer", "Integer"),
+                            ("float", "Float"),
+                            ("monetary", "Monetary"),
+                            ("documentlink", "Document Link"),
+                            ("select", "Select"),
+                            ("longtext", "Long Text"),
+                        ],
+                        editable=False,
+                        max_length=50,
+                        verbose_name="data type",
+                    ),
+                ),
+                (
+                    "extra_data",
+                    models.JSONField(
+                        blank=True,
+                        help_text="Extra data for the custom field, such as select options",
+                        null=True,
+                        verbose_name="extra data",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "custom field",
+                "verbose_name_plural": "custom fields",
+                "ordering": ("created",),
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("name",),
+                        name="documents_customfield_unique_name",
+                    ),
+                ],
+            },
+        ),
         migrations.CreateModel(
             name="CustomFieldInstance",
             fields=[
@@ -880,66 +1142,6 @@ class Migration(migrations.Migration):
                 "ordering": ("created",),
             },
         ),
-        migrations.CreateModel(
-            name="Note",
-            fields=[
-                (
-                    "id",
-                    models.AutoField(
-                        auto_created=True,
-                        primary_key=True,
-                        serialize=False,
-                        verbose_name="ID",
-                    ),
-                ),
-                ("deleted_at", models.DateTimeField(blank=True, null=True)),
-                ("restored_at", models.DateTimeField(blank=True, null=True)),
-                ("transaction_id", models.UUIDField(blank=True, null=True)),
-                (
-                    "note",
-                    models.TextField(
-                        blank=True,
-                        help_text="Note for the document",
-                        verbose_name="content",
-                    ),
-                ),
-                (
-                    "created",
-                    models.DateTimeField(
-                        db_index=True,
-                        default=django.utils.timezone.now,
-                        verbose_name="created",
-                    ),
-                ),
-                (
-                    "document",
-                    models.ForeignKey(
-                        blank=True,
-                        null=True,
-                        on_delete=django.db.models.deletion.CASCADE,
-                        related_name="notes",
-                        to="documents.document",
-                        verbose_name="document",
-                    ),
-                ),
-                (
-                    "user",
-                    models.ForeignKey(
-                        blank=True,
-                        null=True,
-                        on_delete=django.db.models.deletion.SET_NULL,
-                        related_name="notes",
-                        to=settings.AUTH_USER_MODEL,
-                        verbose_name="user",
-                    ),
-                ),
-            ],
-            options={
-                "verbose_name": "note",
-                "verbose_name_plural": "notes",
-                "ordering": ("created",),
-            },
-        ),
         migrations.CreateModel(
             name="PaperlessTask",
             fields=[
@@ -986,7 +1188,6 @@ class Migration(migrations.Migration):
                             ("train_classifier", "Train Classifier"),
                             ("check_sanity", "Check Sanity"),
                             ("index_optimize", "Index Optimize"),
-                            ("llmindex_update", "LLM Index Update"),
                         ],
                         help_text="Name of the task that was run",
                         max_length=255,
@@ -1380,6 +1581,7 @@ class Migration(migrations.Migration):
                         verbose_name="Workflow Action Type",
                     ),
                 ),
+                ("order", models.PositiveIntegerField(default=0, verbose_name="order")),
                 (
                     "assign_title",
                     models.TextField(

src/documents/migrations/0002_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-20 18:46
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import django.db.models.deletion
 from django.db import migrations
@@ -9,8 +9,14 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("documents", "0001_initial"),
-        ("paperless_mail", "0001_initial"),
+        ("documents", "0001_squashed"),
+        ("paperless_mail", "0001_squashed"),
+    ]
+
+    # This migration needs a "replaces", but it doesn't matter which.
+    # Chose the last 2.20.x migration
+    replaces = [
+        ("documents", "1075_workflowaction_order"),
     ]
 
     operations = [

src/documents/migrations/0003_workflowaction_order.py

@@ -6,7 +6,7 @@ from django.db import models
 
 class Migration(migrations.Migration):
     dependencies = [
-        ("documents", "0002_initial"),
+        ("documents", "0002_squashed"),
     ]
 
     operations = [

src/documents/migrations/0014_alter_paperlesstask_task_name.py

@@ -0,0 +1,30 @@
+# Generated by Django 5.2.11 on 2026-03-03 16:42
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("documents", "0013_document_root_document"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="paperlesstask",
+            name="task_name",
+            field=models.CharField(
+                choices=[
+                    ("consume_file", "Consume File"),
+                    ("train_classifier", "Train Classifier"),
+                    ("check_sanity", "Check Sanity"),
+                    ("index_optimize", "Index Optimize"),
+                    ("llmindex_update", "LLM Index Update"),
+                ],
+                help_text="Name of the task that was run",
+                max_length=255,
+                null=True,
+                verbose_name="Task Name",
+            ),
+        ),
+    ]

src/documents/models.py

@@ -75,7 +75,7 @@ class MatchingModel(ModelWithOwner):
 
     is_insensitive = models.BooleanField(_("is insensitive"), default=True)
 
-    class Meta:
+    class Meta(ModelWithOwner.Meta):
         abstract = True
         ordering = ("name",)
         constraints = [
@@ -427,16 +427,6 @@ class Document(SoftDeleteModel, ModelWithOwner):  # type: ignore[django-manager-
     def created_date(self):
         return self.created
 
-    @property
-    def version_index(self):
-        if self.root_document_id is None or self.pk is None:
-            return 0
-
-        return Document.objects.filter(
-            root_document_id=self.root_document_id,
-            id__lte=self.id,
-        ).count()
-
     def add_nested_tags(self, tags) -> None:
         tag_ids = set()
         for tag in tags:

src/documents/sanity_checker.py

@@ -1,80 +1,174 @@
+"""
+Sanity checker for the Paperless-ngx document archive.
+
+Verifies that all documents have valid files, correct checksums,
+and consistent metadata. Reports orphaned files in the media directory.
+
+Progress display is the caller's responsibility -- pass an ``iter_wrapper``
+to wrap the document queryset (e.g., with a progress bar). The default
+is an identity function that adds no overhead.
+"""
+
+from __future__ import annotations
+
 import hashlib
 import logging
 import uuid
 from collections import defaultdict
+from collections.abc import Callable
+from collections.abc import Iterable
+from collections.abc import Iterator
 from pathlib import Path
+from typing import TYPE_CHECKING
 from typing import Final
+from typing import TypedDict
+from typing import TypeVar
 
 from celery import states
 from django.conf import settings
 from django.utils import timezone
-from tqdm import tqdm
 
 from documents.models import Document
 from documents.models import PaperlessTask
 from paperless.config import GeneralConfig
 
+logger = logging.getLogger("paperless.sanity_checker")
+
+_T = TypeVar("_T")
+IterWrapper = Callable[[Iterable[_T]], Iterable[_T]]
+
+
+class MessageEntry(TypedDict):
+    """A single sanity check message with its severity level."""
+
+    level: int
+    message: str
+
+
+def _identity(iterable: Iterable[_T]) -> Iterable[_T]:
+    """Pass through an iterable unchanged (default iter_wrapper)."""
+    return iterable
+
 
 class SanityCheckMessages:
-    def __init__(self) -> None:
-        self._messages: dict[int, list[dict]] = defaultdict(list)
-        self.has_error = False
-        self.has_warning = False
+    """Collects sanity check messages grouped by document primary key.
 
-    def error(self, doc_pk, message) -> None:
+    Messages are categorized as error, warning, or info. ``None`` is used
+    as the key for messages not associated with a specific document
+    (e.g., orphaned files).
+    """
+
+    def __init__(self) -> None:
+        self._messages: dict[int | None, list[MessageEntry]] = defaultdict(list)
+        self.has_error: bool = False
+        self.has_warning: bool = False
+        self.has_info: bool = False
+        self.document_count: int = 0
+        self.document_error_count: int = 0
+        self.document_warning_count: int = 0
+        self.document_info_count: int = 0
+        self.global_warning_count: int = 0
+
+    # -- Recording ----------------------------------------------------------
+
+    def error(self, doc_pk: int | None, message: str) -> None:
         self._messages[doc_pk].append({"level": logging.ERROR, "message": message})
         self.has_error = True
+        if doc_pk is not None:
+            self.document_count += 1
+            self.document_error_count += 1
 
-    def warning(self, doc_pk, message) -> None:
+    def warning(self, doc_pk: int | None, message: str) -> None:
         self._messages[doc_pk].append({"level": logging.WARNING, "message": message})
         self.has_warning = True
 
-    def info(self, doc_pk, message) -> None:
+        if doc_pk is not None:
+            self.document_count += 1
+            self.document_warning_count += 1
+        else:
+            # This is the only type of global message we do right now
+            self.global_warning_count += 1
+
+    def info(self, doc_pk: int | None, message: str) -> None:
         self._messages[doc_pk].append({"level": logging.INFO, "message": message})
+        self.has_info = True
+
+        if doc_pk is not None:
+            self.document_count += 1
+            self.document_info_count += 1
+
+    # -- Iteration / query --------------------------------------------------
+
+    def document_pks(self) -> list[int | None]:
+        """Return all document PKs (including None for global messages)."""
+        return list(self._messages.keys())
+
+    def iter_messages(self) -> Iterator[tuple[int | None, list[MessageEntry]]]:
+        """Iterate over (doc_pk, messages) pairs."""
+        yield from self._messages.items()
+
+    def __getitem__(self, item: int | None) -> list[MessageEntry]:
+        return self._messages[item]
+
+    # -- Summarize Helpers --------------------------------------------------
+
+    @property
+    def has_global_issues(self) -> bool:
+        return None in self._messages
+
+    @property
+    def total_issue_count(self) -> int:
+        """Total number of error and warning messages across all documents and global."""
+        return (
+            self.document_error_count
+            + self.document_warning_count
+            + self.global_warning_count
+        )
+
+    # -- Logging output (used by Celery task path) --------------------------
 
     def log_messages(self) -> None:
-        logger = logging.getLogger("paperless.sanity_checker")
+        """Write all messages to the ``paperless.sanity_checker`` logger.
 
+        This is the output path for headless / Celery execution.
+        Management commands use Rich rendering instead.
+        """
         if len(self._messages) == 0:
             logger.info("Sanity checker detected no issues.")
-        else:
-            # Query once
-            all_docs = Document.global_objects.all()
+            return
 
-            for doc_pk in self._messages:
-                if doc_pk is not None:
-                    doc = all_docs.get(pk=doc_pk)
-                    logger.info(
-                        f"Detected following issue(s) with document #{doc.pk},"
-                        f" titled {doc.title}",
-                    )
-                for msg in self._messages[doc_pk]:
-                    logger.log(msg["level"], msg["message"])
+        doc_pks = [pk for pk in self._messages if pk is not None]
+        titles: dict[int, str] = {}
+        if doc_pks:
+            titles = dict(
+                Document.global_objects.filter(pk__in=doc_pks)
+                .only("pk", "title")
+                .values_list("pk", "title"),
+            )
 
-    def __len__(self):
-        return len(self._messages)
-
-    def __getitem__(self, item):
-        return self._messages[item]
+        for doc_pk, entries in self._messages.items():
+            if doc_pk is not None:
+                title = titles.get(doc_pk, "Unknown")
+                logger.info(
+                    "Detected following issue(s) with document #%s, titled %s",
+                    doc_pk,
+                    title,
+                )
+            for msg in entries:
+                logger.log(msg["level"], msg["message"])
 
 
 class SanityCheckFailedException(Exception):
     pass
 
 
-def check_sanity(*, progress=False, scheduled=True) -> SanityCheckMessages:
-    paperless_task = PaperlessTask.objects.create(
-        task_id=uuid.uuid4(),
-        type=PaperlessTask.TaskType.SCHEDULED_TASK
-        if scheduled
-        else PaperlessTask.TaskType.MANUAL_TASK,
-        task_name=PaperlessTask.TaskName.CHECK_SANITY,
-        status=states.STARTED,
-        date_created=timezone.now(),
-        date_started=timezone.now(),
-    )
-    messages = SanityCheckMessages()
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
 
+
+def _build_present_files() -> set[Path]:
+    """Collect all files in MEDIA_ROOT, excluding directories and ignorable files."""
     present_files = {
         x.resolve()
         for x in Path(settings.MEDIA_ROOT).glob("**/*")
@@ -82,95 +176,178 @@ def check_sanity(*, progress=False, scheduled=True) -> SanityCheckMessages:
     }
 
     lockfile = Path(settings.MEDIA_LOCK).resolve()
-    if lockfile in present_files:
-        present_files.remove(lockfile)
+    present_files.discard(lockfile)
 
     general_config = GeneralConfig()
     app_logo = general_config.app_logo or settings.APP_LOGO
     if app_logo:
         logo_file = Path(settings.MEDIA_ROOT / Path(app_logo.lstrip("/"))).resolve()
-        if logo_file in present_files:
-            present_files.remove(logo_file)
+        present_files.discard(logo_file)
 
-    for doc in tqdm(Document.global_objects.all(), disable=not progress):
-        # Check sanity of the thumbnail
-        thumbnail_path: Final[Path] = Path(doc.thumbnail_path).resolve()
-        if not thumbnail_path.exists() or not thumbnail_path.is_file():
-            messages.error(doc.pk, "Thumbnail of document does not exist.")
-        else:
-            if thumbnail_path in present_files:
-                present_files.remove(thumbnail_path)
-            try:
-                _ = thumbnail_path.read_bytes()
-            except OSError as e:
-                messages.error(doc.pk, f"Cannot read thumbnail file of document: {e}")
+    return present_files
 
-        # Check sanity of the original file
-        # TODO: extract method
-        source_path: Final[Path] = Path(doc.source_path).resolve()
-        if not source_path.exists() or not source_path.is_file():
-            messages.error(doc.pk, "Original of document does not exist.")
-        else:
-            if source_path in present_files:
-                present_files.remove(source_path)
-            try:
-                checksum = hashlib.md5(source_path.read_bytes()).hexdigest()
-            except OSError as e:
-                messages.error(doc.pk, f"Cannot read original file of document: {e}")
-            else:
-                if checksum != doc.checksum:
-                    messages.error(
-                        doc.pk,
-                        "Checksum mismatch. "
-                        f"Stored: {doc.checksum}, actual: {checksum}.",
-                    )
 
-        # Check sanity of the archive file.
-        if doc.archive_checksum is not None and doc.archive_filename is None:
+def _check_thumbnail(
+    doc: Document,
+    messages: SanityCheckMessages,
+    present_files: set[Path],
+) -> None:
+    """Verify the thumbnail exists and is readable."""
+    thumbnail_path: Final[Path] = Path(doc.thumbnail_path).resolve()
+    if not thumbnail_path.exists() or not thumbnail_path.is_file():
+        messages.error(doc.pk, "Thumbnail of document does not exist.")
+        return
+
+    present_files.discard(thumbnail_path)
+    try:
+        _ = thumbnail_path.read_bytes()
+    except OSError as e:
+        messages.error(doc.pk, f"Cannot read thumbnail file of document: {e}")
+
+
+def _check_original(
+    doc: Document,
+    messages: SanityCheckMessages,
+    present_files: set[Path],
+) -> None:
+    """Verify the original file exists, is readable, and has matching checksum."""
+    source_path: Final[Path] = Path(doc.source_path).resolve()
+    if not source_path.exists() or not source_path.is_file():
+        messages.error(doc.pk, "Original of document does not exist.")
+        return
+
+    present_files.discard(source_path)
+    try:
+        checksum = hashlib.md5(source_path.read_bytes()).hexdigest()
+    except OSError as e:
+        messages.error(doc.pk, f"Cannot read original file of document: {e}")
+    else:
+        if checksum != doc.checksum:
             messages.error(
                 doc.pk,
-                "Document has an archive file checksum, but no archive filename.",
+                f"Checksum mismatch. Stored: {doc.checksum}, actual: {checksum}.",
             )
-        elif doc.archive_checksum is None and doc.archive_filename is not None:
+
+
+def _check_archive(
+    doc: Document,
+    messages: SanityCheckMessages,
+    present_files: set[Path],
+) -> None:
+    """Verify archive file consistency: checksum/filename pairing and file integrity."""
+    if doc.archive_checksum is not None and doc.archive_filename is None:
+        messages.error(
+            doc.pk,
+            "Document has an archive file checksum, but no archive filename.",
+        )
+    elif doc.archive_checksum is None and doc.archive_filename is not None:
+        messages.error(
+            doc.pk,
+            "Document has an archive file, but its checksum is missing.",
+        )
+    elif doc.has_archive_version:
+        if TYPE_CHECKING:
+            assert isinstance(doc.archive_path, Path)
+        archive_path: Final[Path] = Path(doc.archive_path).resolve()
+        if not archive_path.exists() or not archive_path.is_file():
+            messages.error(doc.pk, "Archived version of document does not exist.")
+            return
+
+        present_files.discard(archive_path)
+        try:
+            checksum = hashlib.md5(archive_path.read_bytes()).hexdigest()
+        except OSError as e:
             messages.error(
                 doc.pk,
-                "Document has an archive file, but its checksum is missing.",
+                f"Cannot read archive file of document: {e}",
             )
-        elif doc.has_archive_version:
-            archive_path: Final[Path] = Path(doc.archive_path).resolve()
-            if not archive_path.exists() or not archive_path.is_file():
-                messages.error(doc.pk, "Archived version of document does not exist.")
-            else:
-                if archive_path in present_files:
-                    present_files.remove(archive_path)
-                try:
-                    checksum = hashlib.md5(archive_path.read_bytes()).hexdigest()
-                except OSError as e:
-                    messages.error(
-                        doc.pk,
-                        f"Cannot read archive file of document : {e}",
-                    )
-                else:
-                    if checksum != doc.archive_checksum:
-                        messages.error(
-                            doc.pk,
-                            "Checksum mismatch of archived document. "
-                            f"Stored: {doc.archive_checksum}, "
-                            f"actual: {checksum}.",
-                        )
+        else:
+            if checksum != doc.archive_checksum:
+                messages.error(
+                    doc.pk,
+                    "Checksum mismatch of archived document. "
+                    f"Stored: {doc.archive_checksum}, actual: {checksum}.",
+                )
 
-        # other document checks
-        if not doc.content:
-            messages.info(doc.pk, "Document contains no OCR data")
+
+def _check_content(doc: Document, messages: SanityCheckMessages) -> None:
+    """Flag documents with no OCR content."""
+    if not doc.content:
+        messages.info(doc.pk, "Document contains no OCR data")
+
+
+def _check_document(
+    doc: Document,
+    messages: SanityCheckMessages,
+    present_files: set[Path],
+) -> None:
+    """Run all checks for a single document."""
+    _check_thumbnail(doc, messages, present_files)
+    _check_original(doc, messages, present_files)
+    _check_archive(doc, messages, present_files)
+    _check_content(doc, messages)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def check_sanity(
+    *,
+    scheduled: bool = True,
+    iter_wrapper: IterWrapper[Document] = _identity,
+) -> SanityCheckMessages:
+    """Run a full sanity check on the document archive.
+
+    Args:
+        scheduled: Whether this is a scheduled (automatic) or manual check.
+            Controls the task type recorded in the database.
+        iter_wrapper: A callable that wraps the document iterable, e.g.,
+            for progress bar display. Defaults to identity (no wrapping).
+
+    Returns:
+        A SanityCheckMessages instance containing all detected issues.
+    """
+    paperless_task = PaperlessTask.objects.create(
+        task_id=uuid.uuid4(),
+        type=(
+            PaperlessTask.TaskType.SCHEDULED_TASK
+            if scheduled
+            else PaperlessTask.TaskType.MANUAL_TASK
+        ),
+        task_name=PaperlessTask.TaskName.CHECK_SANITY,
+        status=states.STARTED,
+        date_created=timezone.now(),
+        date_started=timezone.now(),
+    )
+
+    messages = SanityCheckMessages()
+    present_files = _build_present_files()
+
+    documents = Document.global_objects.all()
+    for doc in iter_wrapper(documents):
+        _check_document(doc, messages, present_files)
 
     for extra_file in present_files:
         messages.warning(None, f"Orphaned file in media dir: {extra_file}")
 
     paperless_task.status = states.SUCCESS if not messages.has_error else states.FAILURE
-    # result is concatenated messages
-    paperless_task.result = f"{len(messages)} issues found."
-    if messages.has_error:
-        paperless_task.result += " Check logs for details."
+    if messages.total_issue_count == 0:
+        paperless_task.result = "No issues found."
+    else:
+        parts: list[str] = []
+        if messages.document_error_count:
+            parts.append(f"{messages.document_error_count} document(s) with errors")
+        if messages.document_warning_count:
+            parts.append(f"{messages.document_warning_count} document(s) with warnings")
+        if messages.global_warning_count:
+            parts.append(f"{messages.global_warning_count} global warning(s)")
+        paperless_task.result = ", ".join(parts) + " found."
+        if messages.has_error:
+            paperless_task.result += " Check logs for details."
+
     paperless_task.date_done = timezone.now()
     paperless_task.save(update_fields=["status", "result", "date_done"])
+
     return messages

src/documents/serialisers.py

@@ -2749,7 +2749,6 @@ class WorkflowActionSerializer(serializers.ModelSerializer):
                         created_month_name_short="",
                         created_day="",
                         created_time="",
-                        version_index="",
                     )
                 except (ValueError, KeyError) as e:
                     raise serializers.ValidationError(

src/documents/signals/handlers.py

@@ -4,6 +4,7 @@ import logging
 import shutil
 from pathlib import Path
 from typing import TYPE_CHECKING
+from typing import Any
 
 from celery import shared_task
 from celery import states
@@ -32,12 +33,14 @@ from documents.file_handling import create_source_path_directory
 from documents.file_handling import delete_empty_directories
 from documents.file_handling import generate_filename
 from documents.file_handling import generate_unique_filename
+from documents.models import Correspondent
 from documents.models import CustomField
 from documents.models import CustomFieldInstance
 from documents.models import Document
-from documents.models import MatchingModel
+from documents.models import DocumentType
 from documents.models import PaperlessTask
 from documents.models import SavedView
+from documents.models import StoragePath
 from documents.models import Tag
 from documents.models import UiSettings
 from documents.models import Workflow
@@ -81,47 +84,41 @@ def add_inbox_tags(sender, document: Document, logging_group=None, **kwargs) ->
     document.add_nested_tags(inbox_tags)
 
 
-def _suggestion_printer(
-    stdout,
-    style_func,
-    suggestion_type: str,
-    document: Document,
-    selected: MatchingModel,
-    base_url: str | None = None,
-) -> None:
-    """
-    Smaller helper to reduce duplication when just outputting suggestions to the console
-    """
-    doc_str = str(document)
-    if base_url is not None:
-        stdout.write(style_func.SUCCESS(doc_str))
-        stdout.write(style_func.SUCCESS(f"{base_url}/documents/{document.pk}"))
-    else:
-        stdout.write(style_func.SUCCESS(f"{doc_str} [{document.pk}]"))
-    stdout.write(f"Suggest {suggestion_type}: {selected}")
-
-
 def set_correspondent(
-    sender,
+    sender: object,
     document: Document,
     *,
-    logging_group=None,
+    logging_group: object = None,
     classifier: DocumentClassifier | None = None,
-    replace=False,
-    use_first=True,
-    suggest=False,
-    base_url=None,
-    stdout=None,
-    style_func=None,
-    **kwargs,
-) -> None:
+    replace: bool = False,
+    use_first: bool = True,
+    dry_run: bool = False,
+    **kwargs: Any,
+) -> Correspondent | None:
+    """
+    Assign a correspondent to a document based on classifier results.
+
+    Args:
+        document: The document to classify.
+        logging_group: Optional logging group for structured log output.
+        classifier: The trained classifier. If None, only rule-based matching runs.
+        replace: If True, overwrite an existing correspondent assignment.
+        use_first: If True, pick the first match when multiple correspondents
+            match. If False, skip assignment when multiple match.
+        dry_run: If True, compute and return the selection without saving.
+        **kwargs: Absorbed for Django signal compatibility (e.g. sender, signal).
+
+    Returns:
+        The correspondent that was (or would be) assigned, or None if no match
+        was found or assignment was skipped.
+    """
     if document.correspondent and not replace:
-        return
+        return None
 
     potential_correspondents = matching.match_correspondents(document, classifier)
-
     potential_count = len(potential_correspondents)
     selected = potential_correspondents[0] if potential_correspondents else None
+
     if potential_count > 1:
         if use_first:
             logger.debug(
@@ -135,49 +132,53 @@ def set_correspondent(
                 f"not assigning any correspondent",
                 extra={"group": logging_group},
             )
-            return
+            return None
 
-    if selected or replace:
-        if suggest:
-            _suggestion_printer(
-                stdout,
-                style_func,
-                "correspondent",
-                document,
-                selected,
-                base_url,
-            )
-        else:
-            logger.info(
-                f"Assigning correspondent {selected} to {document}",
-                extra={"group": logging_group},
-            )
+    if (selected or replace) and not dry_run:
+        logger.info(
+            f"Assigning correspondent {selected} to {document}",
+            extra={"group": logging_group},
+        )
+        document.correspondent = selected
+        document.save(update_fields=("correspondent",))
 
-            document.correspondent = selected
-            document.save(update_fields=("correspondent",))
+    return selected
 
 
 def set_document_type(
-    sender,
+    sender: object,
     document: Document,
     *,
-    logging_group=None,
+    logging_group: object = None,
     classifier: DocumentClassifier | None = None,
-    replace=False,
-    use_first=True,
-    suggest=False,
-    base_url=None,
-    stdout=None,
-    style_func=None,
-    **kwargs,
-) -> None:
+    replace: bool = False,
+    use_first: bool = True,
+    dry_run: bool = False,
+    **kwargs: Any,
+) -> DocumentType | None:
+    """
+    Assign a document type to a document based on classifier results.
+
+    Args:
+        document: The document to classify.
+        logging_group: Optional logging group for structured log output.
+        classifier: The trained classifier. If None, only rule-based matching runs.
+        replace: If True, overwrite an existing document type assignment.
+        use_first: If True, pick the first match when multiple types match.
+            If False, skip assignment when multiple match.
+        dry_run: If True, compute and return the selection without saving.
+        **kwargs: Absorbed for Django signal compatibility (e.g. sender, signal).
+
+    Returns:
+        The document type that was (or would be) assigned, or None if no match
+        was found or assignment was skipped.
+    """
     if document.document_type and not replace:
-        return
+        return None
 
-    potential_document_type = matching.match_document_types(document, classifier)
-
-    potential_count = len(potential_document_type)
-    selected = potential_document_type[0] if potential_document_type else None
+    potential_document_types = matching.match_document_types(document, classifier)
+    potential_count = len(potential_document_types)
+    selected = potential_document_types[0] if potential_document_types else None
 
     if potential_count > 1:
         if use_first:
@@ -192,42 +193,64 @@ def set_document_type(
                 f"not assigning any document type",
                 extra={"group": logging_group},
             )
-            return
+            return None
 
-    if selected or replace:
-        if suggest:
-            _suggestion_printer(
-                stdout,
-                style_func,
-                "document type",
-                document,
-                selected,
-                base_url,
-            )
-        else:
-            logger.info(
-                f"Assigning document type {selected} to {document}",
-                extra={"group": logging_group},
-            )
+    if (selected or replace) and not dry_run:
+        logger.info(
+            f"Assigning document type {selected} to {document}",
+            extra={"group": logging_group},
+        )
+        document.document_type = selected
+        document.save(update_fields=("document_type",))
 
-            document.document_type = selected
-            document.save(update_fields=("document_type",))
+    return selected
 
 
 def set_tags(
-    sender,
+    sender: object,
     document: Document,
     *,
-    logging_group=None,
+    logging_group: object = None,
     classifier: DocumentClassifier | None = None,
-    replace=False,
-    suggest=False,
-    base_url=None,
-    stdout=None,
-    style_func=None,
-    **kwargs,
-) -> None:
+    replace: bool = False,
+    dry_run: bool = False,
+    **kwargs: Any,
+) -> tuple[set[Tag], set[Tag]]:
+    """
+    Assign tags to a document based on classifier results.
+
+    When replace=True, existing auto-matched and rule-matched tags are removed
+    before applying the new set (inbox tags and manually-added tags are preserved).
+
+    Args:
+        document: The document to classify.
+        logging_group: Optional logging group for structured log output.
+        classifier: The trained classifier. If None, only rule-based matching runs.
+        replace: If True, remove existing classifier-managed tags before applying
+            new ones. Inbox tags and manually-added tags are always preserved.
+        dry_run: If True, compute what would change without saving anything.
+        **kwargs: Absorbed for Django signal compatibility (e.g. sender, signal).
+
+    Returns:
+        A two-tuple of (tags_added, tags_removed). In non-replace mode,
+        tags_removed is always an empty set. In dry_run mode, neither set
+        is applied to the database.
+    """
+    # Compute which tags would be removed under replace mode.
+    # The filter mirrors the .delete() call below: keep inbox tags and
+    # manually-added tags (match="" and not auto-matched).
     if replace:
+        tags_to_remove: set[Tag] = set(
+            document.tags.exclude(
+                is_inbox_tag=True,
+            ).exclude(
+                Q(match="") & ~Q(matching_algorithm=Tag.MATCH_AUTO),
+            ),
+        )
+    else:
+        tags_to_remove = set()
+
+    if replace and not dry_run:
         Document.tags.through.objects.filter(document=document).exclude(
             Q(tag__is_inbox_tag=True),
         ).exclude(
@@ -235,65 +258,53 @@ def set_tags(
         ).delete()
 
     current_tags = set(document.tags.all())
-
     matched_tags = matching.match_tags(document, classifier)
+    tags_to_add = set(matched_tags) - current_tags
 
-    relevant_tags = set(matched_tags) - current_tags
-
-    if suggest:
-        extra_tags = current_tags - set(matched_tags)
-        extra_tags = [
-            t for t in extra_tags if t.matching_algorithm == MatchingModel.MATCH_AUTO
-        ]
-        if not relevant_tags and not extra_tags:
-            return
-        doc_str = style_func.SUCCESS(str(document))
-        if base_url:
-            stdout.write(doc_str)
-            stdout.write(f"{base_url}/documents/{document.pk}")
-        else:
-            stdout.write(doc_str + style_func.SUCCESS(f" [{document.pk}]"))
-        if relevant_tags:
-            stdout.write("Suggest tags: " + ", ".join([t.name for t in relevant_tags]))
-        if extra_tags:
-            stdout.write("Extra tags: " + ", ".join([t.name for t in extra_tags]))
-    else:
-        if not relevant_tags:
-            return
-
-        message = 'Tagging "{}" with "{}"'
+    if tags_to_add and not dry_run:
         logger.info(
-            message.format(document, ", ".join([t.name for t in relevant_tags])),
+            f'Tagging "{document}" with "{", ".join(t.name for t in tags_to_add)}"',
             extra={"group": logging_group},
         )
+        document.add_nested_tags(tags_to_add)
 
-        document.add_nested_tags(relevant_tags)
+    return tags_to_add, tags_to_remove
 
 
 def set_storage_path(
-    sender,
+    sender: object,
     document: Document,
     *,
-    logging_group=None,
+    logging_group: object = None,
     classifier: DocumentClassifier | None = None,
-    replace=False,
-    use_first=True,
-    suggest=False,
-    base_url=None,
-    stdout=None,
-    style_func=None,
-    **kwargs,
-) -> None:
+    replace: bool = False,
+    use_first: bool = True,
+    dry_run: bool = False,
+    **kwargs: Any,
+) -> StoragePath | None:
+    """
+    Assign a storage path to a document based on classifier results.
+
+    Args:
+        document: The document to classify.
+        logging_group: Optional logging group for structured log output.
+        classifier: The trained classifier. If None, only rule-based matching runs.
+        replace: If True, overwrite an existing storage path assignment.
+        use_first: If True, pick the first match when multiple paths match.
+            If False, skip assignment when multiple match.
+        dry_run: If True, compute and return the selection without saving.
+        **kwargs: Absorbed for Django signal compatibility (e.g. sender, signal).
+
+    Returns:
+        The storage path that was (or would be) assigned, or None if no match
+        was found or assignment was skipped.
+    """
     if document.storage_path and not replace:
-        return
+        return None
 
-    potential_storage_path = matching.match_storage_paths(
-        document,
-        classifier,
-    )
-
-    potential_count = len(potential_storage_path)
-    selected = potential_storage_path[0] if potential_storage_path else None
+    potential_storage_paths = matching.match_storage_paths(document, classifier)
+    potential_count = len(potential_storage_paths)
+    selected = potential_storage_paths[0] if potential_storage_paths else None
 
     if potential_count > 1:
         if use_first:
@@ -308,26 +319,17 @@ def set_storage_path(
                 f"not assigning any storage directory",
                 extra={"group": logging_group},
             )
-            return
+            return None
 
-    if selected or replace:
-        if suggest:
-            _suggestion_printer(
-                stdout,
-                style_func,
-                "storage directory",
-                document,
-                selected,
-                base_url,
-            )
-        else:
-            logger.info(
-                f"Assigning storage path {selected} to {document}",
-                extra={"group": logging_group},
-            )
+    if (selected or replace) and not dry_run:
+        logger.info(
+            f"Assigning storage path {selected} to {document}",
+            extra={"group": logging_group},
+        )
+        document.storage_path = selected
+        document.save(update_fields=("storage_path",))
 
-            document.storage_path = selected
-            document.save(update_fields=("storage_path",))
+    return selected
 
 
 # see empty_trash in documents/tasks.py for signal handling
@@ -782,6 +784,14 @@ def run_workflows(
     """
 
     use_overrides = overrides is not None
+
+    if isinstance(document, Document) and document.root_document_id is not None:
+        logger.debug(
+            "Skipping workflow execution for version document %s",
+            document.pk,
+        )
+        return None
+
     if original_file is None:
         original_file = (
             document.source_path if not use_overrides else document.original_file

src/documents/tasks.py

@@ -4,11 +4,13 @@ import logging
 import shutil
 import uuid
 import zipfile
+from collections.abc import Callable
+from collections.abc import Iterable
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from tempfile import mkstemp
+from typing import TypeVar
 
-import tqdm
 from celery import Task
 from celery import shared_task
 from celery import states
@@ -66,11 +68,19 @@ from paperless_ai.indexing import llm_index_add_or_update_document
 from paperless_ai.indexing import llm_index_remove_document
 from paperless_ai.indexing import update_llm_index
 
+_T = TypeVar("_T")
+IterWrapper = Callable[[Iterable[_T]], Iterable[_T]]
+
+
 if settings.AUDIT_LOG_ENABLED:
     from auditlog.models import LogEntry
 logger = logging.getLogger("paperless.tasks")
 
 
+def _identity(iterable: Iterable[_T]) -> Iterable[_T]:
+    return iterable
+
+
 @shared_task
 def index_optimize() -> None:
     ix = index.open_index()
@@ -78,13 +88,13 @@ def index_optimize() -> None:
     writer.commit(optimize=True)
 
 
-def index_reindex(*, progress_bar_disable=False) -> None:
+def index_reindex(*, iter_wrapper: IterWrapper[Document] = _identity) -> None:
     documents = Document.objects.all()
 
     ix = index.open_index(recreate=True)
 
     with AsyncWriter(ix) as writer:
-        for document in tqdm.tqdm(documents, disable=progress_bar_disable):
+        for document in iter_wrapper(documents):
             index.update_document(writer, document)
 
 
@@ -227,20 +237,30 @@ def consume_file(
 @shared_task
 def sanity_check(*, scheduled=True, raise_on_error=True):
     messages = sanity_checker.check_sanity(scheduled=scheduled)
-
     messages.log_messages()
 
+    if not messages.has_error and not messages.has_warning and not messages.has_info:
+        return "No issues detected."
+
+    parts: list[str] = []
+    if messages.document_error_count:
+        parts.append(f"{messages.document_error_count} document(s) with errors")
+    if messages.document_warning_count:
+        parts.append(f"{messages.document_warning_count} document(s) with warnings")
+    if messages.document_info_count:
+        parts.append(f"{messages.document_info_count} document(s) with infos")
+    if messages.global_warning_count:
+        parts.append(f"{messages.global_warning_count} global warning(s)")
+
+    summary = ", ".join(parts) + " found."
+
     if messages.has_error:
-        message = "Sanity check exited with errors. See log."
+        message = summary + " Check logs for details."
         if raise_on_error:
             raise SanityCheckFailedException(message)
         return message
-    elif messages.has_warning:
-        return "Sanity check exited with warnings. See log."
-    elif len(messages) > 0:
-        return "Sanity check exited with infos. See log."
-    else:
-        return "No issues detected."
+
+    return summary
 
 
 @shared_task
@@ -265,7 +285,6 @@ def bulk_update_documents(document_ids) -> None:
     ai_config = AIConfig()
     if ai_config.llm_index_enabled:
         update_llm_index(
-            progress_bar_disable=True,
             rebuild=False,
         )
 
@@ -452,13 +471,22 @@ def check_scheduled_workflows() -> None:
 
                 match trigger.schedule_date_field:
                     case WorkflowTrigger.ScheduleDateField.ADDED:
-                        documents = Document.objects.filter(added__lte=threshold)
+                        documents = Document.objects.filter(
+                            root_document__isnull=True,
+                            added__lte=threshold,
+                        )
 
                     case WorkflowTrigger.ScheduleDateField.CREATED:
-                        documents = Document.objects.filter(created__lte=threshold)
+                        documents = Document.objects.filter(
+                            root_document__isnull=True,
+                            created__lte=threshold,
+                        )
 
                     case WorkflowTrigger.ScheduleDateField.MODIFIED:
-                        documents = Document.objects.filter(modified__lte=threshold)
+                        documents = Document.objects.filter(
+                            root_document__isnull=True,
+                            modified__lte=threshold,
+                        )
 
                     case WorkflowTrigger.ScheduleDateField.CUSTOM_FIELD:
                         # cap earliest date to avoid massive scans
@@ -496,7 +524,10 @@ def check_scheduled_workflows() -> None:
                             )
                         ]
 
-                        documents = Document.objects.filter(id__in=matched_ids)
+                        documents = Document.objects.filter(
+                            root_document__isnull=True,
+                            id__in=matched_ids,
+                        )
 
                 if documents.count() > 0:
                     documents = prefilter_documents_by_workflowtrigger(
@@ -594,7 +625,7 @@ def update_document_parent_tags(tag: Tag, new_parent: Tag) -> None:
 @shared_task
 def llmindex_index(
     *,
-    progress_bar_disable=True,
+    iter_wrapper: IterWrapper[Document] = _identity,
     rebuild=False,
     scheduled=True,
     auto=False,
@@ -617,7 +648,7 @@ def llmindex_index(
 
         try:
             result = update_llm_index(
-                progress_bar_disable=progress_bar_disable,
+                iter_wrapper=iter_wrapper,
                 rebuild=rebuild,
             )
             task.status = states.SUCCESS

src/documents/templating/filepath.py

@@ -6,7 +6,6 @@ from pathlib import PurePath
 
 import pathvalidate
 from django.utils import timezone
-from django.utils.functional import SimpleLazyObject
 from django.utils.text import slugify as django_slugify
 from jinja2 import StrictUndefined
 from jinja2 import Template
@@ -114,7 +113,6 @@ def create_dummy_document():
         archive_filename="/dummy/archive_filename.pdf",
         original_filename="original_file.pdf",
         archive_serial_number=12345,
-        version_label="Version #1",
     )
     return dummy_doc
 
@@ -157,15 +155,14 @@ def get_basic_metadata_context(
     document: Document,
     *,
     no_value_default: str = NO_VALUE_PLACEHOLDER,
-    version_index: object | None = None,
-) -> dict[str, object]:
+) -> dict[str, str]:
     """
     Given a Document, constructs some basic information about it.  If certain values are not set,
     they will be replaced with the no_value_default.
 
     Regardless of set or not, the values will be sanitized
     """
-    context: dict[str, object] = {
+    return {
         "title": pathvalidate.sanitize_filename(
             document.title,
             replacement_text="-",
@@ -192,30 +189,17 @@ def get_basic_metadata_context(
         if document.original_filename
         else no_value_default,
         "doc_pk": f"{document.pk:07}",
-        "version_label": pathvalidate.sanitize_filename(
-            document.version_label,
-            replacement_text="-",
-        )
-        if document.version_label
-        else no_value_default,
     }
 
-    if version_index is not None:
-        context["version_index"] = version_index
-
-    return context
-
 
 def get_safe_document_context(
     document: Document,
     tags: Iterable[Tag],
-    *,
-    version_index: object | None = None,
 ) -> dict[str, object]:
     """
     Build a document context object to avoid supplying entire model instance.
     """
-    context: dict[str, object] = {
+    return {
         "id": document.pk,
         "pk": document.pk,
         "title": document.title,
@@ -253,11 +237,6 @@ def get_safe_document_context(
         else None,
     }
 
-    if version_index is not None:
-        context["version_index"] = version_index
-
-    return context
-
 
 def get_tags_context(tags: Iterable[Tag]) -> dict[str, str | list[str]]:
     """
@@ -368,20 +347,9 @@ def validate_filepath_template_and_render(
         custom_fields = CustomFieldInstance.global_objects.filter(document=document)
 
     # Build the context dictionary
-    lazy_version_index = SimpleLazyObject(lambda: document.version_index)
     context = (
-        {
-            "document": get_safe_document_context(
-                document,
-                tags=tags_list,
-                version_index=lazy_version_index,
-            ),
-        }
-        | get_basic_metadata_context(
-            document,
-            no_value_default=NO_VALUE_PLACEHOLDER,
-            version_index=lazy_version_index,
-        )
+        {"document": get_safe_document_context(document, tags=tags_list)}
+        | get_basic_metadata_context(document, no_value_default=NO_VALUE_PLACEHOLDER)
         | get_creation_date_context(document)
         | get_added_date_context(document)
         | get_tags_context(tags_list)

src/documents/templating/workflows.py

@@ -41,8 +41,6 @@ def parse_w_workflow_placeholders(
     doc_title: str | None = None,
     doc_url: str | None = None,
     doc_id: int | None = None,
-    version_label: str | None = None,
-    version_index: int | None = None,
 ) -> str:
     """
     Available title placeholders for Workflows depend on what has already been assigned,
@@ -64,8 +62,6 @@ def parse_w_workflow_placeholders(
         "owner_username": owner_username,
         "original_filename": Path(original_filename).stem,
         "filename": Path(filename).stem,
-        "version_label": version_label or "",
-        "version_index": version_index or "1",
     }
     if created is not None:
         formatting.update(

src/documents/tests/conftest.py

@@ -1,10 +1,96 @@
+import shutil
 import zoneinfo
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
 
+import filelock
 import pytest
 from django.contrib.auth import get_user_model
 from pytest_django.fixtures import SettingsWrapper
 from rest_framework.test import APIClient
 
+from documents.tests.factories import DocumentFactory
+
+if TYPE_CHECKING:
+    from documents.models import Document
+
+
+@dataclass(frozen=True, slots=True)
+class PaperlessDirs:
+    """Standard Paperless-ngx directory layout for tests."""
+
+    media: Path
+    originals: Path
+    archive: Path
+    thumbnails: Path
+
+
+@pytest.fixture(scope="session")
+def samples_dir() -> Path:
+    """Path to the shared test sample documents."""
+    return Path(__file__).parent / "samples" / "documents"
+
+
+@pytest.fixture()
+def paperless_dirs(tmp_path: Path) -> PaperlessDirs:
+    """Create and return the directory structure for testing."""
+    media = tmp_path / "media"
+    dirs = PaperlessDirs(
+        media=media,
+        originals=media / "documents" / "originals",
+        archive=media / "documents" / "archive",
+        thumbnails=media / "documents" / "thumbnails",
+    )
+    for d in (dirs.originals, dirs.archive, dirs.thumbnails):
+        d.mkdir(parents=True)
+    return dirs
+
+
+@pytest.fixture()
+def _media_settings(paperless_dirs: PaperlessDirs, settings) -> None:
+    """Configure Django settings to point at temp directories."""
+    settings.MEDIA_ROOT = paperless_dirs.media
+    settings.ORIGINALS_DIR = paperless_dirs.originals
+    settings.ARCHIVE_DIR = paperless_dirs.archive
+    settings.THUMBNAIL_DIR = paperless_dirs.thumbnails
+    settings.MEDIA_LOCK = paperless_dirs.media / "media.lock"
+    settings.IGNORABLE_FILES = {".DS_Store", "Thumbs.db", "desktop.ini"}
+    settings.APP_LOGO = ""
+
+
+@pytest.fixture()
+def sample_doc(
+    paperless_dirs: PaperlessDirs,
+    _media_settings: None,
+    samples_dir: Path,
+) -> "Document":
+    """Create a document with valid files and matching checksums."""
+    with filelock.FileLock(paperless_dirs.media / "media.lock"):
+        shutil.copy(
+            samples_dir / "originals" / "0000001.pdf",
+            paperless_dirs.originals / "0000001.pdf",
+        )
+        shutil.copy(
+            samples_dir / "archive" / "0000001.pdf",
+            paperless_dirs.archive / "0000001.pdf",
+        )
+        shutil.copy(
+            samples_dir / "thumbnails" / "0000001.webp",
+            paperless_dirs.thumbnails / "0000001.webp",
+        )
+
+    return DocumentFactory(
+        title="test",
+        checksum="42995833e01aea9b3edee44bbfdd7ce1",
+        archive_checksum="62acb0bcbfbcaa62ca6ad3668e4e404b",
+        content="test content",
+        pk=1,
+        filename="0000001.pdf",
+        mime_type="application/pdf",
+        archive_filename="0000001.pdf",
+    )
+
 
 @pytest.fixture()
 def settings_timezone(settings: SettingsWrapper) -> zoneinfo.ZoneInfo:
@@ -28,3 +114,14 @@ def authenticated_rest_api_client(rest_api_client: APIClient):
     user = UserModel.objects.create_user(username="testuser", password="password")
     rest_api_client.force_authenticate(user=user)
     yield rest_api_client
+
+
+@pytest.fixture(scope="session", autouse=True)
+def faker_session_locale():
+    """Set Faker locale for reproducibility."""
+    return "en_US"
+
+
+@pytest.fixture(scope="session", autouse=True)
+def faker_seed():
+    return 12345

src/documents/tests/factories.py

@@ -1,17 +1,67 @@
-from factory import Faker
+"""
+Factory-boy factories for documents app models.
+"""
+
+from __future__ import annotations
+
+import factory
 from factory.django import DjangoModelFactory
 
 from documents.models import Correspondent
 from documents.models import Document
+from documents.models import DocumentType
+from documents.models import MatchingModel
+from documents.models import StoragePath
+from documents.models import Tag
 
 
 class CorrespondentFactory(DjangoModelFactory):
     class Meta:
         model = Correspondent
 
-    name = Faker("name")
+    name = factory.Sequence(lambda n: f"{factory.Faker('company')} {n}")
+    match = ""
+    matching_algorithm = MatchingModel.MATCH_NONE
+
+
+class DocumentTypeFactory(DjangoModelFactory):
+    class Meta:
+        model = DocumentType
+
+    name = factory.Sequence(lambda n: f"{factory.Faker('bs')} {n}")
+    match = ""
+    matching_algorithm = MatchingModel.MATCH_NONE
+
+
+class TagFactory(DjangoModelFactory):
+    class Meta:
+        model = Tag
+
+    name = factory.Sequence(lambda n: f"{factory.Faker('word')} {n}")
+    match = ""
+    matching_algorithm = MatchingModel.MATCH_NONE
+    is_inbox_tag = False
+
+
+class StoragePathFactory(DjangoModelFactory):
+    class Meta:
+        model = StoragePath
+
+    name = factory.Sequence(
+        lambda n: f"{factory.Faker('file_path', depth=2, extension='')} {n}",
+    )
+    path = factory.LazyAttribute(lambda o: f"{o.name}/{{title}}")
+    match = ""
+    matching_algorithm = MatchingModel.MATCH_NONE
 
 
 class DocumentFactory(DjangoModelFactory):
     class Meta:
         model = Document
+
+    title = factory.Faker("sentence", nb_words=4)
+    checksum = factory.Faker("md5")
+    content = factory.Faker("paragraph")
+    correspondent = None
+    document_type = None
+    storage_path = None

src/documents/tests/management/test_management_sanity_checker.py

@@ -0,0 +1,193 @@
+"""Tests for the document_sanity_checker management command.
+
+Verifies Rich rendering (table, panel, summary) and end-to-end CLI behavior.
+"""
+
+from __future__ import annotations
+
+from io import StringIO
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from django.core.management import call_command
+from rich.console import Console
+
+from documents.management.commands.document_sanity_checker import Command
+from documents.sanity_checker import SanityCheckMessages
+from documents.tests.factories import DocumentFactory
+
+if TYPE_CHECKING:
+    from documents.models import Document
+    from documents.tests.conftest import PaperlessDirs
+
+
+def _render_to_string(messages: SanityCheckMessages) -> str:
+    """Render command output to a plain string for assertion."""
+    buf = StringIO()
+    cmd = Command()
+    cmd.console = Console(file=buf, width=120, no_color=True)
+    cmd._render_results(messages)
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Rich rendering
+# ---------------------------------------------------------------------------
+
+
+class TestRenderResultsNoIssues:
+    """No DB access needed -- renders an empty SanityCheckMessages."""
+
+    def test_shows_panel(self) -> None:
+        output = _render_to_string(SanityCheckMessages())
+        assert "No issues detected" in output
+        assert "Sanity Check" in output
+
+
+@pytest.mark.django_db
+class TestRenderResultsWithIssues:
+    def test_error_row(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(sample_doc.pk, "Original missing")
+        output = _render_to_string(msgs)
+        assert "Sanity Check Results" in output
+        assert "ERROR" in output
+        assert "Original missing" in output
+        assert f"#{sample_doc.pk}" in output
+        assert sample_doc.title in output
+
+    def test_warning_row(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.warning(sample_doc.pk, "Suspicious file")
+        output = _render_to_string(msgs)
+        assert "WARN" in output
+        assert "Suspicious file" in output
+
+    def test_info_row(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.info(sample_doc.pk, "No OCR data")
+        output = _render_to_string(msgs)
+        assert "INFO" in output
+        assert "No OCR data" in output
+
+    @pytest.mark.usefixtures("_media_settings")
+    def test_global_message(self) -> None:
+        msgs = SanityCheckMessages()
+        msgs.warning(None, "Orphaned file: /tmp/stray.pdf")
+        output = _render_to_string(msgs)
+        assert "(global)" in output
+        assert "Orphaned file" in output
+
+    def test_multiple_messages_same_doc(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(sample_doc.pk, "Thumbnail missing")
+        msgs.error(sample_doc.pk, "Checksum mismatch")
+        output = _render_to_string(msgs)
+        assert "Thumbnail missing" in output
+        assert "Checksum mismatch" in output
+
+    @pytest.mark.usefixtures("_media_settings")
+    def test_unknown_doc_pk(self) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(99999, "Ghost document")
+        output = _render_to_string(msgs)
+        assert "#99999" in output
+        assert "Unknown" in output
+
+
+@pytest.mark.django_db
+class TestRenderResultsSummary:
+    def test_errors_only(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(sample_doc.pk, "broken")
+        output = _render_to_string(msgs)
+        assert "1 document(s) with" in output
+        assert "errors" in output
+
+    def test_warnings_only(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.warning(sample_doc.pk, "odd")
+        output = _render_to_string(msgs)
+        assert "1 document(s) with" in output
+        assert "warnings" in output
+
+    def test_infos_only(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.info(sample_doc.pk, "no OCR")
+        output = _render_to_string(msgs)
+        assert "1 document(s) with infos" in output
+
+    def test_empty_messages(self) -> None:
+        msgs = SanityCheckMessages()
+        output = _render_to_string(msgs)
+        assert "No issues detected." in output
+
+    def test_document_errors_and_global_warnings(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(sample_doc.pk, "broken")
+        msgs.warning(None, "orphan")
+        output = _render_to_string(msgs)
+        assert "1 document(s) with" in output
+        assert "errors" in output
+        assert "1 global warning(s)" in output
+        assert "2 document(s)" not in output
+
+    def test_global_warnings_only(self) -> None:
+        msgs = SanityCheckMessages()
+        msgs.warning(None, "extra file")
+        output = _render_to_string(msgs)
+        assert "1 global warning(s)" in output
+        assert "document(s) with" not in output
+
+    def test_all_levels_combined(self, sample_doc: Document) -> None:
+        msgs = SanityCheckMessages()
+        msgs.error(sample_doc.pk, "broken")
+        msgs.warning(sample_doc.pk, "odd")
+        msgs.info(sample_doc.pk, "fyi")
+        msgs.warning(None, "extra file")
+        output = _render_to_string(msgs)
+        assert "1 document(s) with errors" in output
+        assert "1 document(s) with warnings" in output
+        assert "1 document(s) with infos" in output
+        assert "1 global warning(s)" in output
+
+
+# ---------------------------------------------------------------------------
+# End-to-end command execution
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.django_db
+@pytest.mark.management
+class TestDocumentSanityCheckerCommand:
+    def test_no_issues(self, sample_doc: Document) -> None:
+        out = StringIO()
+        call_command("document_sanity_checker", "--no-progress-bar", stdout=out)
+        assert "No issues detected" in out.getvalue()
+
+    def test_missing_original(self, sample_doc: Document) -> None:
+        Path(sample_doc.source_path).unlink()
+        out = StringIO()
+        call_command("document_sanity_checker", "--no-progress-bar", stdout=out)
+        output = out.getvalue()
+        assert "ERROR" in output
+        assert "Original of document does not exist" in output
+
+    @pytest.mark.usefixtures("_media_settings")
+    def test_checksum_mismatch(self, paperless_dirs: PaperlessDirs) -> None:
+        """Lightweight document with zero-byte files triggers checksum mismatch."""
+        doc = DocumentFactory(
+            title="test",
+            content="test",
+            filename="test.pdf",
+            checksum="abc",
+        )
+        Path(doc.source_path).touch()
+        Path(doc.thumbnail_path).touch()
+
+        out = StringIO()
+        call_command("document_sanity_checker", "--no-progress-bar", stdout=out)
+        output = out.getvalue()
+        assert "ERROR" in output
+        assert "Checksum mismatch. Stored: abc, actual:" in output

src/documents/tests/test_api_objects.py

@@ -267,7 +267,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
                     "/{created_month_name_short}/{created_day}/{added}/{added_year}"
                     "/{added_year_short}/{added_month}/{added_month_name}"
                     "/{added_month_name_short}/{added_day}/{asn}"
-                    "/{tag_list}/{owner_username}/{original_name}/{doc_pk}/{version_index}/",
+                    "/{tag_list}/{owner_username}/{original_name}/{doc_pk}/",
                 },
             ),
             content_type="application/json",

src/documents/tests/test_api_workflows.py

@@ -355,35 +355,6 @@ class TestApiWorkflows(DirectoriesMixin, APITestCase):
 
         self.assertEqual(Workflow.objects.count(), 1)
 
-    def test_api_create_assign_title_accepts_version_index(self) -> None:
-        response = self.client.post(
-            self.ENDPOINT,
-            json.dumps(
-                {
-                    "name": "Workflow with version index",
-                    "order": 1,
-                    "triggers": [
-                        {
-                            "type": WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED,
-                        },
-                    ],
-                    "actions": [
-                        {
-                            "assign_title": "Version {version_index}",
-                        },
-                    ],
-                },
-            ),
-            content_type="application/json",
-        )
-
-        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
-        workflow = Workflow.objects.get(name="Workflow with version index")
-        self.assertEqual(
-            workflow.actions.first().assign_title,
-            "Version {version_index}",
-        )
-
     def test_api_create_workflow_trigger_action_empty_fields(self) -> None:
         """
         GIVEN:

src/documents/tests/test_consumer.py

@@ -428,11 +428,7 @@ class TestConsumer(
             DocumentMetadataOverrides(
                 correspondent_id=c.pk,
                 document_type_id=dt.pk,
-                title=(
-                    "{{correspondent}}{{document_type}} "
-                    "{{added_month}}-{{added_year_short}}.{{version_label}}"
-                ),
-                version_label="v2",
+                title="{{correspondent}}{{document_type}} {{added_month}}-{{added_year_short}}",
             ),
         ) as consumer:
             consumer.run()
@@ -440,10 +436,7 @@ class TestConsumer(
             document = Document.objects.first()
 
         now = timezone.now()
-        self.assertEqual(
-            document.title,
-            f"{c.name}{dt.name} {now.strftime('%m-%y')}.v2",
-        )
+        self.assertEqual(document.title, f"{c.name}{dt.name} {now.strftime('%m-%y')}")
         self._assert_first_last_send_progress()
 
     def testOverrideOwner(self) -> None:

src/documents/tests/test_document_model.py

@@ -156,54 +156,6 @@ class TestDocument(TestCase):
         )
         self.assertEqual(doc.get_public_filename(), "2020-12-25 test")
 
-    def test_version_index_for_root_is_zero(self) -> None:
-        root = Document.objects.create(
-            title="Root",
-            content="content",
-            checksum="checksum-root",
-            mime_type="application/pdf",
-            created=date(2025, 1, 1),
-        )
-
-        self.assertEqual(root.version_index, 0)
-
-    def test_version_index_uses_id_ordering(self) -> None:
-        root = Document.objects.create(
-            title="Root",
-            content="content",
-            checksum="checksum-root",
-            mime_type="application/pdf",
-            created=date(2025, 1, 1),
-        )
-        v1 = Document.objects.create(
-            root_document=root,
-            title="V1",
-            content="content",
-            checksum="checksum-v1",
-            mime_type="application/pdf",
-            created=date(2025, 1, 3),
-        )
-        v2 = Document.objects.create(
-            root_document=root,
-            title="V2",
-            content="content",
-            checksum="checksum-v2",
-            mime_type="application/pdf",
-            created=date(2025, 1, 2),
-        )
-        v3 = Document.objects.create(
-            root_document=root,
-            title="V3",
-            content="content",
-            checksum="checksum-v3",
-            mime_type="application/pdf",
-            created=date(2025, 1, 1),
-        )
-
-        self.assertEqual(v1.version_index, 1)
-        self.assertEqual(v2.version_index, 2)
-        self.assertEqual(v3.version_index, 3)
-
 
 def test_suggestion_content() -> None:
     """

src/documents/tests/test_file_handling.py

@@ -281,32 +281,6 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
         self.assertEqual(generate_filename(d1), Path("652 - the_doc.pdf"))
         self.assertEqual(generate_filename(d2), Path("none - the_doc.pdf"))
 
-    @override_settings(FILENAME_FORMAT="{title}.{version_label}")
-    def test_version_label(self) -> None:
-        d1 = Document.objects.create(
-            title="the_doc",
-            mime_type="application/pdf",
-            checksum="A",
-            version_label="Version #2",
-        )
-        d2 = Document.objects.create(
-            title="the_doc",
-            mime_type="application/pdf",
-            checksum="B",
-        )
-        d3 = Document.objects.create(
-            title="the_doc",
-            mime_type="application/pdf",
-            checksum="C",
-            version_label="Super weird %@\"'<> ¯\\_(ツ)_/¯",
-        )
-        self.assertEqual(generate_filename(d1), Path("the_doc.Version #2.pdf"))
-        self.assertEqual(generate_filename(d2), Path("the_doc.none.pdf"))
-        self.assertEqual(
-            generate_filename(d3),
-            Path("the_doc.Super weird %@-'-- ¯-_(ツ)_-¯.pdf"),
-        )
-
     @override_settings(FILENAME_FORMAT="{title} {tag_list}")
     def test_tag_list(self) -> None:
         doc = Document.objects.create(title="doc1", mime_type="application/pdf")
@@ -409,21 +383,6 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
 
         self.assertEqual(generate_filename(document), Path("0013579.pdf"))
 
-    @override_settings(FILENAME_FORMAT="{version_index}")
-    def test_format_version_index(self) -> None:
-        root = Document.objects.create(
-            checksum="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-            mime_type="application/pdf",
-        )
-        version = Document.objects.create(
-            root_document=root,
-            checksum="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-            mime_type="application/pdf",
-        )
-
-        self.assertEqual(generate_filename(root), Path("0.pdf"))
-        self.assertEqual(generate_filename(version), Path("1.pdf"))
-
     @override_settings(FILENAME_FORMAT=None)
     def test_format_none(self) -> None:
         document = Document()

src/documents/tests/test_management.py

@@ -134,6 +134,7 @@ class TestRenamer(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
         self.assertIsFile(doc2.archive_path)
 
 
+@pytest.mark.management
 class TestCreateClassifier(TestCase):
     @mock.patch(
         "documents.management.commands.document_create_classifier.train_classifier",
@@ -144,32 +145,6 @@ class TestCreateClassifier(TestCase):
         m.assert_called_once()
 
 
-@pytest.mark.management
-class TestSanityChecker(DirectoriesMixin, TestCase):
-    def test_no_issues(self) -> None:
-        with self.assertLogs() as capture:
-            call_command("document_sanity_checker")
-
-        self.assertEqual(len(capture.output), 1)
-        self.assertIn("Sanity checker detected no issues.", capture.output[0])
-
-    def test_errors(self) -> None:
-        doc = Document.objects.create(
-            title="test",
-            content="test",
-            filename="test.pdf",
-            checksum="abc",
-        )
-        Path(doc.source_path).touch()
-        Path(doc.thumbnail_path).touch()
-
-        with self.assertLogs() as capture:
-            call_command("document_sanity_checker")
-
-        self.assertEqual(len(capture.output), 2)
-        self.assertIn("Checksum mismatch. Stored: abc, actual:", capture.output[1])
-
-
 @pytest.mark.management
 class TestConvertMariaDBUUID(TestCase):
     @mock.patch("django.db.connection.schema_editor")

src/documents/tests/test_management_exporter.py

@@ -288,7 +288,7 @@ class TestExportImport(
             self.assertEqual(Permission.objects.count(), num_permission_objects)
             messages = check_sanity()
             # everything is alright after the test
-            self.assertEqual(len(messages), 0)
+            self.assertEqual(messages.total_issue_count, 0)
 
     def test_exporter_with_filename_format(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")

src/documents/tests/test_management_retagger.py

@@ -1,298 +1,442 @@
+"""
+Tests for the document_retagger management command.
+"""
+
+from __future__ import annotations
+
 import pytest
 from django.core.management import call_command
 from django.core.management.base import CommandError
-from django.test import TestCase
 
 from documents.models import Correspondent
 from documents.models import Document
 from documents.models import DocumentType
+from documents.models import MatchingModel
 from documents.models import StoragePath
 from documents.models import Tag
+from documents.tests.factories import CorrespondentFactory
+from documents.tests.factories import DocumentFactory
+from documents.tests.factories import DocumentTypeFactory
+from documents.tests.factories import StoragePathFactory
+from documents.tests.factories import TagFactory
 from documents.tests.utils import DirectoriesMixin
 
+# ---------------------------------------------------------------------------
+# Module-level type aliases
+# ---------------------------------------------------------------------------
+
+StoragePathTuple = tuple[StoragePath, StoragePath, StoragePath]
+TagTuple = tuple[Tag, Tag, Tag, Tag, Tag]
+CorrespondentTuple = tuple[Correspondent, Correspondent]
+DocumentTypeTuple = tuple[DocumentType, DocumentType]
+DocumentTuple = tuple[Document, Document, Document, Document]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def storage_paths(db) -> StoragePathTuple:
+    """Three storage paths with varying match rules."""
+    sp1 = StoragePathFactory(
+        path="{created_data}/{title}",
+        match="auto document",
+        matching_algorithm=MatchingModel.MATCH_LITERAL,
+    )
+    sp2 = StoragePathFactory(
+        path="{title}",
+        match="^first|^unrelated",
+        matching_algorithm=MatchingModel.MATCH_REGEX,
+    )
+    sp3 = StoragePathFactory(
+        path="{title}",
+        match="^blah",
+        matching_algorithm=MatchingModel.MATCH_REGEX,
+    )
+    return sp1, sp2, sp3
+
+
+@pytest.fixture()
+def tags(db) -> TagTuple:
+    """Tags covering the common matching scenarios."""
+    tag_first = TagFactory(match="first", matching_algorithm=Tag.MATCH_ANY)
+    tag_second = TagFactory(match="second", matching_algorithm=Tag.MATCH_ANY)
+    tag_inbox = TagFactory(is_inbox_tag=True)
+    tag_no_match = TagFactory()
+    tag_auto = TagFactory(matching_algorithm=Tag.MATCH_AUTO)
+    return tag_first, tag_second, tag_inbox, tag_no_match, tag_auto
+
+
+@pytest.fixture()
+def correspondents(db) -> CorrespondentTuple:
+    """Two correspondents matching 'first' and 'second' content."""
+    c_first = CorrespondentFactory(
+        match="first",
+        matching_algorithm=MatchingModel.MATCH_ANY,
+    )
+    c_second = CorrespondentFactory(
+        match="second",
+        matching_algorithm=MatchingModel.MATCH_ANY,
+    )
+    return c_first, c_second
+
+
+@pytest.fixture()
+def document_types(db) -> DocumentTypeTuple:
+    """Two document types matching 'first' and 'second' content."""
+    dt_first = DocumentTypeFactory(
+        match="first",
+        matching_algorithm=MatchingModel.MATCH_ANY,
+    )
+    dt_second = DocumentTypeFactory(
+        match="second",
+        matching_algorithm=MatchingModel.MATCH_ANY,
+    )
+    return dt_first, dt_second
+
+
+@pytest.fixture()
+def documents(storage_paths: StoragePathTuple, tags: TagTuple) -> DocumentTuple:
+    """Four documents with varied content used across most retagger tests."""
+    _, _, sp3 = storage_paths
+    _, _, tag_inbox, tag_no_match, tag_auto = tags
+
+    d1 = DocumentFactory(checksum="A", title="A", content="first document")
+    d2 = DocumentFactory(checksum="B", title="B", content="second document")
+    d3 = DocumentFactory(
+        checksum="C",
+        title="C",
+        content="unrelated document",
+        storage_path=sp3,
+    )
+    d4 = DocumentFactory(checksum="D", title="D", content="auto document")
+
+    d3.tags.add(tag_inbox, tag_no_match)
+    d4.tags.add(tag_auto)
+
+    return d1, d2, d3, d4
+
+
+def _get_docs() -> DocumentTuple:
+    return (
+        Document.objects.get(title="A"),
+        Document.objects.get(title="B"),
+        Document.objects.get(title="C"),
+        Document.objects.get(title="D"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tag assignment
+# ---------------------------------------------------------------------------
+
 
 @pytest.mark.management
-class TestRetagger(DirectoriesMixin, TestCase):
-    def make_models(self) -> None:
-        self.sp1 = StoragePath.objects.create(
-            name="dummy a",
-            path="{created_data}/{title}",
-            match="auto document",
-            matching_algorithm=StoragePath.MATCH_LITERAL,
-        )
-        self.sp2 = StoragePath.objects.create(
-            name="dummy b",
-            path="{title}",
-            match="^first|^unrelated",
-            matching_algorithm=StoragePath.MATCH_REGEX,
-        )
-
-        self.sp3 = StoragePath.objects.create(
-            name="dummy c",
-            path="{title}",
-            match="^blah",
-            matching_algorithm=StoragePath.MATCH_REGEX,
-        )
-
-        self.d1 = Document.objects.create(
-            checksum="A",
-            title="A",
-            content="first document",
-        )
-        self.d2 = Document.objects.create(
-            checksum="B",
-            title="B",
-            content="second document",
-        )
-        self.d3 = Document.objects.create(
-            checksum="C",
-            title="C",
-            content="unrelated document",
-            storage_path=self.sp3,
-        )
-        self.d4 = Document.objects.create(
-            checksum="D",
-            title="D",
-            content="auto document",
-        )
-
-        self.tag_first = Tag.objects.create(
-            name="tag1",
-            match="first",
-            matching_algorithm=Tag.MATCH_ANY,
-        )
-        self.tag_second = Tag.objects.create(
-            name="tag2",
-            match="second",
-            matching_algorithm=Tag.MATCH_ANY,
-        )
-        self.tag_inbox = Tag.objects.create(name="test", is_inbox_tag=True)
-        self.tag_no_match = Tag.objects.create(name="test2")
-        self.tag_auto = Tag.objects.create(
-            name="tagauto",
-            matching_algorithm=Tag.MATCH_AUTO,
-        )
-
-        self.d3.tags.add(self.tag_inbox)
-        self.d3.tags.add(self.tag_no_match)
-        self.d4.tags.add(self.tag_auto)
-
-        self.correspondent_first = Correspondent.objects.create(
-            name="c1",
-            match="first",
-            matching_algorithm=Correspondent.MATCH_ANY,
-        )
-        self.correspondent_second = Correspondent.objects.create(
-            name="c2",
-            match="second",
-            matching_algorithm=Correspondent.MATCH_ANY,
-        )
-
-        self.doctype_first = DocumentType.objects.create(
-            name="dt1",
-            match="first",
-            matching_algorithm=DocumentType.MATCH_ANY,
-        )
-        self.doctype_second = DocumentType.objects.create(
-            name="dt2",
-            match="second",
-            matching_algorithm=DocumentType.MATCH_ANY,
-        )
-
-    def get_updated_docs(self):
-        return (
-            Document.objects.get(title="A"),
-            Document.objects.get(title="B"),
-            Document.objects.get(title="C"),
-            Document.objects.get(title="D"),
-        )
-
-    def setUp(self) -> None:
-        super().setUp()
-        self.make_models()
-
-    def test_add_tags(self) -> None:
+@pytest.mark.django_db
+class TestRetaggerTags(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    def test_add_tags(self, tags: TagTuple) -> None:
+        tag_first, tag_second, *_ = tags
         call_command("document_retagger", "--tags")
-        d_first, d_second, d_unrelated, d_auto = self.get_updated_docs()
+        d_first, d_second, d_unrelated, d_auto = _get_docs()
 
-        self.assertEqual(d_first.tags.count(), 1)
-        self.assertEqual(d_second.tags.count(), 1)
-        self.assertEqual(d_unrelated.tags.count(), 2)
-        self.assertEqual(d_auto.tags.count(), 1)
+        assert d_first.tags.count() == 1
+        assert d_second.tags.count() == 1
+        assert d_unrelated.tags.count() == 2
+        assert d_auto.tags.count() == 1
+        assert d_first.tags.first() == tag_first
+        assert d_second.tags.first() == tag_second
 
-        self.assertEqual(d_first.tags.first(), self.tag_first)
-        self.assertEqual(d_second.tags.first(), self.tag_second)
-
-    def test_add_type(self) -> None:
-        call_command("document_retagger", "--document_type")
-        d_first, d_second, _, _ = self.get_updated_docs()
-
-        self.assertEqual(d_first.document_type, self.doctype_first)
-        self.assertEqual(d_second.document_type, self.doctype_second)
-
-    def test_add_correspondent(self) -> None:
-        call_command("document_retagger", "--correspondent")
-        d_first, d_second, _, _ = self.get_updated_docs()
-
-        self.assertEqual(d_first.correspondent, self.correspondent_first)
-        self.assertEqual(d_second.correspondent, self.correspondent_second)
-
-    def test_overwrite_preserve_inbox(self) -> None:
-        self.d1.tags.add(self.tag_second)
+    def test_overwrite_removes_stale_tags_and_preserves_inbox(
+        self,
+        documents: DocumentTuple,
+        tags: TagTuple,
+    ) -> None:
+        d1, *_ = documents
+        tag_first, tag_second, tag_inbox, tag_no_match, _ = tags
+        d1.tags.add(tag_second)
 
         call_command("document_retagger", "--tags", "--overwrite")
 
-        d_first, d_second, d_unrelated, d_auto = self.get_updated_docs()
+        d_first, d_second, d_unrelated, d_auto = _get_docs()
 
-        self.assertIsNotNone(Tag.objects.get(id=self.tag_second.id))
+        assert Tag.objects.filter(id=tag_second.id).exists()
+        assert list(d_first.tags.values_list("id", flat=True)) == [tag_first.id]
+        assert list(d_second.tags.values_list("id", flat=True)) == [tag_second.id]
+        assert set(d_unrelated.tags.values_list("id", flat=True)) == {
+            tag_inbox.id,
+            tag_no_match.id,
+        }
+        assert d_auto.tags.count() == 0
 
-        self.assertCountEqual(
-            [tag.id for tag in d_first.tags.all()],
-            [self.tag_first.id],
+    @pytest.mark.usefixtures("documents")
+    @pytest.mark.parametrize(
+        "extra_args",
+        [
+            pytest.param([], id="no_base_url"),
+            pytest.param(["--base-url=http://localhost"], id="with_base_url"),
+        ],
+    )
+    def test_suggest_does_not_apply_tags(self, extra_args: list[str]) -> None:
+        call_command("document_retagger", "--tags", "--suggest", *extra_args)
+        d_first, d_second, _, d_auto = _get_docs()
+
+        assert d_first.tags.count() == 0
+        assert d_second.tags.count() == 0
+        assert d_auto.tags.count() == 1
+
+
+# ---------------------------------------------------------------------------
+# Document type assignment
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.management
+@pytest.mark.django_db
+class TestRetaggerDocumentType(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    def test_add_type(self, document_types: DocumentTypeTuple) -> None:
+        dt_first, dt_second = document_types
+        call_command("document_retagger", "--document_type")
+        d_first, d_second, _, _ = _get_docs()
+
+        assert d_first.document_type == dt_first
+        assert d_second.document_type == dt_second
+
+    @pytest.mark.usefixtures("documents", "document_types")
+    @pytest.mark.parametrize(
+        "extra_args",
+        [
+            pytest.param([], id="no_base_url"),
+            pytest.param(["--base-url=http://localhost"], id="with_base_url"),
+        ],
+    )
+    def test_suggest_does_not_apply_document_type(self, extra_args: list[str]) -> None:
+        call_command("document_retagger", "--document_type", "--suggest", *extra_args)
+        d_first, d_second, _, _ = _get_docs()
+
+        assert d_first.document_type is None
+        assert d_second.document_type is None
+
+    @pytest.mark.parametrize(
+        ("use_first_flag", "expects_assignment"),
+        [
+            pytest.param(["--use-first"], True, id="use_first_assigns_first_match"),
+            pytest.param([], False, id="no_use_first_skips_ambiguous_match"),
+        ],
+    )
+    def test_use_first_with_multiple_matches(
+        self,
+        use_first_flag: list[str],
+        *,
+        expects_assignment: bool,
+    ) -> None:
+        DocumentTypeFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
         )
-        self.assertCountEqual(
-            [tag.id for tag in d_second.tags.all()],
-            [self.tag_second.id],
+        DocumentTypeFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
         )
-        self.assertCountEqual(
-            [tag.id for tag in d_unrelated.tags.all()],
-            [self.tag_inbox.id, self.tag_no_match.id],
+        doc = DocumentFactory(content="ambiguous content")
+
+        call_command("document_retagger", "--document_type", *use_first_flag)
+
+        doc.refresh_from_db()
+        assert (doc.document_type is not None) is expects_assignment
+
+
+# ---------------------------------------------------------------------------
+# Correspondent assignment
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.management
+@pytest.mark.django_db
+class TestRetaggerCorrespondent(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    def test_add_correspondent(self, correspondents: CorrespondentTuple) -> None:
+        c_first, c_second = correspondents
+        call_command("document_retagger", "--correspondent")
+        d_first, d_second, _, _ = _get_docs()
+
+        assert d_first.correspondent == c_first
+        assert d_second.correspondent == c_second
+
+    @pytest.mark.usefixtures("documents", "correspondents")
+    @pytest.mark.parametrize(
+        "extra_args",
+        [
+            pytest.param([], id="no_base_url"),
+            pytest.param(["--base-url=http://localhost"], id="with_base_url"),
+        ],
+    )
+    def test_suggest_does_not_apply_correspondent(self, extra_args: list[str]) -> None:
+        call_command("document_retagger", "--correspondent", "--suggest", *extra_args)
+        d_first, d_second, _, _ = _get_docs()
+
+        assert d_first.correspondent is None
+        assert d_second.correspondent is None
+
+    @pytest.mark.parametrize(
+        ("use_first_flag", "expects_assignment"),
+        [
+            pytest.param(["--use-first"], True, id="use_first_assigns_first_match"),
+            pytest.param([], False, id="no_use_first_skips_ambiguous_match"),
+        ],
+    )
+    def test_use_first_with_multiple_matches(
+        self,
+        use_first_flag: list[str],
+        *,
+        expects_assignment: bool,
+    ) -> None:
+        CorrespondentFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
         )
-        self.assertEqual(d_auto.tags.count(), 0)
-
-    def test_add_tags_suggest(self) -> None:
-        call_command("document_retagger", "--tags", "--suggest")
-        d_first, d_second, _, d_auto = self.get_updated_docs()
-
-        self.assertEqual(d_first.tags.count(), 0)
-        self.assertEqual(d_second.tags.count(), 0)
-        self.assertEqual(d_auto.tags.count(), 1)
-
-    def test_add_type_suggest(self) -> None:
-        call_command("document_retagger", "--document_type", "--suggest")
-        d_first, d_second, _, _ = self.get_updated_docs()
-
-        self.assertIsNone(d_first.document_type)
-        self.assertIsNone(d_second.document_type)
-
-    def test_add_correspondent_suggest(self) -> None:
-        call_command("document_retagger", "--correspondent", "--suggest")
-        d_first, d_second, _, _ = self.get_updated_docs()
-
-        self.assertIsNone(d_first.correspondent)
-        self.assertIsNone(d_second.correspondent)
-
-    def test_add_tags_suggest_url(self) -> None:
-        call_command(
-            "document_retagger",
-            "--tags",
-            "--suggest",
-            "--base-url=http://localhost",
+        CorrespondentFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
         )
-        d_first, d_second, _, d_auto = self.get_updated_docs()
+        doc = DocumentFactory(content="ambiguous content")
 
-        self.assertEqual(d_first.tags.count(), 0)
-        self.assertEqual(d_second.tags.count(), 0)
-        self.assertEqual(d_auto.tags.count(), 1)
+        call_command("document_retagger", "--correspondent", *use_first_flag)
 
-    def test_add_type_suggest_url(self) -> None:
-        call_command(
-            "document_retagger",
-            "--document_type",
-            "--suggest",
-            "--base-url=http://localhost",
-        )
-        d_first, d_second, _, _ = self.get_updated_docs()
+        doc.refresh_from_db()
+        assert (doc.correspondent is not None) is expects_assignment
 
-        self.assertIsNone(d_first.document_type)
-        self.assertIsNone(d_second.document_type)
 
-    def test_add_correspondent_suggest_url(self) -> None:
-        call_command(
-            "document_retagger",
-            "--correspondent",
-            "--suggest",
-            "--base-url=http://localhost",
-        )
-        d_first, d_second, _, _ = self.get_updated_docs()
+# ---------------------------------------------------------------------------
+# Storage path assignment
+# ---------------------------------------------------------------------------
 
-        self.assertIsNone(d_first.correspondent)
-        self.assertIsNone(d_second.correspondent)
 
-    def test_add_storage_path(self) -> None:
+@pytest.mark.management
+@pytest.mark.django_db
+class TestRetaggerStoragePath(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    def test_add_storage_path(self, storage_paths: StoragePathTuple) -> None:
         """
-        GIVEN:
-            - 2 storage paths with documents which match them
-            - 1 document which matches but has a storage path
-        WHEN:
-            - document retagger is called
-        THEN:
-            - Matching document's storage paths updated
-            - Non-matching documents have no storage path
-            - Existing storage patch left unchanged
+        GIVEN documents matching various storage path rules
+        WHEN document_retagger --storage_path is called
+        THEN matching documents get the correct path; existing path is unchanged
         """
-        call_command(
-            "document_retagger",
-            "--storage_path",
-        )
-        d_first, d_second, d_unrelated, d_auto = self.get_updated_docs()
+        sp1, sp2, sp3 = storage_paths
+        call_command("document_retagger", "--storage_path")
+        d_first, d_second, d_unrelated, d_auto = _get_docs()
 
-        self.assertEqual(d_first.storage_path, self.sp2)
-        self.assertEqual(d_auto.storage_path, self.sp1)
-        self.assertIsNone(d_second.storage_path)
-        self.assertEqual(d_unrelated.storage_path, self.sp3)
+        assert d_first.storage_path == sp2
+        assert d_auto.storage_path == sp1
+        assert d_second.storage_path is None
+        assert d_unrelated.storage_path == sp3
 
-    def test_overwrite_storage_path(self) -> None:
+    @pytest.mark.usefixtures("documents")
+    def test_overwrite_storage_path(self, storage_paths: StoragePathTuple) -> None:
         """
-        GIVEN:
-            - 2 storage paths with documents which match them
-            - 1 document which matches but has a storage path
-        WHEN:
-            - document retagger is called with overwrite
-        THEN:
-            - Matching document's storage paths updated
-            - Non-matching documents have no storage path
-            - Existing storage patch overwritten
+        GIVEN a document with an existing storage path that matches a different rule
+        WHEN document_retagger --storage_path --overwrite is called
+        THEN the existing path is replaced by the newly matched path
         """
+        sp1, sp2, _ = storage_paths
         call_command("document_retagger", "--storage_path", "--overwrite")
-        d_first, d_second, d_unrelated, d_auto = self.get_updated_docs()
+        d_first, d_second, d_unrelated, d_auto = _get_docs()
 
-        self.assertEqual(d_first.storage_path, self.sp2)
-        self.assertEqual(d_auto.storage_path, self.sp1)
-        self.assertIsNone(d_second.storage_path)
-        self.assertEqual(d_unrelated.storage_path, self.sp2)
+        assert d_first.storage_path == sp2
+        assert d_auto.storage_path == sp1
+        assert d_second.storage_path is None
+        assert d_unrelated.storage_path == sp2
 
-    def test_id_range_parameter(self) -> None:
-        commandOutput = ""
-        Document.objects.create(
-            checksum="E",
-            title="E",
-            content="NOT the first document",
+    @pytest.mark.parametrize(
+        ("use_first_flag", "expects_assignment"),
+        [
+            pytest.param(["--use-first"], True, id="use_first_assigns_first_match"),
+            pytest.param([], False, id="no_use_first_skips_ambiguous_match"),
+        ],
+    )
+    def test_use_first_with_multiple_matches(
+        self,
+        use_first_flag: list[str],
+        *,
+        expects_assignment: bool,
+    ) -> None:
+        StoragePathFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
         )
-        call_command("document_retagger", "--tags", "--id-range", "1", "2")
-        # The retagger shouldn`t apply the 'first' tag to our new document
-        self.assertEqual(Document.objects.filter(tags__id=self.tag_first.id).count(), 1)
+        StoragePathFactory(
+            match="ambiguous",
+            matching_algorithm=MatchingModel.MATCH_ANY,
+        )
+        doc = DocumentFactory(content="ambiguous content")
 
-        try:
-            commandOutput = call_command("document_retagger", "--tags", "--id-range")
-        except CommandError:
-            # Just ignore the error
-            None
-        self.assertIn(commandOutput, "Error: argument --id-range: expected 2 arguments")
+        call_command("document_retagger", "--storage_path", *use_first_flag)
 
-        try:
-            commandOutput = call_command(
-                "document_retagger",
-                "--tags",
-                "--id-range",
-                "a",
-                "b",
-            )
-        except CommandError:
-            # Just ignore the error
-            None
-        self.assertIn(commandOutput, "error: argument --id-range: invalid int value:")
+        doc.refresh_from_db()
+        assert (doc.storage_path is not None) is expects_assignment
 
-        call_command("document_retagger", "--tags", "--id-range", "1", "9999")
-        # Now we should have 2 documents
-        self.assertEqual(Document.objects.filter(tags__id=self.tag_first.id).count(), 2)
+
+# ---------------------------------------------------------------------------
+# ID range filtering
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.management
+@pytest.mark.django_db
+class TestRetaggerIdRange(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    @pytest.mark.parametrize(
+        ("id_range_args", "expected_count"),
+        [
+            pytest.param(["1", "2"], 1, id="narrow_range_limits_scope"),
+            pytest.param(["1", "9999"], 2, id="wide_range_tags_all_matches"),
+        ],
+    )
+    def test_id_range_limits_scope(
+        self,
+        tags: TagTuple,
+        id_range_args: list[str],
+        expected_count: int,
+    ) -> None:
+        DocumentFactory(content="NOT the first document")
+        call_command("document_retagger", "--tags", "--id-range", *id_range_args)
+        tag_first, *_ = tags
+        assert Document.objects.filter(tags__id=tag_first.id).count() == expected_count
+
+    @pytest.mark.usefixtures("documents")
+    @pytest.mark.parametrize(
+        "args",
+        [
+            pytest.param(["--tags", "--id-range"], id="missing_both_values"),
+            pytest.param(["--tags", "--id-range", "a", "b"], id="non_integer_values"),
+        ],
+    )
+    def test_id_range_invalid_arguments_raise(self, args: list[str]) -> None:
+        with pytest.raises((CommandError, SystemExit)):
+            call_command("document_retagger", *args)
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.management
+@pytest.mark.django_db
+class TestRetaggerEdgeCases(DirectoriesMixin):
+    @pytest.mark.usefixtures("documents")
+    def test_no_targets_exits_cleanly(self) -> None:
+        """Calling the retagger with no classifier targets should not raise."""
+        call_command("document_retagger")
+
+    @pytest.mark.usefixtures("documents")
+    def test_inbox_only_skips_non_inbox_documents(self) -> None:
+        """--inbox-only must restrict processing to documents with an inbox tag."""
+        call_command("document_retagger", "--tags", "--inbox-only")
+        d_first, _, d_unrelated, _ = _get_docs()
+
+        assert d_first.tags.count() == 0
+        assert d_unrelated.tags.count() == 2

src/documents/tests/test_sanity_check.py

@@ -1,192 +1,295 @@
-import logging
-import shutil
-from pathlib import Path
+"""Tests for the sanity checker module.
 
-import filelock
-from django.conf import settings
-from django.test import TestCase
-from django.test import override_settings
+Tests exercise ``check_sanity`` as a whole, verifying document validation,
+orphan detection, task recording, and the iter_wrapper contract.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
 
 from documents.models import Document
+from documents.models import PaperlessTask
 from documents.sanity_checker import check_sanity
-from documents.tests.utils import DirectoriesMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from documents.tests.conftest import PaperlessDirs
 
 
-class TestSanityCheck(DirectoriesMixin, TestCase):
-    def make_test_data(self):
-        with filelock.FileLock(settings.MEDIA_LOCK):
-            # just make sure that the lockfile is present.
-            shutil.copy(
-                (
-                    Path(__file__).parent
-                    / "samples"
-                    / "documents"
-                    / "originals"
-                    / "0000001.pdf"
-                ),
-                Path(self.dirs.originals_dir) / "0000001.pdf",
-            )
-            shutil.copy(
-                (
-                    Path(__file__).parent
-                    / "samples"
-                    / "documents"
-                    / "archive"
-                    / "0000001.pdf"
-                ),
-                Path(self.dirs.archive_dir) / "0000001.pdf",
-            )
-            shutil.copy(
-                (
-                    Path(__file__).parent
-                    / "samples"
-                    / "documents"
-                    / "thumbnails"
-                    / "0000001.webp"
-                ),
-                Path(self.dirs.thumbnail_dir) / "0000001.webp",
-            )
+@pytest.mark.django_db
+class TestCheckSanityNoDocuments:
+    """Sanity checks against an empty archive."""
 
-        return Document.objects.create(
-            title="test",
-            checksum="42995833e01aea9b3edee44bbfdd7ce1",
-            archive_checksum="62acb0bcbfbcaa62ca6ad3668e4e404b",
-            content="test",
-            pk=1,
-            filename="0000001.pdf",
-            mime_type="application/pdf",
-            archive_filename="0000001.pdf",
-        )
-
-    def assertSanityError(self, doc: Document, messageRegex) -> None:
+    @pytest.mark.usefixtures("_media_settings")
+    def test_no_documents(self) -> None:
         messages = check_sanity()
-        self.assertTrue(messages.has_error)
-        with self.assertLogs() as capture:
+        assert not messages.has_error
+        assert not messages.has_warning
+        assert messages.total_issue_count == 0
+
+    @pytest.mark.usefixtures("_media_settings")
+    def test_no_issues_logs_clean(self, caplog: pytest.LogCaptureFixture) -> None:
+        messages = check_sanity()
+        with caplog.at_level(logging.INFO, logger="paperless.sanity_checker"):
             messages.log_messages()
-            self.assertEqual(
-                capture.records[0].message,
-                f"Detected following issue(s) with document #{doc.pk}, titled {doc.title}",
-            )
-            self.assertRegex(capture.records[1].message, messageRegex)
+        assert "Sanity checker detected no issues." in caplog.text
 
-    def test_no_issues(self) -> None:
-        self.make_test_data()
+
+@pytest.mark.django_db
+class TestCheckSanityHealthyDocument:
+    def test_no_errors(self, sample_doc: Document) -> None:
         messages = check_sanity()
-        self.assertFalse(messages.has_error)
-        self.assertFalse(messages.has_warning)
-        with self.assertLogs() as capture:
-            messages.log_messages()
-            self.assertEqual(len(capture.output), 1)
-            self.assertEqual(capture.records[0].levelno, logging.INFO)
-            self.assertEqual(
-                capture.records[0].message,
-                "Sanity checker detected no issues.",
-            )
+        assert not messages.has_error
+        assert not messages.has_warning
+        assert messages.total_issue_count == 0
 
-    def test_no_docs(self) -> None:
-        self.assertEqual(len(check_sanity()), 0)
 
-    def test_success(self) -> None:
-        self.make_test_data()
-        self.assertEqual(len(check_sanity()), 0)
-
-    def test_no_thumbnail(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.thumbnail_path).unlink()
-        self.assertSanityError(doc, "Thumbnail of document does not exist")
-
-    def test_thumbnail_no_access(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.thumbnail_path).chmod(0o000)
-        self.assertSanityError(doc, "Cannot read thumbnail file of document")
-        Path(doc.thumbnail_path).chmod(0o777)
-
-    def test_no_original(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.source_path).unlink()
-        self.assertSanityError(doc, "Original of document does not exist.")
-
-    def test_original_no_access(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.source_path).chmod(0o000)
-        self.assertSanityError(doc, "Cannot read original file of document")
-        Path(doc.source_path).chmod(0o777)
-
-    def test_original_checksum_mismatch(self) -> None:
-        doc = self.make_test_data()
-        doc.checksum = "WOW"
-        doc.save()
-        self.assertSanityError(doc, "Checksum mismatch. Stored: WOW, actual: ")
-
-    def test_no_archive(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.archive_path).unlink()
-        self.assertSanityError(doc, "Archived version of document does not exist.")
-
-    def test_archive_no_access(self) -> None:
-        doc = self.make_test_data()
-        Path(doc.archive_path).chmod(0o000)
-        self.assertSanityError(doc, "Cannot read archive file of document")
-        Path(doc.archive_path).chmod(0o777)
-
-    def test_archive_checksum_mismatch(self) -> None:
-        doc = self.make_test_data()
-        doc.archive_checksum = "WOW"
-        doc.save()
-        self.assertSanityError(doc, "Checksum mismatch of archived document")
-
-    def test_empty_content(self) -> None:
-        doc = self.make_test_data()
-        doc.content = ""
-        doc.save()
+@pytest.mark.django_db
+class TestCheckSanityThumbnail:
+    def test_missing(self, sample_doc: Document) -> None:
+        Path(sample_doc.thumbnail_path).unlink()
         messages = check_sanity()
-        self.assertFalse(messages.has_error)
-        self.assertFalse(messages.has_warning)
-        self.assertEqual(len(messages), 1)
-        self.assertRegex(
-            messages[doc.pk][0]["message"],
-            "Document contains no OCR data",
+        assert messages.has_error
+        assert any(
+            "Thumbnail of document does not exist" in m["message"]
+            for m in messages[sample_doc.pk]
         )
 
-    def test_orphaned_file(self) -> None:
-        self.make_test_data()
-        Path(self.dirs.originals_dir, "orphaned").touch()
+    def test_unreadable(self, sample_doc: Document) -> None:
+        thumb = Path(sample_doc.thumbnail_path)
+        thumb.chmod(0o000)
+        try:
+            messages = check_sanity()
+            assert messages.has_error
+            assert any(
+                "Cannot read thumbnail" in m["message"] for m in messages[sample_doc.pk]
+            )
+        finally:
+            thumb.chmod(0o644)
+
+
+@pytest.mark.django_db
+class TestCheckSanityOriginal:
+    def test_missing(self, sample_doc: Document) -> None:
+        Path(sample_doc.source_path).unlink()
         messages = check_sanity()
-        self.assertTrue(messages.has_warning)
-        self.assertRegex(
-            messages._messages[None][0]["message"],
-            "Orphaned file in media dir",
+        assert messages.has_error
+        assert any(
+            "Original of document does not exist" in m["message"]
+            for m in messages[sample_doc.pk]
         )
 
-    @override_settings(
-        APP_LOGO="logo/logo.png",
+    def test_checksum_mismatch(self, sample_doc: Document) -> None:
+        sample_doc.checksum = "badhash"
+        sample_doc.save()
+        messages = check_sanity()
+        assert messages.has_error
+        assert any(
+            "Checksum mismatch" in m["message"] and "badhash" in m["message"]
+            for m in messages[sample_doc.pk]
+        )
+
+    def test_unreadable(self, sample_doc: Document) -> None:
+        src = Path(sample_doc.source_path)
+        src.chmod(0o000)
+        try:
+            messages = check_sanity()
+            assert messages.has_error
+            assert any(
+                "Cannot read original" in m["message"] for m in messages[sample_doc.pk]
+            )
+        finally:
+            src.chmod(0o644)
+
+
+@pytest.mark.django_db
+class TestCheckSanityArchive:
+    def test_checksum_without_filename(self, sample_doc: Document) -> None:
+        sample_doc.archive_filename = None
+        sample_doc.save()
+        messages = check_sanity()
+        assert messages.has_error
+        assert any(
+            "checksum, but no archive filename" in m["message"]
+            for m in messages[sample_doc.pk]
+        )
+
+    def test_filename_without_checksum(self, sample_doc: Document) -> None:
+        sample_doc.archive_checksum = None
+        sample_doc.save()
+        messages = check_sanity()
+        assert messages.has_error
+        assert any(
+            "checksum is missing" in m["message"] for m in messages[sample_doc.pk]
+        )
+
+    def test_missing_file(self, sample_doc: Document) -> None:
+        Path(sample_doc.archive_path).unlink()
+        messages = check_sanity()
+        assert messages.has_error
+        assert any(
+            "Archived version of document does not exist" in m["message"]
+            for m in messages[sample_doc.pk]
+        )
+
+    def test_checksum_mismatch(self, sample_doc: Document) -> None:
+        sample_doc.archive_checksum = "wronghash"
+        sample_doc.save()
+        messages = check_sanity()
+        assert messages.has_error
+        assert any(
+            "Checksum mismatch of archived document" in m["message"]
+            for m in messages[sample_doc.pk]
+        )
+
+    def test_unreadable(self, sample_doc: Document) -> None:
+        archive = Path(sample_doc.archive_path)
+        archive.chmod(0o000)
+        try:
+            messages = check_sanity()
+            assert messages.has_error
+            assert any(
+                "Cannot read archive" in m["message"] for m in messages[sample_doc.pk]
+            )
+        finally:
+            archive.chmod(0o644)
+
+    def test_no_archive_at_all(self, sample_doc: Document) -> None:
+        """Document with neither archive checksum nor filename is valid."""
+        Path(sample_doc.archive_path).unlink()
+        sample_doc.archive_checksum = None
+        sample_doc.archive_filename = None
+        sample_doc.save()
+        messages = check_sanity()
+        assert not messages.has_error
+
+
+@pytest.mark.django_db
+class TestCheckSanityContent:
+    @pytest.mark.parametrize(
+        "content",
+        [
+            pytest.param("", id="empty-string"),
+        ],
     )
-    def test_ignore_logo(self) -> None:
-        self.make_test_data()
-        logo_dir = Path(self.dirs.media_dir, "logo")
-        logo_dir.mkdir(parents=True, exist_ok=True)
-        Path(self.dirs.media_dir, "logo", "logo.png").touch()
+    def test_no_content(self, sample_doc: Document, content: str) -> None:
+        sample_doc.content = content
+        sample_doc.save()
         messages = check_sanity()
-        self.assertFalse(messages.has_warning)
+        assert not messages.has_error
+        assert not messages.has_warning
+        assert any("no OCR data" in m["message"] for m in messages[sample_doc.pk])
 
-    def test_ignore_ignorable_files(self) -> None:
-        self.make_test_data()
-        Path(self.dirs.media_dir, ".DS_Store").touch()
-        Path(self.dirs.media_dir, "desktop.ini").touch()
+
+@pytest.mark.django_db
+class TestCheckSanityOrphans:
+    def test_orphaned_file(
+        self,
+        sample_doc: Document,
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
+        (paperless_dirs.originals / "orphan.pdf").touch()
         messages = check_sanity()
-        self.assertFalse(messages.has_warning)
+        assert messages.has_warning
+        assert any("Orphaned file" in m["message"] for m in messages[None])
 
-    def test_archive_filename_no_checksum(self) -> None:
-        doc = self.make_test_data()
-        doc.archive_checksum = None
-        doc.save()
-        self.assertSanityError(doc, "has an archive file, but its checksum is missing.")
+    @pytest.mark.usefixtures("_media_settings")
+    def test_ignorable_files_not_flagged(
+        self,
+        paperless_dirs: PaperlessDirs,
+    ) -> None:
+        (paperless_dirs.media / ".DS_Store").touch()
+        (paperless_dirs.media / "desktop.ini").touch()
+        messages = check_sanity()
+        assert not messages.has_warning
 
-    def test_archive_checksum_no_filename(self) -> None:
-        doc = self.make_test_data()
-        doc.archive_filename = None
-        doc.save()
-        self.assertSanityError(
-            doc,
-            "has an archive file checksum, but no archive filename.",
-        )
+
+@pytest.mark.django_db
+class TestCheckSanityIterWrapper:
+    def test_wrapper_receives_documents(self, sample_doc: Document) -> None:
+        seen: list[Document] = []
+
+        def tracking(iterable: Iterable[Document]) -> Iterable[Document]:
+            for item in iterable:
+                seen.append(item)
+                yield item
+
+        check_sanity(iter_wrapper=tracking)
+        assert len(seen) == 1
+        assert seen[0].pk == sample_doc.pk
+
+    def test_default_works_without_wrapper(self, sample_doc: Document) -> None:
+        messages = check_sanity()
+        assert not messages.has_error
+
+
+@pytest.mark.django_db
+class TestCheckSanityTaskRecording:
+    @pytest.mark.parametrize(
+        ("expected_type", "scheduled"),
+        [
+            pytest.param(PaperlessTask.TaskType.SCHEDULED_TASK, True, id="scheduled"),
+            pytest.param(PaperlessTask.TaskType.MANUAL_TASK, False, id="manual"),
+        ],
+    )
+    @pytest.mark.usefixtures("_media_settings")
+    def test_task_type(self, expected_type: str, *, scheduled: bool) -> None:
+        check_sanity(scheduled=scheduled)
+        task = PaperlessTask.objects.latest("date_created")
+        assert task.task_name == PaperlessTask.TaskName.CHECK_SANITY
+        assert task.type == expected_type
+
+    def test_success_status(self, sample_doc: Document) -> None:
+        check_sanity()
+        task = PaperlessTask.objects.latest("date_created")
+        assert task.status == "SUCCESS"
+
+    def test_failure_status(self, sample_doc: Document) -> None:
+        Path(sample_doc.source_path).unlink()
+        check_sanity()
+        task = PaperlessTask.objects.latest("date_created")
+        assert task.status == "FAILURE"
+        assert "Check logs for details" in task.result
+
+
+@pytest.mark.django_db
+class TestCheckSanityLogMessages:
+    def test_logs_doc_issues(
+        self,
+        sample_doc: Document,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        Path(sample_doc.source_path).unlink()
+        messages = check_sanity()
+        with caplog.at_level(logging.INFO, logger="paperless.sanity_checker"):
+            messages.log_messages()
+        assert f"document #{sample_doc.pk}" in caplog.text
+        assert "Original of document does not exist" in caplog.text
+
+    def test_logs_global_issues(
+        self,
+        sample_doc: Document,
+        paperless_dirs: PaperlessDirs,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        (paperless_dirs.originals / "orphan.pdf").touch()
+        messages = check_sanity()
+        with caplog.at_level(logging.WARNING, logger="paperless.sanity_checker"):
+            messages.log_messages()
+        assert "Orphaned file" in caplog.text
+
+    @pytest.mark.usefixtures("_media_settings")
+    def test_logs_unknown_doc_pk(self, caplog: pytest.LogCaptureFixture) -> None:
+        """A doc PK not in the DB logs 'Unknown' as the title."""
+        messages = check_sanity()
+        messages.error(99999, "Ghost document")
+        with caplog.at_level(logging.INFO, logger="paperless.sanity_checker"):
+            messages.log_messages()
+        assert "#99999" in caplog.text
+        assert "Unknown" in caplog.text

src/documents/tests/test_tasks.py

@@ -3,6 +3,7 @@ from datetime import timedelta
 from pathlib import Path
 from unittest import mock
 
+import pytest
 from celery import states
 from django.conf import settings
 from django.test import TestCase
@@ -105,55 +106,83 @@ class TestClassifier(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
             self.assertNotEqual(mtime2, mtime3)
 
 
-class TestSanityCheck(DirectoriesMixin, TestCase):
-    @mock.patch("documents.tasks.sanity_checker.check_sanity")
-    def test_sanity_check_success(self, m) -> None:
-        m.return_value = SanityCheckMessages()
-        self.assertEqual(tasks.sanity_check(), "No issues detected.")
-        m.assert_called_once()
+@pytest.mark.django_db
+class TestSanityCheck:
+    @pytest.fixture
+    def mock_check_sanity(self, mocker) -> mock.MagicMock:
+        return mocker.patch("documents.tasks.sanity_checker.check_sanity")
 
-    @mock.patch("documents.tasks.sanity_checker.check_sanity")
-    def test_sanity_check_error(self, m) -> None:
-        messages = SanityCheckMessages()
-        messages.error(None, "Some error")
-        m.return_value = messages
-        self.assertRaises(SanityCheckFailedException, tasks.sanity_check)
-        m.assert_called_once()
+    def test_sanity_check_success(self, mock_check_sanity: mock.MagicMock) -> None:
+        mock_check_sanity.return_value = SanityCheckMessages()
+        assert tasks.sanity_check() == "No issues detected."
+        mock_check_sanity.assert_called_once()
 
-    @mock.patch("documents.tasks.sanity_checker.check_sanity")
-    def test_sanity_check_error_no_raise(self, m) -> None:
+    def test_sanity_check_error_raises(
+        self,
+        mock_check_sanity: mock.MagicMock,
+        sample_doc: Document,
+    ) -> None:
         messages = SanityCheckMessages()
-        messages.error(None, "Some error")
-        m.return_value = messages
-        # No exception should be raised
+        messages.error(sample_doc.pk, "some error")
+        mock_check_sanity.return_value = messages
+        with pytest.raises(SanityCheckFailedException):
+            tasks.sanity_check()
+        mock_check_sanity.assert_called_once()
+
+    def test_sanity_check_error_no_raise(
+        self,
+        mock_check_sanity: mock.MagicMock,
+        sample_doc: Document,
+    ) -> None:
+        messages = SanityCheckMessages()
+        messages.error(sample_doc.pk, "some error")
+        mock_check_sanity.return_value = messages
         result = tasks.sanity_check(raise_on_error=False)
-        self.assertEqual(
-            result,
-            "Sanity check exited with errors. See log.",
-        )
-        m.assert_called_once()
+        assert "1 document(s) with errors" in result
+        assert "Check logs for details." in result
+        mock_check_sanity.assert_called_once()
 
-    @mock.patch("documents.tasks.sanity_checker.check_sanity")
-    def test_sanity_check_warning(self, m) -> None:
+    def test_sanity_check_warning_only(
+        self,
+        mock_check_sanity: mock.MagicMock,
+    ) -> None:
         messages = SanityCheckMessages()
-        messages.warning(None, "Some warning")
-        m.return_value = messages
-        self.assertEqual(
-            tasks.sanity_check(),
-            "Sanity check exited with warnings. See log.",
-        )
-        m.assert_called_once()
+        messages.warning(None, "extra file")
+        mock_check_sanity.return_value = messages
+        result = tasks.sanity_check()
+        assert result == "1 global warning(s) found."
+        mock_check_sanity.assert_called_once()
 
-    @mock.patch("documents.tasks.sanity_checker.check_sanity")
-    def test_sanity_check_info(self, m) -> None:
+    def test_sanity_check_info_only(
+        self,
+        mock_check_sanity: mock.MagicMock,
+        sample_doc: Document,
+    ) -> None:
         messages = SanityCheckMessages()
-        messages.info(None, "Some info")
-        m.return_value = messages
-        self.assertEqual(
-            tasks.sanity_check(),
-            "Sanity check exited with infos. See log.",
-        )
-        m.assert_called_once()
+        messages.info(sample_doc.pk, "some info")
+        mock_check_sanity.return_value = messages
+        result = tasks.sanity_check()
+        assert result == "1 document(s) with infos found."
+        mock_check_sanity.assert_called_once()
+
+    def test_sanity_check_errors_warnings_and_infos(
+        self,
+        mock_check_sanity: mock.MagicMock,
+        sample_doc: Document,
+    ) -> None:
+        messages = SanityCheckMessages()
+        messages.error(sample_doc.pk, "broken")
+        messages.warning(sample_doc.pk, "odd")
+        messages.info(sample_doc.pk, "fyi")
+        messages.warning(None, "extra file")
+        mock_check_sanity.return_value = messages
+        result = tasks.sanity_check(raise_on_error=False)
+        assert "1 document(s) with errors" in result
+        assert "1 document(s) with warnings" in result
+        assert "1 document(s) with infos" in result
+        assert "1 global warning(s)" in result
+        assert "Check logs for details." in result
+        mock_check_sanity.assert_called_once()
 
 
 class TestBulkUpdate(DirectoriesMixin, TestCase):

src/documents/tests/test_workflows.py

@@ -951,38 +951,6 @@ class TestWorkflows(
         self.assertEqual(doc.correspondent, self.c2)
         self.assertEqual(doc.title, f"Doc created in {created.year}")
 
-    def test_document_updated_workflow_version_index_placeholder(self) -> None:
-        trigger = WorkflowTrigger.objects.create(
-            type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED,
-        )
-        action = WorkflowAction.objects.create(
-            assign_title="Version {{ version_index }}",
-        )
-        workflow = Workflow.objects.create(
-            name="Workflow version index",
-            order=0,
-        )
-        workflow.triggers.add(trigger)
-        workflow.actions.add(action)
-        workflow.save()
-
-        root = Document.objects.create(
-            title="root",
-            checksum="cccccccccccccccccccccccccccccccc",
-            mime_type="application/pdf",
-        )
-        version = Document.objects.create(
-            title="v1",
-            checksum="dddddddddddddddddddddddddddddddd",
-            mime_type="application/pdf",
-            root_document=root,
-        )
-
-        run_workflows(WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED, version)
-        version.refresh_from_db()
-
-        self.assertEqual(version.title, "Version 1")
-
     def test_document_added_no_match_filename(self) -> None:
         trigger = WorkflowTrigger.objects.create(
             type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_ADDED,
@@ -1774,6 +1742,48 @@ class TestWorkflows(
 
         self.assertEqual(doc.title, "Doc {created_year]")
 
+    def test_document_updated_workflow_ignores_version_documents(self) -> None:
+        trigger = WorkflowTrigger.objects.create(
+            type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED,
+        )
+        action = WorkflowAction.objects.create(
+            assign_title="Doc assign owner",
+            assign_owner=self.user2,
+        )
+        workflow = Workflow.objects.create(
+            name="Workflow 1",
+            order=0,
+        )
+        workflow.triggers.add(trigger)
+        workflow.actions.add(action)
+
+        root_doc = Document.objects.create(
+            title="root",
+            correspondent=self.c,
+            original_filename="root.pdf",
+        )
+        version_doc = Document.objects.create(
+            title="version",
+            correspondent=self.c,
+            original_filename="version.pdf",
+            root_document=root_doc,
+        )
+
+        run_workflows(WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED, version_doc)
+
+        root_doc.refresh_from_db()
+        version_doc.refresh_from_db()
+
+        self.assertIsNone(root_doc.owner)
+        self.assertIsNone(version_doc.owner)
+        self.assertFalse(
+            WorkflowRun.objects.filter(
+                workflow=workflow,
+                type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED,
+                document=version_doc,
+            ).exists(),
+        )
+
     def test_document_updated_workflow(self) -> None:
         trigger = WorkflowTrigger.objects.create(
             type=WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED,
@@ -2042,6 +2052,60 @@ class TestWorkflows(
         doc.refresh_from_db()
         self.assertEqual(doc.owner, self.user2)
 
+    def test_workflow_scheduled_trigger_ignores_version_documents(self) -> None:
+        trigger = WorkflowTrigger.objects.create(
+            type=WorkflowTrigger.WorkflowTriggerType.SCHEDULED,
+            schedule_offset_days=1,
+            schedule_date_field=WorkflowTrigger.ScheduleDateField.ADDED,
+        )
+        action = WorkflowAction.objects.create(
+            assign_title="Doc assign owner",
+            assign_owner=self.user2,
+        )
+        workflow = Workflow.objects.create(
+            name="Workflow 1",
+            order=0,
+        )
+        workflow.triggers.add(trigger)
+        workflow.actions.add(action)
+
+        root_doc = Document.objects.create(
+            title="root",
+            correspondent=self.c,
+            original_filename="root.pdf",
+            added=timezone.now() - timedelta(days=10),
+        )
+        version_doc = Document.objects.create(
+            title="version",
+            correspondent=self.c,
+            original_filename="version.pdf",
+            root_document=root_doc,
+            added=timezone.now() - timedelta(days=10),
+        )
+
+        tasks.check_scheduled_workflows()
+
+        root_doc.refresh_from_db()
+        version_doc.refresh_from_db()
+
+        self.assertEqual(root_doc.owner, self.user2)
+        self.assertIsNone(version_doc.owner)
+        self.assertEqual(
+            WorkflowRun.objects.filter(
+                workflow=workflow,
+                type=WorkflowTrigger.WorkflowTriggerType.SCHEDULED,
+                document=root_doc,
+            ).count(),
+            1,
+        )
+        self.assertFalse(
+            WorkflowRun.objects.filter(
+                workflow=workflow,
+                type=WorkflowTrigger.WorkflowTriggerType.SCHEDULED,
+                document=version_doc,
+            ).exists(),
+        )
+
     @mock.patch("documents.models.Document.objects.filter", autospec=True)
     def test_workflow_scheduled_trigger_modified(self, mock_filter) -> None:
         """
@@ -3444,10 +3508,7 @@ class TestWorkflows(
         )
         webhook_action = WorkflowActionWebhook.objects.create(
             use_params=False,
-            body=(
-                "Test message: {{doc_url}} with id {{doc_id}} "
-                "and version {{version_label}}"
-            ),
+            body="Test message: {{doc_url}} with id {{doc_id}}",
             url="http://paperless-ngx.com",
             include_document=False,
         )
@@ -3471,7 +3532,6 @@ class TestWorkflows(
             title="sample test",
             correspondent=self.c,
             original_filename="sample.pdf",
-            version_label="v3",
         )
 
         run_workflows(WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED, doc)
@@ -3480,7 +3540,7 @@ class TestWorkflows(
             url="http://paperless-ngx.com",
             data=(
                 f"Test message: http://localhost:8000/paperless/documents/{doc.id}/"
-                f" with id {doc.id} and version {doc.version_label}"
+                f" with id {doc.id}"
             ),
             headers={},
             files=None,

src/documents/views.py

@@ -1758,6 +1758,11 @@ class DocumentViewSet(
             .order_by("-id")
             .first()
         )
+
+        document_updated.send(
+            sender=self.__class__,
+            document=root_doc,
+        )
         return Response(
             {
                 "result": "OK",
@@ -1827,6 +1832,11 @@ class DocumentViewSet(
                 },
             )
 
+        document_updated.send(
+            sender=self.__class__,
+            document=root_doc,
+        )
+
         return Response(
             {
                 "id": version_doc.id,

src/documents/workflows/actions.py

@@ -6,7 +6,6 @@ from pathlib import Path
 from django.conf import settings
 from django.contrib.auth.models import User
 from django.utils import timezone
-from django.utils.functional import SimpleLazyObject
 
 from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
@@ -25,16 +24,6 @@ from documents.workflows.webhooks import send_webhook
 logger = logging.getLogger("paperless.workflows.actions")
 
 
-def _get_consumable_version_index(document: ConsumableDocument) -> int:
-    if document.root_document_id is None:
-        return 0
-
-    # The document is not yet saved, so use the next index in the version chain.
-    return (
-        Document.objects.filter(root_document_id=document.root_document_id).count() + 1
-    )
-
-
 def build_workflow_action_context(
     document: Document | ConsumableDocument,
     overrides: DocumentMetadataOverrides | None,
@@ -45,11 +34,6 @@ def build_workflow_action_context(
     use_overrides = overrides is not None
 
     if not use_overrides:
-        version_index = (
-            document.version_index
-            if isinstance(document, Document)
-            else _get_consumable_version_index(document)
-        )
         return {
             "title": document.title,
             "doc_url": f"{settings.PAPERLESS_URL}{settings.BASE_URL}documents/{document.pk}/",
@@ -65,8 +49,6 @@ def build_workflow_action_context(
             "added": timezone.localtime(document.added),
             "created": document.created,
             "id": document.pk,
-            "version_label": document.version_label,
-            "version_index": version_index,
         }
 
     correspondent_obj = (
@@ -86,11 +68,6 @@ def build_workflow_action_context(
     )
 
     filename = document.original_file if document.original_file else ""
-    version_index = (
-        SimpleLazyObject(lambda: _get_consumable_version_index(document))
-        if isinstance(document, ConsumableDocument)
-        else SimpleLazyObject(lambda: document.version_index)
-    )
     return {
         "title": overrides.title
         if overrides and overrides.title
@@ -104,8 +81,6 @@ def build_workflow_action_context(
         "added": timezone.localtime(timezone.now()),
         "created": overrides.created if overrides else None,
         "id": "",
-        "version_label": overrides.version_label if overrides else None,
-        "version_index": version_index,
     }
 
 
@@ -141,8 +116,6 @@ def execute_email_action(
             context["title"],
             context["doc_url"],
             context["id"],
-            context["version_label"],
-            context["version_index"],
         )
         if action.email.subject
         else ""
@@ -160,8 +133,6 @@ def execute_email_action(
             context["title"],
             context["doc_url"],
             context["id"],
-            context["version_label"],
-            context["version_index"],
         )
         if action.email.body
         else ""
@@ -241,8 +212,6 @@ def execute_webhook_action(
                             context["title"],
                             context["doc_url"],
                             context["id"],
-                            context["version_label"],
-                            context["version_index"],
                         )
                 except Exception as e:
                     logger.error(
@@ -262,8 +231,6 @@ def execute_webhook_action(
                 context["title"],
                 context["doc_url"],
                 context["id"],
-                context["version_label"],
-                context["version_index"],
             )
         headers = {}
         if action.webhook.headers:

src/documents/workflows/mutations.py

@@ -58,8 +58,6 @@ def apply_assignment_to_document(
                 "",  # dont pass the title to avoid recursion
                 "",  # no urls in titles
                 document.pk,
-                document.version_label,
-                document.version_index,
             )
         except Exception:  # pragma: no cover
             logger.exception(

src/locale/en_US/LC_MESSAGES/django.po

@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: paperless-ngx\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-02-28 10:33+0000\n"
+"POT-Creation-Date: 2026-03-02 16:22+0000\n"
 "PO-Revision-Date: 2022-02-17 04:17\n"
 "Last-Translator: \n"
 "Language-Team: English\n"
@@ -1339,7 +1339,7 @@ msgstr ""
 msgid "Duplicate document identifiers are not allowed."
 msgstr ""
 
-#: documents/serialisers.py:2419 documents/views.py:3317
+#: documents/serialisers.py:2419 documents/views.py:3327
 #, python-format
 msgid "Documents not found: %(ids)s"
 msgstr ""
@@ -1603,20 +1603,20 @@ msgstr ""
 msgid "Unable to parse URI {value}"
 msgstr ""
 
-#: documents/views.py:3329
+#: documents/views.py:3339
 #, python-format
 msgid "Insufficient permissions to share document %(id)s."
 msgstr ""
 
-#: documents/views.py:3372
+#: documents/views.py:3382
 msgid "Bundle is already being processed."
 msgstr ""
 
-#: documents/views.py:3429
+#: documents/views.py:3439
 msgid "The share link bundle is still being prepared. Please try again later."
 msgstr ""
 
-#: documents/views.py:3439
+#: documents/views.py:3449
 msgid "The share link bundle is unavailable."
 msgstr ""
 

src/paperless/checks.py

@@ -204,6 +204,61 @@ def audit_log_check(app_configs, **kwargs):
     return result
 
 
+@register()
+def check_v3_minimum_upgrade_version(
+    app_configs: object,
+    **kwargs: object,
+) -> list[Error]:
+    """Enforce that upgrades to v3 must start from v2.20.9.
+
+    v3 squashes all prior migrations into 0001_squashed and 0002_squashed.
+    If a user skips v2.20.9, the data migration in 1075_workflowaction_order
+    never runs and the squash may apply schema changes against an incomplete
+    database state.
+    """
+    from django.db import DatabaseError
+    from django.db import OperationalError
+
+    try:
+        all_tables = connections["default"].introspection.table_names()
+
+        if "django_migrations" not in all_tables:
+            return []
+
+        with connections["default"].cursor() as cursor:
+            cursor.execute(
+                "SELECT name FROM django_migrations WHERE app = %s",
+                ["documents"],
+            )
+            applied: set[str] = {row[0] for row in cursor.fetchall()}
+
+        if not applied:
+            return []
+
+        # Already in a valid v3 state
+        if {"0001_squashed", "0002_squashed"} & applied:
+            return []
+
+        # On v2.20.9 exactly — squash will pick up cleanly from here
+        if "1075_workflowaction_order" in applied:
+            return []
+
+    except (DatabaseError, OperationalError):
+        return []
+
+    return [
+        Error(
+            "Cannot upgrade to Paperless-ngx v3 from this version.",
+            hint=(
+                "Upgrading to v3 can only be performed from v2.20.9."
+                "Please upgrade to v2.20.9, run migrations, then upgrade to v3."
+                "See https://docs.paperless-ngx.com/setup/#upgrading for details."
+            ),
+            id="paperless.E002",
+        ),
+    ]
+
+
 @register()
 def check_deprecated_db_settings(
     app_configs: object,

src/paperless/tests/test_checks.py

@@ -3,6 +3,7 @@ from pathlib import Path
 from unittest import mock
 
 import pytest
+from django.core.checks import Error
 from django.core.checks import Warning
 from django.test import TestCase
 from django.test import override_settings
@@ -13,6 +14,7 @@ from documents.tests.utils import FileSystemAssertsMixin
 from paperless.checks import audit_log_check
 from paperless.checks import binaries_check
 from paperless.checks import check_deprecated_db_settings
+from paperless.checks import check_v3_minimum_upgrade_version
 from paperless.checks import debug_mode_check
 from paperless.checks import paths_check
 from paperless.checks import settings_values_check
@@ -395,3 +397,240 @@ class TestDeprecatedDbSettings:
 
         assert len(result) == 1
         assert "PAPERLESS_DBSSLCERT" in result[0].msg
+
+
+class TestV3MinimumUpgradeVersionCheck:
+    """Test suite for check_v3_minimum_upgrade_version system check."""
+
+    @pytest.fixture
+    def build_conn_mock(self, mocker: MockerFixture):
+        """Factory fixture that builds a connections['default'] mock.
+
+        Usage::
+
+            conn = build_conn_mock(tables=["django_migrations"], applied=["1075_..."])
+        """
+
+        def _build(tables: list[str], applied: list[str]) -> mock.MagicMock:
+            conn = mocker.MagicMock()
+            conn.introspection.table_names.return_value = tables
+            cursor = conn.cursor.return_value.__enter__.return_value
+            cursor.fetchall.return_value = [(name,) for name in applied]
+            return conn
+
+        return _build
+
+    def test_no_migrations_table_fresh_install(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - No django_migrations table exists in the database
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (fresh install, nothing to enforce)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock([], [])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_no_documents_migrations_fresh_install(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - django_migrations table exists but has no documents app rows
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (fresh install, nothing to enforce)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], [])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v3_state_with_0001_squashed(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 0001_squashed is recorded in django_migrations
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (DB is already in a valid v3 state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["0001_squashed", "0002_squashed", "0003_workflowaction_order"],
+                ),
+            },
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v3_state_with_0002_squashed_only(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - Only 0002_squashed is recorded in django_migrations
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (0002_squashed alone confirms a valid v3 state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], ["0002_squashed"])},
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v2_20_9_state_ready_to_upgrade(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 1075_workflowaction_order (the last v2.20.9 migration) is in the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No errors are reported (squash will pick up cleanly from this state)
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    [
+                        "1074_workflowrun_deleted_at_workflowrun_restored_at_and_more",
+                        "1075_workflowaction_order",
+                    ],
+                ),
+            },
+        )
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_v2_20_8_raises_error(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - 1074 (last v2.20.8 migration) is applied but 1075 is not
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - An Error with id paperless.E002 is returned
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["1074_workflowrun_deleted_at_workflowrun_restored_at_and_more"],
+                ),
+            },
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert isinstance(result[0], Error)
+        assert result[0].id == "paperless.E002"
+
+    def test_very_old_version_raises_error(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - Only old migrations (well below v2.20.9) are applied
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - An Error with id paperless.E002 is returned
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {
+                "default": build_conn_mock(
+                    ["django_migrations"],
+                    ["1000_update_paperless_all", "1022_paperlesstask"],
+                ),
+            },
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert isinstance(result[0], Error)
+        assert result[0].id == "paperless.E002"
+
+    def test_error_hint_mentions_v2_20_9(
+        self,
+        mocker: MockerFixture,
+        build_conn_mock,
+    ) -> None:
+        """
+        GIVEN:
+            - DB is on an old v2 version (pre-v2.20.9)
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - The error hint explicitly references v2.20.9 so users know what to do
+        """
+        mocker.patch.dict(
+            "paperless.checks.connections",
+            {"default": build_conn_mock(["django_migrations"], ["1022_paperlesstask"])},
+        )
+        result = check_v3_minimum_upgrade_version(None)
+        assert len(result) == 1
+        assert "v2.20.9" in result[0].hint
+
+    def test_db_error_is_swallowed(self, mocker: MockerFixture) -> None:
+        """
+        GIVEN:
+            - A DatabaseError is raised when querying the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No exception propagates and an empty list is returned
+        """
+        from django.db import DatabaseError
+
+        conn = mocker.MagicMock()
+        conn.introspection.table_names.side_effect = DatabaseError("connection refused")
+        mocker.patch.dict("paperless.checks.connections", {"default": conn})
+        assert check_v3_minimum_upgrade_version(None) == []
+
+    def test_operational_error_is_swallowed(self, mocker: MockerFixture) -> None:
+        """
+        GIVEN:
+            - An OperationalError is raised when querying the DB
+        WHEN:
+            - The v3 upgrade check runs
+        THEN:
+            - No exception propagates and an empty list is returned
+        """
+        from django.db import OperationalError
+
+        conn = mocker.MagicMock()
+        conn.introspection.table_names.side_effect = OperationalError("DB unavailable")
+        mocker.patch.dict("paperless.checks.connections", {"default": conn})
+        assert check_v3_minimum_upgrade_version(None) == []

src/paperless/views.py

@@ -378,7 +378,6 @@ class ApplicationConfigurationViewSet(ModelViewSet):
         ):
             # AI index was just enabled and vector store file does not exist
             llmindex_index.delay(
-                progress_bar_disable=True,
                 rebuild=True,
                 scheduled=False,
                 auto=True,

src/paperless_ai/indexing.py

@@ -1,11 +1,13 @@
 import logging
 import shutil
+from collections.abc import Callable
+from collections.abc import Iterable
 from datetime import timedelta
 from pathlib import Path
+from typing import TypeVar
 
 import faiss
 import llama_index.core.settings as llama_settings
-import tqdm
 from celery import states
 from django.conf import settings
 from django.utils import timezone
@@ -29,6 +31,14 @@ from paperless_ai.embedding import build_llm_index_text
 from paperless_ai.embedding import get_embedding_dim
 from paperless_ai.embedding import get_embedding_model
 
+_T = TypeVar("_T")
+IterWrapper = Callable[[Iterable[_T]], Iterable[_T]]
+
+
+def _identity(iterable: Iterable[_T]) -> Iterable[_T]:
+    return iterable
+
+
 logger = logging.getLogger("paperless_ai.indexing")
 
 
@@ -156,7 +166,11 @@ def vector_store_file_exists():
     return Path(settings.LLM_INDEX_DIR / "default__vector_store.json").exists()
 
 
-def update_llm_index(*, progress_bar_disable=False, rebuild=False) -> str:
+def update_llm_index(
+    *,
+    iter_wrapper: IterWrapper[Document] = _identity,
+    rebuild=False,
+) -> str:
     """
     Rebuild or update the LLM index.
     """
@@ -176,7 +190,7 @@ def update_llm_index(*, progress_bar_disable=False, rebuild=False) -> str:
         embed_model = get_embedding_model()
         llama_settings.Settings.embed_model = embed_model
         storage_context = get_or_create_storage_context(rebuild=True)
-        for document in tqdm.tqdm(documents, disable=progress_bar_disable):
+        for document in iter_wrapper(documents):
             document_nodes = build_document_node(document)
             nodes.extend(document_nodes)
 
@@ -184,7 +198,7 @@ def update_llm_index(*, progress_bar_disable=False, rebuild=False) -> str:
             nodes=nodes,
             storage_context=storage_context,
             embed_model=embed_model,
-            show_progress=not progress_bar_disable,
+            show_progress=False,
         )
         msg = "LLM index rebuilt successfully."
     else:
@@ -196,7 +210,7 @@ def update_llm_index(*, progress_bar_disable=False, rebuild=False) -> str:
             for node in index.docstore.get_nodes(all_node_ids)
         }
 
-        for document in tqdm.tqdm(documents, disable=progress_bar_disable):
+        for document in iter_wrapper(documents):
             doc_id = str(document.id)
             document_modified = document.modified.isoformat()
 

src/paperless_mail/migrations/0001_squashed.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-20 18:46
+# Generated by Django 5.2.11 on 2026-03-03 16:27
 
 import django.db.models.deletion
 import django.utils.timezone
@@ -15,6 +15,50 @@ class Migration(migrations.Migration):
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
+    replaces = [
+        ("paperless_mail", "0001_initial"),
+        ("paperless_mail", "0001_initial_squashed_0009_mailrule_assign_tags"),
+        ("paperless_mail", "0002_auto_20201117_1334"),
+        ("paperless_mail", "0003_auto_20201118_1940"),
+        ("paperless_mail", "0004_mailrule_order"),
+        ("paperless_mail", "0005_help_texts"),
+        ("paperless_mail", "0006_auto_20210101_2340"),
+        ("paperless_mail", "0007_auto_20210106_0138"),
+        ("paperless_mail", "0008_auto_20210516_0940"),
+        ("paperless_mail", "0009_alter_mailrule_action_alter_mailrule_folder"),
+        ("paperless_mail", "0009_mailrule_assign_tags"),
+        ("paperless_mail", "0010_auto_20220311_1602"),
+        ("paperless_mail", "0011_remove_mailrule_assign_tag"),
+        (
+            "paperless_mail",
+            "0011_remove_mailrule_assign_tag_squashed_0024_alter_mailrule_name_and_more",
+        ),
+        ("paperless_mail", "0012_alter_mailrule_assign_tags"),
+        ("paperless_mail", "0013_merge_20220412_1051"),
+        ("paperless_mail", "0014_alter_mailrule_action"),
+        ("paperless_mail", "0015_alter_mailrule_action"),
+        ("paperless_mail", "0016_mailrule_consumption_scope"),
+        ("paperless_mail", "0017_mailaccount_owner_mailrule_owner"),
+        ("paperless_mail", "0018_processedmail"),
+        ("paperless_mail", "0019_mailrule_filter_to"),
+        ("paperless_mail", "0020_mailaccount_is_token"),
+        ("paperless_mail", "0021_alter_mailaccount_password"),
+        ("paperless_mail", "0022_mailrule_assign_owner_from_rule_and_more"),
+        ("paperless_mail", "0023_remove_mailrule_filter_attachment_filename_and_more"),
+        ("paperless_mail", "0024_alter_mailrule_name_and_more"),
+        (
+            "paperless_mail",
+            "0025_alter_mailaccount_owner_alter_mailrule_owner_and_more",
+        ),
+        ("paperless_mail", "0026_mailrule_enabled"),
+        (
+            "paperless_mail",
+            "0027_mailaccount_expiration_mailaccount_account_type_and_more",
+        ),
+        ("paperless_mail", "0028_alter_mailaccount_password_and_more"),
+        ("paperless_mail", "0029_mailrule_pdf_layout"),
+    ]
+
     operations = [
         migrations.CreateModel(
             name="MailAccount",

src/paperless_mail/migrations/0002_optimize_integer_field_sizes.py

@@ -6,7 +6,7 @@ from django.db import models
 
 class Migration(migrations.Migration):
     dependencies = [
-        ("paperless_mail", "0001_initial"),
+        ("paperless_mail", "0001_squashed"),
     ]
 
     operations = [

src/paperless_mail/templates/package.json

@@ -1,5 +1,5 @@
 {
   "devDependencies": {
-    "tailwindcss": "^3.4.4"
+    "tailwindcss": "^3.4.19"
   }
 }

uv.lock

@@ -1342,11 +1342,11 @@ wheels = [
 
 [[package]]
 name = "faker"
-version = "40.1.2"
+version = "40.5.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/5e/77/1c3ff07b6739b9a1d23ca01ec0a90a309a33b78e345a3eb52f9ce9240e36/faker-40.1.2.tar.gz", hash = "sha256:b76a68163aa5f171d260fc24827a8349bc1db672f6a665359e8d0095e8135d30", size = 1949802, upload-time = "2026-01-13T20:51:49.917Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/03/2a/96fff3edcb10f6505143448a4b91535f77b74865cec45be52690ee280443/faker-40.5.1.tar.gz", hash = "sha256:70222361cd82aa10cb86066d1a4e8f47f2bcdc919615c412045a69c4e6da0cd3", size = 1952684, upload-time = "2026-02-23T21:34:38.362Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/46/ec/91a434c8a53d40c3598966621dea9c50512bec6ce8e76fa1751015e74cef/faker-40.1.2-py3-none-any.whl", hash = "sha256:93503165c165d330260e4379fd6dc07c94da90c611ed3191a0174d2ab9966a42", size = 1985633, upload-time = "2026-01-13T20:51:47.982Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/a9/1eed4db92d0aec2f9bfdf1faae0ab0418b5e121dda5701f118a7a4f0cd6a/faker-40.5.1-py3-none-any.whl", hash = "sha256:c69640c1e13bad49b4bcebcbf1b52f9f1a872b6ea186c248ada34d798f1661bf", size = 1987053, upload-time = "2026-02-23T21:34:36.418Z" },
 ]
 
 [[package]]
@@ -3121,6 +3121,7 @@ webserver = [
 dev = [
     { name = "daphne", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "factory-boy", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "faker", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "imagehash", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "prek", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "pytest", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
@@ -3145,6 +3146,7 @@ lint = [
 testing = [
     { name = "daphne", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "factory-boy", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "faker", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "imagehash", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "pytest", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
     { name = "pytest-cov", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
@@ -3257,6 +3259,7 @@ provides-extras = ["mariadb", "postgres", "webserver"]
 dev = [
     { name = "daphne" },
     { name = "factory-boy", specifier = "~=3.3.1" },
+    { name = "faker", specifier = "~=40.5.1" },
     { name = "imagehash" },
     { name = "prek", specifier = "~=0.3.0" },
     { name = "pytest", specifier = "~=9.0.0" },
@@ -3279,6 +3282,7 @@ lint = [
 testing = [
     { name = "daphne" },
     { name = "factory-boy", specifier = "~=3.3.1" },
+    { name = "faker", specifier = "~=40.5.1" },
     { name = "imagehash" },
     { name = "pytest", specifier = "~=9.0.0" },
     { name = "pytest-cov", specifier = "~=7.0.0" },
@@ -5906,11 +5910,11 @@ wheels = [
 
 [[package]]
 name = "whitenoise"
-version = "6.11.0"
+version = "6.12.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/15/95/8c81ec6b6ebcbf8aca2de7603070ccf37dbb873b03f20708e0f7c1664bc6/whitenoise-6.11.0.tar.gz", hash = "sha256:0f5bfce6061ae6611cd9396a8231e088722e4fc67bc13a111be74c738d99375f", size = 26432, upload-time = "2025-09-18T09:16:10.995Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/cb/2a/55b3f3a4ec326cd077c1c3defeee656b9298372a69229134d930151acd01/whitenoise-6.12.0.tar.gz", hash = "sha256:f723ebb76a112e98816ff80fcea0a6c9b8ecde835f8ddda25df7a30a3c2db6ad", size = 26841, upload-time = "2026-02-27T00:05:42.028Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6c/e9/4366332f9295fe0647d7d3251ce18f5615fbcb12d02c79a26f8dba9221b3/whitenoise-6.11.0-py3-none-any.whl", hash = "sha256:b2aeb45950597236f53b5342b3121c5de69c8da0109362aee506ce88e022d258", size = 20197, upload-time = "2025-09-18T09:16:09.754Z" },
+    { url = "https://files.pythonhosted.org/packages/db/eb/d5583a11486211f3ebd4b385545ae787f32363d453c19fffd81106c9c138/whitenoise-6.12.0-py3-none-any.whl", hash = "sha256:fc5e8c572e33ebf24795b47b6a7da8da3c00cff2349f5b04c02f28d0cc5a3cc2", size = 20302, upload-time = "2026-02-27T00:05:40.086Z" },
 ]
 
 [[package]]