impl migration to pdfium for metadata

# Conflicts:
#	app/common/build.gradle

.dockerignore

@@ -1,75 +1,110 @@
-# Node modules and build artifacts
-node_modules
-frontend/node_modules
-frontend/dist
-frontend/build
-frontend/.vite
-frontend/.tauri
-frontend/src-tauri/target
-
-# Gradle build artifacts
-.gradle
-build
-bin
-target
-out
-
-# Git
-.git
+# Version control
+.git/
 .gitignore
+.git-blame-ignore-revs
+.gitattributes
 
-# IDE
-.vscode
-.idea
+# Build outputs
+build/
+*/build/
+**/build/
+out/
+target/
+**/target/
+bin/
+version_builds/
+
+# Gradle caches (local, not what's in the container)
+.gradle/
+**/.gradle/
+.gradle-home/
+
+# Task (go-task) cache
+.task/
+
+# Node / frontend
+node_modules/
+**/node_modules/
+frontend/node_modules/
+frontend/dist/
+frontend/playwright-report/
+.npm/
+.yarn/
+
+# Tauri/desktop builds
+src-tauri/target/
+src-tauri/dist/
+frontend/src-tauri/target/
+frontend/src-tauri/dist/
+
+# IDE and editor
+.idea/
+.vscode/
+.settings/
+.settings.zip
+.classpath
+.project
+.devcontainer/
 *.iml
-*.iws
 *.ipr
+*.iws
 
-# Logs
+# Logs and temp files
 *.log
-logs
+*.tmp
+*.pid
+.DS_Store
+Thumbs.db
+logs/
 
-# Environment files
+# Docker itself
+Dockerfile*
+.dockerignore
+
+# CI / CD configs (not needed in build context)
+.github/
+.circleci/
+.gitlab-ci.yml
+
+# Test reports
+**/test-results/
+**/jacoco/
+test_*.pdf
+
+# Testing and documentation (not needed in build)
+testing/
+docs/
+devGuide/
+devTools/
+*.md
+README*
+
+# Separate projects not consumed by the Java/frontend build
+commonforms-onnx/
+
+# Runtime mount points used by docker-compose volumes, not build input
+stirling/
+customFiles/
+configs/
+
+# Claude Code workspace
+.claude/
+
+# Python caches
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+**/__pycache__/
+
+# Local env
 .env
 .env.*
 !.env.example
+!engine/.env
 
-# OS files
-.DS_Store
-Thumbs.db
-
-# Java compiled files
-*.class
-*.jar
-*.war
-*.ear
-
-# Test reports
-test-results
-coverage
-
-# Docker
-docker-compose.override.yml
-.dockerignore
-
-# Temporary files
-tmp
-temp
-*.tmp
+# Misc
 *.swp
+*.swo
 *~
-
-# Runtime database and config files (locked by running app)
-app/core/configs/**
-stirling/**
-stirling-pdf-DB*.mv.db
-stirling-pdf-DB*.trace.db
-
-# Documentation
-*.md
-!README.md
-docs
-
-# CI/CD
-.github
-.gitlab-ci.yml
+.DS_Store
+.cache/

.editorconfig

@@ -14,7 +14,8 @@ indent_size = 4
 max_line_length = 100
 
 [*.py]
-indent_size = 2
+indent_size = 4
+max_line_length = 120
 
 [*.gradle]
 indent_size = 4

.github/actions/setup-bot/action.yml

@@ -22,7 +22,7 @@ runs:
   steps:
     - name: Generate a GitHub App Token
       id: generate-token
-      uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
       with:
         app-id: ${{ inputs.app-id }}
         private-key: ${{ inputs.private-key }}

.github/aur/stirling-pdf-desktop/PKGBUILD

@@ -0,0 +1,29 @@
+# Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
+pkgname=stirling-pdf-desktop
+pkgver=2.11.0
+pkgrel=1
+pkgdesc="Locally hosted, web-based PDF manipulation tool (Tauri desktop app, official Stirling PDF Inc build)"
+arch=('x86_64')
+url="https://www.stirling.com"
+license=('MIT' 'LicenseRef-Stirling-PDF-Proprietary')
+depends=('gtk3' 'webkit2gtk-4.1' 'libappindicator-gtk3')
+provides=('stirling-pdf')
+conflicts=('stirling-pdf' 'stirling-pdf-git' 'stirling-pdf-bin')
+options=('!strip')
+
+source_x86_64=("${pkgname}-${pkgver}.deb::https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v${pkgver}/Stirling-PDF-linux-x86_64.deb")
+sha256sums_x86_64=('PLACEHOLDER_DEB_SHA256')
+
+package() {
+    # Extract the .deb archive
+    bsdtar -xf data.tar* -C "${pkgdir}"
+
+    # Fix permissions
+    find "${pkgdir}" -type d -exec chmod 755 {} \;
+
+    # Install license
+    install -Dm644 /dev/stdin "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE" <<EOF
+Copyright (c) 2025 Stirling PDF Inc
+All rights reserved. See https://github.com/Stirling-Tools/Stirling-PDF/blob/main/LICENSE
+EOF
+}

.github/aur/stirling-pdf-server-bin/PKGBUILD

@@ -0,0 +1,77 @@
+# Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
+pkgname=stirling-pdf-server-bin
+pkgver=2.11.0
+pkgrel=1
+pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
+arch=('any')
+url="https://www.stirling.com"
+license=('MIT' 'LicenseRef-Stirling-PDF-Proprietary')
+depends=('java-runtime>=25')
+provides=('stirling-pdf-server')
+conflicts=('stirling-pdf-server' 'stirling-pdf-server-git')
+backup=('etc/stirling-pdf-server/settings.yml')
+
+source=("Stirling-PDF-with-login-${pkgver}.jar::https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v${pkgver}/Stirling-PDF-with-login.jar")
+sha256sums=('PLACEHOLDER_JAR_SHA256')
+
+package() {
+    # JAR
+    install -Dm644 "Stirling-PDF-with-login-${pkgver}.jar" \
+        "${pkgdir}/usr/share/stirling-pdf-server/stirling-pdf-server.jar"
+
+    # Wrapper script
+    install -Dm755 /dev/stdin "${pkgdir}/usr/bin/stirling-pdf-server" << 'EOF'
+#!/bin/sh
+exec java $JAVA_OPTS -jar /usr/share/stirling-pdf-server/stirling-pdf-server.jar "$@"
+EOF
+
+    # systemd unit
+    install -Dm644 /dev/stdin "${pkgdir}/usr/lib/systemd/system/stirling-pdf-server.service" << 'EOF'
+[Unit]
+Description=Stirling-PDF Server
+After=network.target
+
+[Service]
+Type=simple
+User=stirling-pdf
+Group=stirling-pdf
+WorkingDirectory=/var/lib/stirling-pdf-server
+ExecStart=/usr/bin/java -jar /usr/share/stirling-pdf-server/stirling-pdf-server.jar
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=stirling-pdf-server
+Environment=JAVA_OPTS=-Xmx512m
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+    # sysusers
+    install -Dm644 /dev/stdin "${pkgdir}/usr/lib/sysusers.d/stirling-pdf-server.conf" << 'EOF'
+u stirling-pdf - "Stirling-PDF Server" /var/lib/stirling-pdf-server -
+EOF
+
+    # tmpfiles
+    install -Dm644 /dev/stdin "${pkgdir}/usr/lib/tmpfiles.d/stirling-pdf-server.conf" << 'EOF'
+d /var/lib/stirling-pdf-server 0750 stirling-pdf stirling-pdf -
+d /var/log/stirling-pdf-server 0750 stirling-pdf stirling-pdf -
+EOF
+
+    # Default config stub
+    install -dm755 "${pkgdir}/etc/stirling-pdf-server"
+    install -Dm644 /dev/stdin "${pkgdir}/etc/stirling-pdf-server/settings.yml" << 'EOF'
+# Stirling-PDF Server configuration
+# See https://github.com/Stirling-Tools/Stirling-PDF for all options
+server:
+  port: 8080
+EOF
+
+    # License
+    install -Dm644 /dev/stdin "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE" << 'EOF'
+MIT License with proprietary carve-outs (open-core).
+SPDX: MIT AND LicenseRef-Stirling-PDF-Proprietary
+See https://github.com/Stirling-Tools/Stirling-PDF/blob/main/LICENSE
+EOF
+}

.github/config/.files.yaml

@@ -6,14 +6,20 @@ openapi: &openapi
   - *build
   - app/(common|core|proprietary)/src/main/java/**
 
+docker-base: &docker-base
+  - docker/base/Dockerfile
+  - ".github/workflows/push-docker-base.yml"
+
 docker: &docker
-  - Dockerfile
-  - Dockerfile.fat
-  - Dockerfile.ultra-lite
+  - docker/embedded/Dockerfile
+  - docker/embedded/Dockerfile.fat
+  - docker/embedded/Dockerfile.ultra-lite
   - ".github/workflows/build.yml"
+  - ".github/workflows/push-docker.yml"
   - scripts/init.sh
   - scripts/init-without-ocr.sh
   - exampleYmlFiles/**
+  - *docker-base
 
 project: &project
   - app/(common|core|proprietary)/src/(main|test)/java/**
@@ -24,6 +30,7 @@ project: &project
   - libs/**
   - "testing/**/!(requirements*.txt|requirements*.in)*"
   - *docker
+  - *docker-base
   - gradle.properties
   - gradlew
   - gradlew.bat
@@ -39,8 +46,7 @@ frontend: &frontend
   - testing/**
   - docker/**
   - scripts/translations/*.py
-  - scripts/build-tauri-jlink.bat
-  - scripts/build-tauri-jlink.sh
+  - .taskfiles/desktop.yml
   - scripts/convert_cff_to_ttf.py
   - scripts/harvest_type3_fonts.py
   - scripts/ignore_translation.toml
@@ -49,6 +55,25 @@ frontend: &frontend
   - scripts/type3_to_cff.py
   - scripts/update_type3_library.py
 
+# Files that affect the Tauri desktop bundle. Gate the multi-OS Tauri build
+# job on changes to any of these.
+tauri: &tauri
+  - frontend/src-tauri/**
+  - frontend/src/desktop/**
+  - frontend/tsconfig.desktop.json
+  - frontend/package.json
+  - frontend/package-lock.json
+  - frontend/vite.config.ts
+  - .github/workflows/tauri-build.yml
+
+# Files that affect the AI engine (Python tool models, fixers, tests). Gate
+# the engine validation job on changes to engine sources or to the Java
+# tool surfaces it generates models from.
+engine: &engine
+  - engine/**
+  - app/(common|core|proprietary)/src/main/java/**
+  - .github/workflows/ai-engine.yml
+
 licenses-frontend: &licenses-frontend
   - ".github/workflows/frontend-backend-licenses-update.yml"
   - "frontend/package.json"
@@ -57,4 +82,23 @@ licenses-frontend: &licenses-frontend
 
 licenses-backend: &licenses-backend
   - ".github/workflows/frontend-backend-licenses-update.yml"
-  - *build
+  - *build
+
+# Files that can affect premium / enterprise behaviour. Gate the enterprise
+# Playwright job on changes to any of these on PRs.
+proprietary: &proprietary
+  - app/proprietary/**
+  - frontend/src/proprietary/**
+  - frontend/src/core/tests/enterprise/**
+  - testing/compose/docker-compose-keycloak-oauth.yml
+  - testing/compose/docker-compose-keycloak-saml.yml
+  - testing/compose/keycloak-realm-oauth.json
+  - testing/compose/keycloak-realm-saml.json
+  - testing/compose/start-oauth-test.sh
+  - testing/compose/start-saml-test.sh
+  - testing/compose/validate-oauth-test.sh
+  - testing/compose/validate-saml-test.sh
+  - configs/settings.yml.template
+  - build.gradle
+  - app/proprietary/build.gradle
+  - .github/workflows/build-enterprise.yml

.github/dependabot.yml

@@ -13,58 +13,150 @@ updates:
       - "/app/proprietary"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"
 
   - package-ecosystem: "docker"
-    directory: "/" # Location of Dockerfile
+    directories:
+      - "/" # Location of Dockerfile
+      - "/docker/backend"
+      - "/docker/embedded"
+      - "/docker/frontend"
+      - "/docker/base"
+      - "/docker/engine"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"
 
   - package-ecosystem: github-actions
     directory: /
     schedule:
       interval: weekly
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"
 
   - package-ecosystem: npm
-    directory: /devTools
-    schedule:
-      interval: "weekly"
-    rebase-strategy: "auto"
-
-  - package-ecosystem: docker
-    directory: /docker/backend
-    schedule:
-      interval: "weekly"
-    rebase-strategy: "auto"
-
-  - package-ecosystem: docker
-    directory: /docker/embedded
-    schedule:
-      interval: "weekly"
-    rebase-strategy: "auto"
-
-  - package-ecosystem: docker
-    directory: /docker/frontend
-    schedule:
-      interval: "weekly"
-    rebase-strategy: "auto"
-
-  - package-ecosystem: npm
-    directory: /frontend
+    directories:
+      - /devTools
+      - /frontend
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"
+    groups:
+      embedpdf:
+        patterns:
+          - "@embedpdf/*"
+      mantine:
+        patterns:
+          - "@mantine/*"
+          - "postcss-preset-mantine"
+      mui:
+        patterns:
+          - "@mui/*"
+      tauri-js:
+        patterns:
+          - "@tauri-apps/*"
+      emotion:
+        patterns:
+          - "@emotion/*"
+      react:
+        patterns:
+          - "react"
+          - "react-dom"
+          - "@types/react"
+          - "@types/react-dom"
+      typescript-eslint:
+        patterns:
+          - "@typescript-eslint/*"
+          - "typescript-eslint"
+      eslint:
+        patterns:
+          - "eslint"
+          - "@eslint/*"
+      vite:
+        patterns:
+          - "vite"
+          - "vite-*"
+          - "@vitejs/*"
+      vitest:
+        patterns:
+          - "vitest"
+          - "@vitest/*"
+      testing-library:
+        patterns:
+          - "@testing-library/*"
+      i18next:
+        patterns:
+          - "i18next"
+          - "i18next-*"
+          - "react-i18next"
+      iconify:
+        patterns:
+          - "@iconify/*"
+          - "@iconify-json/*"
+      stripe:
+        patterns:
+          - "@stripe/*"
+      posthog:
+        patterns:
+          - "@posthog/*"
+          - "posthog-js"
+      supabase:
+        patterns:
+          - "@supabase/*"
+      dnd-kit:
+        patterns:
+          - "@dnd-kit/*"
+      tailwind:
+        patterns:
+          - "tailwindcss"
+          - "@tailwindcss/*"
+      postcss:
+        patterns:
+          - "postcss"
+          - "postcss-*"
+        exclude-patterns:
+          - "postcss-preset-mantine"
 
   - package-ecosystem: cargo
-    directory: /frontend/src-tauri
+    directories:
+      - /frontend/src-tauri
+      - /frontend/src-tauri/thumbnail-handler
+      - /frontend/src-tauri/provisioner
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"
+    groups:
+      tauri:
+        patterns:
+          - "tauri"
+          - "tauri-build"
+          - "tauri-plugin-*"
+      serde:
+        patterns:
+          - "serde"
+          - "serde_*"
+      tracing:
+        patterns:
+          - "tracing"
+          - "tracing-*"
+      tokio:
+        patterns:
+          - "tokio"
+          - "tokio-*"
 
   - package-ecosystem: pip
     directory: /testing/cucumber
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     rebase-strategy: "auto"

.github/labeler-config-srvaroa.yml

@@ -72,6 +72,12 @@ labels:
       - 'frontend/src-tauri/**'
       - 'frontend/src-tauri/.*'
 
+  - label: 'engine'
+    files:
+      - 'engine/**'
+      - 'engine/.*'
+      - 'engine/**/.*'
+
   - label: 'Java'
     files:
       - 'app/common/src/main/java/.*.java'

.github/pull_request_template.md

@@ -17,7 +17,7 @@ Closes #(issue_number)
 ### General
 
 - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
-- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) (if applicable)
+- [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable)
 - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) (if applicable)
 - [ ] I have performed a self-review of my own code
 - [ ] My changes generate no new warnings
@@ -37,4 +37,5 @@ Closes #(issue_number)
 
 ### Testing (if applicable)
 
-- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing) for more details.
+- [ ] I have run `task check` to verify linters, typechecks, and tests pass
+- [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#7-testing) for more details.

.github/release.yml

@@ -1,4 +1,11 @@
 changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+      # engine: Python AI engine - not currently live / not yet shipped to users.
+      # Remove this entry once the engine is released.
+      - engine
+
   categories:
     - title: Breaking Changes
       labels:
@@ -6,16 +13,22 @@ changelog:
 
     - title: Bug Fixes
       labels:
+        - Bugfix
         - Bug
 
     - title: Enhancements
       labels:
         - enhancement
+        - Java
+        - Front End
+        - Back End
+        - Tauri
 
     - title: Minor Enhancements
       labels:
-        - Java
-        - Front End
+        - chore
+        - style
+        - refactor
 
     - title: Docker Updates
       labels:

.github/scripts/requirements_dev.txt

@@ -101,269 +101,273 @@ cfgv==3.5.0 \
     --hash=sha256:a8dc6b26ad22ff227d2634a65cb388215ce6cc96bbcc5cfde7641ae87e8dacc0 \
     --hash=sha256:d5b1034354820651caa73ede66a6294d6e95c1b00acc5e9b098e917404669132
     # via pre-commit
-cssselect2==0.8.0 \
-    --hash=sha256:46fc70ebc41ced7a32cd42d58b1884d72ade23d21e5a4eaaf022401c13f0e76e \
-    --hash=sha256:7674ffb954a3b46162392aee2a3a0aedb2e14ecf99fcc28644900f4e6e3e9d3a
+cssselect2==0.9.0 \
+    --hash=sha256:6a99e5f91f9a016a304dd929b0966ca464bcfda15177b6fb4a118fc0fb5d9563 \
+    --hash=sha256:759aa22c216326356f65e62e791d66160a0f9c91d1424e8d8adc5e74dddfc6fb
     # via weasyprint
 distlib==0.4.0 \
     --hash=sha256:9659f7d87e46584a30b5780e43ac7a2143098441670ff0a49d5f9034c54a6c16 \
     --hash=sha256:feec40075be03a04501a973d81f633735b4b69f98b05450592310c0f401a4e0d
     # via virtualenv
-filelock==3.20.3 \
-    --hash=sha256:18c57ee915c7ec61cff0ecf7f0f869936c7c30191bb0cf406f1341778d0834e1 \
-    --hash=sha256:4b0dda527ee31078689fc205ec4f1c1bf7d56cf88b6dc9426c4f230e46c2dce1
-    # via virtualenv
-fonttools==4.61.1 \
-    --hash=sha256:0de30bfe7745c0d1ffa2b0b7048fb7123ad0d71107e10ee090fa0b16b9452e87 \
-    --hash=sha256:10d88e55330e092940584774ee5e8a6971b01fc2f4d3466a1d6c158230880796 \
-    --hash=sha256:11f35ad7805edba3aac1a3710d104592df59f4b957e30108ae0ba6c10b11dd75 \
-    --hash=sha256:15acc09befd16a0fb8a8f62bc147e1a82817542d72184acca9ce6e0aeda9fa6d \
-    --hash=sha256:17d2bf5d541add43822bcf0c43d7d847b160c9bb01d15d5007d84e2217aaa371 \
-    --hash=sha256:2180f14c141d2f0f3da43f3a81bc8aa4684860f6b0e6f9e165a4831f24e6a23b \
-    --hash=sha256:21e7c8d76f62ab13c9472ccf74515ca5b9a761d1bde3265152a6dc58700d895b \
-    --hash=sha256:41a7170d042e8c0024703ed13b71893519a1a6d6e18e933e3ec7507a2c26a4b2 \
-    --hash=sha256:41ed4b5ec103bd306bb68f81dc166e77409e5209443e5773cb4ed837bcc9b0d3 \
-    --hash=sha256:497c31ce314219888c0e2fce5ad9178ca83fe5230b01a5006726cdf3ac9f24d9 \
-    --hash=sha256:4c1b526c8d3f615a7b1867f38a9410849c8f4aef078535742198e942fba0e9bd \
-    --hash=sha256:4d7092bb38c53bbc78e9255a59158b150bcdc115a1e3b3ce0b5f267dc35dd63c \
-    --hash=sha256:4f5686e1fe5fce75d82d93c47a438a25bf0d1319d2843a926f741140b2b16e0c \
-    --hash=sha256:58b0ee0ab5b1fc9921eccfe11d1435added19d6494dde14e323f25ad2bc30c56 \
-    --hash=sha256:5ce02f38a754f207f2f06557523cd39a06438ba3aafc0639c477ac409fc64e37 \
-    --hash=sha256:5fade934607a523614726119164ff621e8c30e8fa1ffffbbd358662056ba69f0 \
-    --hash=sha256:5fe9fd43882620017add5eabb781ebfbc6998ee49b35bd7f8f79af1f9f99a958 \
-    --hash=sha256:64102ca87e84261419c3747a0d20f396eb024bdbeb04c2bfb37e2891f5fadcb5 \
-    --hash=sha256:664c5a68ec406f6b1547946683008576ef8b38275608e1cee6c061828171c118 \
-    --hash=sha256:6675329885c44657f826ef01d9e4fb33b9158e9d93c537d84ad8399539bc6f69 \
-    --hash=sha256:75c1a6dfac6abd407634420c93864a1e274ebc1c7531346d9254c0d8f6ca00f9 \
-    --hash=sha256:75da8f28eff26defba42c52986de97b22106cb8f26515b7c22443ebc9c2d3261 \
-    --hash=sha256:77efb033d8d7ff233385f30c62c7c79271c8885d5c9657d967ede124671bbdfb \
-    --hash=sha256:78a7d3ab09dc47ac1a363a493e6112d8cabed7ba7caad5f54dbe2f08676d1b47 \
-    --hash=sha256:7c7db70d57e5e1089a274cbb2b1fd635c9a24de809a231b154965d415d6c6d24 \
-    --hash=sha256:8c56c488ab471628ff3bfa80964372fc13504ece601e0d97a78ee74126b2045c \
-    --hash=sha256:91669ccac46bbc1d09e9273546181919064e8df73488ea087dcac3e2968df9ba \
-    --hash=sha256:9b666a475a65f4e839d3d10473fad6d47e0a9db14a2f4a224029c5bfde58ad2c \
-    --hash=sha256:9cfef3ab326780c04d6646f68d4b4742aae222e8b8ea1d627c74e38afcbc9d91 \
-    --hash=sha256:a13fc8aeb24bad755eea8f7f9d409438eb94e82cf86b08fe77a03fbc8f6a96b1 \
-    --hash=sha256:a75c301f96db737e1c5ed5fd7d77d9c34466de16095a266509e13da09751bd19 \
-    --hash=sha256:a76d4cb80f41ba94a6691264be76435e5f72f2cb3cab0b092a6212855f71c2f6 \
-    --hash=sha256:aed04cabe26f30c1647ef0e8fbb207516fd40fe9472e9439695f5c6998e60ac5 \
-    --hash=sha256:b148b56f5de675ee16d45e769e69f87623a4944f7443850bf9a9376e628a89d2 \
-    --hash=sha256:b501c862d4901792adaec7c25b1ecc749e2662543f68bb194c42ba18d6eec98d \
-    --hash=sha256:b846a1fcf8beadeb9ea4f44ec5bdde393e2f1569e17d700bfc49cd69bde75881 \
-    --hash=sha256:b931ae8f62db78861b0ff1ac017851764602288575d65b8e8ff1963fed419063 \
-    --hash=sha256:c33ab3ca9d3ccd581d58e989d67554e42d8d4ded94ab3ade3508455fe70e65f7 \
-    --hash=sha256:c6604b735bb12fef8e0efd5578c9fb5d3d8532d5001ea13a19cddf295673ee09 \
-    --hash=sha256:d8db08051fc9e7d8bc622f2112511b8107d8f27cd89e2f64ec45e9825e8288da \
-    --hash=sha256:d9203500f7c63545b4ce3799319fe4d9feb1a1b89b28d3cb5abd11b9dd64147e \
-    --hash=sha256:dc492779501fa723b04d0ab1f5be046797fee17d27700476edc7ee9ae535a61e \
-    --hash=sha256:e6bcdf33aec38d16508ce61fd81838f24c83c90a1d1b8c68982857038673d6b8 \
-    --hash=sha256:e76ce097e3c57c4bcb67c5aa24a0ecdbd9f74ea9219997a707a4061fbe2707aa \
-    --hash=sha256:eff1ac3cc66c2ac7cda1e64b4e2f3ffef474b7335f92fc3833fc632d595fcee6 \
-    --hash=sha256:f3cb4a569029b9f291f88aafc927dd53683757e640081ca8c412781ea144565e \
-    --hash=sha256:f79b168428351d11e10c5aeb61a74e1851ec221081299f4cf56036a95431c43a \
-    --hash=sha256:fa646ecec9528bef693415c79a86e733c70a4965dd938e9a226b0fc64c9d2e6c \
-    --hash=sha256:fe2efccb324948a11dd09d22136fe2ac8a97d6c1347cf0b58a911dcd529f66b7 \
-    --hash=sha256:fff4f534200a04b4a36e7ae3cb74493afe807b517a09e99cb4faa89a34ed6ecd
+filelock==3.29.0 \
+    --hash=sha256:69974355e960702e789734cb4871f884ea6fe50bd8404051a3530bc07809cf90 \
+    --hash=sha256:96f5f6344709aa1572bbf631c640e4ebeeb519e08da902c39a001882f30ac258
+    # via
+    #   python-discovery
+    #   virtualenv
+fonttools==4.62.1 \
+    --hash=sha256:0aa72c43a601cfa9273bb1ae0518f1acadc01ee181a6fc60cd758d7fdadffc04 \
+    --hash=sha256:0b3ae47e8636156a9accff64c02c0924cbebad62854c4a6dbdc110cd5b4b341a \
+    --hash=sha256:12859ff0b47dd20f110804c3e0d0970f7b832f561630cd879969011541a464a9 \
+    --hash=sha256:149f7d84afca659d1a97e39a4778794a2f83bf344c5ee5134e09995086cc2392 \
+    --hash=sha256:1596aeaddf7f78e21e68293c011316a25267b3effdaccaf4d59bc9159d681b82 \
+    --hash=sha256:19177c8d96c7c36359266e571c5173bcee9157b59cfc8cb0153c5673dc5a3a7d \
+    --hash=sha256:1c5c25671ce8805e0d080e2ffdeca7f1e86778c5cbfbeae86d7f866d8830517b \
+    --hash=sha256:1eecc128c86c552fb963fe846ca4e011b1be053728f798185a1687502f6d398e \
+    --hash=sha256:268abb1cb221e66c014acc234e872b7870d8b5d4657a83a8f4205094c32d2416 \
+    --hash=sha256:2d850f66830a27b0d498ee05adb13a3781637b1826982cd7e2b3789ef0cc71ae \
+    --hash=sha256:2e7abd2b1e11736f58c1de27819e1955a53267c21732e78243fa2fa2e5c1e069 \
+    --hash=sha256:403d28ce06ebfc547fbcb0cb8b7f7cc2f7a2d3e1a67ba9a34b14632df9e080f9 \
+    --hash=sha256:40975849bac44fb0b9253d77420c6d8b523ac4dcdcefeff6e4d706838a5b80f7 \
+    --hash=sha256:486f32c8047ccd05652aba17e4a8819a3a9d78570eb8a0e3b4503142947880ed \
+    --hash=sha256:49a445d2f544ce4a69338694cad575ba97b9a75fff02720da0882d1a73f12800 \
+    --hash=sha256:59b372b4f0e113d3746b88985f1c796e7bf830dd54b28374cd85c2b8acd7583e \
+    --hash=sha256:5a648bde915fba9da05ae98856987ca91ba832949a9e2888b48c47ef8b96c5a9 \
+    --hash=sha256:5f37df1cac61d906e7b836abe356bc2f34c99d4477467755c216b72aa3dc748b \
+    --hash=sha256:6706d1cb1d5e6251a97ad3c1b9347505c5615c112e66047abbef0f8545fa30d1 \
+    --hash=sha256:68959f5fc58ed4599b44aad161c2837477d7f35f5f79402d97439974faebfebe \
+    --hash=sha256:6acb4109f8bee00fec985c8c7afb02299e35e9c94b57287f3ea542f28bd0b0a7 \
+    --hash=sha256:7487782e2113861f4ddcc07c3436450659e3caa5e470b27dc2177cade2d8e7fd \
+    --hash=sha256:7aa21ff53e28a9c2157acbc44e5b401149d3c9178107130e82d74ceb500e5056 \
+    --hash=sha256:7bca7a1c1faf235ffe25d4f2e555246b4750220b38de8261d94ebc5ce8a23c23 \
+    --hash=sha256:8d337fdd49a79b0d51c4da87bc38169d21c3abbf0c1aa9367eff5c6656fb6dae \
+    --hash=sha256:8f8fca95d3bb3208f59626a4b0ea6e526ee51f5a8ad5d91821c165903e8d9260 \
+    --hash=sha256:90365821debbd7db678809c7491ca4acd1e0779b9624cdc6ddaf1f31992bf974 \
+    --hash=sha256:92bb00a947e666169c99b43753c4305fc95a890a60ef3aeb2a6963e07902cc87 \
+    --hash=sha256:93c316e0f5301b2adbe6a5f658634307c096fd5aae60a5b3412e4f3e1728ab24 \
+    --hash=sha256:942b03094d7edbb99bdf1ae7e9090898cad7bf9030b3d21f33d7072dbcb51a53 \
+    --hash=sha256:9c125ffa00c3d9003cdaaf7f2c79e6e535628093e14b5de1dccb08859b680936 \
+    --hash=sha256:9dde91633f77fa576879a0c76b1d89de373cae751a98ddf0109d54e173b40f14 \
+    --hash=sha256:9e7863e10b3de72376280b515d35b14f5eeed639d1aa7824f4cf06779ec65e42 \
+    --hash=sha256:a24decd24d60744ee8b4679d38e88b8303d86772053afc29b19d23bb8207803c \
+    --hash=sha256:a5d8825e1140f04e6c99bb7d37a9e31c172f3bc208afbe02175339e699c710e1 \
+    --hash=sha256:aa69d10ed420d8121118e628ad47d86e4caa79ba37f968597b958f6cceab7eca \
+    --hash=sha256:ad5cca75776cd453b1b035b530e943334957ae152a36a88a320e779d61fc980c \
+    --hash=sha256:b4e0fcf265ad26e487c56cb12a42dffe7162de708762db951e1b3f755319507d \
+    --hash=sha256:b820fcb92d4655513d8402d5b219f94481c4443d825b4372c75a2072aa4b357a \
+    --hash=sha256:bd13b7999d59c5eb1c2b442eb2d0c427cb517a0b7a1f5798fc5c9e003f5ff782 \
+    --hash=sha256:bdfe592802ef939a0e33106ea4a318eeb17822c7ee168c290273cbd5fabd746c \
+    --hash=sha256:c05557a78f8fa514da0f869556eeda40887a8abc77c76ee3f74cf241778afd5a \
+    --hash=sha256:c22b1014017111c401469e3acc5433e6acf6ebcc6aa9efb538a533c800971c79 \
+    --hash=sha256:c9b9e288b4da2f64fd6180644221749de651703e8d0c16bd4b719533a3a7d6e3 \
+    --hash=sha256:d241cdc4a67b5431c6d7f115fdf63335222414995e3a1df1a41e1182acd4bcc7 \
+    --hash=sha256:e54c75fd6041f1122476776880f7c3c3295ffa31962dc6ebe2543c00dca58b5d \
+    --hash=sha256:e8514f4924375f77084e81467e63238b095abda5107620f49421c368a6017ed2 \
+    --hash=sha256:ee91628c08e76f77b533d65feb3fbe6d9dad699f95be51cf0d022db94089cdc4 \
+    --hash=sha256:ef46db46c9447103b8f3ff91e8ba009d5fe181b1920a83757a5762551e32bb68 \
+    --hash=sha256:fa1d16210b6b10a826d71bed68dd9ec24a9e218d5a5e2797f37c573e7ec215ca
     # via weasyprint
-identify==2.6.16 \
-    --hash=sha256:391ee4d77741d994189522896270b787aed8670389bfd60f326d677d64a6dfb0 \
-    --hash=sha256:846857203b5511bbe94d5a352a48ef2359532bc8f6727b5544077a0dcfb24980
+identify==2.6.19 \
+    --hash=sha256:20e6a87f786f768c092a721ad107fc9df0eb89347be9396cadf3f4abbd1fb78a \
+    --hash=sha256:6be5020c38fcb07da56c53733538a3081ea5aa70d36a156f83044bfbf9173842
     # via pre-commit
 nodeenv==1.10.0 \
     --hash=sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827 \
     --hash=sha256:996c191ad80897d076bdfba80a41994c2b47c68e224c542b48feba42ba00f8bb
     # via pre-commit
-numpy==2.4.1 \
-    --hash=sha256:0093e85df2960d7e4049664b26afc58b03236e967fb942354deef3208857a04c \
-    --hash=sha256:09aa8a87e45b55a1c2c205d42e2808849ece5c484b2aab11fecabec3841cafba \
-    --hash=sha256:0cce2a669e3c8ba02ee563c7835f92c153cf02edff1ae05e1823f1dde21b16a5 \
-    --hash=sha256:0e6e8f9d9ecf95399982019c01223dc130542960a12edfa8edd1122dfa66a8a8 \
-    --hash=sha256:0f118ce6b972080ba0758c6087c3617b5ba243d806268623dc34216d69099ba0 \
-    --hash=sha256:178de8f87948163d98a4c9ab5bee4ce6519ca918926ec8df195af582de28544d \
-    --hash=sha256:18e14c4d09d55eef39a6ab5b08406e84bc6869c1e34eef45564804f90b7e0574 \
-    --hash=sha256:2023ef86243690c2791fd6353e5b4848eedaa88ca8a2d129f462049f6d484696 \
-    --hash=sha256:20d4649c773f66cc2fc36f663e091f57c3b7655f936a4c681b4250855d1da8f5 \
-    --hash=sha256:2302dc0224c1cbc49bb94f7064f3f923a971bfae45c33870dcbff63a2a550505 \
-    --hash=sha256:26f0bcd9c79a00e339565b303badc74d3ea2bd6d52191eeca5f95936cad107d0 \
-    --hash=sha256:297c72b1b98100c2e8f873d5d35fb551fce7040ade83d67dd51d38c8d42a2162 \
-    --hash=sha256:2f44de05659b67d20499cbc96d49f2650769afcb398b79b324bb6e297bfe3844 \
-    --hash=sha256:2ffd257026eb1b34352e749d7cc1678b5eeec3e329ad8c9965a797e08ccba205 \
-    --hash=sha256:382ad67d99ef49024f11d1ce5dcb5ad8432446e4246a4b014418ba3a1175a1f4 \
-    --hash=sha256:3869ea1ee1a1edc16c29bbe3a2f2a4e515cc3a44d43903ad41e0cacdbaf733dc \
-    --hash=sha256:3d1a100e48cb266090a031397863ff8a30050ceefd798f686ff92c67a486753d \
-    --hash=sha256:423797bdab2eeefbe608d7c1ec7b2b4fd3c58d51460f1ee26c7500a1d9c9ee93 \
-    --hash=sha256:42d7dd5fa36d16d52a84f821eb96031836fd405ee6955dd732f2023724d0aa01 \
-    --hash=sha256:49e792ec351315e16da54b543db06ca8a86985ab682602d90c60ef4ff4db2a9c \
-    --hash=sha256:4e53170557d37ae404bf8d542ca5b7c629d6efa1117dac6a83e394142ea0a43f \
-    --hash=sha256:4f1b68ff47680c2925f8063402a693ede215f0257f02596b1318ecdfb1d79e33 \
-    --hash=sha256:4f9c360ecef085e5841c539a9a12b883dff005fbd7ce46722f5e9cef52634d82 \
-    --hash=sha256:529050522e983e00a6c1c6b67411083630de8b57f65e853d7b03d9281b8694d2 \
-    --hash=sha256:52b5f61bdb323b566b528899cc7db2ba5d1015bda7ea811a8bcf3c89c331fa42 \
-    --hash=sha256:538bf4ec353709c765ff75ae616c34d3c3dca1a68312727e8f2676ea644f8509 \
-    --hash=sha256:5adf01965456a664fc727ed69cc71848f28d063217c63e1a0e200a118d5eec9a \
-    --hash=sha256:5b55aa56165b17aaf15520beb9cbd33c9039810e0d9643dd4379e44294c7303e \
-    --hash=sha256:5d558123217a83b2d1ba316b986e9248a1ed1971ad495963d555ccd75dcb1556 \
-    --hash=sha256:5de60946f14ebe15e713a6f22850c2372fa72f4ff9a432ab44aa90edcadaa65a \
-    --hash=sha256:62fea415f83ad8fdb6c20840578e5fbaf5ddd65e0ec6c3c47eda0f69da172510 \
-    --hash=sha256:6436cffb4f2bf26c974344439439c95e152c9a527013f26b3577be6c2ca64295 \
-    --hash=sha256:6461de5113088b399d655d45c3897fa188766415d0f568f175ab071c8873bd73 \
-    --hash=sha256:69e7419c9012c4aaf695109564e3387f1259f001b4326dfa55907b098af082d3 \
-    --hash=sha256:71abbea030f2cfc3092a0ff9f8c8fdefdc5e0bf7d9d9c99663538bb0ecdac0b9 \
-    --hash=sha256:7211b95ca365519d3596a1d8688a95874cc94219d417504d9ecb2df99fa7bfa8 \
-    --hash=sha256:727c6c3275ddefa0dc078524a85e064c057b4f4e71ca5ca29a19163c607be745 \
-    --hash=sha256:79e9e06c4c2379db47f3f6fc7a8652e7498251789bf8ff5bd43bf478ef314ca2 \
-    --hash=sha256:7ad270f438cbdd402c364980317fb6b117d9ec5e226fff5b4148dd9aa9fc6e02 \
-    --hash=sha256:7d5d7999df434a038d75a748275cd6c0094b0ecdb0837342b332a82defc4dc4d \
-    --hash=sha256:8097529164c0f3e32bb89412a0905d9100bf434d9692d9fc275e18dcf53c9344 \
-    --hash=sha256:82c55962006156aeef1629b953fd359064aa47e4d82cfc8e67f0918f7da3344f \
-    --hash=sha256:8361ea4220d763e54cff2fbe7d8c93526b744f7cd9ddab47afeff7e14e8503be \
-    --hash=sha256:899d2c18024984814ac7e83f8f49d8e8180e2fbe1b2e252f2e7f1d06bea92425 \
-    --hash=sha256:8ad35f20be147a204e28b6a0575fbf3540c5e5f802634d4258d55b1ff5facce1 \
-    --hash=sha256:8f085da926c0d491ffff3096f91078cc97ea67e7e6b65e490bc8dcda65663be2 \
-    --hash=sha256:9171a42fcad32dcf3fa86f0a4faa5e9f8facefdb276f54b8b390d90447cff4e2 \
-    --hash=sha256:92a0e65272fd60bfa0d9278e0484c2f52fe03b97aedc02b357f33fe752c52ffb \
-    --hash=sha256:941c2a93313d030f219f3a71fd3d91a728b82979a5e8034eb2e60d394a2b83f9 \
-    --hash=sha256:98b35775e03ab7f868908b524fc0a84d38932d8daf7b7e1c3c3a1b6c7a2c9f15 \
-    --hash=sha256:a1ceafc5042451a858231588a104093474c6a5c57dcc724841f5c888d237d690 \
-    --hash=sha256:a73044b752f5d34d4232f25f18160a1cc418ea4507f5f11e299d8ac36875f8a0 \
-    --hash=sha256:a7870e8c5fc11aef57d6fea4b4085e537a3a60ad2cdd14322ed531fdca68d261 \
-    --hash=sha256:a92f227dbcdc9e4c3e193add1a189a9909947d4f8504c576f4a732fd0b54240a \
-    --hash=sha256:ac08c63cb7779b85e9d5318e6c3518b424bc1f364ac4cb2c6136f12e5ff2dccc \
-    --hash=sha256:b6bcf39112e956594b3331316d90c90c90fb961e39696bda97b89462f5f3943f \
-    --hash=sha256:c0faba4a331195bfa96f93dd9dfaa10b2c7aa8cda3a02b7fd635e588fe821bf5 \
-    --hash=sha256:ce9ce141a505053b3c7bce3216071f3bf5c182b8b28930f14cd24d43932cd2df \
-    --hash=sha256:cf6470d91d34bf669f61d515499859fa7a4c2f7c36434afb70e82df7217933f9 \
-    --hash=sha256:d3703409aac693fa82c0aee023a1ae06a6e9d065dba10f5e8e80f642f1e9d0a2 \
-    --hash=sha256:d3e3087f53e2b4428766b54932644d148613c5a595150533ae7f00dab2f319a8 \
-    --hash=sha256:d3f8f0df9f4b8be57b3bf74a1d087fec68f927a2fab68231fdb442bf2c12e426 \
-    --hash=sha256:d797454e37570cfd61143b73b8debd623c3c0952959adb817dd310a483d58a1b \
-    --hash=sha256:e1a27bb1b2dee45a2a53f5ca6ff2d1a7f135287883a1689e930d44d1ff296c87 \
-    --hash=sha256:e3bd2cb07841166420d2fa7146c96ce00cb3410664cbc1a6be028e456c4ee220 \
-    --hash=sha256:e7b6b5e28bbd47b7532698e5db2fe1db693d84b58c254e4389d99a27bb9b8f6b \
-    --hash=sha256:e867df947d427cdd7a60e3e271729090b0f0df80f5f10ab7dd436f40811699c3 \
-    --hash=sha256:ea66d2b41ca4a1630aae5507ee0a71647d3124d1741980138aa8f28f44dac36e \
-    --hash=sha256:edee228f76ee2dab4579fad6f51f6a305de09d444280109e0f75df247ff21501 \
-    --hash=sha256:f0a90aba7d521e6954670550e561a4cb925713bd944445dbe9e729b71f6cabee \
-    --hash=sha256:f93bc6892fe7b0663e5ffa83b61aab510aacffd58c16e012bb9352d489d90cb7 \
-    --hash=sha256:fb1461c99de4d040666ca0444057b06541e5642f800b71c56e6ea92d6a853a0c
+numpy==2.4.4 \
+    --hash=sha256:07077278157d02f65c43b1b26a3886bce886f95d20aabd11f87932750dfb14ed \
+    --hash=sha256:08f2e31ed5e6f04b118e49821397f12767934cfdd12a1ce86a058f91e004ee50 \
+    --hash=sha256:0aec54fd785890ecca25a6003fd9a5aed47ad607bbac5cd64f836ad8666f4959 \
+    --hash=sha256:0d35aea54ad1d420c812bfa0385c71cd7cc5bcf7c65fed95fc2cd02fe8c79827 \
+    --hash=sha256:0d4e437e295f18ec29bc79daf55e8a47a9113df44d66f702f02a293d93a2d6dd \
+    --hash=sha256:0dfd3f9d3adbe2920b68b5cd3d51444e13a10792ec7154cd0a2f6e74d4ab3233 \
+    --hash=sha256:1378871da56ca8943c2ba674530924bb8ca40cd228358a3b5f302ad60cf875fc \
+    --hash=sha256:15716cfef24d3a9762e3acdf87e27f58dc823d1348f765bbea6bef8c639bfa1b \
+    --hash=sha256:19710a9ca9992d7174e9c52f643d4272dcd1558c5f7af7f6f8190f633bd651a7 \
+    --hash=sha256:23cbfd4c17357c81021f21540da84ee282b9c8fba38a03b7b9d09ba6b951421e \
+    --hash=sha256:2483e4584a1cb3092da4470b38866634bafb223cbcd551ee047633fd2584599a \
+    --hash=sha256:27a8d92cd10f1382a67d7cf4db7ce18341b66438bdd9f691d7b0e48d104c2a9d \
+    --hash=sha256:28a650663f7314afc3e6ec620f44f333c386aad9f6fc472030865dc0ebb26ee3 \
+    --hash=sha256:2aa0613a5177c264ff5921051a5719d20095ea586ca88cc802c5c218d1c67d3e \
+    --hash=sha256:2c194dd721e54ecad9ad387c1d35e63dce5c4450c6dc7dd5611283dda239aabb \
+    --hash=sha256:2d19e6e2095506d1736b7d80595e0f252d76b89f5e715c35e06e937679ea7d7a \
+    --hash=sha256:2d390634c5182175533585cc89f3608a4682ccb173cc9bb940b2881c8d6f8fa0 \
+    --hash=sha256:30caa73029a225b2d40d9fae193e008e24b2026b7ee1a867b7ee8d96ca1a448e \
+    --hash=sha256:42c16925aa5a02362f986765f9ebabf20de75cdefdca827d14315c568dcab113 \
+    --hash=sha256:45dbed2ab436a9e826e302fcdcbe9133f9b0006e5af7168afb8963a6520da103 \
+    --hash=sha256:4636de7fd195197b7535f231b5de9e4b36d2c440b6e566d2e4e4746e6af0ca93 \
+    --hash=sha256:4a19d9dba1a76618dd86b164d608566f393f8ec6ac7c44f0cc879011c45e65af \
+    --hash=sha256:4bbc7f303d125971f60ec0aaad5e12c62d0d2c925f0ab1273debd0e4ba37aba5 \
+    --hash=sha256:4d6d57903571f86180eb98f8f0c839fa9ebbfb031356d87f1361be91e433f5b7 \
+    --hash=sha256:4e874c976154687c1f71715b034739b45c7711bec81db01914770373d125e392 \
+    --hash=sha256:51fc224f7ca4d92656d5a5eb315f12eb5fe2c97a66249aa7b5f562528a3be38c \
+    --hash=sha256:58c8b5929fcb8287cbd6f0a3fae19c6e03a5c48402ae792962ac465224a629a4 \
+    --hash=sha256:5a285b3b96f951841799528cd1f4f01cd70e7e0204b4abebac9463eecfcf2a40 \
+    --hash=sha256:5c70f1cc1c4efbe316a572e2d8b9b9cc44e89b95f79ca3331553fbb63716e2bf \
+    --hash=sha256:62d6b0f03b694173f9fcb1fb317f7222fd0b0b103e784c6549f5e53a27718c44 \
+    --hash=sha256:6a246d5914aa1c820c9443ddcee9c02bec3e203b0c080349533fae17727dfd1b \
+    --hash=sha256:6aa3236c78803afbcb255045fbef97a9e25a1f6c9888357d205ddc42f4d6eba5 \
+    --hash=sha256:6bbe4eb67390b0a0265a2c25458f6b90a409d5d069f1041e6aff1e27e3d9a79e \
+    --hash=sha256:715d1c092715954784bc79e1174fc2a90093dc4dc84ea15eb14dad8abdcdeb74 \
+    --hash=sha256:72944b19f2324114e9dc86a159787333b77874143efcf89a5167ef83cfee8af0 \
+    --hash=sha256:81f4a14bee47aec54f883e0cad2d73986640c1590eb9bfaaba7ad17394481e6e \
+    --hash=sha256:846300f379b5b12cc769334464656bc882e0735d27d9726568bc932fdc49d5ec \
+    --hash=sha256:86b6f55f5a352b48d7fbfd2dbc3d5b780b2d79f4d3c121f33eb6efb22e9a2015 \
+    --hash=sha256:874f200b2a981c647340f841730fc3a2b54c9d940566a3c4149099591e2c4c3d \
+    --hash=sha256:8a87ec22c87be071b6bdbd27920b129b94f2fc964358ce38f3822635a3e2e03d \
+    --hash=sha256:8b3b60bb7cba2c8c81837661c488637eee696f59a877788a396d33150c35d842 \
+    --hash=sha256:8e3ed142f2728df44263aaf5fb1f5b0b99f4070c553a0d7f033be65338329150 \
+    --hash=sha256:93e15038125dc1e5345d9b5b68aa7f996ec33b98118d18c6ca0d0b7d6198b7e8 \
+    --hash=sha256:989824e9faf85f96ec9c7761cd8d29c531ad857bfa1daa930cba85baaecf1a9a \
+    --hash=sha256:99d838547ace2c4aace6c4f76e879ddfe02bb58a80c1549928477862b7a6d6ed \
+    --hash=sha256:9b2aec6af35c113b05695ebb5749a787acd63cafc83086a05771d1e1cd1e555f \
+    --hash=sha256:9c585a1790d5436a5374bac930dad6ed244c046ed91b2b2a3634eb2971d21008 \
+    --hash=sha256:a7164afb23be6e37ad90b2f10426149fd75aee07ca55653d2aa41e66c4ef697e \
+    --hash=sha256:ac6b31e35612a26483e20750126d30d0941f949426974cace8e6b5c58a3657b0 \
+    --hash=sha256:ad2e2ef14e0b04e544ea2fa0a36463f847f113d314aa02e5b402fdf910ef309e \
+    --hash=sha256:b268594bccac7d7cf5844c7732e3f20c50921d94e36d7ec9b79e9857694b1b2f \
+    --hash=sha256:b5f0362dc928a6ecd9db58868fca5e48485205e3855957bdedea308f8672ea4a \
+    --hash=sha256:ba1f4fc670ed79f876f70082eff4f9583c15fb9a4b89d6188412de4d18ae2f40 \
+    --hash=sha256:ba203255017337d39f89bdd58417f03c4426f12beed0440cfd933cb15f8669c7 \
+    --hash=sha256:c901b15172510173f5cb310eae652908340f8dede90fff9e3bf6c0d8dfd92f83 \
+    --hash=sha256:c9b39d38a9bd2ae1becd7eac1303d031c5c110ad31f2b319c6e7d98b135c934d \
+    --hash=sha256:d2a8490669bfe99a233298348acc2d824d496dee0e66e31b66a6022c2ad74a5c \
+    --hash=sha256:dddbbd259598d7240b18c9d87c56a9d2fb3b02fe266f49a7c101532e78c1d871 \
+    --hash=sha256:df3775294accfdd75f32c74ae39fcba920c9a378a2fc18a12b6820aa8c1fb502 \
+    --hash=sha256:e44319a2953c738205bf3354537979eaa3998ed673395b964c1176083dd46252 \
+    --hash=sha256:e4a010c27ff6f210ff4c6ef34394cd61470d01014439b192ec22552ee867f2a8 \
+    --hash=sha256:e823b8b6edc81e747526f70f71a9c0a07ac4e7ad13020aa736bb7c9d67196115 \
+    --hash=sha256:e892aff75639bbef0d2a2cfd55535510df26ff92f63c92cd84ef8d4ba5a5557f \
+    --hash=sha256:eea7ac5d2dce4189771cedb559c738a71512768210dc4e4753b107a2048b3d0e \
+    --hash=sha256:ef4059d6e5152fa1a39f888e344c73fdc926e1b2dd58c771d67b0acfbf2aa67d \
+    --hash=sha256:f169b9a863d34f5d11b8698ead99febeaa17a13ca044961aa8e2662a6c7766a0 \
+    --hash=sha256:f2cf083b324a467e1ab358c105f6cad5ea950f50524668a80c486ff1db24e119 \
+    --hash=sha256:f8474c4241bc18b750be2abea9d7a9ec84f46ef861dbacf86a4f6e043401f79e \
+    --hash=sha256:f983334aea213c99992053ede6168500e5f086ce74fbc4acc3f2b00f5762e9db \
+    --hash=sha256:f9e75681b59ddaa5e659898085ae0eaea229d054f2ac0c7e563a62205a700121 \
+    --hash=sha256:fbc356aae7adf9e6336d336b9c8111d390a05df88f1805573ebb0807bd06fd1d \
+    --hash=sha256:fcfe2045fd2e8f3cb0ce9d4ba6dba6333b8fa05bb8a4939c908cd43322d14c7e
     # via opencv-python-headless
-opencv-python-headless==4.13.0.90 \
-    --hash=sha256:0e0c8c9f620802fddc4fa7f471a1d263c7b0dca16cd9e7e2f996bb8bd2128c0c \
-    --hash=sha256:12a28674f215542c9bf93338de1b5bffd76996d32da9acb9e739fdb9c8bbd738 \
-    --hash=sha256:32255203040dc98803be96362e13f9e4bce20146898222d2e5c242f80de50da5 \
-    --hash=sha256:96060fc57a1abb1144b0b8129e2ff3bfcdd0ccd8e8bd05bd85256ff4ed587d3b \
-    --hash=sha256:dbc1f4625e5af3a80ebdbd84380227c0f445228588f2521b11af47710caca1ba \
-    --hash=sha256:e13790342591557050157713af17a7435ac1b50c65282715093c9297fa045d8f \
-    --hash=sha256:eba38bc255d0b7d1969c5bcc90a060ca2b61a3403b613872c750bfa5dfe9e03b \
-    --hash=sha256:f46b17ea0aa7e4124ca6ad71143f89233ae9557f61d2326bcdb34329a1ddf9bd
+opencv-python-headless==4.13.0.92 \
+    --hash=sha256:0525a3d2c0b46c611e2130b5fdebc94cf404845d8fa64d2f3a3b679572a5bd22 \
+    --hash=sha256:0bd48544f77c68b2941392fcdf9bcd2b9cdf00e98cb8c29b2455d194763cf99e \
+    --hash=sha256:1a7d040ac656c11b8c38677cc8cccdc149f98535089dbe5b081e80a4e5903209 \
+    --hash=sha256:3e0a6f0a37994ec6ce5f59e936be21d5d6384a4556f2d2da9c2f9c5dc948394c \
+    --hash=sha256:5c8cfc8e87ed452b5cecb9419473ee5560a989859fe1d10d1ce11ae87b09a2cb \
+    --hash=sha256:77a82fe35ddcec0f62c15f2ba8a12ecc2ed4207c17b0902c7a3151ae29f37fb6 \
+    --hash=sha256:a7cf08e5b191f4ebb530791acc0825a7986e0d0dee2a3c491184bd8599848a4b \
+    --hash=sha256:eb60e36b237b1ebd40a912da5384b348df8ed534f6f644d8e0b4f103e272ba7d
     # via -r .github/scripts/requirements_dev.in
 pdf2image==1.17.0 \
     --hash=sha256:eaa959bc116b420dd7ec415fcae49b98100dda3dd18cd2fdfa86d09f112f6d57 \
     --hash=sha256:ecdd58d7afb810dffe21ef2b1bbc057ef434dabbac6c33778a38a3f7744a27e2
     # via -r .github/scripts/requirements_dev.in
-pillow==12.1.0 \
-    --hash=sha256:00162e9ca6d22b7c3ee8e61faa3c3253cd19b6a37f126cad04f2f88b306f557d \
-    --hash=sha256:079af2fb0c599c2ec144ba2c02766d1b55498e373b3ac64687e43849fbbef5bc \
-    --hash=sha256:0b022eaaf709541b391ee069f0022ee5b36c709df71986e3f7be312e46f42c84 \
-    --hash=sha256:0c27407a2d1b96774cbc4a7594129cc027339fd800cd081e44497722ea1179de \
-    --hash=sha256:0ddedfaa8b5f0b4ffbc2fa87b556dc59f6bb4ecb14a53b33f9189713ae8053c0 \
-    --hash=sha256:0deedf2ea233722476b3a81e8cdfbad786f7adbed5d848469fa59fe52396e4ef \
-    --hash=sha256:0ed07dca4a8464bada6139ab38f5382f83e5f111698caf3191cb8dbf27d908b4 \
-    --hash=sha256:0fde7ec5538ab5095cc02df38ee99b0443ff0e1c847a045554cf5f9af1f4aa82 \
-    --hash=sha256:15c794d74303828eaa957ff8070846d0efe8c630901a1c753fdc63850e19ecd9 \
-    --hash=sha256:1a949604f73eb07a8adab38c4fe50791f9919344398bdc8ac6b307f755fc7030 \
-    --hash=sha256:1f345e7bc9d7f368887c712aa5054558bad44d2a301ddf9248599f4161abc7c0 \
-    --hash=sha256:1fcc52d86ce7a34fd17cb04e87cfdb164648a3662a6f20565910a99653d66c18 \
-    --hash=sha256:21e686a21078b0f9cb8c8a961d99e6a4ddb88e0fc5ea6e130172ddddc2e5221a \
-    --hash=sha256:2415373395a831f53933c23ce051021e79c8cd7979822d8cc478547a3f4da8ef \
-    --hash=sha256:277518bf4fe74aa91489e1b20577473b19ee70fb97c374aa50830b279f25841b \
-    --hash=sha256:27b9baecb428899db6c0de572d6d305cfaf38ca1596b5c0542a5182e3e74e8c6 \
-    --hash=sha256:29a4cef9cb672363926f0470afc516dbf7305a14d8c54f7abbb5c199cd8f8179 \
-    --hash=sha256:3413c2ae377550f5487991d444428f1a8ae92784aac79caa8b1e3b89b175f77e \
-    --hash=sha256:351889afef0f485b84078ea40fe33727a0492b9af3904661b0abbafee0355b72 \
-    --hash=sha256:3ffaa2f0659e2f740473bcf03c702c39a8d4b2b7ffc629052028764324842c64 \
-    --hash=sha256:40a8e3b9e8773876d6e30daed22f016509e3987bab61b3b7fe309d7019a87451 \
-    --hash=sha256:414b9a78e14ffeb98128863314e62c3f24b8a86081066625700b7985b3f529bd \
-    --hash=sha256:43aca0a55ce1eefc0aefa6253661cb54571857b1a7b2964bd8a1e3ef4b729924 \
-    --hash=sha256:43b4899cfd091a9693a1278c4982f3e50f7fb7cff5153b05174b4afc9593b616 \
-    --hash=sha256:461f9dfdafa394c59cd6d818bdfdbab4028b83b02caadaff0ffd433faf4c9a7a \
-    --hash=sha256:4f9f6a650743f0ddee5593ac9e954ba1bdbc5e150bc066586d4f26127853ab94 \
-    --hash=sha256:53d8b764726d3af1a138dd353116f774e3862ec7e3794e0c8781e30db0f35dfc \
-    --hash=sha256:565c986f4b45c020f5421a4cea13ef294dde9509a8577f29b2fc5edc7587fff8 \
-    --hash=sha256:5c5ae0a06e9ea030ab786b0251b32c7e4ce10e58d983c0d5c56029455180b5b9 \
-    --hash=sha256:5cb7bc1966d031aec37ddb9dcf15c2da5b2e9f7cc3ca7c54473a20a927e1eb91 \
-    --hash=sha256:5da841d81b1a05ef940a8567da92decaa15bc4d7dedb540a8c219ad83d91808a \
-    --hash=sha256:5fee4c04aad8932da9f8f710af2c1a15a83582cfb884152a9caa79d4efcdbf9c \
-    --hash=sha256:609e89d9f90b581c8d16358c9087df76024cf058fa693dd3e1e1620823f39670 \
-    --hash=sha256:6258f3260986990ba2fa8a874f8b6e808cf5abb51a94015ca3dc3c68aa4f30ea \
-    --hash=sha256:64efdf00c09e31efd754448a383ea241f55a994fd079866b92d2bbff598aad91 \
-    --hash=sha256:65b80c1ee7e14a87d6a068dd3b0aea268ffcabfe0498d38661b00c5b4b22e74c \
-    --hash=sha256:6741e6f3074a35e47c77b23a4e4f2d90db3ed905cb1c5e6e0d49bff2045632bc \
-    --hash=sha256:681088909d7e8fa9e31b9799aaa59ba5234c58e5e4f1951b4c4d1082a2e980e0 \
-    --hash=sha256:6b7a9d1db5dad90e2991645874f708e87d9a3c370c243c2d7684d28f7e133e6b \
-    --hash=sha256:7315f9137087c4e0ee73a761b163fc9aa3b19f5f606a7fc08d83fd3e4379af65 \
-    --hash=sha256:742aea052cf5ab5034a53c3846165bc3ce88d7c38e954120db0ab867ca242661 \
-    --hash=sha256:75af0b4c229ac519b155028fa1be632d812a519abba9b46b20e50c6caa184f19 \
-    --hash=sha256:7b5dd7cbae20285cdb597b10eb5a2c13aa9de6cde9bb64a3c1317427b1db1ae1 \
-    --hash=sha256:7d6daa89a00b58c37cb1747ec9fb7ac3bc5ffd5949f5888657dfddde6d1312e0 \
-    --hash=sha256:800429ac32c9b72909c671aaf17ecd13110f823ddb7db4dfef412a5587c2c24e \
-    --hash=sha256:806f3987ffe10e867bab0ddad45df1148a2b98221798457fa097ad85d6e8bc75 \
-    --hash=sha256:808b99604f7873c800c4840f55ff389936ef1948e4e87645eaf3fccbc8477ac4 \
-    --hash=sha256:80941e6d573197a0c28f394753de529bb436b1ca990ed6e765cf42426abc39f8 \
-    --hash=sha256:84cabc7095dd535ca934d57e9ce2a72ffd216e435a84acb06b2277b1de2689bd \
-    --hash=sha256:8637e29d13f478bc4f153d8daa9ffb16455f0a6cb287da1b432fdad2bfbd66c7 \
-    --hash=sha256:896866d2d436563fa2a43a9d72f417874f16b5545955c54a64941e87c1376c61 \
-    --hash=sha256:8e178e3e99d3c0ea8fc64b88447f7cac8ccf058af422a6cedc690d0eadd98c51 \
-    --hash=sha256:907bfa8a9cb790748a9aa4513e37c88c59660da3bcfffbd24a7d9e6abf224551 \
-    --hash=sha256:9212d6b86917a2300669511ed094a9406888362e085f2431a7da985a6b124f45 \
-    --hash=sha256:92a7fe4225365c5e3a8e598982269c6d6698d3e783b3b1ae979e7819f9cd55c1 \
-    --hash=sha256:935b9d1aed48fcfb3f838caac506f38e29621b44ccc4f8a64d575cb1b2a88644 \
-    --hash=sha256:97e9993d5ed946aba26baf9c1e8cf18adbab584b99f452ee72f7ee8acb882796 \
-    --hash=sha256:983976c2ab753166dc66d36af6e8ec15bb511e4a25856e2227e5f7e00a160587 \
-    --hash=sha256:9f5fefaca968e700ad1a4a9de98bf0869a94e397fe3524c4c9450c1445252304 \
-    --hash=sha256:a332ac4ccb84b6dde65dbace8431f3af08874bf9770719d32a635c4ef411b18b \
-    --hash=sha256:a40905599d8079e09f25027423aed94f2823adaf2868940de991e53a449e14a8 \
-    --hash=sha256:a6dfc2af5b082b635af6e08e0d1f9f1c4e04d17d4e2ca0ef96131e85eda6eb17 \
-    --hash=sha256:a786bf667724d84aa29b5db1c61b7bfdde380202aaca12c3461afd6b71743171 \
-    --hash=sha256:a83e0850cb8f5ac975291ebfc4170ba481f41a28065277f7f735c202cd8e0af3 \
-    --hash=sha256:aa0c9cc0b82b14766a99fbe6084409972266e82f459821cd26997a488a7261a7 \
-    --hash=sha256:b17fbdbe01c196e7e159aacb889e091f28e61020a8abeac07b68079b6e626988 \
-    --hash=sha256:b63e13dd27da389ed9475b3d28510f0f954bca0041e8e551b2a4eb1eab56a39a \
-    --hash=sha256:b6e53e82ec2db0717eabb276aa56cf4e500c9a7cec2c2e189b55c24f65a3e8c0 \
-    --hash=sha256:bb0984b30e973f7e2884362b7d23d0a348c7143ee559f38ef3eaab640144204c \
-    --hash=sha256:bc11908616c8a283cf7d664f77411a5ed2a02009b0097ff8abbba5e79128ccf2 \
-    --hash=sha256:bdec5e43377761c5dbca620efb69a77f6855c5a379e32ac5b158f54c84212b14 \
-    --hash=sha256:bef9768cab184e7ae6e559c032e95ba8d07b3023c289f79a2bd36e8bf85605a5 \
-    --hash=sha256:c990547452ee2800d8506c4150280757f88532f3de2a58e3022e9b179107862a \
-    --hash=sha256:ca94b6aac0d7af2a10ba08c0f888b3d5114439b6b3ef39968378723622fed377 \
-    --hash=sha256:cad302dc10fac357d3467a74a9561c90609768a6f73a1923b0fd851b6486f8b0 \
-    --hash=sha256:d0a7735df32ccbcc98b98a1ac785cc4b19b580be1bdf0aeb5c03223220ea09d5 \
-    --hash=sha256:d70347c8a5b7ccd803ec0c85c8709f036e6348f1e6a5bf048ecd9c64d3550b8b \
-    --hash=sha256:d70534cea9e7966169ad29a903b99fc507e932069a881d0965a1a84bb57f6c6d \
-    --hash=sha256:db44d5c160a90df2d24a24760bbd37607d53da0b34fb546c4c232af7192298ac \
-    --hash=sha256:e115c15e3bc727b1ca3e641a909f77f8ca72a64fff150f666fcc85e57701c26c \
-    --hash=sha256:e2479c7f02f9d505682dc47df8c0ea1fc5e264c4d1629a5d63fe3e2334b89554 \
-    --hash=sha256:e5dcbe95016e88437ecf33544ba5db21ef1b8dd6e1b434a2cb2a3d605299e643 \
-    --hash=sha256:e6bdb408f7c9dd2a5ff2b14a3b0bb6d4deb29fb9961e6eb3ae2031ae9a5cec13 \
-    --hash=sha256:e75d3dba8fc1ddfec0cd752108f93b83b4f8d6ab40e524a95d35f016b9683b09 \
-    --hash=sha256:efdc140e7b63b8f739d09a99033aa430accce485ff78e6d311973a67b6bf3208 \
-    --hash=sha256:f10c98f49227ed8383d28174ee95155a675c4ed7f85e2e573b04414f7e371bda \
-    --hash=sha256:f188028b5af6b8fb2e9a76ac0f841a575bd1bd396e46ef0840d9b88a48fdbcea \
-    --hash=sha256:f188d580bd870cda1e15183790d1cc2fa78f666e76077d103edf048eed9c356e \
-    --hash=sha256:f45bd71d1fa5e5749587613037b172e0b3b23159d1c00ef2fc920da6f470e6f0 \
-    --hash=sha256:f61333d817698bdcdd0f9d7793e365ac3d2a21c1f1eb02b32ad6aefb8d8ea831 \
-    --hash=sha256:fb125d860738a09d363a88daa0f59c4533529a90e564785e20fe875b200b6dbd
+pillow==12.2.0 \
+    --hash=sha256:00a2865911330191c0b818c59103b58a5e697cae67042366970a6b6f1b20b7f9 \
+    --hash=sha256:01afa7cf67f74f09523699b4e88c73fb55c13346d212a59a2db1f86b0a63e8c5 \
+    --hash=sha256:03e7e372d5240cc23e9f07deca4d775c0817bffc641b01e9c3af208dbd300987 \
+    --hash=sha256:03f6fab9219220f041c74aeaa2939ff0062bd5c364ba9ce037197f4c6d498cd9 \
+    --hash=sha256:042db20a421b9bafecc4b84a8b6e444686bd9d836c7fd24542db3e7df7baad9b \
+    --hash=sha256:0538bd5e05efec03ae613fd89c4ce0368ecd2ba239cc25b9f9be7ed426b0af1f \
+    --hash=sha256:0a34329707af4f73cf1782a36cd2289c0368880654a2c11f027bcee9052d35dd \
+    --hash=sha256:0c838a5125cee37e68edec915651521191cef1e6aa336b855f495766e77a366e \
+    --hash=sha256:144748b3af2d1b358d41286056d0003f47cb339b8c43a9ea42f5fea4d8c66b6e \
+    --hash=sha256:1610dd6c61621ae1cf811bef44d77e149ce3f7b95afe66a4512f8c59f25d9ebe \
+    --hash=sha256:1e1757442ed87f4912397c6d35a0db6a7b52592156014706f17658ff58bbf795 \
+    --hash=sha256:22db17c68434de69d8ecfc2fe821569195c0c373b25cccb9cbdacf2c6e53c601 \
+    --hash=sha256:25373b66e0dd5905ed63fa3cae13c82fbddf3079f2c8bf15c6fb6a35586324c1 \
+    --hash=sha256:2bb4a8d594eacdfc59d9e5ad972aa8afdd48d584ffd5f13a937a664c3e7db0ed \
+    --hash=sha256:2c727a6d53cb0018aadd8018c2b938376af27914a68a492f59dfcaca650d5eea \
+    --hash=sha256:2d192a155bbcec180f8564f693e6fd9bccff5a7af9b32e2e4bf8c9c69dbad6b5 \
+    --hash=sha256:2e589959f10d9824d39b350472b92f0ce3b443c0a3442ebf41c40cb8361c5b97 \
+    --hash=sha256:2e5a76d03a6c6dcef67edabda7a52494afa4035021a79c8558e14af25313d453 \
+    --hash=sha256:325ca0528c6788d2a6c3d40e3568639398137346c3d6e66bb61db96b96511c98 \
+    --hash=sha256:34c0d99ecccea270c04882cb3b86e7b57296079c9a4aff88cb3b33563d95afaa \
+    --hash=sha256:390ede346628ccc626e5730107cde16c42d3836b89662a115a921f28440e6a3b \
+    --hash=sha256:394167b21da716608eac917c60aa9b969421b5dcbbe02ae7f013e7b85811c69d \
+    --hash=sha256:3997232e10d2920a68d25191392e3a4487d8183039e1c74c2297f00ed1c50705 \
+    --hash=sha256:3adc9215e8be0448ed6e814966ecf3d9952f0ea40eb14e89a102b87f450660d8 \
+    --hash=sha256:3e080565d8d7c671db5802eedfb438e5565ffa40115216eabb8cd52d0ecce024 \
+    --hash=sha256:4a6c9fa44005fa37a91ebfc95d081e8079757d2e904b27103f4f5fa6f0bf78c0 \
+    --hash=sha256:4bfd07bc812fbd20395212969e41931001fd59eb55a60658b0e5710872e95286 \
+    --hash=sha256:4e6c62e9d237e9b65fac06857d511e90d8461a32adcc1b9065ea0c0fa3a28150 \
+    --hash=sha256:50d8520da2a6ce0af445fa6d648c4273c3eeefbc32d7ce049f22e8b5c3daecc2 \
+    --hash=sha256:51c4167c34b0d8ba05b547a3bb23578d0ba17b80a5593f93bd8ecb123dd336a3 \
+    --hash=sha256:56a3f9c60a13133a98ecff6197af34d7824de9b7b38c3654861a725c970c197b \
+    --hash=sha256:56b25336f502b6ed02e889f4ece894a72612fe885889a6e8c4c80239ff6e5f5f \
+    --hash=sha256:57850958fe9c751670e49b2cecf6294acc99e562531f4bd317fa5ddee2068463 \
+    --hash=sha256:58f62cc0f00fd29e64b29f4fd923ffdb3859c9f9e6105bfc37ba1d08994e8940 \
+    --hash=sha256:5c0a9f29ca8e79f09de89293f82fc9b0270bb4af1d58bc98f540cc4aedf03166 \
+    --hash=sha256:5cdfebd752ec52bf5bb4e35d9c64b40826bc5b40a13df7c3cda20a2c03a0f5ed \
+    --hash=sha256:5d04bfa02cc2d23b497d1e90a0f927070043f6cbf303e738300532379a4b4e0f \
+    --hash=sha256:5d2fd0fa6b5d9d1de415060363433f28da8b1526c1c129020435e186794b3795 \
+    --hash=sha256:62f5409336adb0663b7caa0da5c7d9e7bdbaae9ce761d34669420c2a801b2780 \
+    --hash=sha256:632ff19b2778e43162304d50da0181ce24ac5bb8180122cbe1bf4673428328c7 \
+    --hash=sha256:6562ace0d3fb5f20ed7290f1f929cae41b25ae29528f2af1722966a0a02e2aa1 \
+    --hash=sha256:673aa32138f3e7531ccdbca7b3901dba9b70940a19ccecc6a37c77d5fdeb05b5 \
+    --hash=sha256:6a6e67ea2e6feda684ed370f9a1c52e7a243631c025ba42149a2cc5934dec295 \
+    --hash=sha256:6a9adfc6d24b10f89588096364cc726174118c62130c817c2837c60cf08a392b \
+    --hash=sha256:6bb77b2dcb06b20f9f4b4a8454caa581cd4dd0643a08bacf821216a16d9c8354 \
+    --hash=sha256:6e6b2a0c538fc200b38ff9eb6628228b77908c319a005815f2dde585a0664b60 \
+    --hash=sha256:71cde9a1e1551df7d34a25462fc60325e8a11a82cc2e2f54578e5e9a1e153d65 \
+    --hash=sha256:7371b48c4fa448d20d2714c9a1f775a81155050d383333e0a6c15b1123dda005 \
+    --hash=sha256:766cef22385fa1091258ad7e6216792b156dc16d8d3fa607e7545b2b72061f1c \
+    --hash=sha256:7b14cc0106cd9aecda615dd6903840a058b4700fcb817687d0ee4fc8b6e389be \
+    --hash=sha256:7f84204dee22a783350679a0333981df803dac21a0190d706a50475e361c93f5 \
+    --hash=sha256:8023abc91fba39036dbce14a7d6535632f99c0b857807cbbbf21ecc9f4717f06 \
+    --hash=sha256:80b2da48193b2f33ed0c32c38140f9d3186583ce7d516526d462645fd98660ae \
+    --hash=sha256:8297651f5b5679c19968abefd6bb84d95fe30ef712eb1b2d9b2d31ca61267f4c \
+    --hash=sha256:88d387ff40b3ff7c274947ed3125dedf5262ec6919d83946753b5f3d7c67ea4c \
+    --hash=sha256:88ddbc66737e277852913bd1e07c150cc7bb124539f94c4e2df5344494e0a612 \
+    --hash=sha256:8bd7903a5f2a4545f6fd5935c90058b89d30045568985a71c79f5fd6edf9b91e \
+    --hash=sha256:8be29e59487a79f173507c30ddf57e733a357f67881430449bb32614075a40ab \
+    --hash=sha256:8c984051042858021a54926eb597d6ee3012393ce9c181814115df4c60b9a808 \
+    --hash=sha256:8cbeb542b2ebc6fcdacabf8aca8c1a97c9b3ad3927d46b8723f9d4f033288a0f \
+    --hash=sha256:8e9c4f5b3c546fa3458a29ab22646c1c6c787ea8f5ef51300e5a60300736905e \
+    --hash=sha256:90e6f81de50ad6b534cab6e5aef77ff6e37722b2f5d908686f4a5c9eba17a909 \
+    --hash=sha256:975385f4776fafde056abb318f612ef6285b10a1f12b8570f3647ad0d74b48ec \
+    --hash=sha256:9a8a34cc89c67a65ea7437ce257cea81a9dad65b29805f3ecee8c8fe8ff25ffe \
+    --hash=sha256:9aba9a17b623ef750a4d11b742cbafffeb48a869821252b30ee21b5e91392c50 \
+    --hash=sha256:9f08483a632889536b8139663db60f6724bfcb443c96f1b18855860d7d5c0fd4 \
+    --hash=sha256:a4e8f36e677d3336f35089648c8955c51c6d386a13cf6ee9c189c5f5bd713a9f \
+    --hash=sha256:a52edc8bfff4429aaabdf4d9ee0daadbbf8562364f940937b941f87a4290f5ff \
+    --hash=sha256:a830b1a40919539d07806aa58e1b114df53ddd43213d9c8b75847eee6c0182b5 \
+    --hash=sha256:aa88ccfe4e32d362816319ed727a004423aab09c5cea43c01a4b435643fa34eb \
+    --hash=sha256:af73337013e0b3b46f175e79492d96845b16126ddf79c438d7ea7ff27783a414 \
+    --hash=sha256:b1c1fbd8a5a1af3412a0810d060a78b5136ec0836c8a4ef9aa11807f2a22f4e1 \
+    --hash=sha256:b85f66ae9eb53e860a873b858b789217ba505e5e405a24b85c0464822fe88032 \
+    --hash=sha256:b86024e52a1b269467a802258c25521e6d742349d760728092e1bc2d135b4d76 \
+    --hash=sha256:bd9c0c7a0c681a347b3194c500cb1e6ca9cab053ea4d82a5cf45b6b754560136 \
+    --hash=sha256:bfa9c230d2fe991bed5318a5f119bd6780cda2915cca595393649fc118ab895e \
+    --hash=sha256:d362d1878f00c142b7e1a16e6e5e780f02be8195123f164edf7eddd911eefe7c \
+    --hash=sha256:d5d38f1411c0ed9f97bcb49b7bd59b6b7c314e0e27420e34d99d844b9ce3b6f3 \
+    --hash=sha256:dac8d77255a37e81a2efcbd1fc05f1c15ee82200e6c240d7e127e25e365c39ea \
+    --hash=sha256:dd025009355c926a84a612fecf58bb315a3f6814b17ead51a8e48d3823d9087f \
+    --hash=sha256:deede7c263feb25dba4e82ea23058a235dcc2fe1f6021025dc71f2b618e26104 \
+    --hash=sha256:e74473c875d78b8e9d5da2a70f7099549f9eb37ded4e2f6a463e60125bccd176 \
+    --hash=sha256:ee3120ae9dff32f121610bb08e4313be87e03efeadfc6c0d18f89127e24d0c24 \
+    --hash=sha256:eedf4b74eda2b5a4b2b2fb4c006d6295df3bf29e459e198c90ea48e130dc75c3 \
+    --hash=sha256:efd8c21c98c5cc60653bcb311bef2ce0401642b7ce9d09e03a7da87c878289d4 \
+    --hash=sha256:f1c943e96e85df3d3478f7b691f229887e143f81fedab9b20205349ab04d73ed \
+    --hash=sha256:f278f034eb75b4e8a13a54a876cc4a5ab39173d2cdd93a638e1b467fc545ac43 \
+    --hash=sha256:f3f40b3c5a968281fd507d519e444c35f0ff171237f4fdde090dd60699458421 \
+    --hash=sha256:f490f9368b6fc026f021db16d7ec2fbf7d89e2edb42e8ec09d2c60505f5729c7 \
+    --hash=sha256:fb043ee2f06b41473269765c2feae53fc2e2fbf96e5e22ca94fb5ad677856f06 \
+    --hash=sha256:fc3d34d4a8fbec3e88a79b92e5465e0f9b842b628675850d860b8bd300b159f5
     # via
     #   -r .github/scripts/requirements_dev.in
     #   pdf2image
     #   weasyprint
-platformdirs==4.5.1 \
-    --hash=sha256:61d5cdcc6065745cdd94f0f878977f8de9437be93de97c1c12f853c9c0cdcbda \
-    --hash=sha256:d03afa3963c806a9bed9d5125c8f4cb2fdaf74a55ab60e5d59b3fde758104d31
-    # via virtualenv
-pre-commit==4.5.1 \
-    --hash=sha256:3b3afd891e97337708c1674210f8eba659b52a38ea5f822ff142d10786221f77 \
-    --hash=sha256:eb545fcff725875197837263e977ea257a402056661f09dae08e4b149b030a61
+platformdirs==4.9.6 \
+    --hash=sha256:3bfa75b0ad0db84096ae777218481852c0ebc6c727b3168c1b9e0118e458cf0a \
+    --hash=sha256:e61adb1d5e5cb3441b4b7710bea7e4c12250ca49439228cc1021c00dcfac0917
+    # via
+    #   python-discovery
+    #   virtualenv
+pre-commit==4.6.0 \
+    --hash=sha256:718d2208cef53fdc38206e40524a6d4d9576d103eb16f0fec11c875e7716e9d9 \
+    --hash=sha256:e2cf246f7299edcabcf15f9b0571fdce06058527f0a06535068a86d38089f29b
     # via -r .github/scripts/requirements_dev.in
 pycparser==3.0 \
     --hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
@@ -377,6 +381,10 @@ pyphen==0.17.2 \
     --hash=sha256:3a07fb017cb2341e1d9ff31b8634efb1ae4dc4b130468c7c39dd3d32e7c3affd \
     --hash=sha256:f60647a9c9b30ec6c59910097af82bc5dd2d36576b918e44148d8b07ef3b4aa3
     # via weasyprint
+python-discovery==1.2.2 \
+    --hash=sha256:876e9c57139eb757cb5878cbdd9ae5379e5d96266c99ef731119e04fffe533bb \
+    --hash=sha256:e1ae95d9af875e78f15e19aed0c6137ab1bb49c200f21f5061786490c9585c7a
+    # via virtualenv
 pyyaml==6.0.3 \
     --hash=sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c \
     --hash=sha256:0150219816b6a1fa26fb4699fb7daa9caf09eb1999f3b70fb6e786805e80375a \
@@ -458,21 +466,21 @@ tinycss2==1.5.1 \
     # via
     #   cssselect2
     #   weasyprint
-tinyhtml5==2.0.0 \
-    --hash=sha256:086f998833da24c300c414d9fe81d9b368fd04cb9d2596a008421cbc705fcfcc \
-    --hash=sha256:13683277c5b176d070f82d099d977194b7a1e26815b016114f581a74bbfbf47e
+tinyhtml5==2.1.0 \
+    --hash=sha256:60a50ec3d938a37e491efa01af895853060943dcebb5627de5b10d188b338a67 \
+    --hash=sha256:6e11cfff38515834268daf89d5f85bbde0b6dd02e8d9e212d1385c2289b89f0a
     # via weasyprint
 unoserver==3.6 \
     --hash=sha256:25c360fa194396a89cb79b4edd2735f8e4f0fd8531e59db3952114585bd7df05 \
     --hash=sha256:e446bcb3638c51880f002aaeecab1cf74dfa9df81035f027f7ff2e081b6d7015
     # via -r .github/scripts/requirements_dev.in
-virtualenv==20.36.1 \
-    --hash=sha256:575a8d6b124ef88f6f51d56d656132389f961062a9177016a50e4f507bbcc19f \
-    --hash=sha256:8befb5c81842c641f8ee658481e42641c68b5eab3521d8e092d18320902466ba
+virtualenv==21.2.4 \
+    --hash=sha256:29d21e941795206138d0f22f4e45ff7050e5da6c6472299fb7103318763861ac \
+    --hash=sha256:b294ef68192638004d72524ce7ef303e9d0cf5a44c95ce2e54a7500a6381cada
     # via pre-commit
-weasyprint==68.0 \
-    --hash=sha256:447f40898b747cb44ac31a5d493d512e7441fd56e13f63744c099383bbf9cda9 \
-    --hash=sha256:c2cb40c71b50837c5971f00171c9e4078e8c9912dd7c217f3e90e068f11e8aa1
+weasyprint==68.1 \
+    --hash=sha256:4dc3ba63c68bbbce3e9617cb2226251c372f5ee90a8a484503b1c099da9cf5be \
+    --hash=sha256:d3b752049b453a5c95edb27ce78d69e9319af5a34f257fa0f4c738c701b4184e
     # via -r .github/scripts/requirements_dev.in
 webencodings==0.5.1 \
     --hash=sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78 \
@@ -481,27 +489,27 @@ webencodings==0.5.1 \
     #   cssselect2
     #   tinycss2
     #   tinyhtml5
-zopfli==0.4.0 \
-    --hash=sha256:03181d48e719fcb6cf8340189c61e8f9883d8bbbdf76bf5212a74457f7d083c1 \
-    --hash=sha256:18b5f1570f64d4988482e4466f10ef5f2a30f687c19ad62a64560f2152dc89eb \
-    --hash=sha256:25e4863b8dc30e5d5309f87c106b0b7d3da4ed0e340b8a52b36d4471e797589f \
-    --hash=sha256:7d66337be6d5613dec55213e9ac28f378c41e2cc04fbad4a10748e4df774ca85 \
-    --hash=sha256:9097e8e1dfdb7f5aea5464e469946857e80502b6d29ba1b232450916bd4a74d1 \
-    --hash=sha256:a8ee992b2549e090cd3f0178bf606dd41a29e0613a04cdf5054224662c72dce6 \
-    --hash=sha256:b72a010d205d00b2855acc2302772067362f9ab5a012e3550662aec60d28e6b3 \
-    --hash=sha256:b8bdb41fbfdc4738b7bdc09ed7c1e951579fae192391a5e694d59bb186cdbec7 \
-    --hash=sha256:c3ba02a9a6ca90481d2b2f68bab038b310d63a1e3b5ae305e95a6599787ed941 \
-    --hash=sha256:d1b98ad47c434ef213444a03ef2f826eeec100144d64f6a57504b9893d3931ce \
-    --hash=sha256:f67d04280065e24cb9a4174cb6b3d1f763687f8cb2963aa135ad8f57c6995f5a \
-    --hash=sha256:f94e4dd7d76b4fe9f5d9229372be20d7f786164eea5152d1af1c34298c3d5975
+zopfli==0.4.1 \
+    --hash=sha256:02086247dd12fda929f9bfe8b3962b6bcdbfc8c82e99255aebcf367867cf0760 \
+    --hash=sha256:07a5cdc5d1aaa6c288c5d9f5a5383042ba743641abf8e2fd898dcad622d8a38e \
+    --hash=sha256:27823dc1161a4031d1c25925fd45d9868ec0cbc7692341830a7dcfa25063662c \
+    --hash=sha256:2f992ac7d83cbddd889e1813ace576cbc91a05d5d7a0a21b366e2e5f492e7707 \
+    --hash=sha256:4238d4d746d1095e29c9125490985e0c12ffd3654f54a24af551e2391e936d54 \
+    --hash=sha256:5a4c22b6161f47f5bd34637dbaee6735abd287cd64e0d1ce28ef1871bf625f4b \
+    --hash=sha256:84a31ba9edc921b1d3a4449929394a993888f32d70de3a3617800c428a947b9b \
+    --hash=sha256:a899eca405662a23ae75054affa3517a060362eae1185d3d791c86a50153c4dd \
+    --hash=sha256:a93c2ecafff372de6c0aa2212eff18a75f6c71a100372fee7b4b129cc0b6f9a7 \
+    --hash=sha256:cb136a74d14a4ecfae29cb0fdecece58a6c115abc9a74c12bc6ac62e80f229d7 \
+    --hash=sha256:d7bcee1b189d64ec33d1e05cfa1b6a1268c29329c382f6ca1bd6245b04925c57 \
+    --hash=sha256:fdfb7ce9f5de37a5b2f75dd2642fd7717956ef2a72e0387302a36d382440db07
     # via fonttools
 
 # The following packages are considered to be unsafe in a requirements file:
-pip==26.0 \
-    --hash=sha256:3ce220a0a17915972fbf1ab451baae1521c4539e778b28127efa79b974aff0fa \
-    --hash=sha256:98436feffb9e31bc9339cf369fd55d3331b1580b6a6f1173bacacddcf9c34754
+pip==26.0.1 \
+    --hash=sha256:bdb1b08f4274833d62c1aa29e20907365a2ceb950410df15fc9521bad440122b \
+    --hash=sha256:c4037d8a277c89b320abe636d59f91e6d0922d08a05b60e85e53b296613346d8
     # via -r .github/scripts/requirements_dev.in
-setuptools==80.10.2 \
-    --hash=sha256:8b0e9d10c784bf7d262c4e5ec5d4ec94127ce206e8738f29a437945fbc219b70 \
-    --hash=sha256:95b30ddfb717250edb492926c92b5221f7ef3fbcc2b07579bcd4a27da21d0173
+setuptools==82.0.1 \
+    --hash=sha256:7d872682c5d01cfde07da7bccc7b65469d3dca203318515ada1de5eda35efbf9 \
+    --hash=sha256:a59e362652f08dcd477c78bb6e7bd9d80a7995bc73ce773050228a348ce2e5bb
     # via -r .github/scripts/requirements_dev.in

.github/scripts/requirements_pre_commit.txt

@@ -12,26 +12,34 @@ distlib==0.4.0 \
     --hash=sha256:9659f7d87e46584a30b5780e43ac7a2143098441670ff0a49d5f9034c54a6c16 \
     --hash=sha256:feec40075be03a04501a973d81f633735b4b69f98b05450592310c0f401a4e0d
     # via virtualenv
-filelock==3.20.3 \
-    --hash=sha256:18c57ee915c7ec61cff0ecf7f0f869936c7c30191bb0cf406f1341778d0834e1 \
-    --hash=sha256:4b0dda527ee31078689fc205ec4f1c1bf7d56cf88b6dc9426c4f230e46c2dce1
-    # via virtualenv
-identify==2.6.16 \
-    --hash=sha256:391ee4d77741d994189522896270b787aed8670389bfd60f326d677d64a6dfb0 \
-    --hash=sha256:846857203b5511bbe94d5a352a48ef2359532bc8f6727b5544077a0dcfb24980
+filelock==3.29.0 \
+    --hash=sha256:69974355e960702e789734cb4871f884ea6fe50bd8404051a3530bc07809cf90 \
+    --hash=sha256:96f5f6344709aa1572bbf631c640e4ebeeb519e08da902c39a001882f30ac258
+    # via
+    #   python-discovery
+    #   virtualenv
+identify==2.6.19 \
+    --hash=sha256:20e6a87f786f768c092a721ad107fc9df0eb89347be9396cadf3f4abbd1fb78a \
+    --hash=sha256:6be5020c38fcb07da56c53733538a3081ea5aa70d36a156f83044bfbf9173842
     # via pre-commit
 nodeenv==1.10.0 \
     --hash=sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827 \
     --hash=sha256:996c191ad80897d076bdfba80a41994c2b47c68e224c542b48feba42ba00f8bb
     # via pre-commit
-platformdirs==4.5.1 \
-    --hash=sha256:61d5cdcc6065745cdd94f0f878977f8de9437be93de97c1c12f853c9c0cdcbda \
-    --hash=sha256:d03afa3963c806a9bed9d5125c8f4cb2fdaf74a55ab60e5d59b3fde758104d31
-    # via virtualenv
-pre-commit==4.5.1 \
-    --hash=sha256:3b3afd891e97337708c1674210f8eba659b52a38ea5f822ff142d10786221f77 \
-    --hash=sha256:eb545fcff725875197837263e977ea257a402056661f09dae08e4b149b030a61
+platformdirs==4.9.6 \
+    --hash=sha256:3bfa75b0ad0db84096ae777218481852c0ebc6c727b3168c1b9e0118e458cf0a \
+    --hash=sha256:e61adb1d5e5cb3441b4b7710bea7e4c12250ca49439228cc1021c00dcfac0917
+    # via
+    #   python-discovery
+    #   virtualenv
+pre-commit==4.6.0 \
+    --hash=sha256:718d2208cef53fdc38206e40524a6d4d9576d103eb16f0fec11c875e7716e9d9 \
+    --hash=sha256:e2cf246f7299edcabcf15f9b0571fdce06058527f0a06535068a86d38089f29b
     # via -r .github/scripts/requirements_pre_commit.in
+python-discovery==1.2.2 \
+    --hash=sha256:876e9c57139eb757cb5878cbdd9ae5379e5d96266c99ef731119e04fffe533bb \
+    --hash=sha256:e1ae95d9af875e78f15e19aed0c6137ab1bb49c200f21f5061786490c9585c7a
+    # via virtualenv
 pyyaml==6.0.3 \
     --hash=sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c \
     --hash=sha256:0150219816b6a1fa26fb4699fb7daa9caf09eb1999f3b70fb6e786805e80375a \
@@ -107,7 +115,7 @@ pyyaml==6.0.3 \
     --hash=sha256:fa160448684b4e94d80416c0fa4aac48967a969efe22931448d853ada8baf926 \
     --hash=sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0
     # via pre-commit
-virtualenv==20.36.1 \
-    --hash=sha256:575a8d6b124ef88f6f51d56d656132389f961062a9177016a50e4f507bbcc19f \
-    --hash=sha256:8befb5c81842c641f8ee658481e42641c68b5eab3521d8e092d18320902466ba
+virtualenv==21.2.4 \
+    --hash=sha256:29d21e941795206138d0f22f4e45ff7050e5da6c6472299fb7103318763861ac \
+    --hash=sha256:b294ef68192638004d72524ce7ef303e9d0cf5a44c95ce2e54a7500a6381cada
     # via pre-commit

.github/workflows/PR-Auto-Deploy-V2.yml

@@ -35,13 +35,13 @@ jobs:
       pr_ref: ${{ steps.resolve.outputs.ref }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: Resolve PR info
         id: resolve
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const { owner, repo } = context.repo;
@@ -111,7 +111,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -132,7 +132,7 @@ jobs:
 
       - name: Add deployment started comment
         id: deployment-started
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -180,7 +180,7 @@ jobs:
           fetch-depth: 0 # Fetch full history for commit hash detection
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Get version number
         id: versionNumber
@@ -189,7 +189,7 @@ jobs:
           echo "versionNumber=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_API }}
@@ -226,11 +226,13 @@ jobs:
 
       - name: Build and push V2 image
         if: steps.check-image.outputs.exists == 'false'
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           file: ./docker/embedded/Dockerfile
           push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
           tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-${{ steps.commit-hash.outputs.app_short }}
           build-args: VERSION_TAG=v2-alpha
           platforms: linux/amd64
@@ -307,7 +309,7 @@ jobs:
 
       - name: Post V2 deployment URL to PR
         if: success()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -357,7 +359,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -374,7 +376,7 @@ jobs:
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
       - name: Clean up V2 deployment comments
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |

.github/workflows/PR-Demo-Comment-with-react.yml

@@ -3,6 +3,31 @@ name: PR Deployment via Comment
 on:
   issue_comment:
     types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to deploy"
+        required: true
+      enable_prototypes:
+        description: "Build with prototypes frontend"
+        required: false
+        type: boolean
+        default: false
+      enable_pro:
+        description: "Enable pro features"
+        required: false
+        type: boolean
+        default: false
+      enable_enterprise:
+        description: "Enable enterprise features"
+        required: false
+        type: boolean
+        default: false
+      disable_security:
+        description: "Disable security/login"
+        required: false
+        type: boolean
+        default: true
 
 permissions:
   contents: read
@@ -14,23 +39,27 @@ jobs:
     permissions:
       issues: write
     if: |
-      vars.CI_PROFILE != 'lite' &&
-      github.event.issue.pull_request &&
-      (
-        contains(github.event.comment.body, 'prdeploy') ||
-        contains(github.event.comment.body, 'deploypr')
-      )
-      &&
-      (
-        github.event.comment.user.login == 'frooodle' ||
-        github.event.comment.user.login == 'sf298' ||
-        github.event.comment.user.login == 'Ludy87' ||
-        github.event.comment.user.login == 'balazs-szucs' ||
-        github.event.comment.user.login == 'reecebrowne' ||
-        github.event.comment.user.login == 'DarioGii' ||
-        github.event.comment.user.login == 'EthanHealy01' ||
-        github.event.comment.user.login == 'jbrunton96' ||
-        github.event.comment.user.login == 'ConnorYoh'
+      vars.CI_PROFILE != 'lite' && (
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event.issue.pull_request &&
+          (
+            contains(github.event.comment.body, 'prdeploy') ||
+            contains(github.event.comment.body, 'deploypr')
+          )
+          &&
+          (
+            github.event.comment.user.login == 'frooodle' ||
+            github.event.comment.user.login == 'sf298' ||
+            github.event.comment.user.login == 'Ludy87' ||
+            github.event.comment.user.login == 'balazs-szucs' ||
+            github.event.comment.user.login == 'reecebrowne' ||
+            github.event.comment.user.login == 'DarioGii' ||
+            github.event.comment.user.login == 'EthanHealy01' ||
+            github.event.comment.user.login == 'jbrunton96' ||
+            github.event.comment.user.login == 'ConnorYoh'
+          )
+        )
       )
     outputs:
       pr_number: ${{ steps.get-pr.outputs.pr_number }}
@@ -38,9 +67,10 @@ jobs:
       disable_security: ${{ steps.check-security-flag.outputs.disable_security }}
       enable_pro: ${{ steps.check-pro-flag.outputs.enable_pro }}
       enable_enterprise: ${{ steps.check-pro-flag.outputs.enable_enterprise }}
+      enable_prototypes: ${{ steps.check-prototypes-flag.outputs.enable_prototypes }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -58,10 +88,12 @@ jobs:
 
       - name: Get PR data
         id: get-pr
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
-            const prNumber = context.payload.issue.number;
+            const prNumber = context.eventName === 'workflow_dispatch'
+              ? context.payload.inputs.pr_number
+              : context.payload.issue.number;
             console.log(`PR Number: ${prNumber}`);
             core.setOutput('pr_number', prNumber);
 
@@ -69,12 +101,14 @@ jobs:
         id: check-security-flag
         env:
           COMMENT_BODY: ${{ github.event.comment.body }}
+          IS_DISPATCH: ${{ github.event_name == 'workflow_dispatch' }}
+          DISPATCH_DISABLE_SECURITY: ${{ inputs.disable_security }}
         run: |
-          if [[ "$COMMENT_BODY" == *"security"* ]] || [[ "$COMMENT_BODY" == *"login"* ]]; then
-            echo "Security flags detected in comment"
+          if [[ "$IS_DISPATCH" == "true" ]]; then
+            echo "disable_security=$DISPATCH_DISABLE_SECURITY" >> $GITHUB_OUTPUT
+          elif [[ "$COMMENT_BODY" == *"security"* ]] || [[ "$COMMENT_BODY" == *"login"* ]]; then
             echo "disable_security=false" >> $GITHUB_OUTPUT
           else
-            echo "No security flags detected in comment"
             echo "disable_security=true" >> $GITHUB_OUTPUT
           fi
 
@@ -82,24 +116,45 @@ jobs:
         id: check-pro-flag
         env:
           COMMENT_BODY: ${{ github.event.comment.body }}
+          IS_DISPATCH: ${{ github.event_name == 'workflow_dispatch' }}
+          DISPATCH_PRO: ${{ inputs.enable_pro }}
+          DISPATCH_ENTERPRISE: ${{ inputs.enable_enterprise }}
         run: |
-          if [[ "$COMMENT_BODY" == *"pro"* ]] || [[ "$COMMENT_BODY" == *"premium"* ]]; then
-            echo "pro flags detected in comment"
+          if [[ "$IS_DISPATCH" == "true" ]]; then
+            echo "enable_pro=$DISPATCH_PRO" >> $GITHUB_OUTPUT
+            echo "enable_enterprise=$DISPATCH_ENTERPRISE" >> $GITHUB_OUTPUT
+          elif [[ "$COMMENT_BODY" == *"pro"* ]] || [[ "$COMMENT_BODY" == *"premium"* ]]; then
             echo "enable_pro=true" >> $GITHUB_OUTPUT
             echo "enable_enterprise=false" >> $GITHUB_OUTPUT
           elif [[ "$COMMENT_BODY" == *"enterprise"* ]]; then
-            echo "enterprise flags detected in comment"
             echo "enable_enterprise=true" >> $GITHUB_OUTPUT
             echo "enable_pro=true" >> $GITHUB_OUTPUT
           else
-            echo "No pro or enterprise flags detected in comment"
             echo "enable_pro=false" >> $GITHUB_OUTPUT
             echo "enable_enterprise=false" >> $GITHUB_OUTPUT
           fi
 
+      - name: Check for prototypes flag
+        id: check-prototypes-flag
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          IS_DISPATCH: ${{ github.event_name == 'workflow_dispatch' }}
+          DISPATCH_PROTOTYPES: ${{ inputs.enable_prototypes }}
+        run: |
+          if [[ "$IS_DISPATCH" == "true" ]]; then
+            echo "enable_prototypes=$DISPATCH_PROTOTYPES" >> $GITHUB_OUTPUT
+          elif [[ "$COMMENT_BODY" == *"prototypes"* ]]; then
+            echo "Prototypes flag detected in comment"
+            echo "enable_prototypes=true" >> $GITHUB_OUTPUT
+          else
+            echo "No prototypes flag detected in comment"
+            echo "enable_prototypes=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Add 'in_progress' reaction to comment
+        if: github.event_name == 'issue_comment'
         id: add-eyes-reaction
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -128,7 +183,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -150,17 +205,19 @@ jobs:
           ref: refs/pull/${{ needs.check-comment.outputs.pr_number }}/merge
           token: ${{ steps.setup-bot.outputs.token }}
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Run Gradle Command
         run: |
           if [ "${{ needs.check-comment.outputs.disable_security }}" == "true" ]; then
@@ -168,7 +225,7 @@ jobs:
           else
             export DISABLE_ADDITIONAL_FEATURES=false
           fi
-          ./gradlew build
+          task backend:build
         env:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
@@ -176,22 +233,38 @@ jobs:
           STIRLING_PDF_DESKTOP_UI: false
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_API }}
 
       - name: Build and push PR-specific image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           file: ./docker/embedded/Dockerfile
           push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
           tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:pr-${{ needs.check-comment.outputs.pr_number }}
-          build-args: VERSION_TAG=alpha
+          build-args: |
+            VERSION_TAG=alpha
+            PROTOTYPES_BUILD=${{ needs.check-comment.outputs.enable_prototypes }}
+          platforms: linux/amd64
+
+      - name: Build and push engine image
+        if: needs.check-comment.outputs.enable_prototypes == 'true'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: ./engine
+          file: ./engine/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-pdf-engine
+          cache-to: type=gha,mode=max,scope=stirling-pdf-engine
+          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:engine-pr-${{ needs.check-comment.outputs.pr_number }}
           platforms: linux/amd64
 
       - name: Set up SSH
@@ -229,33 +302,64 @@ jobs:
             PREMIUM_PROFEATURES_AUDIT_ENABLED="false"
           fi
 
+          ENABLE_PROTOTYPES="${{ needs.check-comment.outputs.enable_prototypes }}"
+          PR_NUMBER="${{ needs.check-comment.outputs.pr_number }}"
+          DOCKER_USER="${{ secrets.DOCKER_HUB_USERNAME }}"
+
+          # Build engine env vars for backend (only set when prototypes enabled)
+          if [ "$ENABLE_PROTOTYPES" == "true" ]; then
+            AI_ENGINE_VARS="
+                SYSTEM_AIENGINE_ENABLED: \"true\"
+                SYSTEM_AIENGINE_URL: \"http://stirling-pdf-engine-pr-${PR_NUMBER}:5001\""
+            ENGINE_SERVICE="
+            stirling-pdf-engine:
+              container_name: stirling-pdf-engine-pr-${PR_NUMBER}
+              image: ${DOCKER_USER}/test:engine-pr-${PR_NUMBER}
+              environment:
+                ANTHROPIC_API_KEY: \"${{ secrets.ANTHROPIC_API_KEY }}\"
+              networks:
+                - pr-network
+              restart: on-failure:5"
+            NETWORK_SECTION="
+          networks:
+            pr-network:"
+            BACKEND_NETWORK="
+              networks:
+                - pr-network"
+          else
+            AI_ENGINE_VARS=""
+            ENGINE_SERVICE=""
+            NETWORK_SECTION=""
+            BACKEND_NETWORK=""
+          fi
+
           # First create the docker-compose content locally
           cat > docker-compose.yml << EOF
           version: '3.3'
           services:
             stirling-pdf:
-              container_name: stirling-pdf-pr-${{ needs.check-comment.outputs.pr_number }}
-              image: ${{ secrets.DOCKER_HUB_USERNAME }}/test:pr-${{ needs.check-comment.outputs.pr_number }}
+              container_name: stirling-pdf-pr-${PR_NUMBER}
+              image: ${DOCKER_USER}/test:pr-${PR_NUMBER}
               ports:
-                - "${{ needs.check-comment.outputs.pr_number }}:8080"
+                - "${PR_NUMBER}:8080"
               volumes:
-                - /stirling/PR-${{ needs.check-comment.outputs.pr_number }}/data:/usr/share/tessdata:rw
-                - /stirling/PR-${{ needs.check-comment.outputs.pr_number }}/config:/configs:rw
-                - /stirling/PR-${{ needs.check-comment.outputs.pr_number }}/logs:/logs:rw
+                - /stirling/PR-${PR_NUMBER}/data:/usr/share/tessdata:rw
+                - /stirling/PR-${PR_NUMBER}/config:/configs:rw
+                - /stirling/PR-${PR_NUMBER}/logs:/logs:rw
               environment:
                 DISABLE_ADDITIONAL_FEATURES: "${DISABLE_ADDITIONAL_FEATURES}"
                 SECURITY_ENABLELOGIN: "${LOGIN_SECURITY}"
                 SYSTEM_DEFAULTLOCALE: en-GB
-                UI_APPNAME: "Stirling-PDF PR#${{ needs.check-comment.outputs.pr_number }}"
-                UI_HOMEDESCRIPTION: "PR#${{ needs.check-comment.outputs.pr_number }} for Stirling-PDF Latest"
-                UI_APPNAMENAVBAR: "PR#${{ needs.check-comment.outputs.pr_number }}"
+                UI_APPNAME: "Stirling-PDF PR#${PR_NUMBER}"
+                UI_HOMEDESCRIPTION: "PR#${PR_NUMBER} for Stirling-PDF Latest"
+                UI_APPNAMENAVBAR: "PR#${PR_NUMBER}"
                 SYSTEM_MAXFILESIZE: "100"
                 METRICS_ENABLED: "true"
                 SYSTEM_GOOGLEVISIBILITY: "false"
                 PREMIUM_KEY:                         "${PREMIUM_KEY}"
                 PREMIUM_ENABLED:                     "${PREMIUM_ENABLED}"
-                PREMIUM_PROFEATURES_AUDIT_ENABLED:   "${PREMIUM_PROFEATURES_AUDIT_ENABLED}"
-              restart: on-failure:5
+                PREMIUM_PROFEATURES_AUDIT_ENABLED:   "${PREMIUM_PROFEATURES_AUDIT_ENABLED}"${AI_ENGINE_VARS}
+              restart: on-failure:5${BACKEND_NETWORK}${ENGINE_SERVICE}${NETWORK_SECTION}
           EOF
 
           # Then copy the file and execute commands
@@ -263,13 +367,13 @@ jobs:
 
           ssh -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -T ${{ secrets.NEW_VPS_USERNAME }}@${{ secrets.NEW_VPS_HOST }} << ENDSSH
             # Create PR-specific directories
-            mkdir -p /stirling/PR-${{ needs.check-comment.outputs.pr_number }}/{data,config,logs}
+            mkdir -p /stirling/PR-${PR_NUMBER}/{data,config,logs}
 
             # Move docker-compose file to correct location
-            mv /tmp/docker-compose.yml /stirling/PR-${{ needs.check-comment.outputs.pr_number }}/docker-compose.yml
+            mv /tmp/docker-compose.yml /stirling/PR-${PR_NUMBER}/docker-compose.yml
 
             # Start or restart the container
-            cd /stirling/PR-${{ needs.check-comment.outputs.pr_number }}
+            cd /stirling/PR-${PR_NUMBER}
             docker-compose pull
             docker-compose up -d
           ENDSSH
@@ -278,8 +382,8 @@ jobs:
           echo "security_status=${SECURITY_STATUS}" >> $GITHUB_ENV
 
       - name: Add success reaction to comment
-        if: success()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        if: success() && github.event_name == 'issue_comment'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -313,8 +417,8 @@ jobs:
             }
 
       - name: Add failure reaction to comment
-        if: failure()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        if: failure() && github.event_name == 'issue_comment'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -334,7 +438,7 @@ jobs:
 
       - name: Post deployment URL to PR
         if: success()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -370,7 +474,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -385,7 +489,7 @@ jobs:
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
       - name: Apply label commands
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |

.github/workflows/PR-Demo-cleanup.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -39,7 +39,7 @@ jobs:
 
       - name: Remove 'pr-deployed' label if present
         id: remove-label-comment
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -121,8 +121,9 @@ jobs:
               # Remove PR-specific directories
               rm -rf /stirling/PR-${{ github.event.pull_request.number }}
 
-              # Remove the Docker image
+              # Remove the Docker images
               docker rmi --no-prune ${{ secrets.DOCKER_HUB_USERNAME }}/test:pr-${{ github.event.pull_request.number }} || true
+              docker rmi --no-prune ${{ secrets.DOCKER_HUB_USERNAME }}/test:engine-pr-${{ github.event.pull_request.number }} || true
 
               echo "PERFORMED_CLEANUP"
             else

.github/workflows/ai-engine.yml

@@ -0,0 +1,115 @@
+name: AI Engine CI
+
+# Validates the Python AI engine: regenerates tool models, runs fixers,
+# lint, type-check, and tests. Called from build.yml on PRs and merge_group;
+# also runs directly on push to main as a post-merge safety net.
+on:
+  workflow_call:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  engine:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+
+      - name: Regenerate tool models
+        run: task engine:tool-models
+
+      - name: Verify tool models are up to date
+        run: |
+          if ! git diff --exit-code engine/src/stirling/models/tool_models.py; then
+            echo "tool_models.py is out of date."
+            echo "Run 'task engine:tool-models' locally and commit the updated file."
+            exit 1
+          fi
+
+      - name: Run fixers
+        run: task engine:fix
+
+      - name: Verify fixes are committed
+        id: fixer_changes
+        run: |
+          if ! git diff --quiet; then
+            git --no-pager diff --stat
+            echo "::error::There are issues with your Python code that will need to be fixed before they can be merged in. Run 'task engine:fix' to auto-fix what can be fixed automatically, then run 'task engine:check' to see what still needs fixing manually."
+            exit 1
+          fi
+
+      - name: Comment on fixer failures
+        if: steps.fixer_changes.outcome == 'failure' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- engine-check -->';
+            const body = [
+              marker,
+              '### Engine Check Failed',
+              '',
+              'There are issues with your Python code that will need to be fixed before they can be merged in.',
+              '',
+              'Run `task engine:fix` to auto-fix what can be fixed automatically, then run `task engine:check` to see what still needs fixing manually.',
+            ].join('\n');
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Run linting
+        run: task engine:lint
+
+      - name: Run type checking
+        run: task engine:typecheck
+
+      - name: Run tests
+        run: task engine:test

.github/workflows/ai_pr_title_review.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -87,7 +87,7 @@ jobs:
       - name: AI PR Title Analysis
         if: steps.actor.outputs.is_repo_dev == 'true'
         id: ai-title-analysis
-        uses: actions/ai-inference@a6101c89c6feaecc585efdd8d461f18bb7896f20 # v2.0.5
+        uses: actions/ai-inference@e09e65981758de8b2fdab13c2bfb7c7d5493b0b6 # v2.0.7
         with:
           model: openai/gpt-4o
           system-prompt-file: ".github/config/system-prompt.txt"
@@ -158,7 +158,7 @@ jobs:
 
       - name: Post comment on PR if needed
         if: steps.actor.outputs.is_repo_dev == 'true'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         continue-on-error: true
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}

.github/workflows/aur-publish.yml

@@ -0,0 +1,128 @@
+name: Publish to AUR
+
+on:
+  release:
+    types: [released]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish (e.g. 2.9.2 — no v prefix)"
+        required: true
+        type: string
+      dry_run:
+        description: "Skip the AUR push (safe test)"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  get-release-info:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.info.outputs.version }}
+      deb_sha256: ${{ steps.hashes.outputs.deb_sha256 }}
+      jar_sha256: ${{ steps.hashes.outputs.jar_sha256 }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Extract version from tag or manual input
+        id: info
+        env:
+          DISPATCH_VERSION: ${{ inputs.version }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="$DISPATCH_VERSION"
+          else
+            VERSION="$RELEASE_TAG"
+          fi
+          VERSION="${VERSION#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Download release assets and compute SHA256
+        id: hashes
+        env:
+          VERSION: ${{ steps.info.outputs.version }}
+        run: |
+          BASE="https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v${VERSION}"
+
+          download_sha256() {
+            local url="$1"
+            local file
+            file=$(basename "$url")
+            curl -fsSL --retry 3 -o "$file" "$url"
+            sha256sum "$file" | awk '{print $1}'
+          }
+
+          DEB_SHA=$(download_sha256 "${BASE}/Stirling-PDF-linux-x86_64.deb")
+          JAR_SHA=$(download_sha256 "${BASE}/Stirling-PDF-with-login.jar")
+
+          echo "deb_sha256=$DEB_SHA" >> "$GITHUB_OUTPUT"
+          echo "jar_sha256=$JAR_SHA" >> "$GITHUB_OUTPUT"
+
+  publish-aur:
+    needs: get-release-info
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository (for PKGBUILD templates)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Update stirling-pdf-desktop PKGBUILD
+        env:
+          VERSION: ${{ needs.get-release-info.outputs.version }}
+          DEB_SHA: ${{ needs.get-release-info.outputs.deb_sha256 }}
+        run: |
+          PKGBUILD=".github/aur/stirling-pdf-desktop/PKGBUILD"
+          sed -i "s/^pkgver=.*/pkgver=${VERSION}/" "$PKGBUILD"
+          sed -i "s/^pkgrel=.*/pkgrel=1/" "$PKGBUILD"
+          sed -i "s/'PLACEHOLDER_DEB_SHA256'/'${DEB_SHA}'/" "$PKGBUILD"
+
+      # Disabled until we sort out the server packaging story.
+      # The third-party stirling-pdf-bin on AUR currently covers a similar use case.
+      # - name: Update stirling-pdf-server-bin PKGBUILD
+      #   env:
+      #     VERSION: ${{ needs.get-release-info.outputs.version }}
+      #     JAR_SHA: ${{ needs.get-release-info.outputs.jar_sha256 }}
+      #   run: |
+      #     PKGBUILD=".github/aur/stirling-pdf-server-bin/PKGBUILD"
+      #     sed -i "s/^pkgver=.*/pkgver=${VERSION}/" "$PKGBUILD"
+      #     sed -i "s/^pkgrel=.*/pkgrel=1/" "$PKGBUILD"
+      #     sed -i "s/'PLACEHOLDER_JAR_SHA256'/'${JAR_SHA}'/" "$PKGBUILD"
+
+      - name: Show updated PKGBUILD (for dry-run visibility)
+        run: |
+          echo "--- stirling-pdf-desktop PKGBUILD ---"
+          cat .github/aur/stirling-pdf-desktop/PKGBUILD
+
+      - name: Publish stirling-pdf-desktop to AUR
+        if: ${{ github.event_name == 'release' || inputs.dry_run == false }}
+        uses: KSXGitHub/github-actions-deploy-aur@v4.1.3
+        with:
+          pkgname: stirling-pdf-desktop
+          pkgbuild: .github/aur/stirling-pdf-desktop/PKGBUILD
+          commit_username: Stirling PDF Inc
+          commit_email: contact@stirlingpdf.com
+          ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+          commit_message: "Update to v${{ needs.get-release-info.outputs.version }}"
+
+      # Disabled until we sort out the server packaging story.
+      # - name: Publish stirling-pdf-server-bin to AUR
+      #   if: ${{ github.event_name == 'release' || inputs.dry_run == false }}
+      #   uses: KSXGitHub/github-actions-deploy-aur@2ac5a4c1d7035885d46b10e3193393be8460b6f1 # v4.1.1
+      #   with:
+      #     pkgname: stirling-pdf-server-bin
+      #     pkgbuild: .github/aur/stirling-pdf-server-bin/PKGBUILD
+      #     commit_username: Stirling PDF Inc
+      #     commit_email: contact@stirlingpdf.com
+      #     ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+      #     commit_message: "Update to v${{ needs.get-release-info.outputs.version }}"

.github/workflows/auto-labelerV2.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -29,7 +29,7 @@ jobs:
           app-id: ${{ secrets.GH_APP_ID }}
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
-      - uses: srvaroa/labeler@0a20eccb8c94a1ee0bed5f16859aece1c45c3e55 # v1.13.0
+      - uses: srvaroa/labeler@bf262763a8a8e191f5847873aecc0f29df84f957 # v1.14.0
         with:
           config_path: .github/labeler-config-srvaroa.yml
           use_local_config: false

.github/workflows/backend-build.yml

@@ -0,0 +1,175 @@
+name: Backend build, format check, and coverage
+
+# Reusable workflow called from build.yml. Runs the backend build matrix
+# (JDK 25 × spring-security on/off), Spotless formatting check, JUnit, and
+# posts Jacoco coverage to PRs.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  pull-requests: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        jdk-version: [25]
+        spring-security: [true, false]
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up JDK ${{ matrix.jdk-version }}
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: ${{ matrix.jdk-version }}
+          distribution: "temurin"
+
+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-${{ matrix.jdk-version }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+          cache-disabled: true
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Check Java formatting (Spotless)
+        if: matrix.jdk-version == 25 && matrix.spring-security == false
+        id: spotless-check
+        run: task backend:format:check
+        continue-on-error: true
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+
+      - name: Comment on Java formatting failure
+        # Only post a comment on PRs. github-script's PR helpers need an
+        # issue/PR number, which doesn't exist on merge_group runs.
+        if: steps.spotless-check.outcome == 'failure' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- java-formatting-check -->';
+            const body = [
+              marker,
+              '### Java Formatting Check Failed',
+              '',
+              'Your code has formatting issues. Run the following command to fix them:',
+              '',
+              '```bash',
+              'task backend:format',
+              '```',
+              '',
+              'Then commit and push the changes.',
+            ].join('\n');
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Fail if Java formatting issues found
+        if: steps.spotless-check.outcome == 'failure'
+        run: |
+          echo "============================================"
+          echo "  Java Formatting Check Failed"
+          echo "============================================"
+          echo ""
+          echo "Your code has formatting issues."
+          echo "Run the following command to fix them:"
+          echo ""
+          echo "  task backend:format"
+          echo ""
+          echo "Then commit and push the changes."
+          echo "============================================"
+          exit 1
+
+      - name: Build with Gradle and spring security ${{ matrix.spring-security }}
+        run: task backend:build:ci
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+          DISABLE_ADDITIONAL_FEATURES: ${{ matrix.spring-security }}
+
+      - name: Check Test Reports Exist
+        if: always()
+        run: |
+          declare -a dirs=(
+            "app/core/build/reports/tests/"
+            "app/core/build/test-results/"
+            "app/common/build/reports/tests/"
+            "app/common/build/test-results/"
+            "app/proprietary/build/reports/tests/"
+            "app/proprietary/build/test-results/"
+          )
+          for dir in "${dirs[@]}"; do
+            if [ ! -d "$dir" ]; then
+              echo "Missing $dir"
+              exit 1
+            fi
+          done
+
+      - name: Upload Test Reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: test-reports-jdk-${{ matrix.jdk-version }}-spring-security-${{ matrix.spring-security }}
+          path: |
+            app/**/build/reports/jacoco/test
+            app/**/build/reports/tests/
+            app/**/build/test-results/
+            app/**/build/reports/problems/
+            build/reports/problems/
+          retention-days: 3
+          if-no-files-found: warn
+
+      - name: Add coverage to PR with spring security ${{ matrix.spring-security }} and JDK ${{ matrix.jdk-version }}
+        # The action only supports the pull_request event (it posts a PR comment),
+        # so skip it for merge_group runs and workflow_dispatch.
+        if: github.event_name == 'pull_request'
+        id: jacoco
+        uses: madrapps/jacoco-report@50d3aff4548aa991e6753342d9ba291084e63848 # v1.7.2
+        with:
+          paths: |
+            ${{ github.workspace }}/**/build/reports/jacoco/test/jacocoTestReport.xml
+          token: ${{ secrets.GITHUB_TOKEN }}
+          min-coverage-overall: 10
+          min-coverage-changed-files: 0
+          comment-type: summary

.github/workflows/build-enterprise.yml

@@ -0,0 +1,272 @@
+name: Enterprise E2E (Playwright)
+
+# Enterprise Playwright suite — exercises premium-key gated features (audit,
+# teams, analytics) plus full OAuth + SAML logins via the Keycloak compose
+# stacks under testing/compose. Slow and secret-gated, so it runs in three
+# situations:
+#
+#   - PRs that touch proprietary / premium / SSO compose / enterprise tests
+#     (driven by build.yml via workflow_call, path-filtered against
+#     .github/config/.files.yaml `proprietary`),
+#   - every push to main (post-merge safety net),
+#   - on a nightly cron schedule (catches Keycloak image drift, license
+#     expiry, upstream proprietary changes),
+#   - manual workflow_dispatch.
+#
+# Auto-skipped when secrets.PREMIUM_KEY_ENTERPRISE is missing (forks, dependabot).
+
+on:
+  workflow_call:
+  push:
+    branches: ["main"]
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+# No `concurrency:` block here on purpose. When this workflow is called via
+# workflow_call from build.yml, ${{ github.workflow }}/event_name/pr_number
+# resolve to the *caller's* values, producing the same group key as build.yml
+# and causing the workflow_call instantiation to self-cancel — the job
+# silently fails to spawn while `${{ needs.X.result }}` still reports
+# `failure`. Standalone runs (push-to-main, nightly cron, dispatch) don't
+# overlap often enough to need explicit concurrency control.
+
+permissions:
+  contents: read
+
+jobs:
+  playwright-e2e-enterprise:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      PREMIUM_KEY: ${{ secrets.PREMIUM_KEY_ENTERPRISE }}
+      PREMIUM_ENABLED: "true"
+      SYSTEM_ENABLEANALYTICS: "false"
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Install Playwright (chromium only)
+        run: task e2e:install -- chromium
+      - name: Build frontend (needed for playwright's vite preview webServer)
+        # Enterprise tests target :8080 (Spring Boot's bundled frontend), but
+        # playwright's webServer config still launches `vite preview --port 5173`
+        # before any test run, which needs dist/ to exist. VITE_BUILD_FOR_PREVIEW
+        # forces absolute asset paths so vite preview can serve deep SPA routes.
+        env:
+          VITE_BUILD_FOR_PREVIEW: "1"
+        run: task frontend:build
+
+      - name: Resolve kubernetes.docker.internal to localhost
+        # The compose stacks set KC_HOSTNAME=kubernetes.docker.internal so
+        # Keycloak issues redirect URIs against that host. Docker Desktop
+        # auto-resolves it; GHA runners don't. Map it to 127.0.0.1 so the
+        # browser-driven OAuth flow lands back on Stirling-PDF correctly.
+        run: |
+          echo "127.0.0.1 kubernetes.docker.internal" | sudo tee -a /etc/hosts
+
+      # Helper function used by all phases — boots `:stirling-pdf:bootRun`
+      # with the React frontend baked in (-PbuildWithFrontend=true) so the
+      # SPA serves on :8080 and OAuth/SAML callbacks land on the same host
+      # that the browser is interacting with.
+      - name: Define helpers
+        run: |
+          {
+            echo 'wait_for_backend() {'
+            echo '  start=$SECONDS'
+            echo '  for i in $(seq 1 300); do'
+            echo '    if curl -fsS http://localhost:8080/api/v1/info/status >/dev/null 2>&1; then'
+            echo '      echo "Backend up after $((SECONDS - start))s"; return 0'
+            echo '    fi; sleep 2'
+            echo '  done'
+            echo '  tail -200 /tmp/backend.log || true; return 1'
+            echo '}'
+            echo 'stop_backend() {'
+            echo '  if [ -f /tmp/backend.pid ]; then'
+            echo '    kill "$(cat /tmp/backend.pid)" 2>/dev/null || true'
+            echo '    rm -f /tmp/backend.pid'
+            echo '  fi'
+            echo '  pkill -f "gradlew :stirling-pdf:bootRun" 2>/dev/null || true'
+            echo '  for i in $(seq 1 30); do'
+            echo '    curl -fsS http://localhost:8080/api/v1/info/status >/dev/null 2>&1 || return 0'
+            echo '    sleep 1'
+            echo '  done'
+            echo '}'
+          } > /tmp/helpers.sh
+          chmod +x /tmp/helpers.sh
+
+      # ───────── OAuth round-trip ─────────
+      - name: Bring up Keycloak (OAuth realm)
+        working-directory: testing/compose
+        run: docker compose -f docker-compose-keycloak-oauth.yml up -d --no-deps keycloak-oauth-db keycloak-oauth
+      - name: Wait for Keycloak (OAuth) ready
+        working-directory: testing/compose
+        run: |
+          for i in $(seq 1 60); do
+            bash validate-oauth-test.sh 2>/dev/null && exit 0 || true
+            # validate script also pings stirling on :8080 — accept just the
+            # keycloak realm as our gate here, stirling boots in the next step
+            curl -fsS http://localhost:9080/realms/stirling-oauth >/dev/null 2>&1 && exit 0
+            sleep 5
+          done
+          docker compose -f docker-compose-keycloak-oauth.yml logs --tail=200 keycloak-oauth
+          exit 1
+      - name: Boot Stirling-PDF (frontend baked in, OAuth env)
+        env:
+          SECURITY_ENABLELOGIN: "true"
+          SECURITY_LOGINMETHOD: "all"
+          SECURITY_OAUTH2_ENABLED: "true"
+          SECURITY_OAUTH2_AUTOCREATEUSER: "true"
+          # Keycloak issues redirect URIs against KC_HOSTNAME, which the
+          # compose default sets to kubernetes.docker.internal. Match here
+          # (resolves to localhost via /etc/hosts mapping above).
+          SECURITY_OAUTH2_CLIENT_KEYCLOAK_ISSUER: "http://kubernetes.docker.internal:9080/realms/stirling-oauth"
+          SECURITY_OAUTH2_CLIENT_KEYCLOAK_CLIENTID: "stirling-pdf-client"
+          SECURITY_OAUTH2_CLIENT_KEYCLOAK_CLIENTSECRET: "test-client-secret-change-in-production"
+          SECURITY_OAUTH2_CLIENT_KEYCLOAK_USEASUSERNAME: "email"
+          SECURITY_OAUTH2_CLIENT_KEYCLOAK_SCOPES: "openid,profile,email"
+        run: |
+          source /tmp/helpers.sh
+          nohup ./gradlew :stirling-pdf:bootRun -PbuildWithFrontend=true > /tmp/backend.log 2>&1 &
+          echo $! > /tmp/backend.pid
+          wait_for_backend
+      - name: Run enterprise OAuth Playwright tests
+        id: oauth-tests
+        run: task e2e:enterprise -- --grep "OAuth"
+      - name: Stop backend + tear down OAuth Keycloak
+        if: always()
+        run: |
+          source /tmp/helpers.sh
+          stop_backend
+          (cd testing/compose && docker compose -f docker-compose-keycloak-oauth.yml down -v)
+
+      # ───────── SAML round-trip ─────────
+      - name: Bring up Keycloak (SAML realm)
+        working-directory: testing/compose
+        run: docker compose -f docker-compose-keycloak-saml.yml up -d --no-deps keycloak-saml-db keycloak-saml
+      - name: Wait for Keycloak (SAML) ready
+        working-directory: testing/compose
+        run: |
+          for i in $(seq 1 60); do
+            curl -fsS http://localhost:9080/realms/stirling-saml >/dev/null 2>&1 && exit 0
+            sleep 5
+          done
+          docker compose -f docker-compose-keycloak-saml.yml logs --tail=200 keycloak-saml
+          exit 1
+      - name: Generate SAML SP certs + fetch Keycloak IdP cert
+        # The .pem/.crt/.key files are gitignored (test-only certs); the
+        # docker-based start-saml-test.sh generates them at runtime, so do
+        # the same in CI before bootRun reads them.
+        working-directory: testing/compose
+        run: |
+          openssl req -x509 -newkey rsa:2048 \
+            -keyout saml-private-key.key \
+            -out saml-public-cert.crt \
+            -days 3650 -nodes \
+            -subj "/CN=stirling-pdf-saml-sp" >/dev/null 2>&1
+          # Fetch Keycloak's SAML signing cert from the realm descriptor
+          CERT_BODY=$(curl -sf http://localhost:9080/realms/stirling-saml/protocol/saml/descriptor \
+            | awk 'BEGIN{RS="<[^>]*X509Certificate>|</[^>]*X509Certificate>"} NR==2{gsub(/[[:space:]]+/,""); print; exit}')
+          {
+            echo "-----BEGIN CERTIFICATE-----"
+            echo "$CERT_BODY"
+            echo "-----END CERTIFICATE-----"
+          } > keycloak-saml-cert.pem
+          test -s saml-private-key.key
+          test -s saml-public-cert.crt
+          test -s keycloak-saml-cert.pem
+          echo "✓ SAML certs prepared"
+      - name: Boot Stirling-PDF (frontend baked in, SAML env)
+        env:
+          SECURITY_ENABLELOGIN: "true"
+          SECURITY_LOGINMETHOD: "all"
+          SECURITY_SAML2_ENABLED: "true"
+          SECURITY_SAML2_AUTOCREATEUSER: "true"
+          SECURITY_SAML2_PROVIDER: "keycloak"
+          SECURITY_SAML2_REGISTRATIONID: "keycloak"
+          SECURITY_SAML2_IDP_ISSUER: "http://localhost:9080/realms/stirling-saml"
+          SECURITY_SAML2_IDP_ENTITYID: "http://localhost:9080/realms/stirling-saml"
+          SECURITY_SAML2_IDP_METADATAURI: "http://localhost:9080/realms/stirling-saml/protocol/saml/descriptor"
+          SECURITY_SAML2_IDPSINGLELOGINURL: "http://localhost:9080/realms/stirling-saml/protocol/saml"
+          SECURITY_SAML2_IDPSINGLELOGOUTURL: "http://localhost:9080/realms/stirling-saml/protocol/saml"
+          SECURITY_SAML2_IDP_CERT: "${{ github.workspace }}/testing/compose/keycloak-saml-cert.pem"
+          SECURITY_SAML2_PRIVATEKEY: "${{ github.workspace }}/testing/compose/saml-private-key.key"
+          SECURITY_SAML2_SP_CERT: "${{ github.workspace }}/testing/compose/saml-public-cert.crt"
+          # Realm registers the SP entity as the metadata URL — see
+          # keycloak-realm-saml.json `clientId`. Match it here so Keycloak
+          # accepts the AuthnRequest issuer.
+          SECURITY_SAML2_SP_ENTITYID: "http://localhost:8080/saml2/service-provider-metadata/keycloak"
+          SECURITY_SAML2_SP_ACS: "http://localhost:8080/login/saml2/sso/keycloak"
+          SECURITY_SAML2_SP_SLS: "http://localhost:8080/logout/saml2/slo"
+        run: |
+          source /tmp/helpers.sh
+          nohup ./gradlew :stirling-pdf:bootRun -PbuildWithFrontend=true > /tmp/backend.log 2>&1 &
+          echo $! > /tmp/backend.pid
+          wait_for_backend
+      - name: Run enterprise SAML Playwright tests
+        id: saml-tests
+        run: task e2e:enterprise -- --grep "SAML"
+      - name: Stop backend + tear down SAML Keycloak
+        if: always()
+        run: |
+          source /tmp/helpers.sh
+          stop_backend
+          (cd testing/compose && docker compose -f docker-compose-keycloak-saml.yml down -v)
+
+      # ───────── License-gated feature tests (no IdP needed) ─────────
+      - name: Wipe DB so InitialSecuritySetup re-runs with admin/adminadmin
+        # Earlier phases (OAuth, SAML) create the default admin/stirling user.
+        # InitialSecuritySetup only honours SECURITY_INITIALLOGIN_* when the
+        # admin user doesn't already exist, so the persisted DB has to be
+        # cleared between phases for the feature env vars to take effect.
+        run: |
+          rm -f app/core/configs/stirling-pdf-DB*.mv.db
+          rm -rf app/core/configs/backup
+      - name: Boot Stirling-PDF (frontend baked in, premium only)
+        env:
+          SECURITY_INITIALLOGIN_USERNAME: admin
+          SECURITY_INITIALLOGIN_PASSWORD: adminadmin
+          SECURITY_ENABLELOGIN: "true"
+          SECURITY_LOGINMETHOD: "all"
+        run: |
+          source /tmp/helpers.sh
+          nohup ./gradlew :stirling-pdf:bootRun -PbuildWithFrontend=true > /tmp/backend.log 2>&1 &
+          echo $! > /tmp/backend.pid
+          wait_for_backend
+      - name: Run enterprise feature Playwright tests
+        id: feature-tests
+        run: task e2e:enterprise -- --grep "Enterprise license"
+      - name: Print backend log on failure
+        if: failure()
+        run: |
+          echo "::group::Enterprise backend log"
+          tail -500 /tmp/backend.log || true
+          echo "::endgroup::"
+      - name: Stop backend (final)
+        if: always()
+        run: |
+          source /tmp/helpers.sh
+          stop_backend
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report-enterprise-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 7

.github/workflows/build.yml

@@ -1,8 +1,18 @@
 name: Build and Test Workflow
 
+# Top-level PR / merge-queue gate. Detects which paths changed and dispatches
+# to the dedicated reusable workflows under .github/workflows/. Each child
+# workflow keeps its own setup/teardown so this file stays a routing layer.
+#
+# The final `all-checks-passed` job is the single status check that branch
+# protection should require — it succeeds only if every required upstream
+# job either succeeded or was legitimately skipped by its path filter.
+
 on:
   pull_request:
     branches: ["main"]
+  merge_group:
+    branches: ["main"]
   workflow_dispatch:
 
 # cancel in-progress jobs if a new job is triggered
@@ -30,358 +40,193 @@ jobs:
       project: ${{ steps.changes.outputs.project }}
       openapi: ${{ steps.changes.outputs.openapi }}
       frontend: ${{ steps.changes.outputs.frontend }}
+      docker-base: ${{ steps.changes.outputs.docker-base }}
+      tauri: ${{ steps.changes.outputs.tauri }}
+      engine: ${{ steps.changes.outputs.engine }}
+      proprietary: ${{ steps.changes.outputs.proprietary }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: changes
         with:
           filters: .github/config/.files.yaml
 
   build:
-    runs-on: ubuntu-latest
+    needs: [files-changed]
     permissions:
       actions: read
+      contents: read
       security-events: write
-    strategy:
-      fail-fast: false
-      matrix:
-        jdk-version: [17, 21]
-        spring-security: [true, false]
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up JDK ${{ matrix.jdk-version }}
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: ${{ matrix.jdk-version }}
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: Build with Gradle and spring security ${{ matrix.spring-security }}
-        run: ./gradlew build -PnoSpotless
-        env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-          DISABLE_ADDITIONAL_FEATURES: ${{ matrix.spring-security }}
-
-      - name: Check Test Reports Exist
-        if: always()
-        run: |
-          declare -a dirs=(
-            "app/core/build/reports/tests/"
-            "app/core/build/test-results/"
-            "app/common/build/reports/tests/"
-            "app/common/build/test-results/"
-            "app/proprietary/build/reports/tests/"
-            "app/proprietary/build/test-results/"
-          )
-          for dir in "${dirs[@]}"; do
-            if [ ! -d "$dir" ]; then
-              echo "Missing $dir"
-              exit 1
-            fi
-          done
-
-      - name: Upload Test Reports
-        if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
-        with:
-          name: test-reports-jdk-${{ matrix.jdk-version }}-spring-security-${{ matrix.spring-security }}
-          path: |
-            app/**/build/reports/jacoco/test
-            app/**/build/reports/tests/
-            app/**/build/test-results/
-            app/**/build/reports/problems/
-            build/reports/problems/
-          retention-days: 3
-          if-no-files-found: warn
-
-      - name: Add coverage to PR with spring security ${{ matrix.spring-security }} and JDK ${{ matrix.jdk-version }}
-        id: jacoco
-        uses: madrapps/jacoco-report@50d3aff4548aa991e6753342d9ba291084e63848 # v1.7.2
-        with:
-          paths: |
-            ${{ github.workspace }}/**/build/reports/jacoco/test/jacocoTestReport.xml
-          token: ${{ secrets.GITHUB_TOKEN }}
-          min-coverage-overall: 10
-          min-coverage-changed-files: 0
-          comment-type: summary
+      pull-requests: write
+    uses: ./.github/workflows/backend-build.yml
+    secrets: inherit
 
   check-generateOpenApiDocs:
     if: needs.files-changed.outputs.openapi == 'true'
     needs: [files-changed]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: "21"
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: Generate OpenAPI documentation
-        run: ./gradlew :stirling-pdf:generateOpenApiDocs
-        env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-          DISABLE_ADDITIONAL_FEATURES: true
-
-      - name: Upload OpenAPI Documentation
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
-        with:
-          name: openapi-docs
-          path: ./SwaggerDoc.json
+    permissions:
+      contents: read
+    uses: ./.github/workflows/check-openapi.yml
+    secrets: inherit
 
   frontend-validation:
     if: needs.files-changed.outputs.frontend == 'true'
-    needs: files-changed
-    runs-on: ubuntu-latest
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Set up Node.js
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
-        with:
-          node-version: "22"
-          cache: "npm"
-          cache-dependency-path: frontend/package-lock.json
-      - name: Install frontend dependencies
-        run: cd frontend && npm ci
-      - name: Type-check frontend
-        run: cd frontend && npm run prebuild && npm run typecheck:all
-      - name: Lint frontend
-        run: cd frontend && npm run lint
-      - name: Build frontend
-        run: cd frontend && npm run build
-      - name: Run frontend tests
-        run: cd frontend && npm run test -- --run
-      - name: Upload frontend build artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
-        with:
-          name: frontend-build
-          path: frontend/dist/
-          retention-days: 3
+    needs: [files-changed]
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/frontend-validation.yml
+    secrets: inherit
+
+  playwright-e2e:
+    if: needs.files-changed.outputs.frontend == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/e2e-stubbed.yml
+    secrets: inherit
+
+  playwright-e2e-live:
+    if: needs.files-changed.outputs.frontend == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/e2e-live.yml
+    secrets: inherit
+
+  playwright-e2e-enterprise:
+    if: needs.files-changed.outputs.proprietary == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/build-enterprise.yml
+    secrets: inherit
 
   check-licence:
     if: needs.files-changed.outputs.build == 'true'
     needs: [files-changed, build]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: "21"
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: check the licenses for compatibility
-        run: ./gradlew checkLicense
-        env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-
-      - name: FAILED - check the licenses for compatibility
-        if: failure()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
-        with:
-          name: dependencies-without-allowed-license.json
-          path: build/reports/dependency-license/dependencies-without-allowed-license.json
-          retention-days: 3
+    permissions:
+      contents: read
+    uses: ./.github/workflows/check-licence.yml
+    secrets: inherit
 
   docker-compose-tests:
     if: needs.files-changed.outputs.project == 'true'
-    needs: files-changed
-    # if: github.event_name == 'push' && github.ref == 'refs/heads/main' ||
-    #     (github.event_name == 'pull_request' &&
-    #     contains(github.event.pull_request.labels.*.name, 'licenses') == false &&
-    #     (
-    #       contains(github.event.pull_request.labels.*.name, 'Front End') ||
-    #       contains(github.event.pull_request.labels.*.name, 'Java') ||
-    #       contains(github.event.pull_request.labels.*.name, 'Back End') ||
-    #       contains(github.event.pull_request.labels.*.name, 'Security') ||
-    #       contains(github.event.pull_request.labels.*.name, 'API') ||
-    #       contains(github.event.pull_request.labels.*.name, 'Docker') ||
-    #       contains(github.event.pull_request.labels.*.name, 'Test')
-    #     )
-    #     )
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout Repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: "21"
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
-
-      - name: Install Docker Compose
-        run: |
-          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
-          sudo chmod +x /usr/local/bin/docker-compose
-
-      - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
-        with:
-          python-version: "3.12"
-          cache: "pip" # caching pip dependencies
-          cache-dependency-path: ./testing/cucumber/requirements.txt
-
-      - name: Pip requirements
-        run: |
-          pip install --require-hashes -r ./testing/cucumber/requirements.txt
-
-      - name: Run Docker Compose Tests
-        run: |
-          chmod +x ./testing/test_webpages.sh
-          chmod +x ./testing/test.sh
-          chmod +x ./testing/test_disabledEndpoints.sh
-          ./testing/test.sh
-        env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+    needs: [files-changed]
+    permissions:
+      actions: write
+      contents: read
+      checks: write
+    uses: ./.github/workflows/docker-compose-tests.yml
+    secrets: inherit
+    with:
+      docker-base-changed: ${{ needs.files-changed.outputs.docker-base }}
 
   test-build-docker-images:
     if: github.event_name == 'pull_request' && needs.files-changed.outputs.project == 'true'
     needs: [files-changed, build, check-generateOpenApiDocs, check-licence]
+    permissions:
+      contents: read
+      packages: read
+    uses: ./.github/workflows/test-build-docker.yml
+    secrets: inherit
+    with:
+      docker-base-changed: ${{ needs.files-changed.outputs.docker-base }}
+
+  tauri-build:
+    if: needs.files-changed.outputs.tauri == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/tauri-build.yml
+    secrets: inherit
+
+  ai-engine:
+    if: needs.files-changed.outputs.engine == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/ai-engine.yml
+    secrets: inherit
+
+  pre-commit:
+    needs: [files-changed]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/pre_commit.yml
+    secrets: inherit
+
+  dependency-review:
+    needs: [files-changed]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/dependency-review.yml
+    secrets: inherit
+
+  # Single status check that branch protection should mark as required.
+  # Succeeds when every upstream job is either `success` or `skipped` (path-
+  # gated jobs that didn't apply this run). Any `failure` or `cancelled`
+  # result fails the gate. `if: always()` ensures the gate evaluates even
+  # when an upstream job fails.
+  all-checks-passed:
+    name: All checks passed
+    if: always()
+    needs:
+      - files-changed
+      - build
+      - check-generateOpenApiDocs
+      - frontend-validation
+      - playwright-e2e
+      - playwright-e2e-live
+      - playwright-e2e-enterprise
+      - check-licence
+      - docker-compose-tests
+      - test-build-docker-images
+      - tauri-build
+      - ai-engine
+      - pre-commit
+      - dependency-review
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - docker-rev: docker/embedded/Dockerfile
-            artifact-suffix: Dockerfile
-          - docker-rev: docker/embedded/Dockerfile.ultra-lite
-            artifact-suffix: Dockerfile.ultra-lite
-          - docker-rev: docker/embedded/Dockerfile.fat
-            artifact-suffix: Dockerfile.fat
     steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout Repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Free disk space on runner
-        run: |
-          echo "Disk space before cleanup:" && df -h
-          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android /usr/local/share/boost
-          docker system prune -af || true
-          echo "Disk space after cleanup:" && df -h
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: "21"
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: Build application
-        run: ./gradlew build
+      - name: Verify every required job passed (or was legitimately skipped)
         env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-          DISABLE_ADDITIONAL_FEATURES: true
-          STIRLING_PDF_DESKTOP_UI: false
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
-
-      - name: Set up Docker Buildx
-        id: buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
-
-      - name: Build ${{ matrix.docker-rev }}
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
-        with:
-          builder: ${{ steps.buildx.outputs.name }}
-          context: .
-          file: ./${{ matrix.docker-rev }}
-          push: false
-          cache-from: type=gha,scope=${{ matrix.artifact-suffix }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.artifact-suffix }}
-          platforms: linux/amd64,linux/arm64/v8
-          provenance: true
-          sbom: true
-
-      - name: Upload Reports
-        if: always()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
-        with:
-          name: reports-docker-${{ matrix.artifact-suffix }}
-          path: |
-            build/reports/tests/
-            build/test-results/
-            build/reports/problems/
-          retention-days: 3
-          if-no-files-found: warn
+          RESULTS: |
+            files-changed=${{ needs.files-changed.result }}
+            build=${{ needs.build.result }}
+            check-generateOpenApiDocs=${{ needs.check-generateOpenApiDocs.result }}
+            frontend-validation=${{ needs.frontend-validation.result }}
+            playwright-e2e=${{ needs.playwright-e2e.result }}
+            playwright-e2e-live=${{ needs.playwright-e2e-live.result }}
+            playwright-e2e-enterprise=${{ needs.playwright-e2e-enterprise.result }}
+            check-licence=${{ needs.check-licence.result }}
+            docker-compose-tests=${{ needs.docker-compose-tests.result }}
+            test-build-docker-images=${{ needs.test-build-docker-images.result }}
+            tauri-build=${{ needs.tauri-build.result }}
+            ai-engine=${{ needs.ai-engine.result }}
+            pre-commit=${{ needs.pre-commit.result }}
+            dependency-review=${{ needs.dependency-review.result }}
+        run: |
+          ok=true
+          while IFS='=' read -r name result; do
+            [ -z "$name" ] && continue
+            case "$result" in
+              success|skipped) printf '  %-30s %s\n' "$name" "$result" ;;
+              *)               printf '✗ %-30s %s\n' "$name" "$result"; ok=false ;;
+            esac
+          done <<< "$RESULTS"
+          if [ "$ok" != "true" ]; then
+            echo ""
+            echo "One or more required checks failed or were cancelled."
+            exit 1
+          fi
+          echo ""
+          echo "All required checks passed."

.github/workflows/check-licence.yml

@@ -0,0 +1,59 @@
+name: License compatibility check
+
+# Reusable workflow called from build.yml when build.gradle / module gradle
+# files change. Verifies all transitive dependencies use a permitted license.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-licence:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+          cache-disabled: true
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Check licenses for compatibility
+        run: task backend:licenses:check
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+
+      - name: FAILED - check the licenses for compatibility
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dependencies-without-allowed-license.json
+          path: build/reports/dependency-license/dependencies-without-allowed-license.json
+          retention-days: 3

.github/workflows/check-openapi.yml

@@ -0,0 +1,59 @@
+name: Generate OpenAPI documentation
+
+# Reusable workflow called from build.yml when backend Java sources change.
+# Generates SwaggerDoc.json so we know the doc still builds against the
+# current code.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-generate-openapi-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+          cache-disabled: true
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Generate OpenAPI documentation
+        run: task backend:swagger
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+          DISABLE_ADDITIONAL_FEATURES: true
+
+      - name: Upload OpenAPI Documentation
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: openapi-docs
+          path: ./SwaggerDoc.json

.github/workflows/check_toml.yml

@@ -27,7 +27,7 @@ jobs:
       pull-requests: write # Allow writing to pull requests
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -43,7 +43,7 @@ jobs:
 
       - name: Get PR data
         id: get-pr-data
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -87,7 +87,7 @@ jobs:
 
       - name: Determine reference file
         id: determine-file
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -196,12 +196,13 @@ jobs:
             core.exportVariable("REFERENCE_FILE", referenceFilePath);
 
       - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.12"
 
       - name: Install Python dependencies
-        run: pip install --require-hashes -r ./.github/scripts/requirements_sync_readme.txt
+        run: |
+          pip install --require-hashes --only-binary=:all: -r ./.github/scripts/requirements_sync_readme.txt
 
       - name: Run Python script to check files
         id: run-check
@@ -239,7 +240,7 @@ jobs:
 
       - name: Post comment on PR
         if: env.SCRIPT_OUTPUT != ''
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |

.github/workflows/dependency-review.yml

@@ -1,13 +1,10 @@
-# Dependency Review Action
-#
-# This Action will scan dependency manifest files that change as part of a Pull Request,
-# surfacing known-vulnerable versions of the packages declared or updated in the PR.
-# Once installed, if the workflow run is marked as required,
-# PRs introducing known-vulnerable packages will be blocked from merging.
-#
-# Source repository: https://github.com/actions/dependency-review-action
-name: "Dependency Review"
-on: [pull_request]
+name: Dependency Review
+
+# Reusable workflow called from build.yml. Scans dependency manifest files
+# changing in a PR for known-vulnerable packages, using the rules in
+# .github/config/dependency-review-config.yml.
+on:
+  workflow_call:
 
 permissions:
   contents: read
@@ -17,13 +14,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: "Checkout Repository"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: "Dependency Review"
-        uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # v4.8.2
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
           config-file: "./.github/config/dependency-review-config.yml"

.github/workflows/deploy-on-v2-commit.yml

@@ -18,7 +18,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -26,7 +26,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Get commit hashes for frontend and backend
         id: commit-hashes
@@ -85,18 +85,20 @@ jobs:
           fi
 
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_API }}
 
       - name: Build and push frontend image
         if: steps.check-frontend.outputs.exists == 'false'
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           file: ./docker/frontend/Dockerfile
           push: true
+          cache-from: type=gha,scope=stirling-v2-frontend
+          cache-to: type=gha,mode=max,scope=stirling-v2-frontend
           tags: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-frontend-${{ steps.commit-hashes.outputs.frontend_short }}
             ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-frontend-latest
@@ -105,11 +107,13 @@ jobs:
 
       - name: Build and push backend image
         if: steps.check-backend.outputs.exists == 'false'
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           file: ./docker/backend/Dockerfile
           push: true
+          cache-from: type=gha,scope=stirling-v2-backend
+          cache-to: type=gha,mode=max,scope=stirling-v2-backend
           tags: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-backend-${{ steps.commit-hashes.outputs.backend_short }}
             ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-backend-latest

.github/workflows/docker-compose-tests.yml

@@ -0,0 +1,116 @@
+name: Docker Compose Cucumber tests
+
+# Reusable workflow called from build.yml when project / docker / testing
+# sources change. Boots the docker-compose stack and runs the cucumber
+# scenarios in testing/cucumber.
+on:
+  workflow_call:
+    inputs:
+      docker-base-changed:
+        description: "Whether the docker base image changed (forwarded from files-changed)."
+        required: false
+        type: string
+        default: "false"
+
+permissions:
+  contents: read
+
+jobs:
+  docker-compose-tests:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+      contents: read
+      checks: write
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout Repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+          cache-disabled: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      # Expose ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL for docker buildx type=gha cache backend.
+      - name: Expose GitHub runtime for Buildx cache
+        uses: crazy-max/ghaction-github-runtime@04d248b84655b509d8c44dc1d6f990c879747487 # v4.0.0
+
+      - name: Install Docker Compose
+        run: |
+          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+          sudo chmod +x /usr/local/bin/docker-compose
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+          cache: "pip" # caching pip dependencies
+          cache-dependency-path: ./testing/cucumber/requirements.txt
+
+      - name: Pip requirements
+        run: |
+          pip install --require-hashes --only-binary=:all: -r ./testing/cucumber/requirements.txt
+
+      - name: Run Docker Compose Tests
+        run: |
+          chmod +x ./testing/test_webpages.sh
+          chmod +x ./testing/test.sh
+          chmod +x ./testing/test_disabledEndpoints.sh
+          ./testing/test.sh
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+          DOCKER_BASE_CHANGED: ${{ inputs.docker-base-changed }}
+
+      - name: Upload Cucumber Report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: cucumber-report
+          path: testing/cucumber/report.html
+          retention-days: 7
+          if-no-files-found: warn
+
+      - name: Upload Test Reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docker-compose-test-reports
+          path: testing/reports/
+          retention-days: 7
+          if-no-files-found: warn
+
+      - name: Cucumber Test Report
+        if: always()
+        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
+        with:
+          name: Cucumber Tests
+          path: testing/cucumber/junit/*.xml
+          reporter: java-junit
+          fail-on-error: false

.github/workflows/e2e-live.yml

@@ -0,0 +1,64 @@
+name: Playwright E2E (live backend)
+
+# Reusable workflow called from build.yml. Live-backend Playwright suite —
+# boots Spring Boot and runs auth + real tool round-trips against the live
+# server.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  playwright-e2e-live:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Install Playwright (chromium only)
+        run: task e2e:install -- chromium
+      - name: Build frontend (production bundle for vite preview)
+        env:
+          VITE_BUILD_FOR_PREVIEW: "1"
+        run: task frontend:build
+      - name: Run live E2E tests (chromium)
+        id: live-tests
+        run: task e2e:live
+      - name: Print backend log on failure
+        if: failure() && steps.live-tests.conclusion == 'failure'
+        run: |
+          echo "::group::Spring Boot backend log (last 500 lines)"
+          tail -500 .test-state/playwright/backend.log || echo "no backend log found"
+          echo "::endgroup::"
+      - name: Upload backend log
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: backend-log-live-${{ github.run_id }}
+          path: .test-state/playwright/backend.log
+          retention-days: 7
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report-live-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 7

.github/workflows/e2e-stubbed.yml

@@ -0,0 +1,44 @@
+name: Playwright E2E (stubbed)
+
+# Reusable workflow called from build.yml. Backend-free Playwright suite —
+# fast, no Spring Boot required. Runs against the `stubbed` project which
+# mocks API responses in the browser.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  playwright-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Install Playwright (chromium only)
+        run: task e2e:install -- chromium
+      - name: Build frontend (production bundle for vite preview)
+        env:
+          VITE_BUILD_FOR_PREVIEW: "1"
+        run: task frontend:build
+      - name: Run stubbed E2E tests (chromium)
+        run: task e2e:stubbed -- --workers=3
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report-stubbed-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 7

.github/workflows/frontend-backend-licenses-update.yml

@@ -7,6 +7,9 @@ on:
   pull_request:
     branches:
       - main
+  merge_group:
+    branches:
+      - main
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name || github.ref }}
@@ -25,7 +28,7 @@ jobs:
       licenses-backend: ${{ steps.changes.outputs.licenses-backend }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -33,7 +36,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: changes
         with:
           filters: .github/config/.files.yaml
@@ -49,7 +52,7 @@ jobs:
       repository-projects: write # Required for enabling automerge
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -77,7 +80,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Node.js
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: "22"
           cache: "npm"
@@ -89,12 +92,13 @@ jobs:
           NPM_CONFIG_IGNORE_SCRIPTS: "true"
         run: npm ci --ignore-scripts --audit=false --fund=false
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Generate frontend license report (internal PR)
         if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
-        working-directory: frontend
         env:
           PR_IS_FORK: "false"
-        run: npm run generate-licenses
+        run: task frontend:licenses:generate
 
       - name: Generate frontend license report (fork PRs, pinned)
         if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
@@ -135,7 +139,7 @@ jobs:
       # PR Event: Check licenses and comment on PR
       - name: Delete previous license check comments
         if: (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false) && github.actor != 'dependabot[bot]'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -188,7 +192,7 @@ jobs:
 
       - name: Comment on PR - License Check Results
         if: (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false) && github.actor != 'dependabot[bot]'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -273,7 +277,7 @@ jobs:
       - name: Create Pull Request (Push only)
         id: cpr
         if: github.event_name == 'push' && env.CHANGES_DETECTED == 'true'
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           token: ${{ steps.setup-bot.outputs.token }}
           commit-message: "Update Frontend 3rd Party Licenses"
@@ -312,7 +316,7 @@ jobs:
       repository-projects: write # Required for enabling automerge
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -330,21 +334,22 @@ jobs:
           app-id: ${{ secrets.GH_APP_ID }}
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Check licenses and generate report
         id: license-check
-        run: |
-          ./gradlew checkLicense generateLicenseReport || echo "LICENSE_CHECK_FAILED=true" >> $GITHUB_ENV
+        run: task backend:licenses:generate || echo "LICENSE_CHECK_FAILED=true" >> $GITHUB_ENV
         env:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
@@ -364,7 +369,7 @@ jobs:
 
       - name: Upload artifact on license issues
         if: env.LICENSE_WARNINGS_EXIST == 'true'
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: backend-dependencies-without-allowed-license.json
           path: build/reports/dependency-license/dependencies-without-allowed-license.json
@@ -377,7 +382,7 @@ jobs:
 
       - name: Delete previous backend license check comments
         if: (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false) && github.actor != 'dependabot[bot]'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -407,7 +412,7 @@ jobs:
 
       - name: Comment on PR - Backend License Check Results
         if: (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false) && github.actor != 'dependabot[bot]'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -490,7 +495,7 @@ jobs:
       - name: Create Pull Request (push only)
         if: github.event_name == 'push' && env.CHANGES_DETECTED == 'true'
         id: cpr
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           token: ${{ steps.setup-bot.outputs.token }}
           commit-message: "Update Backend 3rd Party Licenses"

.github/workflows/frontend-validation.yml

@@ -0,0 +1,113 @@
+name: Frontend lint, type-check, and build
+
+# Reusable workflow called from build.yml when frontend / testing sources
+# change. Runs the consolidated `task frontend:check:all` (lint, types,
+# unit tests, build) and uploads the dist artifact for downstream jobs.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  frontend-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Quality-check frontend
+        id: frontend-check
+        run: task frontend:check:all
+        continue-on-error: true
+      - name: Comment on frontend check failure
+        # Only post a comment on PRs. github-script's PR helpers need an
+        # issue/PR number, which doesn't exist on merge_group runs.
+        if: steps.frontend-check.outcome == 'failure' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- frontend-check -->';
+            const body = [
+              marker,
+              '### Frontend Check Failed',
+              '',
+              'There are issues with your frontend code that will need to be fixed before they can be merged in.',
+              '',
+              'Run `task frontend:fix` to auto-fix what can be fixed automatically, then run `task frontend:check:all` to see what still needs fixing manually.',
+            ].join('\n');
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+      - name: Fail if frontend check failed
+        if: steps.frontend-check.outcome == 'failure'
+        run: |
+          echo "============================================"
+          echo "  Frontend Check Failed"
+          echo "============================================"
+          echo ""
+          echo "There are issues with your frontend code that"
+          echo "will need to be fixed before they can be merged in."
+          echo ""
+          echo "Run 'task frontend:fix' to auto-fix what can be"
+          echo "fixed automatically, then run 'task frontend:check:all'"
+          echo "to see what still needs fixing manually."
+          echo "============================================"
+          exit 1
+      - name: Remove frontend check comment on success
+        if: steps.frontend-check.outcome == 'success' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- frontend-check -->';
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+              });
+            }
+      - name: Upload frontend build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: frontend-build
+          path: frontend/dist/
+          retention-days: 3

.github/workflows/manage-label.yml

@@ -15,7 +15,7 @@ jobs:
       issues: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -23,7 +23,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@24d110aa46a59976b8a7f35518cb7f14f434c916 # v5.3.0
+        uses: crazy-max/ghaction-github-labeler@548a7c3603594ec17c819e1239f281a3b801ab4d # v6.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           yaml-file: .github/labels.yml

.github/workflows/multiOSReleases.yml

@@ -21,8 +21,14 @@ on:
           - windows
           - macos
           - linux
-  push:
-    branches: [main, V2-master]
+      sign:
+        description: "Code sign the binaries (requires signing secrets)"
+        required: false
+        default: "true"
+        type: choice
+        options:
+          - "true"
+          - "false"
   release:
     types: [created]
 
@@ -38,28 +44,38 @@ jobs:
       version: ${{ steps.versionNumber.outputs.versionNumber }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+      - name: Cache Gradle dependencies
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
-          gradle-version: 8.14
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
 
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Get version number
         id: versionNumber
         run: |
-          echo "Running gradlew printVersion..."
-          ./gradlew printVersion --quiet
           VERSION=$(./gradlew printVersion --quiet | tail -1)
           echo "Extracted version: $VERSION"
           echo "versionNumber=$VERSION" >> $GITHUB_OUTPUT
@@ -74,21 +90,21 @@ jobs:
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             case "${{ github.event.inputs.platform }}" in
               "windows")
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"}]}' >> $GITHUB_OUTPUT
+                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64","jpdfium_platforms":"windows-x64"}]}' >> $GITHUB_OUTPUT
                 ;;
               "macos")
-                echo 'matrix={"include":[{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"}]}' >> $GITHUB_OUTPUT
+                echo 'matrix={"include":[{"platform":"macos-15","args":"--target universal-apple-darwin","name":"macos-universal","jpdfium_platforms":"darwin-arm64,darwin-x64"}]}' >> $GITHUB_OUTPUT
                 ;;
               "linux")
-                echo 'matrix={"include":[{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
+                echo 'matrix={"include":[{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64","jpdfium_platforms":"linux-x64"}]}' >> $GITHUB_OUTPUT
                 ;;
               *)
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
+                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64","jpdfium_platforms":"windows-x64"},{"platform":"macos-15","args":"--target universal-apple-darwin","name":"macos-universal","jpdfium_platforms":"darwin-arm64,darwin-x64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64","jpdfium_platforms":"linux-x64"}]}' >> $GITHUB_OUTPUT
                 ;;
             esac
           else
             # For push/release events, build all platforms
-            echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
+            echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64","jpdfium_platforms":"windows-x64"},{"platform":"macos-15","args":"--target universal-apple-darwin","name":"macos-universal","jpdfium_platforms":"darwin-arm64,darwin-x64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64","jpdfium_platforms":"linux-x64"}]}' >> $GITHUB_OUTPUT
           fi
 
   build-jars:
@@ -111,31 +127,34 @@ jobs:
             file_suffix: "-server"
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
       - name: Setup Node.js
         if: matrix.variant.build_frontend == true
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 22
           cache: "npm"
           cache-dependency-path: frontend/package-lock.json
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+
       - name: Build JAR
         run: ./gradlew build ${{ matrix.variant.build_frontend && '-PbuildWithFrontend=true' || '' }} -x spotlessApply -x spotlessCheck -x test -x sonarqube
         env:
@@ -154,7 +173,7 @@ jobs:
           cp app/core/build/libs/stirling-pdf-${{ needs.determine-matrix.outputs.version }}.jar ./jar-dist/Stirling-PDF${{ matrix.variant.file_suffix }}.jar
 
       - name: Upload JAR artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: jar${{ matrix.variant.file_suffix }}
           path: ./jar-dist/*.jar
@@ -169,11 +188,15 @@ jobs:
     env:
       SM_API_KEY: ${{ secrets.SM_API_KEY }}
       WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
+      RELEASE_GPG_PRIVATE_KEY: ${{ secrets.RELEASE_GPG_PRIVATE_KEY }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
+          allowed-endpoints: >
+            one.digicert.com:443
+            clientauth.one.digicert.com:443
 
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -185,7 +208,7 @@ jobs:
           sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libjavascriptcoregtk-4.0-dev libsoup2.4-dev libjavascriptcoregtk-4.1-dev libsoup-3.0-dev
 
       - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 22
           cache: "npm"
@@ -195,103 +218,61 @@ jobs:
         uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
         with:
           toolchain: stable
-          targets: ${{ (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
+          targets: ${{ matrix.platform == 'macos-15' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
 
-      - name: Set up JDK 21
+      # x86_64 JDK is set up first so the aarch64 step below can leave its
+      # JAVA_HOME as the active one. The macOS universal JRE build needs
+      # jmods from both arches; the x64 path is captured into the env
+      # before the second setup-java overwrites JAVA_HOME.
+      - name: Set up x86_64 JDK 25 (macOS universal JRE)
+        if: matrix.platform == 'macos-15'
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
+          distribution: "temurin"
+          architecture: "x64"
+
+      - name: Capture x86_64 JAVA_HOME
+        if: matrix.platform == 'macos-15'
+        run: echo "X64_JAVA_HOME=$JAVA_HOME" >> "$GITHUB_ENV"
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
-      - name: Build Java backend with JLink
-        working-directory: ./
-        shell: bash
-        run: |
-          chmod +x ./gradlew
-          echo "🔧 Building Stirling-PDF JAR..."
-          ./gradlew build -x spotlessApply -x spotlessCheck -x test -x sonarqube
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
 
-          # Find the built JAR
-          STIRLING_JAR=$(ls app/core/build/libs/stirling-pdf-*.jar | head -n 1)
-          echo "✅ Built JAR: $STIRLING_JAR"
+      # Build the universal JRE before desktop:prepare so the jlink:runtime
+      # task short-circuits on its `test -d runtime/jre` status check.
+      - name: Build universal macOS JRE
+        if: matrix.platform == 'macos-15'
+        env:
+          AARCH64_JAVA_HOME: ${{ env.JAVA_HOME }}
+          JPDFIUM_PLATFORMS: ${{ matrix.jpdfium_platforms }}
+        run: task desktop:jlink:universal-mac
 
-          # Create Tauri directories
-          mkdir -p ./frontend/src-tauri/libs
-          mkdir -p ./frontend/src-tauri/runtime
-
-          # Copy JAR to Tauri libs
-          cp "$STIRLING_JAR" ./frontend/src-tauri/libs/
-          echo "✅ JAR copied to Tauri libs"
-
-          # Analyze JAR dependencies for jlink modules
-          echo "🔍 Analyzing JAR dependencies..."
-          if command -v jdeps &> /dev/null; then
-            DETECTED_MODULES=$(jdeps --print-module-deps --ignore-missing-deps "$STIRLING_JAR" 2>/dev/null || echo "")
-            if [ -n "$DETECTED_MODULES" ]; then
-              echo "📋 jdeps detected modules: $DETECTED_MODULES"
-              MODULES="$DETECTED_MODULES,java.compiler,java.instrument,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-            else
-              echo "⚠️ jdeps analysis failed, using predefined modules"
-              MODULES="java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-            fi
-          else
-            echo "⚠️ jdeps not available, using predefined modules"
-            MODULES="java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-          fi
-
-          # Create custom JRE with jlink
-          echo "🔧 Creating custom JRE with jlink..."
-          echo "📋 Using modules: $MODULES"
-
-          # Remove any existing JRE
-          rm -rf ./frontend/src-tauri/runtime/jre
-
-          # Create the custom JRE
-          jlink \
-            --add-modules "$MODULES" \
-            --strip-debug \
-            --compress=2 \
-            --no-header-files \
-            --no-man-pages \
-            --output ./frontend/src-tauri/runtime/jre
-
-          if [ ! -d "./frontend/src-tauri/runtime/jre" ]; then
-            echo "❌ Failed to create JLink runtime"
-            exit 1
-          fi
-
-          # Test the bundled runtime
-          if [ -f "./frontend/src-tauri/runtime/jre/bin/java" ]; then
-            RUNTIME_VERSION=$(./frontend/src-tauri/runtime/jre/bin/java --version 2>&1 | head -n 1)
-            echo "✅ Custom JRE created successfully: $RUNTIME_VERSION"
-          else
-            echo "❌ Custom JRE executable not found"
-            exit 1
-          fi
-
-          # Calculate runtime size
-          RUNTIME_SIZE=$(du -sh ./frontend/src-tauri/runtime/jre | cut -f1)
-          echo "📊 Custom JRE size: $RUNTIME_SIZE"
+      - name: Prepare desktop build
         env:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
           MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
           DISABLE_ADDITIONAL_FEATURES: true
-
-      - name: Install frontend dependencies
-        working-directory: ./frontend
-        run: npm ci
+          JPDFIUM_PLATFORMS: ${{ matrix.jpdfium_platforms }}
+        run: task desktop:prepare
 
       # DigiCert KeyLocker Setup (Cloud HSM)
       - name: Setup DigiCert KeyLocker
         id: digicert-setup
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') }}
-        uses: digicert/ssm-code-signing@af7f4b07694120e514fe5b19f0598af3c20256e3 # v1.2.0
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
+        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
         env:
           SM_API_KEY: ${{ secrets.SM_API_KEY }}
           SM_CLIENT_CERT_FILE_B64: ${{ secrets.SM_CLIENT_CERT_FILE_B64 }}
@@ -300,7 +281,7 @@ jobs:
           SM_HOST: ${{ secrets.SM_HOST }}
 
       - name: Setup DigiCert KeyLocker Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') }}
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
         shell: pwsh
         run: |
           Write-Host "Setting up DigiCert KeyLocker environment..."
@@ -335,7 +316,7 @@ jobs:
 
       # Traditional PFX Certificate Import (fallback if KeyLocker not configured)
       - name: Import Windows Code Signing Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') }}
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
         env:
           WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
           WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
@@ -366,7 +347,7 @@ jobs:
           }
 
       - name: Import Apple Developer Certificate
-        if: (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master')
+        if: matrix.platform == 'macos-15' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master')
         env:
           APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
           APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
@@ -387,7 +368,7 @@ jobs:
           rm certificate.p12
 
       - name: Verify Certificate
-        if: (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master')
+        if: matrix.platform == 'macos-15' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master')
         run: |
           echo "Verifying Apple Developer Certificate..."
           KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
@@ -398,8 +379,82 @@ jobs:
           echo "APPLE_SIGNING_IDENTITY=$CERT_ID" >> $GITHUB_ENV
           echo "Certificate imported successfully."
 
+      # Pre-flight: verify smctl can talk to DigiCert and sync cert before we sign.
+      # Mirrors the setup from working public Tauri+KeyLocker repos (Labric, Meetily).
+      # Without this, signCommand failures are opaque (Tauri captures but drops
+      # smctl's stderr) - running these loudly surfaces auth/env/keypair issues.
+      - name: Preflight smctl
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
+        shell: pwsh
+        env:
+          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
+        run: |
+          & smctl healthcheck
+          if ($LASTEXITCODE -ne 0) { Write-Host "[ERROR] smctl healthcheck failed"; exit 1 }
+          & smctl keypair ls
+          if ($LASTEXITCODE -ne 0) { Write-Host "[ERROR] smctl keypair ls failed"; exit 1 }
+          & smctl windows certsync --keypair-alias "$env:KEYPAIR_ALIAS"
+          if ($LASTEXITCODE -ne 0) { Write-Host "[WARN] smctl windows certsync returned non-zero - continuing" }
+          Write-Host "[SUCCESS] smctl preflight passed"
+
+      # Write platform-specific Tauri config that adds signCommand for Windows.
+      # Tauri auto-merges tauri.windows.conf.json with tauri.conf.json (RFC 7396).
+      # Tauri calls this command on every binary BEFORE bundling into the MSI,
+      # substituting %1 with the file path.
+      #
+      # Why OBJECT form (cmd + args) instead of string:
+      # Tauri's string-form parser does a naive split(' ') with no shell/quote handling.
+      # Args with spaces or quote characters get mangled. The object form passes each
+      # arg directly to Rust's Command::arg which handles Windows CreateProcess quoting.
+      #
+      # Why --keypair-alias instead of --fingerprint:
+      # --fingerprint requires smctl windows certsync to have synced the cert to the
+      # Windows cert store first. --keypair-alias goes direct through PKCS11 and works
+      # without certsync. All real-world working Tauri+smctl examples use this flag.
+      #
+      # smctl reads SM_HOST, SM_API_KEY, SM_CLIENT_CERT_FILE, SM_CLIENT_CERT_PASSWORD
+      # from env (set by prior DigiCert setup step). No --config-file needed.
+      - name: Configure Windows code signing
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
+        shell: bash
+        env:
+          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
+        run: |
+          cat > ./frontend/src-tauri/tauri.windows.conf.json <<EOF
+          {
+            "bundle": {
+              "windows": {
+                "signCommand": {
+                  "cmd": "smctl",
+                  "args": ["sign", "--keypair-alias", "${KEYPAIR_ALIAS}", "--input", "%1", "--verbose"]
+                }
+              }
+            }
+          }
+          EOF
+          echo "Generated tauri.windows.conf.json (alias masked):"
+          sed "s/${KEYPAIR_ALIAS}/***/g" ./frontend/src-tauri/tauri.windows.conf.json
+
+      - name: Import release GPG signing key (Linux)
+        if: matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master')
+        run: |
+          echo "$RELEASE_GPG_PRIVATE_KEY" | gpg --batch --import
+          gpg --list-secret-keys --keyid-format=long
+
+      - name: Make libjvm discoverable for linuxdeploy (Linux AppImage)
+        if: matrix.platform == 'ubuntu-22.04'
+        run: |
+          JAVA_LIBJVM="$JAVA_HOME/lib/server/libjvm.so"
+          if [ -f "$JAVA_LIBJVM" ]; then
+            sudo ln -sf "$JAVA_LIBJVM" /usr/lib/libjvm.so
+            echo "Linked libjvm from $JAVA_LIBJVM -> /usr/lib/libjvm.so"
+          else
+            echo "libjvm not found at $JAVA_LIBJVM"
+            exit 1
+          fi
+
       - name: Build Tauri app
-        uses: tauri-apps/tauri-action@51a9f1156b33df106d827c3a78f8f894946c5faa # v0.5.25
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
@@ -408,113 +463,116 @@ jobs:
           APPLE_ID: ${{ secrets.APPLE_ID }}
           APPLE_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.APPIMAGETOOL_SIGN_PASSPHRASE }}
+          # AppImage signing — three env vars work together:
+          #   SIGN=1                        tells linuxdeploy-plugin-appimage to forward --sign to appimagetool
+          #   APPIMAGETOOL_SIGN_PASSPHRASE  appimagetool uses this to unlock the GPG key non-interactively
+          #   SIGN_KEY                      appimagetool picks the key matching this fingerprint
+          # Without SIGN=1, the other two are ignored and the AppImage is built unsigned even if a key is present.
+          # Mirror the Windows/macOS gate: only sign on a real release/dispatch+sign or V2-master, when secret is present.
+          SIGN: ${{ (env.RELEASE_GPG_PRIVATE_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master')) && '1' || '0' }}
+          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.RELEASE_GPG_PASSPHRASE }}
+          SIGN_KEY: ${{ vars.RELEASE_GPG_FINGERPRINT }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
-          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY }}
-          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL }}
-          # Only enable Windows signing in Tauri when on release or V2-master
-          SIGN: ${{ (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') && (env.SM_API_KEY == '' && env.WINDOWS_CERTIFICATE != '') && '1' || '0' }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
+          # DigiCert KeyLocker env vars consumed by smctl during signCommand
+          SM_CODE_SIGNING_CERT_SHA1_HASH: ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }}
           CI: true
         with:
           projectPath: ./frontend
           tauriScript: npx tauri
           args: ${{ matrix.args }}
 
-      # Sign with DigiCert KeyLocker (post-build)
-      - name: Sign Windows binaries with DigiCert KeyLocker
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || github.ref == 'refs/heads/V2-master') }}
+      - name: Clear release GPG key from runner keyring (Linux)
+        if: always() && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master')
+        env:
+          RELEASE_GPG_FINGERPRINT: ${{ vars.RELEASE_GPG_FINGERPRINT }}
+        run: |
+          if [ -n "$RELEASE_GPG_FINGERPRINT" ]; then
+            gpg --batch --yes --delete-secret-keys "$RELEASE_GPG_FINGERPRINT" || true
+            gpg --batch --yes --delete-keys "$RELEASE_GPG_FINGERPRINT" || true
+          fi
+
+      # Verify the MSI (outer wrapper users download) AND the inner exe extracted
+      # from it (what actually gets installed and what AV scans). We don't check
+      # target/.../release/stirling-pdf.exe - that's Tauri's intermediate build
+      # artifact. Tauri signs a COPY when bundling into the MSI and leaves the raw
+      # cargo output unsigned, so checking it produces false negatives.
+      - name: Verify Windows Code Signature
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
         shell: pwsh
         run: |
-          Write-Host "=== DigiCert KeyLocker Signing ==="
+          $allSigned = $true
 
-          # Test smctl connectivity first
-          Write-Host "Testing smctl connection..."
-          $healthCheck = & smctl healthcheck 2>&1
-          if ($LASTEXITCODE -eq 0) {
-            Write-Host "[SUCCESS] Connected to DigiCert KeyLocker"
-          } else {
-            Write-Host "[ERROR] Failed to connect to DigiCert KeyLocker"
-            Write-Host $healthCheck
-            exit 1
-          }
-          Write-Host ""
-
-          # Sync certificates to Windows certificate store
-          Write-Host "Syncing certificates to Windows certificate store..."
-          $syncOutput = & smctl windows certsync 2>&1
-          Write-Host "Cert sync result: $syncOutput"
-          Write-Host ""
-
-          # Find only the files we need to sign
-          $filesToSign = @()
-
-          # Main application executable
-          $mainExe = Get-ChildItem -Path "./frontend/src-tauri/target/x86_64-pc-windows-msvc/release" -Filter "stirling-pdf.exe" -File -ErrorAction SilentlyContinue
-          if ($mainExe) { $filesToSign += $mainExe }
-
-          # MSI installer
+          # Check MSI installer (outer wrapper - what users download)
           $msiFiles = Get-ChildItem -Path "./frontend/src-tauri/target" -Filter "*.msi" -Recurse -File
-          $filesToSign += $msiFiles
-
-          if ($filesToSign.Count -eq 0) {
-            Write-Host "[ERROR] No files found to sign"
+          if ($msiFiles.Count -eq 0) {
+            Write-Host "[ERROR] No MSI found under target/"
             exit 1
           }
-
-          Write-Host "Found $($filesToSign.Count) files to sign:"
-          foreach ($f in $filesToSign) { Write-Host "  - $($f.Name)" }
-          Write-Host ""
-
-          $signedCount = 0
-          foreach ($file in $filesToSign) {
-            Write-Host "Signing: $($file.Name)"
-
-            # Get PKCS11 config file path
-            $pkcs11Config = $env:PKCS11_CONFIG
-            if (-not $pkcs11Config) {
-              Write-Host "[ERROR] PKCS11_CONFIG environment variable not set"
-              exit 1
+          foreach ($msi in $msiFiles) {
+            $sig = Get-AuthenticodeSignature -FilePath $msi.FullName
+            Write-Host "MSI: Status=$($sig.Status), Signer=$($sig.SignerCertificate.Subject)"
+            if ($sig.Status -ne "Valid") {
+              Write-Host "[ERROR] MSI is not signed"
+              $allSigned = $false
             }
-
-            Write-Host "Using PKCS11 config: $pkcs11Config"
-
-            # Try signing with certificate fingerprint first (if available)
-            $fingerprint = "${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }}"
-            if ($fingerprint -and $fingerprint -ne "") {
-              Write-Host "Attempting to sign with certificate fingerprint..."
-              $output = & smctl sign --fingerprint "$fingerprint" --input "$($file.FullName)" --config-file "$pkcs11Config" --verbose 2>&1
-              $exitCode = $LASTEXITCODE
-            } else {
-              Write-Host "No fingerprint provided, using keypair alias..."
-              $output = & smctl sign --keypair-alias "${{ secrets.SM_KEYPAIR_ALIAS }}" --input "$($file.FullName)" --config-file "$pkcs11Config" --verbose 2>&1
-              $exitCode = $LASTEXITCODE
-            }
-
-            Write-Host "Exit code: $exitCode"
-            Write-Host "Output: $output"
-
-            if ($output -match "FAILED" -or $output -match "error" -or $output -match "Error") {
-              Write-Host "[ERROR] Signing failed for $($file.Name)"
-              exit 1
-            }
-
-            if ($exitCode -ne 0) {
-              Write-Host "[ERROR] Failed to sign $($file.Name)"
-              Write-Host "Full error output:"
-              Write-Host $output
-              exit 1
-            }
-
-            $signedCount++
-            Write-Host "[SUCCESS] Signed: $($file.Name)"
-            Write-Host ""
           }
 
-          Write-Host "=== Summary ==="
-          Write-Host "[SUCCESS] Signed $signedCount/$($filesToSign.Count) files successfully"
+          # Extract MSI and verify the inner exe (the file that actually gets installed).
+          # This is the critical check - AV flags the installed exe at runtime.
+          $msi = $msiFiles[0].FullName
+          $extractDir = Join-Path $env:RUNNER_TEMP "msi-verify"
+          if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force }
+          $proc = Start-Process msiexec.exe -ArgumentList '/a', $msi, '/qn', "TARGETDIR=$extractDir" -Wait -PassThru -NoNewWindow
+          if ($proc.ExitCode -eq 0) {
+            $innerExe = Get-ChildItem -Path $extractDir -Filter "stirling-pdf.exe" -Recurse -File | Select-Object -First 1
+            if ($innerExe) {
+              $sig = Get-AuthenticodeSignature -FilePath $innerExe.FullName
+              Write-Host "Inner EXE (from MSI): Status=$($sig.Status), Signer=$($sig.SignerCertificate.Subject)"
+              if ($sig.Status -ne "Valid") {
+                Write-Host "[ERROR] Inner exe extracted from MSI is NOT signed - AV will flag this at runtime"
+                $allSigned = $false
+              }
+            } else {
+              Write-Host "[ERROR] Could not find stirling-pdf.exe inside MSI"
+              $allSigned = $false
+            }
+          } else {
+            Write-Host "[ERROR] Failed to extract MSI for verification (exit code: $($proc.ExitCode))"
+            $allSigned = $false
+          }
 
+          if (-not $allSigned) {
+            Write-Host "[ERROR] Signature verification failed"
+            exit 1
+          }
+          Write-Host "[SUCCESS] MSI and installed exe are properly signed"
+
+      # Dump smctl log files on failure. Tauri's signCommand captures smctl output
+      # but drops stderr when the command exits non-zero, making failures opaque.
+      # The real errors live in smctl's log files - surface them here for debugging.
+      - name: Dump smctl logs on failure
+        if: ${{ failure() && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' }}
+        shell: pwsh
+        run: |
+          $logDir = "$env:USERPROFILE\.signingmanager\logs"
+          if (Test-Path $logDir) {
+            Get-ChildItem $logDir | ForEach-Object {
+              Write-Host "=== $($_.FullName) ==="
+              Get-Content $_.FullName -Tail 200
+              Write-Host ""
+            }
+          } else {
+            Write-Host "smctl log directory not found at $logDir"
+          }
+
+      # Rename + Upload: use always() so artifacts are still collected when verify
+      # fails - we need them to manually inspect what actually came out of the build.
       - name: Rename artifacts
+        if: always() && steps.digicert-setup.conclusion != 'failure'
         shell: bash
         run: |
           mkdir -p ./dist
@@ -522,18 +580,21 @@ jobs:
 
           # Find and rename artifacts based on platform
           if [ "${{ matrix.platform }}" = "windows-latest" ]; then
-            find . -name "*.exe" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.exe" \;
+            # Only ship the MSI installer on Windows. The loose exe and WiX toolset exes
+            # are not the user-facing installer - the MSI contains the signed inner exe.
             find . -name "*.msi" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.msi" \;
-          elif [ "${{ matrix.platform }}" = "macos-15" ] || [ "${{ matrix.platform }}" = "macos-15-intel" ]; then
+          elif [ "${{ matrix.platform }}" = "macos-15" ]; then
             find . -name "*.dmg" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.dmg" \;
             find . -name "*.app" -exec cp -r {} "../../../dist/Stirling-PDF-${{ matrix.name }}.app" \;
           else
             find . -name "*.deb" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.deb" \;
+            find . -name "*.rpm" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.rpm" \;
             find . -name "*.AppImage" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.AppImage" \;
           fi
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: always() && steps.digicert-setup.conclusion != 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Stirling-PDF-${{ matrix.name }}
           path: ./dist/*
@@ -547,30 +608,30 @@ jobs:
       contents: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: Download all Tauri artifacts
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: Stirling-PDF-*
           path: ./artifacts/tauri
 
       - name: Download JAR artifact (default)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: jar
           path: ./artifacts/jars
 
       - name: Download JAR artifact (with login)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: jar-with-login
           path: ./artifacts/jars
 
       - name: Download JAR artifact (server only)
-        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: jar-server
           path: ./artifacts/jars
@@ -579,7 +640,7 @@ jobs:
         run: ls -R ./artifacts
 
       - name: Upload binaries to Release
-        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         with:
           tag_name: v${{ needs.determine-matrix.outputs.version }}
           generate_release_notes: true
@@ -588,6 +649,7 @@ jobs:
             ./artifacts/**/*.msi
             ./artifacts/**/*.dmg
             ./artifacts/**/*.deb
+            ./artifacts/**/*.rpm
             ./artifacts/**/*.AppImage
           draft: false
           prerelease: false

.github/workflows/nightly.yml

@@ -0,0 +1,49 @@
+name: Nightly E2E Tests
+
+on:
+  schedule:
+    - cron: "0 2 * * *" # 2 AM UTC every night
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  playwright-all-browsers:
+    name: Playwright (chromium + firefox + webkit)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Install all Playwright browsers
+        run: task e2e:install
+
+      - name: Run E2E tests (all browsers)
+        run: task e2e:cross-browser
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-nightly-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 14

.github/workflows/package-managers.yml

@@ -0,0 +1,155 @@
+name: Update Package Manager Manifests
+
+on:
+  release:
+    types: [ released ]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to test (e.g. 2.9.2 — no v prefix)"
+        required: true
+        type: string
+      dry_run:
+        description: "Skip the git push at the end (safe test)"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  get-release-info:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.info.outputs.version }}
+      dmg_sha256: ${{ steps.hashes.outputs.dmg_sha256 }}
+      msi_sha256: ${{ steps.hashes.outputs.msi_sha256 }}
+      deb_sha256: ${{ steps.hashes.outputs.deb_sha256 }}
+      jar_sha256: ${{ steps.hashes.outputs.jar_sha256 }}
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Extract version from tag or manual input
+        id: info
+        env:
+          DISPATCH_VERSION: ${{ inputs.version }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="$DISPATCH_VERSION"
+          else
+            VERSION="$RELEASE_TAG"
+          fi
+          VERSION="${VERSION#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Download release assets and compute SHA256
+        id: hashes
+        env:
+          VERSION: ${{ steps.info.outputs.version }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BASE="https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v${VERSION}"
+
+          download_sha256() {
+            local url="$1"
+            local file
+            file=$(basename "$url")
+            curl -fsSL --retry 3 -o "$file" "$url"
+            sha256sum "$file" | awk '{print $1}'
+          }
+
+          DMG_SHA=$(download_sha256 "${BASE}/Stirling-PDF-macos-universal.dmg")
+          MSI_SHA=$(download_sha256 "${BASE}/Stirling-PDF-windows-x86_64.msi")
+          DEB_SHA=$(download_sha256 "${BASE}/Stirling-PDF-linux-x86_64.deb")
+          JAR_SHA=$(download_sha256 "${BASE}/Stirling-PDF-with-login.jar")
+
+          echo "dmg_sha256=$DMG_SHA" >> "$GITHUB_OUTPUT"
+          echo "msi_sha256=$MSI_SHA" >> "$GITHUB_OUTPUT"
+          echo "deb_sha256=$DEB_SHA" >> "$GITHUB_OUTPUT"
+          echo "jar_sha256=$JAR_SHA" >> "$GITHUB_OUTPUT"
+
+  update-homebrew-and-scoop:
+    needs: get-release-info
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout homebrew-stirling-pdf tap (also hosts Scoop bucket)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          repository: Stirling-Tools/homebrew-stirling-pdf
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: tap
+
+      # Stirling-PDF now ships a single universal DMG, so the Cask should
+      # have one sha256 line rather than separate on_arm/on_intel blocks.
+      # We rewrite every `sha256 "..."` in the Cask to the same value so
+      # the workflow keeps working through the Cask migration: pre-migration
+      # both arch blocks get the universal SHA (still correct, since both
+      # would resolve to the same DMG), post-migration the lone sha256 line
+      # is updated.
+      - name: Update Homebrew cask (Casks/stirling-pdf.rb)
+        env:
+          VERSION: ${{ needs.get-release-info.outputs.version }}
+          DMG_SHA: ${{ needs.get-release-info.outputs.dmg_sha256 }}
+        run: |
+          CASK="tap/Casks/stirling-pdf.rb"
+          sed -i "s/version \"[^\"]*\"/version \"${VERSION}\"/" "$CASK"
+          sed -i "s/sha256 \"[^\"]*\"/sha256 \"${DMG_SHA}\"/g" "$CASK"
+
+      - name: Update Homebrew formula (Formula/stirling-pdf-server.rb)
+        env:
+          VERSION: ${{ needs.get-release-info.outputs.version }}
+          JAR_SHA: ${{ needs.get-release-info.outputs.jar_sha256 }}
+        run: |
+          FORMULA="tap/Formula/stirling-pdf-server.rb"
+          sed -i "s/version \"[^\"]*\"/version \"${VERSION}\"/" "$FORMULA"
+          sed -i "s/sha256 \"[^\"]*\"/sha256 \"${JAR_SHA}\"/" "$FORMULA"
+
+      - name: Update Scoop stirling-pdf.json
+        env:
+          VERSION: ${{ needs.get-release-info.outputs.version }}
+          MSI_SHA: ${{ needs.get-release-info.outputs.msi_sha256 }}
+        run: |
+          MANIFEST="tap/scoop/stirling-pdf.json"
+          jq --arg v "$VERSION" --arg h "$MSI_SHA" \
+            '.version = $v | .architecture["64bit"].url = "https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v\($v)/Stirling-PDF-windows-x86_64.msi" | .architecture["64bit"].hash = $h' \
+            "$MANIFEST" > tmp.json && mv tmp.json "$MANIFEST"
+
+      - name: Update Scoop stirling-pdf-server.json
+        env:
+          VERSION: ${{ needs.get-release-info.outputs.version }}
+          JAR_SHA: ${{ needs.get-release-info.outputs.jar_sha256 }}
+        run: |
+          MANIFEST="tap/scoop/stirling-pdf-server.json"
+          jq --arg v "$VERSION" --arg h "$JAR_SHA" \
+            '.version = $v | .url = "https://github.com/Stirling-Tools/Stirling-PDF/releases/download/v\($v)/Stirling-PDF-with-login.jar" | .hash = $h' \
+            "$MANIFEST" > tmp.json && mv tmp.json "$MANIFEST"
+
+      - name: Show tap diff (for dry-run visibility)
+        working-directory: tap
+        run: |
+          echo "--- diff --stat ---"
+          git diff --stat
+          echo "--- full diff ---"
+          git diff
+
+      - name: Commit and push all tap updates
+        if: ${{ github.event_name == 'release' || inputs.dry_run == false }}
+        working-directory: tap
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Casks/stirling-pdf.rb Formula/stirling-pdf-server.rb scoop/stirling-pdf.json scoop/stirling-pdf-server.json
+          git diff --cached --quiet && echo "No changes" && exit 0
+          git commit -m "chore: bump Stirling-PDF to v${{ needs.get-release-info.outputs.version }}"
+          git push

.github/workflows/pre_commit.yml

@@ -1,10 +1,11 @@
 name: Pre-commit
 
+# Runs `pre-commit run` for ruff / codespell / gitleaks / EOF / trailing-ws.
+# Called from build.yml on PRs and merge_group; also runnable on demand via
+# workflow_dispatch for manual local-equivalent linting.
 on:
+  workflow_call:
   workflow_dispatch:
-  push:
-    branches:
-      - main
 
 permissions:
   contents: read
@@ -16,12 +17,9 @@ jobs:
       # Prevents sdist builds → no tar extraction
       PIP_ONLY_BINARY: ":all:"
       PIP_DISABLE_PIP_VERSION_CHECK: "1"
-    permissions:
-      contents: write
-      pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -31,15 +29,8 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Setup GitHub App Bot
-        id: setup-bot
-        uses: ./.github/actions/setup-bot
-        with:
-          app-id: ${{ secrets.GH_APP_ID }}
-          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-
       - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: 3.12
           cache: "pip" # caching pip dependencies
@@ -57,47 +48,4 @@ jobs:
           pre-commit run gitleaks --all-files -c .pre-commit-config.yaml
           pre-commit run end-of-file-fixer --all-files -c .pre-commit-config.yaml
           pre-commit run trailing-whitespace --all-files -c .pre-commit-config.yaml
-        continue-on-error: true
-
-      - name: Set up JDK 21
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: 21
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
-        with:
-          gradle-version: 8.14
-
-      - name: Build with Gradle
-        run: ./gradlew build
-        env:
-          MAVEN_USER: ${{ secrets.MAVEN_USER }}
-          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
-          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-
-      - name: git add
-        run: |
-          git add .
-          git diff --staged --quiet || echo "CHANGES_DETECTED=true" >> $GITHUB_ENV
-
-      - name: Create Pull Request
-        if: env.CHANGES_DETECTED == 'true'
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
-        with:
-          token: ${{ steps.setup-bot.outputs.token }}
-          commit-message: ":file_folder: pre-commit"
-          committer: ${{ steps.setup-bot.outputs.committer }}
-          author: ${{ steps.setup-bot.outputs.committer }}
-          signoff: true
-          branch: pre-commit
-          title: "🤖 format everything with pre-commit by ${{ steps.setup-bot.outputs.app-slug }}"
-          body: |
-            Auto-generated by [create-pull-request][1] with **${{ steps.setup-bot.outputs.app-slug }}**
-
-            [1]: https://github.com/peter-evans/create-pull-request
-          draft: false
-          delete-branch: true
-          labels: github-actions
-          sign-commits: true
+          git diff --exit-code

.github/workflows/push-docker-base.yml

@@ -0,0 +1,122 @@
+name: Push Docker Base Image
+
+on:
+  push:
+    branches:
+      - baseDockerImage
+      - accessIssueFix
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Base image version (e.g., 1.0.0, 1.0.1)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  push-base:
+    if: ${{ vars.CI_PROFILE != 'lite' && github.actor == 'Frooodle' }}
+    runs-on: ubuntu-24.04-8core
+    permissions:
+      packages: write
+      id-token: write
+    steps:
+      - name: Verify authorized user
+        run: |
+          if [ "${{ github.actor }}" != "Frooodle" ]; then
+            echo "Error: Only Frooodle is authorized to run this workflow"
+            exit 1
+          fi
+
+      - name: Set version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          elif [ "${{ github.ref_name }}" == "accessIssueFix" ]; then
+            VERSION="1.0.3"
+          else
+            VERSION="1.0.0"
+          fi
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_API }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+
+      - name: Convert repository owner to lowercase
+        id: repoowner
+        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+      - name: Generate tags for base image
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: |
+            ${{ secrets.DOCKER_HUB_ORG_USERNAME }}/stirling-pdf-base
+            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf-base
+          tags: |
+            type=raw,value=${{ steps.version.outputs.version }}
+
+      - name: Build and push base image
+        id: build-push-base
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: docker/base
+          file: ./docker/base/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-pdf-base
+          cache-to: type=gha,mode=max,scope=stirling-pdf-base
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64/v8
+          provenance: true
+          sbom: true
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        with:
+          cosign-release: "v2.4.1"
+
+      - name: Sign base images
+        env:
+          DIGEST: ${{ steps.build-push-base.outputs.digest }}
+          TAGS: ${{ steps.meta.outputs.tags }}
+          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
+          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
+        run: |
+          if [ -n "$COSIGN_PRIVATE_KEY" ]; then
+            echo "$TAGS" | tr ',' '\n' | while read -r tag; do
+              cosign sign --yes \
+                --key env://COSIGN_PRIVATE_KEY \
+                "${tag}@${DIGEST}"
+            done
+          else
+            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping image signing"
+          fi

.github/workflows/push-docker.yml

@@ -2,6 +2,22 @@ name: Push Docker Image with VersionNumber
 
 on:
   workflow_dispatch:
+    inputs:
+      build_main_app:
+        description: "Build & push the main Stirling-PDF image (latest, fat, ultra-lite)."
+        required: false
+        type: boolean
+        default: true
+      build_unoserver:
+        description: "Build & push the standalone stirling-unoserver image."
+        required: false
+        type: boolean
+        default: true
+      force_unoserver_rebuild:
+        description: "Rebuild stirling-unoserver even if its source hash is unchanged."
+        required: false
+        type: boolean
+        default: false
   push:
     branches:
       - master
@@ -31,29 +47,45 @@ jobs:
     permissions:
       packages: write
       id-token: write
+    # On push events these stay 'true'; on workflow_dispatch they follow the inputs.
+    env:
+      RUN_MAIN_APP: ${{ github.event_name != 'workflow_dispatch' || inputs.build_main_app }}
+      RUN_UNOSERVER: ${{ github.event_name != 'workflow_dispatch' || inputs.build_unoserver }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+      - name: Cache Gradle dependencies
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
-          gradle-version: 8.14
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
 
       - name: Set up Docker Buildx
         id: buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Get version number
         id: versionNumber
         run: echo "versionNumber=$(./gradlew printVersion --quiet | tail -1)" >> $GITHUB_OUTPUT
@@ -64,31 +96,31 @@ jobs:
 
       - name: Install cosign
         if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
-        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
         with:
           cosign-release: "v2.4.1"
 
       - name: Install cosign
         if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
-        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
         with:
           cosign-release: "v2.4.1"
 
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_API }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ github.token }}
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
 
       - name: Convert repository owner to lowercase
         id: repoowner
@@ -96,7 +128,8 @@ jobs:
 
       - name: Generate tags for latest
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        if: env.RUN_MAIN_APP == 'true'
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           images: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -110,23 +143,27 @@ jobs:
 
       - name: Build and push Unified Dockerfile (latest variant)
         id: build-push-latest
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        # Empty-tag guard: build-push-action errors when asked to push with no tags.
+        if: env.RUN_MAIN_APP == 'true' && steps.meta.outputs.tags != ''
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: .
           file: ./docker/embedded/Dockerfile
           push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
+          build-args: |
+            VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
+            BASE_VERSION=1.0.0
           platforms: linux/amd64,linux/arm64/v8
           provenance: true
           sbom: true
 
       - name: Sign regular images
-        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
+        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master') && steps.build-push-latest.outputs.digest != ''
         env:
           DIGEST: ${{ steps.build-push-latest.outputs.digest }}
           TAGS: ${{ steps.meta.outputs.tags }}
@@ -141,8 +178,8 @@ jobs:
 
       - name: Generate tags for latest-fat
         id: meta-fat
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
-        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
         with:
           images: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -155,15 +192,15 @@ jobs:
 
       - name: Build and push Unified Dockerfile (fat variant)
         id: build-push-fat
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
-        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-fat.outputs.tags != ''
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: .
           file: ./docker/embedded/Dockerfile.fat
           push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-fat
+          cache-to: type=gha,mode=max,scope=stirling-pdf-fat
           tags: ${{ steps.meta-fat.outputs.tags }}
           labels: ${{ steps.meta-fat.outputs.labels }}
           build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
@@ -172,7 +209,7 @@ jobs:
           sbom: true
 
       - name: Sign fat images
-        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
+        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master') && steps.build-push-fat.outputs.digest != ''
         env:
           DIGEST: ${{ steps.build-push-fat.outputs.digest }}
           TAGS: ${{ steps.meta-fat.outputs.tags }}
@@ -185,8 +222,8 @@ jobs:
 
       - name: Generate tags for ultra-lite
         id: meta-lite
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
-        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
         with:
           images: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
@@ -199,15 +236,15 @@ jobs:
 
       - name: Build and push Unified Dockerfile (ultra-lite variant)
         id: build-push-lite
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
-        if: github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-lite.outputs.tags != ''
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: .
           file: ./docker/embedded/Dockerfile.ultra-lite
           push: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=gha,scope=stirling-pdf-ultra-lite
+          cache-to: type=gha,mode=max,scope=stirling-pdf-ultra-lite
           tags: ${{ steps.meta-lite.outputs.tags }}
           labels: ${{ steps.meta-lite.outputs.labels }}
           build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
@@ -216,7 +253,7 @@ jobs:
           sbom: true
 
       - name: Sign ultra-lite images
-        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master'
+        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/V2-master') && steps.build-push-lite.outputs.digest != ''
         env:
           DIGEST: ${{ steps.build-push-lite.outputs.digest }}
           TAGS: ${{ steps.meta-lite.outputs.tags }}
@@ -226,3 +263,136 @@ jobs:
           echo "$TAGS" | tr ',' '\n' | while read -r tag; do
             cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
           done
+
+      # Standalone unoserver image — versioned independently via
+      # docker/unoserver/VERSION. master/V2-master: publish <version>+latest
+      # only when the version is new. main/testMain: republish :alpha only
+      # when the source hash differs from the published image's annotation.
+      - name: Read unoserver image version
+        id: unoserverVersion
+        if: env.RUN_UNOSERVER == 'true'
+        run: |
+          version=$(tr -d '[:space:]' < docker/unoserver/VERSION)
+          if [ -z "$version" ]; then
+            echo "docker/unoserver/VERSION is empty"; exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "Unoserver image version (from file): ${version}"
+
+      - name: Compute unoserver image source hash
+        id: unoserverHash
+        if: env.RUN_UNOSERVER == 'true'
+        run: |
+          set -eu
+          hash=$(cat \
+            docker/unoserver/Dockerfile \
+            docker/unoserver/entrypoint.sh \
+            docker/unoserver/healthcheck.sh \
+            docker/unoserver/VERSION \
+            | sha256sum | cut -d' ' -f1)
+          echo "hash=${hash}" >> "$GITHUB_OUTPUT"
+          echo "Unoserver source hash: ${hash}"
+
+      - name: Decide whether to publish unoserver image
+        id: unoserverDecision
+        if: env.RUN_UNOSERVER == 'true'
+        env:
+          UNOSERVER_VERSION: ${{ steps.unoserverVersion.outputs.version }}
+          UNOSERVER_HASH: ${{ steps.unoserverHash.outputs.hash }}
+          UNOSERVER_IMAGE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-unoserver
+          UNOSERVER_HASH_ANNOTATION: org.stirlingpdf.unoserver-source-hash
+          FORCE_REBUILD: ${{ inputs.force_unoserver_rebuild }}
+          GH_REF: ${{ github.ref }}
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -eu
+          mode="skip"
+          tags=""
+
+          read_published_hash() {
+            local ref="$1"
+            docker buildx imagetools inspect "$ref" --raw 2>/dev/null \
+              | jq -r --arg key "$UNOSERVER_HASH_ANNOTATION" \
+                  '.annotations[$key] // empty' \
+              2>/dev/null || true
+          }
+
+          # Manual dispatch from any branch routes to the :alpha publish path.
+          EFFECTIVE_REF="$GH_REF"
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            EFFECTIVE_REF="refs/heads/testMain"
+          fi
+
+          case "$EFFECTIVE_REF" in
+            refs/heads/master|refs/heads/V2-master)
+              if [ "${FORCE_REBUILD}" = "true" ]; then
+                echo "force_unoserver_rebuild=true — building stable regardless"
+                mode="stable"
+                tags="${UNOSERVER_IMAGE}:${UNOSERVER_VERSION},${UNOSERVER_IMAGE}:latest"
+              elif docker manifest inspect "${UNOSERVER_IMAGE}:${UNOSERVER_VERSION}" >/dev/null 2>&1; then
+                echo "stirling-unoserver:${UNOSERVER_VERSION} already on GHCR — skipping"
+              else
+                echo "stirling-unoserver:${UNOSERVER_VERSION} is new — will publish"
+                mode="stable"
+                tags="${UNOSERVER_IMAGE}:${UNOSERVER_VERSION},${UNOSERVER_IMAGE}:latest"
+              fi
+              ;;
+            refs/heads/main|refs/heads/testMain)
+              published_hash=$(read_published_hash "${UNOSERVER_IMAGE}:alpha")
+              if [ "${FORCE_REBUILD}" = "true" ]; then
+                echo "force_unoserver_rebuild=true — rebuilding :alpha regardless"
+                mode="alpha"
+                tags="${UNOSERVER_IMAGE}:alpha"
+              elif [ -n "$published_hash" ] && [ "$published_hash" = "$UNOSERVER_HASH" ]; then
+                echo "Published :alpha source hash matches (${published_hash}) — skipping"
+              else
+                if [ -z "$published_hash" ]; then
+                  echo ":alpha has no source-hash annotation (first publish or pre-tracking image) — will publish"
+                else
+                  echo "Source hash changed (was ${published_hash}, now ${UNOSERVER_HASH}) — will publish"
+                fi
+                mode="alpha"
+                tags="${UNOSERVER_IMAGE}:alpha"
+              fi
+              ;;
+            *)
+              echo "Branch ${GH_REF} does not publish unoserver image"
+              ;;
+          esac
+          echo "mode=${mode}" >> "$GITHUB_OUTPUT"
+          echo "tags=${tags}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push unoserver image
+        id: build-push-unoserver
+        if: env.RUN_UNOSERVER == 'true' && steps.unoserverDecision.outputs.mode != 'skip'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: .
+          file: ./docker/unoserver/Dockerfile
+          push: true
+          cache-from: type=gha,scope=stirling-unoserver
+          cache-to: type=gha,mode=max,scope=stirling-unoserver
+          tags: ${{ steps.unoserverDecision.outputs.tags }}
+          # Manifest annotation read by the decision step above to detect drift.
+          annotations: |
+            index:org.stirlingpdf.unoserver-source-hash=${{ steps.unoserverHash.outputs.hash }}
+          platforms: linux/amd64,linux/arm64/v8
+          provenance: true
+          sbom: true
+
+      - name: Sign unoserver image
+        if: env.RUN_UNOSERVER == 'true' && steps.unoserverDecision.outputs.mode == 'stable'
+        env:
+          DIGEST: ${{ steps.build-push-unoserver.outputs.digest }}
+          TAGS: ${{ steps.unoserverDecision.outputs.tags }}
+          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
+          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
+        run: |
+          if [ -n "$COSIGN_PRIVATE_KEY" ]; then
+            echo "$TAGS" | tr ',' '\n' | while read -r tag; do
+              cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
+            done
+          else
+            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping unoserver image signing"
+          fi

.github/workflows/rollback-latest.yml

@@ -0,0 +1,93 @@
+name: Rollback Latest Tags to Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to rollback to (e.g. 2.8.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  rollback:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Install crane
+        uses: imjasonh/setup-crane@31b88afe9de28ae0ffa220711af4b60be9435f6e # v0.4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_API }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Convert repository owner to lowercase
+        id: repoowner
+        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+      - name: Rollback all latest tags to v${{ inputs.version }}
+        env:
+          VERSION: ${{ inputs.version }}
+          DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
+          DOCKER_HUB_ORG_USERNAME: ${{ secrets.DOCKER_HUB_ORG_USERNAME }}
+          REPO_OWNER: ${{ steps.repoowner.outputs.lowercase }}
+        run: |
+          set -euo pipefail
+
+          IMAGES=(
+            "${DOCKER_HUB_USERNAME}/s-pdf"
+            "ghcr.io/${REPO_OWNER}/s-pdf"
+            "ghcr.io/${REPO_OWNER}/stirling-pdf"
+            "${DOCKER_HUB_ORG_USERNAME}/stirling-pdf"
+          )
+
+          VARIANTS=(
+            "${VERSION}:latest"
+            "${VERSION}-fat:latest-fat"
+            "${VERSION}-ultra-lite:latest-ultra-lite"
+          )
+
+          FAILED=0
+
+          for image in "${IMAGES[@]}"; do
+            for variant in "${VARIANTS[@]}"; do
+              SOURCE_TAG="${variant%%:*}"
+              TARGET_TAG="${variant##*:}"
+
+              echo "::group::${image} — ${SOURCE_TAG} → ${TARGET_TAG}"
+
+              if crane manifest "${image}:${SOURCE_TAG}" > /dev/null 2>&1; then
+                crane cp "${image}:${SOURCE_TAG}" "${image}:${TARGET_TAG}"
+                echo "✅ ${image}:${TARGET_TAG} now points to ${SOURCE_TAG}"
+              else
+                echo "::warning::⚠️ ${image}:${SOURCE_TAG} not found, skipping"
+                FAILED=1
+              fi
+
+              echo "::endgroup::"
+            done
+          done
+
+          if [ "$FAILED" -ne 0 ]; then
+            echo "::warning::Some source tags were not found. This is expected if not all variants exist for this version."
+          fi
+
+          echo ""
+          echo "🎉 Rollback to ${VERSION} complete!"

.github/workflows/scorecards.yml

@@ -35,7 +35,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -67,7 +67,7 @@ jobs:
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: SARIF file
           path: results.sarif
@@ -75,6 +75,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@cdefb33c0f6224e58673d9004f47f7cb3e328b89 # v3.29.5
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v3.29.5
         with:
           sarif_file: results.sarif

.github/workflows/stale.yml

@@ -17,12 +17,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: 30 days stale issues
-        uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           days-before-stale: 30

.github/workflows/swagger.yml

@@ -27,22 +27,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
       - name: Generate Swagger documentation
         run: ./gradlew :stirling-pdf:generateOpenApiDocs
@@ -56,6 +56,8 @@ jobs:
           SWAGGERHUB_API_KEY: ${{ secrets.SWAGGERHUB_API_KEY }}
           SWAGGERHUB_USER: "Frooodle"
 
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
       - name: Get version number
         id: versionNumber
         run: echo "versionNumber=$(./gradlew printVersion --quiet | tail -1)" >> $GITHUB_OUTPUT

.github/workflows/sync_files_v2.yml

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -51,13 +51,14 @@ jobs:
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
       - name: Set up Python
-        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.12"
           cache: "pip" # caching pip dependencies
 
       - name: Install Python dependencies
-        run: pip install --require-hashes -r ./.github/scripts/requirements_sync_readme.txt -r ./.github/scripts/requirements_pre_commit.txt
+        run: |
+          pip install --require-hashes --only-binary=:all: -r ./.github/scripts/requirements_sync_readme.txt -r ./.github/scripts/requirements_pre_commit.txt
 
       - name: Sync translation TOML files
         run: |
@@ -83,7 +84,7 @@ jobs:
 
       - name: Create Pull Request
         if: always()
-        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           token: ${{ steps.setup-bot.outputs.token }}
           commit-message: Update files

.github/workflows/tauri-build.yml

@@ -1,6 +1,17 @@
 name: Build Tauri Applications
 
+# Multi-OS Tauri desktop bundle build matrix (Windows / macOS universal /
+# Linux). Called from build.yml on PRs that touch desktop sources (gated
+# via the `tauri` filter in .github/config/.files.yaml). Also runnable
+# on demand via workflow_dispatch with a per-platform selector.
 on:
+  workflow_call:
+    inputs:
+      platform:
+        description: "Platform to build (windows, macos, linux, or all)."
+        required: false
+        type: string
+        default: "all"
   workflow_dispatch:
     inputs:
       platform:
@@ -13,15 +24,6 @@ on:
           - windows
           - macos
           - linux
-  pull_request:
-    branches: [main, V2-tauri-windows]
-    paths:
-      - "frontend/src-tauri/**"
-      - "frontend/src/desktop/**"
-      - "frontend/tsconfig.desktop.json"
-      - ".github/workflows/tauri-build.yml"
-  push:
-    branches: [main]
 
 permissions:
   contents: read
@@ -35,33 +37,40 @@ jobs:
       matrix: ${{ steps.set-matrix.outputs.matrix }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: Determine build matrix
         id: set-matrix
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          PLATFORM: ${{ inputs.platform }}
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            case "${{ github.event.inputs.platform }}" in
-              "windows")
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              "macos")
-                echo 'matrix={"include":[{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              "linux")
-                echo 'matrix={"include":[{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-              *)
-                echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
-                ;;
-            esac
-          else
-            # For PR/push events, build all platforms
-            echo 'matrix={"include":[{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64"},{"platform":"macos-15","args":"--target aarch64-apple-darwin","name":"macos-aarch64"},{"platform":"macos-15-intel","args":"--target x86_64-apple-darwin","name":"macos-x86_64"},{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64"}]}' >> $GITHUB_OUTPUT
+          WINDOWS='{"platform":"windows-latest","args":"--target x86_64-pc-windows-msvc","name":"windows-x86_64","jpdfium_platforms":"windows-x64"}'
+          MACOS='{"platform":"macos-15","args":"--target universal-apple-darwin","name":"macos-universal","jpdfium_platforms":"darwin-arm64,darwin-x64"}'
+          LINUX='{"platform":"ubuntu-22.04","args":"","name":"linux-x86_64","jpdfium_platforms":"linux-x64"}'
+
+          case "$PLATFORM" in
+            windows) ENTRIES=("$WINDOWS") ;;
+            macos)   ENTRIES=("$MACOS") ;;
+            linux)   ENTRIES=("$LINUX") ;;
+            *)       ENTRIES=("$WINDOWS" "$MACOS" "$LINUX") ;;
+          esac
+
+          # Drop macOS entries when Apple certificate secret is unavailable
+          if [ -z "$APPLE_CERTIFICATE" ]; then
+            echo "⚠️ APPLE_CERTIFICATE secret not available - skipping macOS builds"
+            FILTERED=()
+            for entry in "${ENTRIES[@]}"; do
+              [[ "$entry" != *'"macos'* ]] && FILTERED+=("$entry")
+            done
+            ENTRIES=("${FILTERED[@]}")
           fi
 
+          JOINED=$(IFS=','; echo "${ENTRIES[*]}")
+          echo "matrix={\"include\":[$JOINED]}" >> $GITHUB_OUTPUT
+
   build:
     needs: determine-matrix
     strategy:
@@ -71,9 +80,11 @@ jobs:
     env:
       SM_API_KEY: ${{ secrets.SM_API_KEY }}
       WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
+      APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+      RELEASE_GPG_PRIVATE_KEY: ${{ secrets.RELEASE_GPG_PRIVATE_KEY }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -87,7 +98,7 @@ jobs:
           sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libjavascriptcoregtk-4.0-dev libsoup2.4-dev libjavascriptcoregtk-4.1-dev libsoup-3.0-dev
 
       - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 22
           cache: "npm"
@@ -97,104 +108,55 @@ jobs:
         uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
         with:
           toolchain: stable
-          targets: ${{ (matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel') && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
+          targets: ${{ matrix.platform == 'macos-15' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
 
-      - name: Set up JDK 21
+      - name: Set up x86_64 JDK 25 (macOS universal JRE)
+        if: matrix.platform == 'macos-15'
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
+          distribution: "temurin"
+          architecture: "x64"
+
+      - name: Capture x86_64 JAVA_HOME
+        if: matrix.platform == 'macos-15'
+        run: echo "X64_JAVA_HOME=$JAVA_HOME" >> "$GITHUB_ENV"
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
-      - name: Build Java backend with JLink
-        working-directory: ./
-        shell: bash
-        run: |
-          chmod +x ./gradlew
-          echo "🔧 Building Stirling-PDF JAR..."
-          # STIRLING_PDF_DESKTOP_UI=false ./gradlew bootJar --no-daemon
-          ./gradlew build -x spotlessApply -x spotlessCheck -x test -x sonarqube
+      - name: Setup Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
 
-          # Find the built JAR
-          STIRLING_JAR=$(ls app/core/build/libs/stirling-pdf-*.jar | head -n 1)
-          echo "✅ Built JAR: $STIRLING_JAR"
+      - name: Build universal macOS JRE
+        if: matrix.platform == 'macos-15'
+        env:
+          AARCH64_JAVA_HOME: ${{ env.JAVA_HOME }}
+          JPDFIUM_PLATFORMS: ${{ matrix.jpdfium_platforms }}
+        run: task desktop:jlink:universal-mac
 
-          # Create Tauri directories
-          mkdir -p ./frontend/src-tauri/libs
-          mkdir -p ./frontend/src-tauri/runtime
-
-          # Copy JAR to Tauri libs
-          cp "$STIRLING_JAR" ./frontend/src-tauri/libs/
-          echo "✅ JAR copied to Tauri libs"
-
-          # Analyze JAR dependencies for jlink modules
-          echo "🔍 Analyzing JAR dependencies..."
-          if command -v jdeps &> /dev/null; then
-            DETECTED_MODULES=$(jdeps --print-module-deps --ignore-missing-deps "$STIRLING_JAR" 2>/dev/null || echo "")
-            if [ -n "$DETECTED_MODULES" ]; then
-              echo "📋 jdeps detected modules: $DETECTED_MODULES"
-              MODULES="$DETECTED_MODULES,java.compiler,java.instrument,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-            else
-              echo "⚠️ jdeps analysis failed, using predefined modules"
-              MODULES="java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-            fi
-          else
-            echo "⚠️ jdeps not available, using predefined modules"
-            MODULES="java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
-          fi
-
-          # Create custom JRE with jlink (always rebuild)
-          echo "🔧 Creating custom JRE with jlink..."
-          echo "📋 Using modules: $MODULES"
-
-          # Remove any existing JRE
-          rm -rf ./frontend/src-tauri/runtime/jre
-
-          # Create the custom JRE
-          jlink \
-            --add-modules "$MODULES" \
-            --strip-debug \
-            --compress=2 \
-            --no-header-files \
-            --no-man-pages \
-            --output ./frontend/src-tauri/runtime/jre
-
-          if [ ! -d "./frontend/src-tauri/runtime/jre" ]; then
-            echo "❌ Failed to create JLink runtime"
-            exit 1
-          fi
-
-          # Test the bundled runtime
-          if [ -f "./frontend/src-tauri/runtime/jre/bin/java" ]; then
-            RUNTIME_VERSION=$(./frontend/src-tauri/runtime/jre/bin/java --version 2>&1 | head -n 1)
-            echo "✅ Custom JRE created successfully: $RUNTIME_VERSION"
-          else
-            echo "❌ Custom JRE executable not found"
-            exit 1
-          fi
-
-          # Calculate runtime size
-          RUNTIME_SIZE=$(du -sh ./frontend/src-tauri/runtime/jre | cut -f1)
-          echo "📊 Custom JRE size: $RUNTIME_SIZE"
+      - name: Prepare desktop build
         env:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
           MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
           DISABLE_ADDITIONAL_FEATURES: true
-
-      - name: Install frontend dependencies
-        working-directory: ./frontend
-        run: npm ci
+          JPDFIUM_PLATFORMS: ${{ matrix.jpdfium_platforms }}
+        run: task desktop:prepare
 
       # DigiCert KeyLocker Setup (Cloud HSM)
       - name: Setup DigiCert KeyLocker
         id: digicert-setup
         if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
-        uses: digicert/ssm-code-signing@af7f4b07694120e514fe5b19f0598af3c20256e3 # v1.2.0
+        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
         env:
           SM_API_KEY: ${{ secrets.SM_API_KEY }}
           SM_CLIENT_CERT_FILE_B64: ${{ secrets.SM_CLIENT_CERT_FILE_B64 }}
@@ -269,7 +231,7 @@ jobs:
           }
 
       - name: Import Apple Developer Certificate
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
         env:
           APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
           APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
@@ -290,7 +252,7 @@ jobs:
           rm certificate.p12
 
       - name: Verify Certificate
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
         run: |
           echo "Verifying Apple Developer Certificate..."
           KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
@@ -301,8 +263,12 @@ jobs:
           echo "APPLE_SIGNING_IDENTITY=$CERT_ID" >> $GITHUB_ENV
           echo "Certificate imported successfully."
 
+      - name: Sign JPDFium dylibs inside bootJar (macOS only)
+        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
+        run: bash frontend/scripts/sign-jpdfium-dylibs-in-bootjar.sh
+
       - name: Check DMG creation dependencies (macOS only)
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: matrix.platform == 'macos-15'
         run: |
           echo "🔍 Checking DMG creation dependencies on ${{ matrix.platform }}..."
           echo "hdiutil version: $(hdiutil --version || echo 'NOT FOUND')"
@@ -312,8 +278,58 @@ jobs:
           echo "Available tools:"
           ls -la /usr/bin/hd* || echo "No hd* tools found"
 
+      - name: Preflight smctl
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        shell: pwsh
+        env:
+          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
+        run: |
+          & smctl healthcheck
+          if ($LASTEXITCODE -ne 0) { Write-Host "[ERROR] smctl healthcheck failed"; exit 1 }
+          & smctl keypair ls
+          if ($LASTEXITCODE -ne 0) { Write-Host "[ERROR] smctl keypair ls failed"; exit 1 }
+          & smctl windows certsync --keypair-alias "$env:KEYPAIR_ALIAS"
+          if ($LASTEXITCODE -ne 0) { Write-Host "[WARN] smctl windows certsync returned non-zero - continuing" }
+
+      - name: Configure Windows code signing
+        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        shell: bash
+        env:
+          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
+        run: |
+          cat > ./frontend/src-tauri/tauri.windows.conf.json <<EOF
+          {
+            "bundle": {
+              "windows": {
+                "signCommand": {
+                  "cmd": "smctl",
+                  "args": ["sign", "--keypair-alias", "${KEYPAIR_ALIAS}", "--input", "%1", "--verbose"]
+                }
+              }
+            }
+          }
+          EOF
+
+      - name: Import release GPG signing key (Linux)
+        if: matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        run: |
+          echo "$RELEASE_GPG_PRIVATE_KEY" | gpg --batch --import
+          gpg --list-secret-keys --keyid-format=long
+
+      - name: Make libjvm discoverable for linuxdeploy (Linux AppImage)
+        if: matrix.platform == 'ubuntu-22.04'
+        run: |
+          JAVA_LIBJVM="$JAVA_HOME/lib/server/libjvm.so"
+          if [ -f "$JAVA_LIBJVM" ]; then
+            sudo ln -sf "$JAVA_LIBJVM" /usr/lib/libjvm.so
+            echo "Linked libjvm from $JAVA_LIBJVM -> /usr/lib/libjvm.so"
+          else
+            echo "libjvm not found at $JAVA_LIBJVM"
+            exit 1
+          fi
+
       - name: Build Tauri app
-        uses: tauri-apps/tauri-action@51a9f1156b33df106d827c3a78f8f894946c5faa # v0.5.25
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
@@ -322,180 +338,64 @@ jobs:
           APPLE_ID: ${{ secrets.APPLE_ID }}
           APPLE_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.APPIMAGETOOL_SIGN_PASSPHRASE }}
+          # AppImage signing — three env vars work together:
+          #   SIGN=1                        tells linuxdeploy-plugin-appimage to forward --sign to appimagetool
+          #   APPIMAGETOOL_SIGN_PASSPHRASE  appimagetool uses this to unlock the GPG key non-interactively
+          #   SIGN_KEY                      appimagetool picks the key matching this fingerprint
+          # Without SIGN=1, the other two are ignored and the AppImage is built unsigned even if a key is present.
+          # Mirror the Windows/macOS gate: only sign when secret is present AND ref is main (skips PRs from forks/Dependabot).
+          SIGN: ${{ (env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
+          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.RELEASE_GPG_PASSPHRASE }}
+          SIGN_KEY: ${{ vars.RELEASE_GPG_FINGERPRINT }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
-          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY }}
-          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL }}
-          # Only enable Windows signing in Tauri when on main
-          SIGN: ${{ github.ref == 'refs/heads/main' && (env.SM_API_KEY == '' && env.WINDOWS_CERTIFICATE != '') && '1' || '0' }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
+          SM_CODE_SIGNING_CERT_SHA1_HASH: ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }}
           CI: true
         with:
           projectPath: ./frontend
           tauriScript: npx tauri
-          args: ${{ matrix.args }}
+          # Linux: build deb+rpm only here. AppImage runs in its own
+          # continue-on-error step below so its persistent linuxdeploy
+          # failure (#6127 onwards) does not tank deb/rpm uploads.
+          args: ${{ matrix.platform == 'ubuntu-22.04' && '--bundles deb,rpm' || matrix.args }}
 
-      # Sign with DigiCert KeyLocker (post-build)
-      - name: Sign Windows binaries with DigiCert KeyLocker
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
-        shell: pwsh
+      # AppImage is decoupled so its linuxdeploy run gets a fresh process
+      # (rpm scratch state torn down) and its failure can't tank deb/rpm.
+      - name: Build Tauri app (Linux AppImage)
+        if: matrix.platform == 'ubuntu-22.04'
+        continue-on-error: true
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SIGN: ${{ (env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
+          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.RELEASE_GPG_PASSPHRASE }}
+          SIGN_KEY: ${{ vars.RELEASE_GPG_FINGERPRINT }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }} # gitleaks:allow
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
+          CI: true
+        with:
+          projectPath: ./frontend
+          tauriScript: npx tauri
+          args: --bundles appimage
+
+      - name: Clear release GPG key from runner keyring (Linux)
+        if: always() && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        env:
+          RELEASE_GPG_FINGERPRINT: ${{ vars.RELEASE_GPG_FINGERPRINT }}
         run: |
-          Write-Host "=== DigiCert KeyLocker Signing ==="
-
-          # Test smctl connectivity first
-          Write-Host "Testing smctl connection..."
-          $healthCheck = & smctl healthcheck 2>&1
-          if ($LASTEXITCODE -eq 0) {
-            Write-Host "[SUCCESS] Connected to DigiCert KeyLocker"
-          } else {
-            Write-Host "[ERROR] Failed to connect to DigiCert KeyLocker"
-            Write-Host $healthCheck
-            exit 1
-          }
-          Write-Host ""
-
-          # Sync certificates to Windows certificate store
-          Write-Host "Syncing certificates to Windows certificate store..."
-          $syncOutput = & smctl windows certsync 2>&1
-          Write-Host "Cert sync result: $syncOutput"
-          Write-Host ""
-
-          # List available certificates and check if they have certificates attached
-          Write-Host "Checking for available certificates..."
-          $certList = & smctl keypair ls 2>&1
-          Write-Host "Keypair list output:"
-          Write-Host $certList
-          Write-Host ""
-
-          # Parse the output to check certificate status
-          $lines = $certList -split "`n"
-          $foundKeypair = $false
-          $hasCertificate = $false
-
-          foreach ($line in $lines) {
-            if ($line -match "${{ secrets.SM_KEYPAIR_ALIAS }}") {
-              $foundKeypair = $true
-              Write-Host "[SUCCESS] Found keypair in list"
-
-              # Check if this line has certificate info (not just empty spaces after alias)
-              $parts = $line -split "\s+"
-              if ($parts.Count -gt 2 -and $parts[1] -ne "" -and $parts[1] -ne "CERTIFICATE") {
-                $hasCertificate = $true
-                Write-Host "[SUCCESS] Certificate is associated with keypair"
-              }
-            }
-          }
-
-          if (-not $foundKeypair) {
-            Write-Host "[ERROR] Keypair not found: ${{ secrets.SM_KEYPAIR_ALIAS }}"
-            Write-Host "Available keypairs are listed above"
-            Write-Host ""
-            Write-Host "Please verify:"
-            Write-Host "  1. Keypair alias is correct in GitHub secret"
-            Write-Host "  2. API key has access to this keypair"
-            exit 1
-          }
-
-          if (-not $hasCertificate) {
-            Write-Host "[ERROR] No certificate associated with keypair"
-            Write-Host "This usually means:"
-            Write-Host "  1. Certificate not yet synced to KeyLocker (run sync manually)"
-            Write-Host "  2. Certificate is pending approval"
-            Write-Host "  3. Certificate needs to be attached to the keypair"
-            Write-Host ""
-            Write-Host "Try running in DigiCert ONE portal:"
-            Write-Host "  smctl keypair sync"
-            exit 1
-          }
-
-          Write-Host "[SUCCESS] Certificate check passed"
-          Write-Host ""
-
-          # Find only the files we need to sign (not build scripts)
-          $filesToSign = @()
-
-          # Main application executable
-          $mainExe = Get-ChildItem -Path "./frontend/src-tauri/target/x86_64-pc-windows-msvc/release" -Filter "stirling-pdf.exe" -File -ErrorAction SilentlyContinue
-          if ($mainExe) { $filesToSign += $mainExe }
-
-          # MSI installer
-          $msiFiles = Get-ChildItem -Path "./frontend/src-tauri/target" -Filter "*.msi" -Recurse -File
-          $filesToSign += $msiFiles
-
-          if ($filesToSign.Count -eq 0) {
-            Write-Host "[ERROR] No files found to sign"
-            exit 1
-          }
-
-          Write-Host "Found $($filesToSign.Count) files to sign:"
-          foreach ($f in $filesToSign) { Write-Host "  - $($f.Name)" }
-          Write-Host ""
-
-          $signedCount = 0
-          foreach ($file in $filesToSign) {
-            Write-Host "Signing: $($file.Name)"
-
-            # Get PKCS11 config file path (set by DigiCert action)
-            $pkcs11Config = $env:PKCS11_CONFIG
-            if (-not $pkcs11Config) {
-              Write-Host "[ERROR] PKCS11_CONFIG environment variable not set"
-              Write-Host "DigiCert KeyLocker action may not have run correctly"
-              exit 1
-            }
-
-            Write-Host "Using PKCS11 config: $pkcs11Config"
-
-            # Try signing with certificate fingerprint first (if available)
-            $fingerprint = "${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }}"
-            if ($fingerprint -and $fingerprint -ne "") {
-              Write-Host "Attempting to sign with certificate fingerprint..."
-              $output = & smctl sign --fingerprint "$fingerprint" --input "$($file.FullName)" --config-file "$pkcs11Config" --verbose 2>&1
-              $exitCode = $LASTEXITCODE
-            } else {
-              Write-Host "No fingerprint provided, using keypair alias..."
-              # Use smctl to sign with keypair alias
-              $output = & smctl sign --keypair-alias "${{ secrets.SM_KEYPAIR_ALIAS }}" --input "$($file.FullName)" --config-file "$pkcs11Config" --verbose 2>&1
-              $exitCode = $LASTEXITCODE
-            }
-
-            Write-Host "Exit code: $exitCode"
-            Write-Host "Output: $output"
-
-            # Check if output contains "FAILED" even with exit code 0
-            if ($output -match "FAILED" -or $output -match "error" -or $output -match "Error") {
-              Write-Host ""
-              Write-Host "[ERROR] Signing failed for $($file.Name)"
-              Write-Host "[ERROR] smctl returned success but output indicates failure"
-              Write-Host ""
-              Write-Host "Possible issues:"
-              Write-Host "  1. Certificate not fully synced to KeyLocker (wait a few minutes)"
-              Write-Host "  2. Incorrect keypair alias"
-              Write-Host "  3. API key lacks signing permissions"
-              Write-Host ""
-              Write-Host "Please verify in DigiCert ONE portal:"
-              Write-Host "  - Certificate status is 'Issued' (not Pending)"
-              Write-Host "  - Keypair status is 'Online'"
-              Write-Host "  - 'Can sign' is set to 'Yes'"
-              exit 1
-            }
-
-            if ($exitCode -ne 0) {
-              Write-Host "[ERROR] Failed to sign $($file.Name)"
-              Write-Host "Full error output:"
-              Write-Host $output
-              exit 1
-            }
-
-            $signedCount++
-            Write-Host "[SUCCESS] Signed: $($file.Name)"
-            Write-Host ""
-          }
-
-          Write-Host "=== Summary ==="
-          Write-Host "[SUCCESS] Signed $signedCount/$($filesToSign.Count) files successfully"
+          if [ -n "$RELEASE_GPG_FINGERPRINT" ]; then
+            gpg --batch --yes --delete-secret-keys "$RELEASE_GPG_FINGERPRINT" || true
+            gpg --batch --yes --delete-keys "$RELEASE_GPG_FINGERPRINT" || true
+          fi
 
       - name: Verify notarization (macOS only)
-        if: matrix.platform == 'macos-15' || matrix.platform == 'macos-15-intel'
+        if: matrix.platform == 'macos-15'
         run: |
           echo "🔍 Verifying notarization status..."
           cd ./frontend/src-tauri/target
@@ -517,77 +417,84 @@ jobs:
 
           # Find and rename artifacts based on platform
           if [ "${{ matrix.platform }}" = "windows-latest" ]; then
-            find . -name "*.exe" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.exe" \;
+            # Only ship the MSI installer. The loose exe and WiX toolset exes
+            # are not the user-facing installer - the MSI contains the signed inner exe.
             find . -name "*.msi" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.msi" \;
-          elif [ "${{ matrix.platform }}" = "macos-15" ] || [ "${{ matrix.platform }}" = "macos-15-intel" ]; then
+          elif [ "${{ matrix.platform }}" = "macos-15" ]; then
             find . -name "*.dmg" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.dmg" \;
           else
             find . -name "*.deb" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.deb" \;
+            find . -name "*.rpm" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.rpm" \;
             find . -name "*.AppImage" -exec cp {} "../../../dist/Stirling-PDF-${{ matrix.name }}.AppImage" \;
           fi
 
+      # Verify the MSI AND the inner exe extracted from it are signed.
+      # The inner exe is what gets installed on users' machines and what AV scans.
       - name: Verify Windows Code Signature
-        if: matrix.platform == 'windows-latest' && github.ref == 'refs/heads/main'
+        if: matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main'
         shell: pwsh
         run: |
-          Write-Host "Verifying Windows code signatures..."
-
-          $exePath = "./dist/Stirling-PDF-${{ matrix.name }}.exe"
+          $allSigned = $true
           $msiPath = "./dist/Stirling-PDF-${{ matrix.name }}.msi"
 
-          $allSigned = $true
-          $usingKeyLocker = "${{ env.SM_API_KEY }}" -ne ""
-          $usingPfx = "${{ env.WINDOWS_CERTIFICATE }}" -ne ""
-
-          # Check EXE signature
-          if (Test-Path $exePath) {
-            $exeSig = Get-AuthenticodeSignature -FilePath $exePath
-            Write-Host "EXE Signature Status: $($exeSig.Status)"
-            Write-Host "EXE Signer: $($exeSig.SignerCertificate.Subject)"
-            Write-Host "EXE Timestamp: $($exeSig.TimeStamperCertificate.NotAfter)"
-
-            if ($exeSig.Status -ne "Valid") {
-              Write-Host "[WARNING] EXE is not properly signed (Status: $($exeSig.Status))"
-              if ($usingKeyLocker -or $usingPfx) {
-                Write-Host "[ERROR] Certificate was provided but signing failed"
-                $allSigned = $false
-              } else {
-                Write-Host "[INFO] Building unsigned binary (no certificate provided)"
-              }
-            } else {
-              Write-Host "[SUCCESS] EXE is properly signed"
-            }
-          }
-
-          # Check MSI signature
+          # Check MSI (outer wrapper)
           if (Test-Path $msiPath) {
-            $msiSig = Get-AuthenticodeSignature -FilePath $msiPath
-            Write-Host "MSI Signature Status: $($msiSig.Status)"
-            Write-Host "MSI Signer: $($msiSig.SignerCertificate.Subject)"
-            Write-Host "MSI Timestamp: $($msiSig.TimeStamperCertificate.NotAfter)"
+            $sig = Get-AuthenticodeSignature -FilePath $msiPath
+            Write-Host "MSI: Status=$($sig.Status), Signer=$($sig.SignerCertificate.Subject)"
+            if ($sig.Status -ne "Valid") {
+              Write-Host "[ERROR] MSI is not signed"
+              $allSigned = $false
+            }
 
-            if ($msiSig.Status -ne "Valid") {
-              Write-Host "[WARNING] MSI is not properly signed (Status: $($msiSig.Status))"
-              if ($usingKeyLocker -or $usingPfx) {
-                Write-Host "[ERROR] Certificate was provided but signing failed"
-                $allSigned = $false
+            # Extract MSI and verify inner exe
+            $extractDir = Join-Path $env:RUNNER_TEMP "msi-verify"
+            if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force }
+            $proc = Start-Process msiexec.exe -ArgumentList '/a', $msiPath, '/qn', "TARGETDIR=$extractDir" -Wait -PassThru -NoNewWindow
+            if ($proc.ExitCode -eq 0) {
+              $innerExe = Get-ChildItem -Path $extractDir -Filter "stirling-pdf.exe" -Recurse -File | Select-Object -First 1
+              if ($innerExe) {
+                $sig = Get-AuthenticodeSignature -FilePath $innerExe.FullName
+                Write-Host "Inner EXE: Status=$($sig.Status), Signer=$($sig.SignerCertificate.Subject)"
+                if ($sig.Status -ne "Valid") {
+                  Write-Host "[ERROR] Inner exe is NOT signed - AV will flag this at runtime"
+                  $allSigned = $false
+                }
               } else {
-                Write-Host "[INFO] Building unsigned binary (no certificate provided)"
+                Write-Host "[ERROR] Could not find stirling-pdf.exe inside MSI"
+                $allSigned = $false
               }
             } else {
-              Write-Host "[SUCCESS] MSI is properly signed"
+              Write-Host "[ERROR] MSI extraction failed (exit code: $($proc.ExitCode))"
+              $allSigned = $false
             }
+          } else {
+            Write-Host "[ERROR] MSI not found at $msiPath"
+            $allSigned = $false
           }
 
-          if (($usingKeyLocker -or $usingPfx) -and -not $allSigned) {
-            Write-Host "[ERROR] Code signing verification failed"
+          if (-not $allSigned) {
+            Write-Host "[ERROR] Signature verification failed"
             exit 1
+          }
+          Write-Host "[SUCCESS] MSI and inner exe are properly signed"
+
+      - name: Dump smctl logs on failure
+        if: ${{ failure() && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' }}
+        shell: pwsh
+        run: |
+          $logDir = "$env:USERPROFILE\.signingmanager\logs"
+          if (Test-Path $logDir) {
+            Get-ChildItem $logDir | ForEach-Object {
+              Write-Host "=== $($_.FullName) ==="
+              Get-Content $_.FullName -Tail 200
+              Write-Host ""
+            }
           } else {
-            Write-Host "[SUCCESS] Code signature verification completed"
+            Write-Host "smctl log directory not found at $logDir"
           }
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: Stirling-PDF-${{ matrix.name }}
           path: ./dist/*
@@ -606,7 +513,7 @@ jobs:
               echo "❌ No Windows executable found"
               exit 1
             fi
-          elif [ "${{ matrix.platform }}" = "macos-15" ] || [ "${{ matrix.platform }}" = "macos-15-intel" ]; then
+          elif [ "${{ matrix.platform }}" = "macos-15" ]; then
             echo "Checking for macOS artifacts..."
             find . -name "*.dmg" | head -5
             if [ $(find . -name "*.dmg" | wc -l) -eq 0 ]; then
@@ -615,8 +522,8 @@ jobs:
             fi
           else
             echo "Checking for Linux artifacts..."
-            find . -name "*.deb" -o -name "*.AppImage" | head -5
-            if [ $(find . -name "*.deb" -o -name "*.AppImage" | wc -l) -eq 0 ]; then
+            find . -name "*.deb" -o -name "*.rpm" -o -name "*.AppImage" | head -5
+            if [ $(find . -name "*.deb" -o -name "*.rpm" -o -name "*.AppImage" | wc -l) -eq 0 ]; then
               echo "❌ No Linux artifacts found"
               exit 1
             fi
@@ -629,7 +536,7 @@ jobs:
         run: |
           cd ./frontend/src-tauri/target
           echo "Artifact sizes for ${{ matrix.name }}:"
-          find . -name "*.exe" -o -name "*.dmg" -o -name "*.deb" -o -name "*.AppImage" -o -name "*.msi" | while read file; do
+          find . -name "*.exe" -o -name "*.dmg" -o -name "*.deb" -o -name "*.rpm" -o -name "*.AppImage" -o -name "*.msi" | while read file; do
             if [ -f "$file" ]; then
               size=$(stat -c%s "$file" 2>/dev/null || stat -f%z "$file" 2>/dev/null || echo "unknown")
               echo "$file: $size bytes"
@@ -648,12 +555,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden the runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: Post/Update PR Comment with Download Links
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const owner = context.repo.owner;
@@ -671,9 +578,8 @@ jobs:
             // Map of expected artifact names to display info
             const artifactMap = {
               'Stirling-PDF-windows-x86_64': { icon: '🪟', platform: 'Windows x64', files: '.exe, .msi' },
-              'Stirling-PDF-macos-aarch64': { icon: '🍎', platform: 'macOS ARM64', files: '.dmg' },
-              'Stirling-PDF-macos-x86_64': { icon: '🍎', platform: 'macOS Intel', files: '.dmg' },
-              'Stirling-PDF-linux-x86_64': { icon: '🐧', platform: 'Linux x64', files: '.deb, .AppImage' }
+              'Stirling-PDF-macos-universal': { icon: '🍎', platform: 'macOS Universal', files: '.dmg' },
+              'Stirling-PDF-linux-x86_64': { icon: '🐧', platform: 'Linux x64', files: '.deb, .rpm, .AppImage' }
             };
 
             let commentBody = `## 📦 Tauri Desktop Builds Ready!\n\n`;
@@ -740,7 +646,7 @@ jobs:
     if: always()
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 

.github/workflows/test-build-docker.yml

@@ -0,0 +1,217 @@
+name: Build Docker images (PR test)
+
+# Reusable workflow called from build.yml on PRs to verify the three
+# embedded Dockerfiles (default, ultra-lite, fat) still build cleanly,
+# optionally against a freshly-built base image when the PR touches the
+# base Dockerfile.
+on:
+  workflow_call:
+    inputs:
+      docker-base-changed:
+        description: "Whether the docker base image changed (forwarded from files-changed)."
+        required: false
+        type: string
+        default: "false"
+
+permissions:
+  contents: read
+
+jobs:
+  # TODO: extract a pre-matrix `prepare` job that runs once and produces
+  # shared artifacts for the three matrix entries below to consume:
+  #   1. `task backend:build` — currently runs 3× in parallel with
+  #      identical env (DISABLE_ADDITIONAL_FEATURES=true,
+  #      STIRLING_PDF_DESKTOP_UI=false). Build once, upload the JAR as an
+  #      artifact, matrix entries download.
+  #   2. The base-image `docker build` (gated on docker-base-changed) —
+  #      currently runs 3× in parallel against the same Dockerfile and
+  #      context. Build once, `docker save` to an artifact, matrix entries
+  #      `docker load` before the embedded build.
+  # Saves ~2 full backend builds + 2 base-image builds per PR that touches
+  # docker. May also be reusable from backend-build.yml's jdk-25 +
+  # spring-security=true matrix entry if `task backend:build` and
+  # `task backend:build:ci` produce equivalent JARs (verify before wiring).
+  test-build-docker-images:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - docker-rev: docker/embedded/Dockerfile
+            artifact-suffix: Dockerfile
+            cache-scope: stirling-pdf-latest
+          - docker-rev: docker/embedded/Dockerfile.ultra-lite
+            artifact-suffix: Dockerfile.ultra-lite
+            cache-scope: stirling-pdf-ultra-lite
+          - docker-rev: docker/embedded/Dockerfile.fat
+            artifact-suffix: Dockerfile.fat
+            cache-scope: stirling-pdf-fat
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout Repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Convert repository owner to lowercase
+        id: repoowner
+        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT
+
+      - name: Free disk space on runner
+        run: |
+          echo "Disk space before cleanup:" && df -h
+          sudo rm -rf /usr/share/dotnet /opt/ghc /usr/local/lib/android /usr/local/share/boost
+          docker system prune -af || true
+          echo "Disk space after cleanup:" && df -h
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Cache Gradle dependency artifacts
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.gradle/wrapper
+            ~/.gradle/caches/modules-2/files-2.1
+            ~/.gradle/caches/modules-2/metadata-2.*
+          key: gradle-deps-${{ runner.os }}-jdk-25-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties', '**/*.gradle', '**/*.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'gradle/libs.versions.toml') }}
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.3.1
+          cache-disabled: true
+
+      - name: Install Task
+        uses: go-task/setup-task@3be4020d41929789a01026e0e427a4321ce0ad44 # v2.0.0
+      - name: Build application
+        run: task backend:build
+        env:
+          MAVEN_USER: ${{ secrets.MAVEN_USER }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
+          DISABLE_ADDITIONAL_FEATURES: true
+          STIRLING_PDF_DESKTOP_UI: false
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Build base image locally (PR base change only)
+        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+        run: |
+          docker build -t stirling-pdf-base:pr-test -f docker/base/Dockerfile docker/base
+
+      - name: Set base image and platform for this build
+        id: build-params
+        # Pass workflow inputs through env vars rather than expanding `${{ }}`
+        # directly into the shell — defense-in-depth against template injection
+        # if any upstream provider of these values ever becomes less trusted.
+        # GITHUB_EVENT_NAME is already provided by the runner.
+        env:
+          DOCKER_BASE_CHANGED: ${{ inputs.docker-base-changed }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = "pull_request" ] && [ "$DOCKER_BASE_CHANGED" = "true" ]; then
+            echo "base_image=stirling-pdf-base:pr-test" >> "$GITHUB_OUTPUT"
+            echo "platforms=linux/amd64" >> "$GITHUB_OUTPUT"
+          else
+            echo "base_image=stirlingtools/stirling-pdf-base:latest" >> "$GITHUB_OUTPUT"
+            echo "platforms=linux/amd64,linux/arm64/v8" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build ${{ matrix.docker-rev }}
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: .
+          file: ./${{ matrix.docker-rev }}
+          push: false
+          cache-from: type=gha,scope=${{ matrix.cache-scope }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.cache-scope }}
+          platforms: ${{ steps.build-params.outputs.platforms }}
+          build-args: |
+            BASE_IMAGE=${{ steps.build-params.outputs.base_image }}
+          provenance: true
+          sbom: true
+
+      - name: Upload Reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: reports-docker-${{ matrix.artifact-suffix }}
+          path: |
+            build/reports/tests/
+            build/test-results/
+            build/reports/problems/
+          retention-days: 3
+          if-no-files-found: warn
+
+  test-build-unoserver-image:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout Repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Build docker/unoserver/Dockerfile
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          builder: ${{ steps.buildx.outputs.name }}
+          context: .
+          file: ./docker/unoserver/Dockerfile
+          push: false
+          load: true
+          cache-from: type=gha,scope=stirling-unoserver
+          cache-to: type=gha,mode=max,scope=stirling-unoserver
+          platforms: linux/amd64
+          tags: stirling-unoserver:pr-test
+          provenance: false
+          sbom: false
+
+      - name: Smoke test the built image
+        run: |
+          set -eu
+          docker run -d --name unoserver-smoke \
+            -e UNOSERVER_RECYCLE_INTERVAL_SECONDS=0 \
+            stirling-unoserver:pr-test
+          deadline=$((SECONDS + 60))
+          while [ $SECONDS -lt $deadline ]; do
+            status=$(docker inspect -f '{{.State.Health.Status}}' unoserver-smoke 2>/dev/null || echo "starting")
+            if [ "$status" = "healthy" ]; then
+              echo "unoserver became healthy"
+              docker logs unoserver-smoke | tail -30
+              docker rm -f unoserver-smoke
+              exit 0
+            fi
+            sleep 3
+          done
+          echo "unoserver did not become healthy in time"
+          docker logs unoserver-smoke || true
+          docker rm -f unoserver-smoke || true
+          exit 1

.github/workflows/testdriver.yml

@@ -25,23 +25,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up JDK 21
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: "21"
+          java-version: "25"
           distribution: "temurin"
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@f29f5a9d7b09a7c6b29859002d29d24e1674c884 # v5.0.1
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
         with:
-          gradle-version: 8.14
+          gradle-version: 9.3.1
 
       - name: Build with Gradle
         run: ./gradlew build
@@ -52,7 +52,7 @@ jobs:
           DISABLE_ADDITIONAL_FEATURES: true
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Get version number
         id: versionNumber
@@ -61,17 +61,19 @@ jobs:
           echo "versionNumber=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_API }}
 
       - name: Build and push test image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
           file: ./docker/embedded/Dockerfile
           push: true
+          cache-from: type=gha,scope=stirling-pdf-latest
+          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
           tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:test-${{ github.sha }}
           build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
           platforms: linux/amd64
@@ -129,14 +131,14 @@ jobs:
       frontend: ${{ steps.changes.outputs.frontend }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check for file changes
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
         id: changes
         with:
           filters: ".github/config/.files.yaml"
@@ -148,14 +150,14 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Node
-        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           cache: "npm"
           cache-dependency-path: frontend/package-lock.json
@@ -165,9 +167,9 @@ jobs:
         with:
           key: ${{secrets.TESTDRIVER_API_KEY}}
           prerun: |
+            choco install go-task -y
+            task frontend:build
             cd frontend
-            npm install
-            npm run build
             npm install dashcam-chrome --save
             Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "--start-maximized", "--load-extension=$(pwd)/node_modules/dashcam-chrome/build", "http://${{ secrets.NEW_VPS_HOST }}:1337"
             Start-Sleep -Seconds 20
@@ -184,7 +186,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 

.gitignore

@@ -29,8 +29,15 @@ clientWebUI/
 exampleYmlFiles/stirling/
 /stirling/
 /testing/file_snapshots
+/testing/cucumber/junit/
+/testing/cucumber/report.html
+/testing/.failed_tests
+/.test-state/
 SwaggerDoc.json
 
+# Runtime storage for uploaded files and user data (not Java source code)
+app/core/storage/
+
 # Frontend build artifacts copied to backend static resources
 # These are generated by npm build and should not be committed
 app/core/src/main/resources/static/assets/
@@ -44,6 +51,7 @@ app/core/src/main/resources/static/samples/
 app/core/src/main/resources/static/manifest-classic.json
 app/core/src/main/resources/static/robots.txt
 app/core/src/main/resources/static/pdfium/
+app/core/src/main/resources/static/pdfjs/
 app/core/src/main/resources/static/vendor/
 # Note: Keep backend-managed files like fonts/, css/, js/, pdfjs/, etc.
 
@@ -157,7 +165,6 @@ __pycache__/
 *.pyo
 
 # Virtual environments
-.env*
 .venv*
 env*/
 venv*/
@@ -165,6 +172,9 @@ ENV/
 env.bak/
 venv.bak/
 
+# Env files (secrets / local overrides). Subproject .gitignore files whitelist any committed defaults.
+.env*
+
 # VS Code
 /.vscode/**/*
 !/.vscode/settings.json
@@ -174,6 +184,7 @@ venv.bak/
 .idea/
 *.iml
 out/
+.junie/
 
 # Ignore Mac DS_Store files
 .DS_Store
@@ -196,6 +207,9 @@ out/
 *.jks
 *.asc
 
+# Allow test fixture certificates (synthetic, no real credentials)
+!frontend/src/core/tests/test-fixtures/certs/**
+
 # SSH Keys
 *.pub
 *.priv
@@ -206,8 +220,14 @@ id_ecdsa.pub
 id_ed25519
 id_ed25519.pub
 .ssh/
+
+# Allow the published GPG release signing public key (safe to share)
+!docs/security/signing-key.pub
 *ssh
 
+# Taskfile checksum cache
+.task/
+
 # cache
 .cache
 .ruff_cache
@@ -244,3 +264,12 @@ docs/type3/signatures/
 
 # Type3 sample PDFs (development only)
 **/type3/samples/
+
+**/application-dev-local.properties
+
+# Claude
+.claude/
+
+# Playwright MCP screenshots / traces
+.playwright-mcp/
+*.playwright-mcp.png

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.15.11
     hooks:
       - id: ruff
         args:
@@ -12,11 +12,11 @@ repos:
         files: ^((\.github/scripts|scripts|app/core/src/main/resources/static/python)/.+)?[^/]+\.py$
         exclude: (split_photos.py)
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         args:
-          - --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist
+          - --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment
           - --skip="./.*,*.csv,*.json,*.ambr"
           - --quiet-level=2
         files: \.(html|css|js|py|md)$
@@ -35,7 +35,7 @@ repos:
         files: ^.*(\.js|\.java|\.py|\.yml)$
         exclude: ^(.*/pdfjs.*|.*/thirdParty.*|bootstrap.*|.*\.min\..*|.*diff\.js|\.github/workflows/.*$)
   - repo: https://github.com/pappasam/toml-sort
-    rev: v0.24.3
+    rev: v0.24.4
     hooks:
       - id: toml-sort-fix
         files: frontend/public/locales/.*\.toml$

.taskfiles/backend.yml

@@ -0,0 +1,146 @@
+version: '3'
+
+# Gradle invocation strategy:
+#   - Linux/macOS: `./gradlew` runs the POSIX shell wrapper natively.
+#   - Windows:     `cmd /c ".\gradlew.bat ..."` invokes the .bat wrapper through
+#                  cmd.exe so it inherits the user's Windows-side `JAVA_HOME`
+#                  and PATH. Routing through `bash gradlew` on Windows ends up
+#                  under WSL or Git-Bash, neither of which inherits
+#                  Adoptium/Temurin's default Windows-only Java env - gradlew
+#                  then errors with "JAVA_HOME is not set and no 'java' command
+#                  could be found".
+#
+#                  The entire `.\gradlew.bat ...` payload is double-quoted so
+#                  the leading `.\` survives mvdan/sh's POSIX backslash
+#                  stripping; cmd.exe also requires `.\` (not bare `gradlew.bat`)
+#                  because modern Windows excludes cwd from cmd's search path.
+
+tasks:
+  dev:
+    desc: "Start backend dev server"
+    ignore_error: true
+    vars:
+      PORT: '{{.PORT | default "8080"}}'
+      AIENGINE_URL: '{{.AIENGINE_URL | default ""}}'
+    env:
+      SERVER_PORT: '{{.PORT}}'
+    cmds:
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED=true {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
+        platforms: [windows]
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED=true {{end}}./gradlew :stirling-pdf:bootRun'
+        platforms: [linux, darwin]
+
+  dev:bundled:
+    desc: "Clean + bootRun with frontend bundled into the backend (single :8080 server)"
+    ignore_error: true
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat clean bootRun -PbuildWithFrontend=true"
+        platforms: [windows]
+      - cmd: ./gradlew clean bootRun -PbuildWithFrontend=true
+        platforms: [linux, darwin]
+
+  build:
+    desc: "Full backend build"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat clean build"
+        platforms: [windows]
+      - cmd: ./gradlew clean build
+        platforms: [linux, darwin]
+
+  build:fast:
+    desc: "Build without tests"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat clean build -x test"
+        platforms: [windows]
+      - cmd: ./gradlew clean build -x test
+        platforms: [linux, darwin]
+
+  build:ci:
+    desc: "Build for CI (formatting checked separately)"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat build -PnoSpotless"
+        platforms: [windows]
+      - cmd: ./gradlew build -PnoSpotless
+        platforms: [linux, darwin]
+
+  test:
+    desc: "Run backend tests"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat test"
+        platforms: [windows]
+      - cmd: ./gradlew test
+        platforms: [linux, darwin]
+
+  format:
+    desc: "Auto-fix code formatting"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat spotlessApply"
+        platforms: [windows]
+      - cmd: ./gradlew spotlessApply
+        platforms: [linux, darwin]
+
+  format:check:
+    desc: "Check code formatting"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat spotlessCheck"
+        platforms: [windows]
+      - cmd: ./gradlew spotlessCheck
+        platforms: [linux, darwin]
+
+  fix:
+    desc: "Auto-fix backend"
+    cmds:
+      - task: format
+
+  swagger:
+    desc: "Generate OpenAPI docs"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat :stirling-pdf:copySwaggerDoc"
+        platforms: [windows]
+      - cmd: ./gradlew :stirling-pdf:copySwaggerDoc
+        platforms: [linux, darwin]
+    sources:
+      - app/core/src/main/java/**/*.java
+      - app/proprietary/src/main/java/**/*.java
+      - app/common/src/main/java/**/*.java
+    generates:
+      - SwaggerDoc.json
+
+  check:
+    desc: "Backend quality gate"
+    cmds:
+      - task: format:check
+      - task: test
+
+  version:
+    desc: "Print project version"
+    silent: true
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat printVersion --quiet" | tail -1
+        platforms: [windows]
+      - cmd: ./gradlew printVersion --quiet | tail -1
+        platforms: [linux, darwin]
+
+  licenses:check:
+    desc: "Check dependency licenses"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat checkLicense --no-parallel"
+        platforms: [windows]
+      - cmd: ./gradlew checkLicense --no-parallel
+        platforms: [linux, darwin]
+
+  licenses:generate:
+    desc: "Check and generate dependency license report"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat checkLicense generateLicenseReport --no-parallel"
+        platforms: [windows]
+      - cmd: ./gradlew checkLicense generateLicenseReport --no-parallel
+        platforms: [linux, darwin]
+
+  clean:
+    desc: "Clean build artifacts"
+    cmds:
+      - cmd: cmd /c ".\gradlew.bat clean"
+        platforms: [windows]
+      - cmd: ./gradlew clean
+        platforms: [linux, darwin]

.taskfiles/desktop.yml

@@ -0,0 +1,141 @@
+version: '3'
+
+vars:
+  JLINK_MODULES: "java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported"
+
+  # Override via JPDFIUM_PLATFORMS env (csv of platform keys, or 'all').
+  JPDFIUM_PLATFORMS:
+    sh: |
+      if [ -n "${JPDFIUM_PLATFORMS:-}" ]; then
+          echo "$JPDFIUM_PLATFORMS"
+      else
+          case "{{OS}}-{{ARCH}}" in
+              darwin-arm64)  echo "darwin-arm64";;
+              darwin-amd64)  echo "darwin-x64";;
+              linux-amd64)   echo "linux-x64";;
+              linux-arm64)   echo "linux-arm64";;
+              windows-amd64) echo "windows-x64";;
+              *)             echo "all";;
+          esac
+      fi
+
+tasks:
+  prepare:
+    desc: "Prepare desktop build dependencies"
+    deps:
+      - jlink
+      - task: ":frontend:prepare"
+        vars: { MODE: desktop }
+      - provisioner
+
+  provisioner:
+    desc: "Build installer provisioner"
+    platforms: [windows]
+    cmds:
+      - node scripts/build-provisioner.mjs
+
+  dev:
+    desc: "Start Tauri desktop dev mode"
+    deps: [prepare]
+    ignore_error: true
+    cmds:
+      - npx tauri dev --no-watch
+
+  build:
+    desc: "Build Tauri desktop app (production)"
+    deps: [prepare]
+    cmds:
+      - npx tauri build
+
+  build:dev:
+    desc: "Build Tauri desktop app (dev, no bundling)"
+    deps: [prepare]
+    cmds:
+      - npx tauri build --no-bundle
+
+  build:dev:mac:
+    desc: "Build Tauri desktop .app bundle (macOS)"
+    deps: [prepare]
+    cmds:
+      - npx tauri build --bundles app
+
+  build:dev:windows:
+    desc: "Build Tauri desktop NSIS installer (Windows)"
+    deps: [prepare]
+    cmds:
+      - npx tauri build --bundles nsis
+
+  build:dev:linux:
+    desc: "Build Tauri desktop AppImage (Linux)"
+    deps: [prepare]
+    cmds:
+      - npx tauri build --bundles appimage
+
+  clean:
+    desc: "Clean Tauri/Cargo build artifacts"
+    cmds:
+      - task: jlink:clean
+      - cd src-tauri && cargo clean
+      - rm -rf dist build
+
+  # ============================================================
+  # JLink — Build bundled Java runtime for Tauri
+  # ============================================================
+
+  jlink:
+    desc: "Build backend JAR and create JLink runtime for Tauri"
+    deps: [jlink:jar, jlink:runtime]
+
+  jlink:jar:
+    desc: "Build backend JAR for Tauri bundling (host-OS natives only by default)"
+    run: once
+    dir: ..
+    env:
+      DISABLE_ADDITIONAL_FEATURES: "true"
+    cmds:
+      - echo "Building bootJar with JPDFium natives for {{.JPDFIUM_PLATFORMS}}"
+      - cmd: cmd /c gradlew.bat bootJar --no-daemon -PjpdfiumPlatforms={{.JPDFIUM_PLATFORMS}}
+        platforms: [windows]
+      - cmd: ./gradlew bootJar --no-daemon -PjpdfiumPlatforms={{.JPDFIUM_PLATFORMS}}
+        platforms: [linux, darwin]
+      - mkdir -p frontend/src-tauri/libs
+      - cp app/core/build/libs/stirling-pdf-*.jar frontend/src-tauri/libs/
+    status:
+      - test -f frontend/src-tauri/libs/stirling-pdf-*.jar
+
+  jlink:runtime:
+    desc: "Create custom JRE with jlink"
+    deps: [jlink:jar]
+    cmds:
+      - rm -rf src-tauri/runtime/jre
+      - mkdir -p src-tauri/runtime
+      - >-
+        jlink
+        --add-modules {{.JLINK_MODULES}}
+        --strip-debug
+        --compress=zip-6
+        --no-header-files
+        --no-man-pages
+        --output src-tauri/runtime/jre
+    status:
+      - test -d src-tauri/runtime/jre
+
+  jlink:clean:
+    desc: "Remove JLink runtime and bundled JARs"
+    cmds:
+      - rm -rf src-tauri/libs src-tauri/runtime
+
+  # macOS-only. Replaces jlink:runtime's single-arch JRE with a universal
+  # (arm64 + x86_64) one for the universal Tauri shell. Runs the x86_64
+  # jlink under Rosetta on Apple Silicon, so it is opt-in and not part of
+  # the default desktop:build flow. Requires AARCH64_JAVA_HOME and
+  # X64_JAVA_HOME to point at matching JDK installations with jmods/.
+  jlink:universal-mac:
+    desc: "Create universal (arm64+x86_64) JRE for the macOS Tauri build"
+    deps: [jlink:jar]
+    platforms: [darwin]
+    env:
+      JLINK_MODULES: "{{.JLINK_MODULES}}"
+      OUTPUT_DIR: src-tauri/runtime/jre
+    cmds:
+      - scripts/build-universal-mac-jre.sh

.taskfiles/docker.yml

@@ -0,0 +1,63 @@
+version: '3'
+
+vars:
+  COMPOSE_DIR: docker/compose
+  EMBEDDED_DIR: docker/embedded
+
+tasks:
+  build:
+    desc: "Build standard Docker image"
+    cmds:
+      - docker build -t stirling-pdf -f {{.EMBEDDED_DIR}}/Dockerfile .
+
+  build:fat:
+    desc: "Build fat Docker image (all features)"
+    cmds:
+      - docker build -t stirling-pdf-fat -f {{.EMBEDDED_DIR}}/Dockerfile.fat .
+
+  build:ultra-lite:
+    desc: "Build ultra-lite Docker image"
+    cmds:
+      - docker build -t stirling-pdf-ultra-lite -f {{.EMBEDDED_DIR}}/Dockerfile.ultra-lite .
+
+  build:frontend:
+    desc: "Build frontend-only Docker image"
+    cmds:
+      - docker build -t stirling-pdf-frontend -f docker/frontend/Dockerfile .
+
+  build:engine:
+    desc: "Build engine Docker image"
+    dir: engine
+    cmds:
+      - docker build -t stirling-pdf-engine .
+
+  up:
+    desc: "Start standard docker compose stack"
+    cmds:
+      - docker compose -f {{.COMPOSE_DIR}}/docker-compose.yml up -d
+
+  up:fat:
+    desc: "Start fat docker compose stack"
+    cmds:
+      - docker compose -f {{.COMPOSE_DIR}}/docker-compose.fat.yml up -d
+
+  up:ultra-lite:
+    desc: "Start ultra-lite docker compose stack"
+    cmds:
+      - docker compose -f {{.COMPOSE_DIR}}/docker-compose.ultra-lite.yml up -d
+
+  down:
+    desc: "Stop all running docker compose stacks"
+    cmds:
+      - docker compose -f {{.COMPOSE_DIR}}/docker-compose.yml down
+
+  logs:
+    desc: "Tail docker compose logs"
+    cmds:
+      - docker compose -f {{.COMPOSE_DIR}}/docker-compose.yml logs -f
+
+  test:
+    desc: "Run full Docker integration test suite (builds all variants and tests them)"
+    ignore_error: true
+    cmds:
+      - bash testing/test.sh {{.CLI_ARGS}}

.taskfiles/e2e.yml

@@ -0,0 +1,204 @@
+version: '3'
+
+tasks:
+  install:
+    desc: "Install Playwright browsers"
+    dir: frontend
+    deps: [ ':frontend:install' ]
+    cmds:
+      - npx playwright install {{.CLI_ARGS}} --with-deps
+
+  stubbed:
+    desc: "Run stubbed E2E tests"
+    dir: frontend
+    deps: [ ':frontend:prepare' ]
+    cmds:
+      - npx playwright test --project=stubbed {{.CLI_ARGS}}
+
+  live:
+    desc: "Run live E2E tests"
+    summary: |
+      Auto-spawns a Spring Boot backend with isolated state under
+      .test-state/playwright/ (purged on every run) so the suite doesn't
+      touch your local DB, settings.yml, backups or customFiles. The
+      backend is stopped automatically when the runner exits.
+
+      Pass extra Playwright flags via -- :
+        task e2e:live -- --headed --grep merge
+    deps:
+      - live:backend
+      - live:runner
+
+  live:backend:
+    internal: true
+    ignore_error: true
+    vars:
+      BASE_DIR: '{{.ROOT_DIR}}/.test-state/playwright'
+    env:
+      STIRLING_BASE_PATH: '{{.BASE_DIR}}'
+      # Suppress the analytics opt-in modal that fires on first admin login.
+      # It renders a Mantine overlay that intercepts pointer events and blocks
+      # FirstLoginSlide from rendering, so the bootstrap spec times out waiting
+      # for the password-change prompt.
+      SYSTEM_ENABLEANALYTICS: "false"
+      # NOTE: SECURITY_INITIALLOGIN_USERNAME/PASSWORD are intentionally NOT set.
+      # The live-setup project's bootstrap spec performs the real first-login
+      # flow against the backend's default admin/stirling user, exercising the
+      # forced-password-change UI and leaving the DB at admin/adminadmin for
+      # the rest of the live suite. This is both real coverage of the first-
+      # login flow and a stronger seed than env-var-driven user creation.
+    cmds:
+      # Wrapped in `bash -c` because Task's embedded shell (mvdan/sh) doesn't
+      # support `&` + `$!` + `wait` reliably (gradle was never actually
+      # backgrounded, so `$!` recorded a stale PID and the runner saw an
+      # immediate "backend died"). Real bash backgrounds gradle properly and
+      # gives us a stable PID to clean up.
+      - |
+        bash -c '
+          set -e
+          rm -rf "{{.BASE_DIR}}"
+          mkdir -p "{{.BASE_DIR}}"
+          # Background gradle and record its PID so the runner can clean up
+          # the exact process tree (wrapper + forked Spring Boot JVM) without
+          # resorting to fuzzy `pkill -f` patterns. `wait` keeps this script
+          # alive for the lifetime of gradle so Task'"'"'s parallel deps stay
+          # synchronised.
+          bash gradlew :stirling-pdf:bootRun > "{{.BASE_DIR}}/backend.log" 2>&1 &
+          GRADLE_PID=$!
+          echo $GRADLE_PID > "{{.BASE_DIR}}/backend.pid"
+          wait $GRADLE_PID
+        '
+
+  live:runner:
+    internal: true
+    deps: [ ':frontend:prepare' ]
+    dir: frontend
+    vars:
+      BASE_DIR: '{{.ROOT_DIR}}/.test-state/playwright'
+    cmds:
+      # Wrapped in `bash -c` because Task's embedded shell (mvdan/sh) only
+      # supports `EXIT`/`ERR` in `trap`, not `INT`/`TERM`. CLI_ARGS are
+      # passed positionally so quoted args like --grep "foo bar" survive.
+      - |
+        bash -c '
+          set +e
+          # bootRun forks a separate Spring Boot JVM as a child of the gradle
+          # wrapper; killing only the wrapper leaves that JVM orphaned holding
+          # :8080. Walk the recorded PID'"'"'s process tree via pgrep so we kill
+          # every descendant, then lsof as a last-resort backstop.
+          kill_tree() {
+            local pid=$1
+            for child in $(pgrep -P "$pid" 2>/dev/null); do
+              kill_tree "$child"
+            done
+            kill "$pid" 2>/dev/null || true
+          }
+          cleanup() {
+            if [ -f "{{.BASE_DIR}}/backend.pid" ]; then
+              echo "Stopping backend..."
+              kill_tree "$(cat "{{.BASE_DIR}}/backend.pid")"
+              sleep 1
+              lsof -ti:8080 2>/dev/null | xargs kill 2>/dev/null || true
+              echo "Backend stopped"
+            fi
+          }
+          # Trap so cleanup runs on every exit path: tests pass, tests fail,
+          # backend never starts, user Ctrl-Cs. Without this the gradle JVM
+          # is left orphaned holding :8080 whenever the wait loop times out.
+          trap cleanup EXIT INT TERM
+
+          echo "Waiting for backend on :8080 (up to 10min; first compile can be slow)..."
+          WAITED=0
+          while [ $WAITED -lt 600 ]; do
+            if curl -sf http://localhost:8080/api/v1/info/status 2>/dev/null | grep -q UP; then
+              echo "Backend ready, starting Playwright"
+              break
+            fi
+            # Bail early if the backend already died: no point waiting 10min.
+            if [ -f "{{.BASE_DIR}}/backend.pid" ]; then
+              BACKEND_PID=$(cat "{{.BASE_DIR}}/backend.pid")
+              if ! kill -0 "$BACKEND_PID" 2>/dev/null; then
+                echo "Backend process exited before becoming ready; last 100 log lines:"
+                tail -100 "{{.BASE_DIR}}/backend.log" 2>/dev/null || true
+                exit 1
+              fi
+            fi
+            sleep 2
+            WAITED=$((WAITED + 2))
+          done
+          if [ $WAITED -ge 600 ]; then
+            echo "Backend did not become ready within 10min, aborting"
+            exit 1
+          fi
+
+          npx playwright test --project=live "$@"
+        ' bash {{.CLI_ARGS}}
+
+  enterprise:
+    desc: "Run enterprise E2E tests"
+    summary: |
+      Requires an already-running keycloak compose stack on :8080. Bring one
+      up first with:
+        task e2e:oauth:up
+        task e2e:saml:up
+    dir: frontend
+    deps: [ ':frontend:prepare' ]
+    cmds:
+      - npx playwright test --project=enterprise {{.CLI_ARGS}}
+
+  cross-browser:
+    desc: "Run stubbed E2E tests on Chromium, Firefox, and WebKit"
+    dir: frontend
+    deps: [ ':frontend:prepare' ]
+    cmds:
+      - npx playwright test --project=stubbed --project=stubbed-firefox --project=stubbed-webkit {{.CLI_ARGS}}
+
+  check:
+    desc: "Run all E2E tests not requiring Docker"
+    cmds:
+      - task: stubbed
+      - task: live
+
+  check:all:
+    desc: "Run all E2E tests"
+    summary: |
+      Includes the enterprise project, which requires a keycloak compose
+      stack on :8080. Bring one up first with:
+        task e2e:oauth:up
+        task e2e:saml:up
+    cmds:
+      - task: stubbed
+      - task: live
+      - task: enterprise
+
+  oauth:up:
+    desc: "Start the OAuth keycloak test environment"
+    summary: |
+      Set LICENSE_KEY=<KEY> to skip the interactive license prompt:
+        task e2e:oauth:up LICENSE_KEY=abc123
+      Pass extra flags via -- :
+        task e2e:oauth:up -- --auto --nobuild
+    ignore_error: true
+    cmds:
+      - bash testing/compose/start-oauth-test.sh {{if .LICENSE_KEY}}--license-key "{{.LICENSE_KEY}}"{{end}} {{.CLI_ARGS}}
+
+  oauth:down:
+    desc: "Stop the OAuth keycloak test environment"
+    cmds:
+      - docker compose -f testing/compose/docker-compose-keycloak-oauth.yml down -v
+
+  saml:up:
+    desc: "Start the SAML keycloak test environment"
+    summary: |
+      Set LICENSE_KEY=<KEY> to skip the interactive license prompt:
+        task e2e:saml:up LICENSE_KEY=abc123
+      Pass extra flags via -- :
+        task e2e:saml:up -- --auto --with-storage --nobuild --language sv-SE
+    ignore_error: true
+    cmds:
+      - bash testing/compose/start-saml-test.sh {{if .LICENSE_KEY}}--license-key "{{.LICENSE_KEY}}"{{end}} {{.CLI_ARGS}}
+
+  saml:down:
+    desc: "Stop the SAML keycloak test environment"
+    cmds:
+      - docker compose -f testing/compose/docker-compose-keycloak-saml.yml down -v

.taskfiles/engine.yml

@@ -0,0 +1,132 @@
+version: '3'
+
+tasks:
+  install:
+    desc: "Install engine dependencies"
+    run: once
+    cmds:
+      - uv python install 3.13.8
+      - uv sync
+    sources:
+      - uv.lock
+      - pyproject.toml
+    status:
+      - test -d .venv
+
+  prepare:
+    desc: "Set up engine .env from template"
+    deps: [install]
+    cmds:
+      - uv run scripts/setup_env.py
+    sources:
+      - scripts/setup_env.py
+    generates:
+      - .env.local
+
+  run:
+    desc: "Run engine server"
+    deps: [prepare]
+    ignore_error: true
+    dir: src
+    vars:
+      PORT: '{{.PORT | default "5001"}}'
+    env:
+      PYTHONUNBUFFERED: "1"
+    cmds:
+      - uv run uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}}
+
+  dev:
+    desc: "Start engine dev server with hot reload"
+    deps: [prepare]
+    ignore_error: true
+    dir: src
+    vars:
+      PORT: '{{.PORT | default "5001"}}'
+    env:
+      PYTHONUNBUFFERED: "1"
+    cmds:
+      - uv run uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --reload
+
+  lint:
+    desc: "Run linting"
+    deps: [install]
+    cmds:
+      - uv run ruff check .
+
+  lint:fix:
+    desc: "Auto-fix lint issues"
+    deps: [install]
+    cmds:
+      - uv run ruff check . --fix
+
+  format:
+    desc: "Auto-fix code formatting"
+    deps: [install]
+    cmds:
+      - uv run ruff format .
+
+  format:check:
+    desc: "Check code formatting"
+    deps: [install]
+    cmds:
+      - uv run ruff format . --diff
+
+  typecheck:
+    desc: "Run type checking"
+    deps: [install]
+    cmds:
+      - uv run pyright . --warnings
+
+  test:
+    desc: "Run tests"
+    deps: [prepare]
+    cmds:
+      - uv run pytest tests
+
+  fix:
+    desc: "Auto-fix lint + format"
+    cmds:
+      - task: format  # Can auto-fix some things that `lint:fix` can't like line length violations
+      - task: lint:fix
+      - task: format  # Ensure that after lint fixing that the code is still formatted correctly
+
+  check:
+    desc: "Full engine quality gate"
+    cmds:
+      - task: typecheck
+      - task: lint
+      - task: format:check
+      - task: test
+
+  tool-models:
+    desc: "Generate tool_models.py from Java OpenAPI spec (SwaggerDoc.json)"
+    deps: [install, ":backend:swagger"]
+    cmds:
+      - uv run python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py
+    sources:
+      - ../SwaggerDoc.json
+      - scripts/generate_tool_models.py
+    generates:
+      - src/stirling/models/tool_models.py
+
+  clean:
+    desc: "Clean build artifacts"
+    cmds:
+      - task: '{{if eq .OS "Windows_NT"}}clean-windows{{else}}clean-unix{{end}}'
+
+  clean-unix:
+    internal: true
+    desc: "Clean build artifacts"
+    cmds:
+      - rm -rf .venv data logs output
+
+  # On Windows, use PowerShell as bash failed to delete some dependencies
+  clean-windows:
+    internal: true
+    desc: "Clean build artifacts"
+    ignore_error: true
+    cmds:
+      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue .venv
+      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue data
+      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue logs
+      - powershell rm -Recurse -Force -ErrorAction SilentlyContinue output

.taskfiles/frontend.yml

@@ -0,0 +1,295 @@
+version: '3'
+
+tasks:
+  install:
+    desc: "Install dependencies"
+    run: once
+    cmds:
+      - '{{ if eq .CI "true" }}npm ci{{ else }}npm install{{ end }}'
+    sources:
+      - package-lock.json
+      - package.json
+    status:
+      - test -d node_modules
+    env:
+      CI: '{{ .CI | default "false" }}'
+
+  prepare:env:
+    internal: true
+    run: when_changed
+    deps: [install]
+    vars:
+      MODE: '{{.MODE | default ""}}'
+    cmds:
+      - npx tsx scripts/setup-env.ts{{if .MODE}} --{{.MODE}}{{end}}
+    sources:
+      - scripts/setup-env.ts
+    generates:
+      - .env.local
+      - .env{{if .MODE}}.{{.MODE}}{{end}}.local
+
+  prepare:icons:
+    internal: true
+    run: once
+    deps: [install]
+    cmds:
+      - node scripts/generate-icons.js
+
+  prepare:
+    desc: "Set up dev environment"
+    run: when_changed
+    vars:
+      MODE: '{{.MODE | default ""}}'
+    deps:
+      - task: prepare:env
+        vars: { MODE: '{{.MODE}}' }
+      - prepare:icons
+
+  # ============================================================
+  # Development
+  # ============================================================
+
+  dev:_run:
+    internal: true
+    ignore_error: true
+    vars:
+      MODE: '{{.MODE}}'
+      PORT: '{{.PORT | default "5173"}}'
+      BACKEND_URL: '{{.BACKEND_URL | default "http://localhost:8080"}}'
+      OPEN: '{{.OPEN | default ""}}'
+    env:
+      BACKEND_URL: '{{.BACKEND_URL}}'
+    cmds:
+      - npx vite --mode {{.MODE}} --port {{.PORT}}{{if .OPEN}} --open{{end}}
+
+  dev:
+    desc: "Start frontend dev server"
+    cmds:
+      - task: dev:proprietary
+        vars: { PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  dev:core:
+    desc: "Start frontend dev server in core mode"
+    deps: [prepare]
+    cmds:
+      - task: dev:_run
+        vars: { MODE: core, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  dev:proprietary:
+    desc: "Start frontend dev server in proprietary mode"
+    deps: [prepare]
+    cmds:
+      - task: dev:_run
+        vars: { MODE: proprietary, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  dev:saas:
+    desc: "Start frontend dev server in SaaS mode"
+    deps:
+      - task: prepare
+        vars: { MODE: saas }
+    cmds:
+      - task: dev:_run
+        vars: { MODE: saas, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  dev:desktop:
+    desc: "Start frontend dev server in desktop mode"
+    deps:
+      - task: prepare
+        vars: { MODE: desktop }
+    cmds:
+      - task: dev:_run
+        vars: { MODE: desktop, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  dev:prototypes:
+    desc: "Start frontend dev server in prototypes mode"
+    deps: [prepare]
+    cmds:
+      - task: dev:_run
+        vars: { MODE: prototypes, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }
+
+  # ============================================================
+  # Build
+  # ============================================================
+
+  build:
+    desc: "Production build (default mode)"
+    deps: [prepare]
+    cmds:
+      - npx vite build
+
+  build:core:
+    desc: "Build for core mode"
+    deps: [prepare]
+    cmds:
+      - npx vite build --mode core
+
+  build:proprietary:
+    desc: "Build for proprietary mode"
+    deps: [prepare]
+    cmds:
+      - npx vite build --mode proprietary
+
+  build:saas:
+    desc: "Build for SaaS mode"
+    deps:
+      - task: prepare
+        vars: { MODE: saas }
+    cmds:
+      - npx vite build --mode saas
+
+  build:desktop:
+    desc: "Build for desktop mode"
+    deps:
+      - task: prepare
+        vars: { MODE: desktop }
+    cmds:
+      - npx vite build --mode desktop
+
+  build:prototypes:
+    desc: "Build for prototypes mode"
+    deps: [prepare]
+    cmds:
+      - npx vite build --mode prototypes
+
+  # ============================================================
+  # Code quality
+  # ============================================================
+
+  lint:
+    desc: "Run linting"
+    deps: [install]
+    cmds:
+      - npx eslint --max-warnings=0
+      - npx dpdm src --circular --no-warning --no-tree --exit-code circular:1
+
+  lint:fix:
+    desc: "Auto-fix lint issues"
+    deps: [install]
+    cmds:
+      - npx eslint --fix
+
+  format:
+    desc: "Auto-fix code formatting"
+    deps: [install]
+    cmds:
+      - npx prettier --write .
+
+  format:check:
+    desc: "Check code formatting"
+    deps: [install]
+    cmds:
+      - npx prettier --check .
+
+  fix:
+    desc: "Auto-fix lint and format"
+    cmds:
+      - task: format
+      - task: lint:fix
+
+  typecheck:
+    desc: "Typecheck default build of the app"
+    cmds:
+      - task: typecheck:proprietary
+
+  typecheck:core:
+    desc: "Typecheck core build variant"
+    deps: [prepare]
+    cmds:
+      - npx tsc --noEmit --project src/core/tsconfig.json
+
+  typecheck:proprietary:
+    desc: "Typecheck proprietary build variant"
+    deps: [prepare]
+    cmds:
+      - npx tsc --noEmit --project src/proprietary/tsconfig.json
+
+  typecheck:saas:
+    desc: "Typecheck SaaS build variant"
+    deps:
+      - task: prepare
+        vars: { MODE: saas }
+    cmds:
+      - npx tsc --noEmit --project src/saas/tsconfig.json
+
+  typecheck:desktop:
+    desc: "Typecheck desktop build variant"
+    deps:
+      - task: prepare
+        vars: { MODE: desktop }
+    cmds:
+      - npx tsc --noEmit --project src/desktop/tsconfig.json
+
+  typecheck:scripts:
+    desc: "Typecheck scripts"
+    deps: [prepare]
+    cmds:
+      - npx tsc --noEmit --project scripts/tsconfig.json
+
+  typecheck:prototypes:
+    desc: "Typecheck prototypes build variant"
+    deps: [prepare]
+    cmds:
+      - npx tsc --noEmit --project src/prototypes/tsconfig.json
+
+  typecheck:all:
+    desc: "Typecheck all build variants"
+    cmds:
+      - task: typecheck:core
+      - task: typecheck:proprietary
+      - task: typecheck:saas
+      - task: typecheck:desktop
+      - task: typecheck:scripts
+      - task: typecheck:prototypes
+
+  # ============================================================
+  # Quality Gate
+  # ============================================================
+
+  check:
+    desc: "Quick quality gate for local development"
+    cmds:
+      - task: typecheck
+      - task: lint
+      - task: format:check
+      - task: test
+
+  check:all:
+    desc: "Full CI quality gate"
+    cmds:
+      - task: typecheck:all
+      - task: lint
+      - task: format:check
+      - task: build
+      - task: test
+
+  # ============================================================
+  # Test
+  # ============================================================
+
+  test:
+    desc: "Run tests"
+    deps: [install]
+    cmds:
+      - npx vitest run
+
+  test:watch:
+    desc: "Run tests in watch mode"
+    deps: [install]
+    cmds:
+      - npx vitest --watch
+
+  test:coverage:
+    desc: "Run tests with coverage"
+    deps: [install]
+    cmds:
+      - npx vitest --coverage
+
+  # ============================================================
+  # Code Generation
+  # ============================================================
+
+  licenses:generate:
+    desc: "Generate frontend license report"
+    deps: [install]
+    cmds:
+      - node scripts/generate-licenses.js

AGENTS.md

@@ -0,0 +1,460 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents when working with code in this repository.
+
+## Taskfile (Recommended)
+
+This project uses [Task](https://taskfile.dev/) as a unified command runner. All build, dev, test, lint, and docker commands can be run from the repo root via `task <command>`. Run `task --list` to see all available commands.
+
+Task `desc:` fields should describe **what** the task does, not **how** it does it. Keep them generic and stable: don't reference implementation details like aliases, internal helpers, mode flags, or which other task delegates to which. The description is for users picking a command from `task --list`, not a changelog of refactors.
+
+### Quick Reference
+- `task install` — install all dependencies
+- `task dev` — start backend + frontend concurrently
+- `task dev:all` — start backend + frontend + engine concurrently
+- `task build` — build all components
+- `task test` — run all tests (backend + frontend + engine)
+- `task lint` — run all linters
+- `task format` — auto-fix formatting across all components
+- `task check` — full quality gate (lint + typecheck + test)
+- `task clean` — clean all build artifacts
+- `task docker:build` — build standard Docker image
+- `task docker:up` — start Docker compose stack
+
+## Common Development Commands
+
+### Build and Test
+- **Build project**: `task build`
+- **Run backend locally**: `task backend:dev`
+- **Run all tests**: `task test` (or individually: `task backend:test`, `task frontend:test`, `task engine:test`)
+- **Docker integration tests**: `./test.sh` (builds all Docker variants and runs comprehensive tests)
+- **Code formatting**: `task format` (or `task backend:format` for Java only)
+- **Full quality gate**: `task check` (runs lint + typecheck + test across all components)
+
+After modifying any files in the project, you must run the relevant `task check` command that covers that area of the code. For example, when editing frontend files run `task frontend:check`; for Python engine files run `task engine:check`; for Java backend files run `task backend:check`.
+
+### Docker Development
+- **Build standard**: `task docker:build` (or `docker build -t stirling-pdf -f docker/embedded/Dockerfile .`)
+- **Build fat version**: `task docker:build:fat`
+- **Build ultra-lite**: `task docker:build:ultra-lite`
+- **Start compose stack**: `task docker:up` (or `task docker:up:fat`, `task docker:up:ultra-lite`)
+- **Stop compose stack**: `task docker:down`
+- **View logs**: `task docker:logs`
+- **Example compose files**: Located in `exampleYmlFiles/` directory
+
+### Security Mode Development
+Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security features during development. This is required for testing the full version locally.
+
+### Python Development (AI Engine)
+
+The engine is a Python reasoning service for Stirling: it plans and interprets work, but it does not own durable state, and it does not execute Stirling PDF operations directly. Keep the service narrow: typed contracts in, typed contracts out, with AI only where it adds reasoning value. The frontend calls the Python engine via Java as a proxy.
+
+#### Python Commands
+All engine commands run from the repo root using Task:
+- `task engine:check` — run all checks (typecheck + lint + format-check + test)
+- `task engine:fix` — auto-fix lint + formatting
+- `task engine:install` — install Python dependencies via uv
+- `task engine:dev` — start FastAPI with hot reload (localhost:5001)
+- `task engine:test` — run pytest
+- `task engine:lint` — run ruff linting
+- `task engine:typecheck` — run pyright
+- `task engine:format` — format code with ruff
+- `task engine:tool-models` — generate `tool_models.py` from the Java OpenAPI spec
+
+The project structure is defined in `engine/pyproject.toml`. Any new dependencies should be listed there, followed by running `task engine:install`.
+
+#### Python Code Style
+- Keep `task engine:check` passing.
+- Use modern Python when it improves clarity.
+- Prefer explicit names to cleverness.
+- Avoid nested functions and nested classes unless the language construct requires them.
+- Prefer composition to inheritance when combining concepts.
+- Avoid speculative abstractions. Add a layer only when it removes real duplication or clarifies lifecycle.
+- Add comments sparingly and only when they explain non-obvious intent.
+
+#### Python Typing and Models
+- Deserialize into Pydantic models as early as possible.
+- Serialize from Pydantic models as late as possible.
+- Do not pass raw `dict[str, Any]` or `dict[str, object]` across important boundaries when a typed model can exist instead.
+- Avoid `Any` wherever possible.
+- Avoid `cast()` wherever possible (reconsider the structure first).
+- All shared models should subclass `stirling.models.ApiModel` so the service behaves consistently.
+- Do not use string literals for any type annotations, including `cast()`.
+
+#### Python Configuration
+- Keep application-owned configuration in `stirling.config`.
+- Only add `STIRLING_*` environment variables that the engine itself truly owns.
+- Do not mirror third-party provider environment variables unless the engine is actually interpreting them.
+- Let `pydantic-ai` own provider authentication configuration when possible.
+
+#### Python Architecture
+
+**Package roles:**
+- `stirling.contracts`: request/response models and shared typed workflow contracts. If a shape crosses a module or service boundary, it probably belongs here.
+- `stirling.models`: shared model primitives and generated tool models.
+- `stirling.agents`: reasoning modules for individual capabilities.
+- `stirling.api`: HTTP layer, dependency access, and app startup wiring.
+- `stirling.services`: shared runtime and non-AI infrastructure.
+- `stirling.config`: application-owned settings.
+
+**Source of truth:**
+- `stirling.models.tool_models` is the source of truth for operation IDs and parameter models.
+- Do not duplicate operation lists if they can be derived from `tool_models.OPERATIONS`.
+- Do not hand-maintain parallel parameter schemas when the generated tool models already define them.
+- If a tool ID must match a parameter model, validate that relationship explicitly in code.
+
+**Boundaries:**
+- Keep the API layer thin. Route modules should bind requests, resolve dependencies, and call agents or services. They should not contain business logic.
+- Keep agents focused on one reasoning domain. They should not own FastAPI routing, persistence, or execution of Stirling operations.
+- Build long-lived runtime objects centrally at startup when possible rather than reconstructing heavy AI objects per request.
+- If an agent delegates to another agent, the delegated agent should remain the source of truth for its own domain output.
+
+#### Python AI Usage
+- The system must work with any AI, including self-hosted models. We require that the models support structured outputs, but should minimise model-specific code beyond that.
+- Use AI for reasoning-heavy outputs, not deterministic glue.
+- Do not ask the model to invent data that Python can derive safely.
+- Do not fabricate fallback user-facing copy in code to hide incomplete model output.
+- AI output schemas should be impossible to instantiate incorrectly.
+  - Do not require the model to keep separate structures in sync. For example, instead of generating two lists which must be the same length, generate one list of a model containing the same data.
+  - Prefer Python to derive deterministic follow-up structure from a valid AI result.
+- Use `NativeOutput(...)` for structured model outputs.
+- Use `ToolOutput(...)` when the model should select and call delegate functions.
+
+#### Python Testing
+- Test contracts directly.
+- Test agents directly where behaviour matters.
+- Test API routes as thin integration points.
+- Prefer dependency overrides or startup-state seams to monkeypatching random globals.
+
+### Frontend Development
+- **Frontend dev server**: `task frontend:dev` — requires backend on localhost:8080
+- **Tech Stack**: Vite + React + TypeScript + Mantine UI + TailwindCSS
+- **Proxy Configuration**: Vite proxies `/api/*` calls to backend (localhost:8080)
+- **Build Process**: DO NOT run build scripts manually - builds are handled by CI/CD pipelines
+- **Package Installation**: `task frontend:install`
+- **Deployment Options**:
+  - **Desktop App**: `task desktop:build`
+  - **Web Server**: `task frontend:build` then serve dist/ folder
+  - **Development**: `task desktop:dev` for desktop dev mode
+
+#### Environment Variables
+- All `VITE_*` variables must be declared in the appropriate committed env file:
+  - `frontend/.env` — core, proprietary, and shared vars
+  - `frontend/.env.saas` — SaaS-only vars (layered on top of `.env` in SaaS mode)
+  - `frontend/.env.desktop` — desktop (Tauri)-only vars (layered on top of `.env` in desktop mode)
+- These files are committed to Git and must not contain private keys
+- Local overrides (API keys, machine-specific settings) go in uncommitted sibling `.env.local` / `.env.saas.local` / `.env.desktop.local` files — Vite automatically layers them on top
+- Never use `|| 'hardcoded-fallback'` inline — put defaults in the committed env files
+- `task frontend:prepare` creates empty `.local` override files on first run; pass `MODE=saas` or `MODE=desktop` to also create the mode-specific `.local` file
+- Prepare runs automatically as a dependency of all `dev*`, `build*`, and `desktop*` tasks
+- See `frontend/README.md#environment-variables` for full documentation
+
+#### Import Paths - CRITICAL
+**ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.
+
+For a broader explanation of the frontend layering and override architecture, see [frontend/DeveloperGuide.md](frontend/DeveloperGuide.md).
+
+```typescript
+// ✅ CORRECT - Use @app/* for all imports
+import { AppLayout } from "@app/components/AppLayout";
+import { useFileContext } from "@app/contexts/FileContext";
+import { FileContext } from "@app/contexts/FileContext";
+
+// ❌ WRONG - Do not use @core/* or @proprietary/* in normal code
+import { AppLayout } from "@core/components/AppLayout";
+import { useFileContext } from "@proprietary/contexts/FileContext";
+```
+
+**Only use explicit aliases when:**
+- Building layer-specific override that wraps a lower layer's component
+- Example: `import { AppProviders as CoreAppProviders } from "@core/components/AppProviders"` when creating proprietary/AppProviders.tsx that extends the core version
+
+The `@app/*` alias automatically resolves to the correct layer based on build target (core/proprietary/desktop) and handles the fallback cascade.
+
+#### Component Override Pattern (Stub/Shadow)
+Use this pattern for desktop-specific or proprietary-specific features WITHOUT runtime checks or conditionals.
+
+**How it works:**
+1. Core defines stub component (returns null or no-op)
+2. Desktop/proprietary overrides with same path/name
+3. Core imports via `@app/*` - higher layer "shadows" core in those builds
+4. No `@ts-ignore`, no `isTauri()` checks, no runtime conditionals!
+
+**Example - Desktop-specific footer:**
+
+```typescript
+// core/components/workbenchBar/WorkbenchBarFooterExtensions.tsx (stub)
+interface WorkbenchBarFooterExtensionsProps {
+  className?: string;
+}
+
+export function WorkbenchBarFooterExtensions(_props: WorkbenchBarFooterExtensionsProps) {
+  return null; // Stub - does nothing in web builds
+}
+```
+
+```tsx
+// desktop/components/workbenchBar/WorkbenchBarFooterExtensions.tsx (real implementation)
+import { Box } from '@mantine/core';
+import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
+
+interface WorkbenchBarFooterExtensionsProps {
+  className?: string;
+}
+
+export function WorkbenchBarFooterExtensions({ className }: WorkbenchBarFooterExtensionsProps) {
+  return (
+    <Box className={className}>
+      <BackendHealthIndicator />
+    </Box>
+  );
+}
+```
+
+```tsx
+// core/components/shared/WorkbenchBar.tsx (usage - works in ALL builds)
+import { WorkbenchBarFooterExtensions } from '@app/components/workbenchBar/WorkbenchBarFooterExtensions';
+
+export function WorkbenchBar() {
+  return (
+    <div>
+      {/* In web builds: renders nothing (stub returns null) */}
+      {/* In desktop builds: renders BackendHealthIndicator */}
+      <WorkbenchBarFooterExtensions className="workbench-bar-footer" />
+    </div>
+  );
+}
+```
+
+**Build resolution:**
+- **Core build**: `@app/*` → `core/*` → Gets stub (returns null)
+- **Desktop build**: `@app/*` → `desktop/*` → Gets real implementation (shadows core)
+
+**Benefits:**
+- No runtime checks or feature flags
+- Type-safe across all builds
+- Clean, readable code
+- Build-time optimization (dead code elimination)
+
+#### Multi-Tool Workflow Architecture
+Frontend designed for **stateful document processing**:
+- Users upload PDFs once, then chain tools (split → merge → compress → view)
+- File state and processing results persist across tool switches
+- No file reloading between tools - performance critical for large PDFs (up to 100GB+)
+
+#### FileContext - Central State Management
+**Location**: `frontend/src/core/contexts/FileContext.tsx`
+- **Active files**: Currently loaded PDFs and their variants
+- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
+- **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
+- **IndexedDB persistence**: File storage with thumbnail caching
+- **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
+
+**Critical**: All file operations go through FileContext. Don't bypass with direct file handling.
+
+#### Processing Services
+- **enhancedPDFProcessingService**: Background PDF parsing and manipulation
+- **thumbnailGenerationService**: Web Worker-based with main-thread fallback
+- **fileStorage**: IndexedDB with LRU cache management
+
+#### Memory Management Strategy
+**Why manual cleanup exists**: Large PDFs (up to 100GB+) through multiple tools accumulate:
+- PDF.js documents that need explicit .destroy() calls
+- Blob URLs from tool outputs that need revocation
+- Web Workers that need termination
+Without cleanup: browser crashes with memory leaks.
+
+#### Tool Development
+
+**Architecture**: Modular hook-based system with clear separation of concerns:
+
+- **useToolOperation** (`frontend/src/core/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook
+  - Coordinates all tool operations with consistent interface
+  - Integrates with FileContext for operation tracking
+  - Handles validation, error handling, and UI state management
+
+- **Supporting Hooks**:
+  - **useToolState**: UI state management (loading, progress, error, files)
+  - **useToolApiCalls**: HTTP requests and file processing
+  - **useToolResources**: Blob URLs, thumbnails, ZIP downloads
+
+- **Utilities**:
+  - **toolErrorHandler**: Standardized error extraction and i18n support
+  - **toolResponseProcessor**: API response handling (single/zip/custom)
+  - **toolOperationTracker**: FileContext integration utilities
+
+**Three Tool Patterns**:
+
+**Pattern 1: Single-File Tools** (Individual processing)
+- Backend processes one file per API call
+- Set `multiFileEndpoint: false`
+- Examples: Compress, Rotate
+```typescript
+return useToolOperation({
+  operationType: 'compress',
+  endpoint: '/api/v1/misc/compress-pdf',
+  buildFormData: (params, file: File) => { /* single file */ },
+  multiFileEndpoint: false,
+});
+```
+
+**Pattern 2: Multi-File Tools** (Batch processing)
+- Backend accepts `MultipartFile[]` arrays in single API call
+- Set `multiFileEndpoint: true`
+- Examples: Split, Merge, Overlay
+```typescript
+return useToolOperation({
+  operationType: 'split',
+  endpoint: '/api/v1/general/split-pages',
+  buildFormData: (params, files: File[]) => { /* all files */ },
+  multiFileEndpoint: true,
+  filePrefix: 'split_',
+});
+```
+
+**Pattern 3: Complex Tools** (Custom processing)
+- Tools with complex routing logic or non-standard processing
+- Provide `customProcessor` for full control
+- Examples: Convert, OCR
+```typescript
+return useToolOperation({
+  operationType: 'convert',
+  customProcessor: async (params, files) => { /* custom logic */ },
+});
+```
+
+**Benefits**:
+- **No Timeouts**: Operations run until completion (supports 100GB+ files)
+- **Consistent**: All tools follow same pattern and interface
+- **Maintainable**: Single responsibility hooks, easy to test and modify
+- **i18n Ready**: Built-in internationalization support
+- **Type Safe**: Full TypeScript support with generic interfaces
+- **Memory Safe**: Automatic resource cleanup and blob URL management
+
+## Architecture Overview
+
+### Project Structure
+- **Backend**: Spring Boot application
+- **Frontend**: React-based SPA in `/frontend` directory
+  - **File Storage**: IndexedDB for client-side file persistence and thumbnails
+  - **Internationalization**: JSON-based translations (converted from backend .properties)
+- **PDF Processing**: PDFBox for core PDF operations, LibreOffice for conversions, PDF.js for client-side rendering
+- **Security**: Spring Security with optional authentication (controlled by `DOCKER_ENABLE_SECURITY`)
+- **Configuration**: YAML-based configuration with environment variable overrides
+
+### Controller Architecture
+- **API Controllers** (`src/main/java/.../controller/api/`): REST endpoints for PDF operations
+  - Organized by function: converters, security, misc, pipeline
+  - Follow pattern: `@RestController` + `@RequestMapping("/api/v1/...")`
+
+### Key Components
+- **SPDFApplication.java**: Main application class with desktop UI and browser launching logic
+- **ConfigInitializer**: Handles runtime configuration and settings files
+- **Pipeline System**: Automated PDF processing workflows via `PipelineController`
+- **Security Layer**: Authentication, authorization, and user management (when enabled)
+
+### Frontend Directory Structure
+The frontend is organized with a clear separation of concerns:
+
+- **`frontend/src/core/`**: Main application code (shared, production-ready components)
+  - **`core/components/`**: React components organized by feature
+    - `core/components/tools/`: Individual PDF tool implementations
+    - `core/components/viewer/`: PDF viewer components
+    - `core/components/pageEditor/`: Page manipulation UI
+    - `core/components/tooltips/`: Help tooltips for tools
+    - `core/components/shared/`: Reusable UI components
+  - **`core/contexts/`**: React Context providers
+    - `FileContext.tsx`: Central file state management
+    - `file/`: File reducer and selectors
+    - `toolWorkflow/`: Tool workflow state
+  - **`core/hooks/`**: Custom React hooks
+    - `hooks/tools/`: Tool-specific operation hooks (one directory per tool)
+    - `hooks/tools/shared/`: Shared hook utilities (useToolOperation, etc.)
+  - **`core/constants/`**: Application constants and configuration
+  - **`core/data/`**: Static data (tool taxonomy, etc.)
+  - **`core/services/`**: Business logic services (PDF processing, storage, etc.)
+
+- **`frontend/src/desktop/`**: Desktop-specific (Tauri) code
+- **`frontend/src/proprietary/`**: Proprietary/licensed features
+- **`frontend/src-tauri/`**: Tauri (Rust) native desktop application code
+- **`frontend/public/`**: Static assets served directly
+  - `public/locales/`: Translation JSON files
+
+### Component Architecture
+- **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/public/` (modern)
+- **Internationalization**:
+  - Backend: `messages_*.properties` files
+  - Frontend: JSON files in `frontend/public/locales/` (converted from .properties)
+  - Conversion Script: `scripts/convert_properties_to_json.py`
+
+### Configuration Modes
+- **Ultra-lite**: Basic PDF operations only
+- **Standard**: Full feature set
+- **Fat**: Pre-downloaded dependencies for air-gapped environments
+- **Security Mode**: Adds authentication, user management, and enterprise features
+
+### Testing Strategy
+- **Integration Tests**: Cucumber tests in `testing/cucumber/`
+- **Docker Testing**: `test.sh` validates all Docker variants
+- **Manual Testing**: No unit tests currently - relies on UI and API testing
+
+## Development Workflow
+
+1. **Local Development** (using Taskfile):
+   - Backend + frontend: `task dev`
+   - All services (including AI engine): `task dev:all`
+   - Or individually: `task backend:dev` (localhost:8080), `task frontend:dev` (localhost:5173), `task engine:dev` (localhost:5001)
+2. **Quality Gate**: Run `task check` before submitting PRs
+3. **Docker Testing**: Use `./test.sh` for full Docker integration tests
+4. **Code Style**: Spotless enforces Google Java Format automatically (`task backend:format`)
+5. **Translations**:
+   - Backend: Use helper scripts in `/scripts` for multi-language updates
+   - Frontend: Update JSON files in `frontend/public/locales/` or use conversion script
+6. **Documentation**: API docs auto-generated and available at `/swagger-ui/index.html`
+
+## Frontend Architecture Status
+
+- **Core Status**: React SPA architecture complete with multi-tool workflow support
+- **State Management**: FileContext handles all file operations and tool navigation
+- **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
+- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
+  - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
+  - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker`
+  - Pattern: Each tool creates focused operation hook, UI consumes state/actions
+- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
+- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
+
+## Translation Rules
+
+- **CRITICAL**: Always update translations in `en-GB` only, never `en-US`
+- Translation files are located in `frontend/public/locales/`
+
+## Important Notes
+
+- **Java Version**: Requires JDK 25.
+- **Lombok**: Used extensively - ensure IDE plugin is installed
+- **File Persistence**:
+  - **Backend**: Designed to be stateless - files are processed in memory/temp locations only
+  - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails)
+- **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation
+- **Import Paths**: ALWAYS use `@app/*` for imports - never use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer
+- **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling
+- **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code
+- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
+- **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
+- **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
+- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
+
+## Communication Style
+- Be direct and to the point
+- No apologies or conversational filler
+- Answer questions directly without preamble
+- Explain reasoning concisely when asked
+- Avoid unnecessary elaboration
+
+## Decision Making
+- Ask clarifying questions before making assumptions
+- Stop and ask when uncertain about project-specific details
+- Confirm approach before making structural changes
+- Request guidance on preferences (cross-platform vs specific tools, etc.)
+- Verify understanding of requirements before proceeding

CLAUDE.md

@@ -1,337 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Common Development Commands
-
-### Build and Test
-- **Build project**: `./gradlew clean build`
-- **Run locally**: `./gradlew bootRun`
-- **Full test suite**: `./test.sh` (builds all Docker variants and runs comprehensive tests)
-- **Code formatting**: `./gradlew spotlessApply` (runs automatically before compilation)
-
-### Docker Development
-- **Build ultra-lite**: `docker build -t stirlingtools/stirling-pdf:latest-ultra-lite -f ./Dockerfile.ultra-lite .`
-- **Build standard**: `docker build -t stirlingtools/stirling-pdf:latest -f ./Dockerfile .`
-- **Build fat version**: `docker build -t stirlingtools/stirling-pdf:latest-fat -f ./Dockerfile.fat .`
-- **Example compose files**: Located in `exampleYmlFiles/` directory
-
-### Security Mode Development
-Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security features during development. This is required for testing the full version locally.
-
-### Frontend Development
-- **Frontend dev server**: `cd frontend && npm run dev` (requires backend on localhost:8080)
-- **Tech Stack**: Vite + React + TypeScript + Mantine UI + TailwindCSS
-- **Proxy Configuration**: Vite proxies `/api/*` calls to backend (localhost:8080)
-- **Build Process**: DO NOT run build scripts manually - builds are handled by CI/CD pipelines
-- **Package Installation**: DO NOT run npm install commands - package management handled separately
-- **Deployment Options**:
-  - **Desktop App**: `npm run tauri-build` (native desktop application)
-  - **Web Server**: `npm run build` then serve dist/ folder
-  - **Development**: `npm run tauri-dev` for desktop dev mode
-
-#### Import Paths - CRITICAL
-**ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.
-
-```typescript
-// ✅ CORRECT - Use @app/* for all imports
-import { AppLayout } from "@app/components/AppLayout";
-import { useFileContext } from "@app/contexts/FileContext";
-import { FileContext } from "@app/contexts/FileContext";
-
-// ❌ WRONG - Do not use @core/* or @proprietary/* in normal code
-import { AppLayout } from "@core/components/AppLayout";
-import { useFileContext } from "@proprietary/contexts/FileContext";
-```
-
-**Only use explicit aliases when:**
-- Building layer-specific override that wraps a lower layer's component
-- Example: `import { AppProviders as CoreAppProviders } from "@core/components/AppProviders"` when creating proprietary/AppProviders.tsx that extends the core version
-
-The `@app/*` alias automatically resolves to the correct layer based on build target (core/proprietary/desktop) and handles the fallback cascade.
-
-#### Component Override Pattern (Stub/Shadow)
-Use this pattern for desktop-specific or proprietary-specific features WITHOUT runtime checks or conditionals.
-
-**How it works:**
-1. Core defines stub component (returns null or no-op)
-2. Desktop/proprietary overrides with same path/name
-3. Core imports via `@app/*` - higher layer "shadows" core in those builds
-4. No `@ts-ignore`, no `isTauri()` checks, no runtime conditionals!
-
-**Example - Desktop-specific footer:**
-
-```typescript
-// core/components/rightRail/RightRailFooterExtensions.tsx (stub)
-interface RightRailFooterExtensionsProps {
-  className?: string;
-}
-
-export function RightRailFooterExtensions(_props: RightRailFooterExtensionsProps) {
-  return null; // Stub - does nothing in web builds
-}
-```
-
-```typescript
-// desktop/components/rightRail/RightRailFooterExtensions.tsx (real implementation)
-import { Box } from '@mantine/core';
-import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
-
-interface RightRailFooterExtensionsProps {
-  className?: string;
-}
-
-export function RightRailFooterExtensions({ className }: RightRailFooterExtensionsProps) {
-  return (
-    <Box className={className}>
-      <BackendHealthIndicator />
-    </Box>
-  );
-}
-```
-
-```typescript
-// core/components/shared/RightRail.tsx (usage - works in ALL builds)
-import { RightRailFooterExtensions } from '@app/components/rightRail/RightRailFooterExtensions';
-
-export function RightRail() {
-  return (
-    <div>
-      {/* In web builds: renders nothing (stub returns null) */}
-      {/* In desktop builds: renders BackendHealthIndicator */}
-      <RightRailFooterExtensions className="right-rail-footer" />
-    </div>
-  );
-}
-```
-
-**Build resolution:**
-- **Core build**: `@app/*` → `core/*` → Gets stub (returns null)
-- **Desktop build**: `@app/*` → `desktop/*` → Gets real implementation (shadows core)
-
-**Benefits:**
-- No runtime checks or feature flags
-- Type-safe across all builds
-- Clean, readable code
-- Build-time optimization (dead code elimination)
-
-#### Multi-Tool Workflow Architecture
-Frontend designed for **stateful document processing**:
-- Users upload PDFs once, then chain tools (split → merge → compress → view)
-- File state and processing results persist across tool switches
-- No file reloading between tools - performance critical for large PDFs (up to 100GB+)
-
-#### FileContext - Central State Management
-**Location**: `frontend/src/core/contexts/FileContext.tsx`
-- **Active files**: Currently loaded PDFs and their variants
-- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
-- **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
-- **IndexedDB persistence**: File storage with thumbnail caching
-- **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
-
-**Critical**: All file operations go through FileContext. Don't bypass with direct file handling.
-
-#### Processing Services
-- **enhancedPDFProcessingService**: Background PDF parsing and manipulation
-- **thumbnailGenerationService**: Web Worker-based with main-thread fallback
-- **fileStorage**: IndexedDB with LRU cache management
-
-#### Memory Management Strategy
-**Why manual cleanup exists**: Large PDFs (up to 100GB+) through multiple tools accumulate:
-- PDF.js documents that need explicit .destroy() calls
-- Blob URLs from tool outputs that need revocation
-- Web Workers that need termination
-Without cleanup: browser crashes with memory leaks.
-
-#### Tool Development
-
-**Architecture**: Modular hook-based system with clear separation of concerns:
-
-- **useToolOperation** (`frontend/src/core/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook
-  - Coordinates all tool operations with consistent interface
-  - Integrates with FileContext for operation tracking
-  - Handles validation, error handling, and UI state management
-
-- **Supporting Hooks**:
-  - **useToolState**: UI state management (loading, progress, error, files)
-  - **useToolApiCalls**: HTTP requests and file processing
-  - **useToolResources**: Blob URLs, thumbnails, ZIP downloads
-
-- **Utilities**:
-  - **toolErrorHandler**: Standardized error extraction and i18n support
-  - **toolResponseProcessor**: API response handling (single/zip/custom)
-  - **toolOperationTracker**: FileContext integration utilities
-
-**Three Tool Patterns**:
-
-**Pattern 1: Single-File Tools** (Individual processing)
-- Backend processes one file per API call
-- Set `multiFileEndpoint: false`
-- Examples: Compress, Rotate
-```typescript
-return useToolOperation({
-  operationType: 'compress',
-  endpoint: '/api/v1/misc/compress-pdf',
-  buildFormData: (params, file: File) => { /* single file */ },
-  multiFileEndpoint: false,
-});
-```
-
-**Pattern 2: Multi-File Tools** (Batch processing)
-- Backend accepts `MultipartFile[]` arrays in single API call
-- Set `multiFileEndpoint: true`
-- Examples: Split, Merge, Overlay
-```typescript
-return useToolOperation({
-  operationType: 'split',
-  endpoint: '/api/v1/general/split-pages',
-  buildFormData: (params, files: File[]) => { /* all files */ },
-  multiFileEndpoint: true,
-  filePrefix: 'split_',
-});
-```
-
-**Pattern 3: Complex Tools** (Custom processing)
-- Tools with complex routing logic or non-standard processing
-- Provide `customProcessor` for full control
-- Examples: Convert, OCR
-```typescript
-return useToolOperation({
-  operationType: 'convert',
-  customProcessor: async (params, files) => { /* custom logic */ },
-});
-```
-
-**Benefits**:
-- **No Timeouts**: Operations run until completion (supports 100GB+ files)
-- **Consistent**: All tools follow same pattern and interface
-- **Maintainable**: Single responsibility hooks, easy to test and modify
-- **i18n Ready**: Built-in internationalization support
-- **Type Safe**: Full TypeScript support with generic interfaces
-- **Memory Safe**: Automatic resource cleanup and blob URL management
-
-## Architecture Overview
-
-### Project Structure
-- **Backend**: Spring Boot application
-- **Frontend**: React-based SPA in `/frontend` directory
-  - **File Storage**: IndexedDB for client-side file persistence and thumbnails
-  - **Internationalization**: JSON-based translations (converted from backend .properties)
-- **PDF Processing**: PDFBox for core PDF operations, LibreOffice for conversions, PDF.js for client-side rendering
-- **Security**: Spring Security with optional authentication (controlled by `DOCKER_ENABLE_SECURITY`)
-- **Configuration**: YAML-based configuration with environment variable overrides
-
-### Controller Architecture
-- **API Controllers** (`src/main/java/.../controller/api/`): REST endpoints for PDF operations
-  - Organized by function: converters, security, misc, pipeline
-  - Follow pattern: `@RestController` + `@RequestMapping("/api/v1/...")`
-
-### Key Components
-- **SPDFApplication.java**: Main application class with desktop UI and browser launching logic
-- **ConfigInitializer**: Handles runtime configuration and settings files
-- **Pipeline System**: Automated PDF processing workflows via `PipelineController`
-- **Security Layer**: Authentication, authorization, and user management (when enabled)
-
-### Frontend Directory Structure
-The frontend is organized with a clear separation of concerns:
-
-- **`frontend/src/core/`**: Main application code (shared, production-ready components)
-  - **`core/components/`**: React components organized by feature
-    - `core/components/tools/`: Individual PDF tool implementations
-    - `core/components/viewer/`: PDF viewer components
-    - `core/components/pageEditor/`: Page manipulation UI
-    - `core/components/tooltips/`: Help tooltips for tools
-    - `core/components/shared/`: Reusable UI components
-  - **`core/contexts/`**: React Context providers
-    - `FileContext.tsx`: Central file state management
-    - `file/`: File reducer and selectors
-    - `toolWorkflow/`: Tool workflow state
-  - **`core/hooks/`**: Custom React hooks
-    - `hooks/tools/`: Tool-specific operation hooks (one directory per tool)
-    - `hooks/tools/shared/`: Shared hook utilities (useToolOperation, etc.)
-  - **`core/constants/`**: Application constants and configuration
-  - **`core/data/`**: Static data (tool taxonomy, etc.)
-  - **`core/services/`**: Business logic services (PDF processing, storage, etc.)
-
-- **`frontend/src/desktop/`**: Desktop-specific (Tauri) code
-- **`frontend/src/proprietary/`**: Proprietary/licensed features
-- **`frontend/src-tauri/`**: Tauri (Rust) native desktop application code
-- **`frontend/public/`**: Static assets served directly
-  - `public/locales/`: Translation JSON files
-
-### Component Architecture
-- **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/public/` (modern)
-- **Internationalization**:
-  - Backend: `messages_*.properties` files
-  - Frontend: JSON files in `frontend/public/locales/` (converted from .properties)
-  - Conversion Script: `scripts/convert_properties_to_json.py`
-
-### Configuration Modes
-- **Ultra-lite**: Basic PDF operations only
-- **Standard**: Full feature set
-- **Fat**: Pre-downloaded dependencies for air-gapped environments
-- **Security Mode**: Adds authentication, user management, and enterprise features
-
-### Testing Strategy
-- **Integration Tests**: Cucumber tests in `testing/cucumber/`
-- **Docker Testing**: `test.sh` validates all Docker variants
-- **Manual Testing**: No unit tests currently - relies on UI and API testing
-
-## Development Workflow
-
-1. **Local Development**:
-   - Backend: `./gradlew bootRun` (runs on localhost:8080)
-   - Frontend: `cd frontend && npm run dev` (runs on localhost:5173, proxies to backend)
-2. **Docker Testing**: Use `./test.sh` before submitting PRs
-3. **Code Style**: Spotless enforces Google Java Format automatically
-4. **Translations**:
-   - Backend: Use helper scripts in `/scripts` for multi-language updates
-   - Frontend: Update JSON files in `frontend/public/locales/` or use conversion script
-5. **Documentation**: API docs auto-generated and available at `/swagger-ui/index.html`
-
-## Frontend Architecture Status
-
-- **Core Status**: React SPA architecture complete with multi-tool workflow support
-- **State Management**: FileContext handles all file operations and tool navigation
-- **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
-- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
-  - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
-  - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker`
-  - Pattern: Each tool creates focused operation hook, UI consumes state/actions
-- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
-- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
-
-## Translation Rules
-
-- **CRITICAL**: Always update translations in `en-GB` only, never `en-US`
-- Translation files are located in `frontend/public/locales/`
-
-## Important Notes
-
-- **Java Version**: Minimum JDK 17, supports and recommends JDK 21
-- **Lombok**: Used extensively - ensure IDE plugin is installed
-- **File Persistence**:
-  - **Backend**: Designed to be stateless - files are processed in memory/temp locations only
-  - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails)
-- **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation
-- **Import Paths**: ALWAYS use `@app/*` for imports - never use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer
-- **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling
-- **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code
-- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
-- **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
-- **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
-- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
-
-## Communication Style
-- Be direct and to the point
-- No apologies or conversational filler
-- Answer questions directly without preamble
-- Explain reasoning concisely when asked
-- Avoid unnecessary elaboration
-
-## Decision Making
-- Ask clarifying questions before making assumptions
-- Stop and ask when uncertain about project-specific details
-- Confirm approach before making structural changes
-- Request guidance on preferences (cross-platform vs specific tools, etc.)
-- Verify understanding of requirements before proceeding

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -15,6 +15,19 @@ Before you start working on an issue, please comment on (or create) the issue an
 Once you have been assigned an issue, you can start working on it. When you are ready to submit your changes, open a pull request.
 For a detailed pull request tutorial, see [this guide](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github).
 
+## Development Quick Start
+
+This project uses [Task](https://taskfile.dev/) as a unified command runner. After cloning:
+
+1. Install the `task` CLI: https://taskfile.dev/installation/
+2. Run `task install` to install all dependencies
+3. Run `task dev` to start backend + frontend
+4. Run `task check` before submitting a PR
+
+Run `task --list` to see all available commands.
+
+## Pull Request Guidelines
+
 Please make sure your Pull Request adheres to the following guidelines:
 
 - Use the PR template provided.
@@ -39,9 +52,10 @@ If, at any point in time, you have a question, please feel free to ask in the sa
 
 ## Developer Documentation
 
-For technical guides, setup instructions, and development resources, please see our [Developer Documentation](devGuide/) which includes:
+For technical guides, setup instructions, and development resources:
 
-- [Developer Guide](devGuide/DeveloperGuide.md) - Main setup and architecture guide
+- [Developer Guide](DeveloperGuide.md) - Main setup and architecture guide
+- [Taskfile.yml](Taskfile.yml) - Unified task runner for all build/dev/test/lint commands
 - [Exception Handling Guide](devGuide/EXCEPTION_HANDLING_GUIDE.md) - Error handling patterns and i18n
 - [Translation Guide](devGuide/HowToAddNewLanguage.md) - Adding new languages
 - And more in the [devGuide folder](devGuide/)

DeveloperGuide.md

@@ -11,7 +11,7 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
 **Stirling 2.0** is built using:
 
 **Backend:**
-- Spring Boot (Java 17+, JDK 21 recommended)
+- Spring Boot (requires JDK 25)
 - PDFBox for core PDF operations
 - LibreOffice for document conversions
 - qpdf for PDF optimization
@@ -42,11 +42,13 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
 
 ### Prerequisites
 
+- [Task](https://taskfile.dev/installation/) — unified command runner (recommended)
 - Docker
 - Git
-- Java JDK 17 or later (JDK 21 recommended)
+- Java JDK 25
 - Node.js 18+ and npm (required for frontend development)
 - Gradle 7.0 or later (Included within the repo)
+- [uv](https://docs.astral.sh/uv/) — Python package manager (required for engine development)
 - Rust and Cargo (required for Tauri desktop app development)
 - Tauri CLI (install with `cargo install tauri-cli`)
 
@@ -59,7 +61,7 @@ This guide focuses on developing for Stirling 2.0, including both the React fron
    cd Stirling-PDF
    ```
 
-2. Install Docker and JDK17 if not already installed.
+2. Install Docker and JDK 25 if not already installed.
 
 3. Install a recommended Java IDE such as Eclipse, IntelliJ, or VSCode
    1. Only VSCode
@@ -82,13 +84,29 @@ For local testing, you should generally be testing the full 'Security' version o
 5. **Frontend Setup (Required for Stirling 2.0)**
    Navigate to the frontend directory and install dependencies using npm.
 
+### Verify Setup
+
+Run `task install` to install all project dependencies (frontend npm packages, engine Python packages). Gradle manages its own dependencies automatically. Then run `task check` to verify everything builds and passes.
+
 ## 4. Stirling 2.0 Development Workflow
 
+### Using Taskfile (Recommended)
+
+The fastest way to start developing:
+
+1. **Start developing**: `task dev` (runs backend + frontend concurrently — Ctrl+C to stop)
+2. **Or start services individually** in separate terminals:
+   - `task backend:dev` — Spring Boot on localhost:8080
+   - `task frontend:dev` — Vite on localhost:5173
+   - `task engine:dev` — FastAPI on localhost:5001
+
+Run `task --list` to see all available commands.
+
 ### Frontend Development (React)
 The frontend is a React SPA that runs independently during development:
 
-1. **Start the backend**: Run the Spring Boot application (serves API endpoints on localhost:8080)
-2. **Start the frontend dev server**: Navigate to the frontend directory and run the development server (serves UI on localhost:5173)
+1. **Start the backend**: `task backend:dev` (serves API endpoints on localhost:8080)
+2. **Start the frontend dev server**: `task frontend:dev` (serves UI on localhost:5173)
 3. **Development flow**: The Vite dev server automatically proxies API calls to the backend
 
 ### File Storage Architecture
@@ -99,7 +117,10 @@ Stirling 2.0 uses client-side file storage:
 
 ### Tauri Desktop App Development
 Stirling-PDF can be packaged as a cross-platform desktop application using Tauri with PDF file association support and bundled JRE.
-See [the frontend README](frontend/README.md#tauri) for build instructions.
+
+Using Taskfile: `task desktop:dev` (development) or `task desktop:build` (production build).
+
+See [the frontend README](frontend/README.md#tauri) for detailed build instructions.
 
 ## 5. Project Structure
 
@@ -187,7 +208,7 @@ services:
         limits:
           memory: 4G
     healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
+      test: ["CMD-SHELL", "curl -f http://localhost:8080$${SYSTEM_ROOTURIPATH:-''}/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
       interval: 5s
       timeout: 10s
       retries: 16
@@ -222,6 +243,20 @@ docker-compose -f exampleYmlFiles/docker-compose-latest-security.yml up
 
 ### Building Docker Images
 
+#### Using Taskfile (Recommended)
+
+```bash
+task docker:build            # standard image
+task docker:build:fat        # fat image (all features)
+task docker:build:ultra-lite # ultra-lite image
+task docker:up               # start standard compose stack
+task docker:up:fat           # start fat compose stack
+task docker:down             # stop all stacks
+task docker:logs             # tail logs
+```
+
+#### Manual Docker Builds
+
 Stirling-PDF uses different Docker images for various configurations. The build process is controlled by environment variables and uses specific Dockerfile variants. Here's how to build the Docker images:
 
 1. Set the security environment variable:
@@ -230,10 +265,10 @@ Stirling-PDF uses different Docker images for various configurations. The build
    export DISABLE_ADDITIONAL_FEATURES=true  # or false for to enable login and security features for builds
    ```
 
-2. Build the project with Gradle:
+2. Build the project:
 
    ```bash
-   ./gradlew clean build
+   task backend:build
    ```
 
 3. Build the Docker images:
@@ -261,9 +296,18 @@ Note: The `--no-cache` and `--pull` flags ensure that the build process uses the
 
 ## 7. Testing
 
+### Quick Testing with Taskfile
+
+Run all unit/integration tests across all components:
+
+```bash
+task test    # run all tests (backend + frontend + engine)
+task check   # full quality gate: lint + typecheck + test
+```
+
 ### Comprehensive Testing Script
 
-Stirling-PDF provides a `test.sh` script in the root directory. This script builds all versions of Stirling-PDF, checks that each version works, and runs Cucumber tests. It's recommended to run this script before submitting a final pull request.
+Stirling-PDF also provides a `test.sh` script in the root directory for Docker integration tests. This script builds all versions of Stirling-PDF, checks that each version works, and runs Cucumber tests. It's recommended to run this script before submitting a final pull request.
 
 To run the test script:
 
@@ -289,10 +333,11 @@ Note: The `test.sh` script will run automatically when you raise a PR. However,
 
 For React frontend development:
 
-1. Start the backend: Run the Spring Boot application to serve API endpoints on localhost:8080
-2. Start the frontend dev server: Navigate to the frontend directory and run the development server on localhost:5173
+1. Start the backend: `task backend:dev` (serves API endpoints on localhost:8080)
+2. Start the frontend dev server: `task frontend:dev` (serves UI on localhost:5173)
 3. The Vite dev server automatically proxies API calls to the backend
-4. Test React components, UI interactions, and IndexedDB file operations using browser developer tools
+4. Run frontend tests: `task frontend:test` (or `task frontend:test:watch` for watch mode)
+5. Test React components, UI interactions, and IndexedDB file operations using browser developer tools
 
 ### Local Testing (Java and UI Components)
 
@@ -308,7 +353,7 @@ To run Stirling-PDF locally:
 1. Compile and run the project using built-in IDE methods or by running:
 
    ```bash
-   ./gradlew bootRun
+   task backend:dev
    ```
 
 2. Access the application at `http://localhost:8080` in your web browser.
@@ -329,10 +374,11 @@ Important notes:
 2. Create a new branch for your feature or bug fix.
 3. Make your changes and commit them with clear, descriptive messages and ensure any documentation is updated related to your changes.
 4. Test your changes thoroughly in the Docker environment.
-5. Run the `test.sh` script to ensure all versions build correctly and pass the Cucumber tests:
+5. Run the quality gate and integration tests:
 
    ```bash
-   ./test.sh
+   task check   # lint + typecheck + test across all components
+   ./test.sh    # Docker integration tests (builds all variants + Cucumber)
    ```
 
 6. Push your changes to your fork.

FILE_SHARING.md

@@ -0,0 +1,444 @@
+# File Sharing Feature - Architecture & Workflow
+
+## Overview
+
+The File Sharing feature enables users to store files server-side and share them with other registered users or via token-based share links. Files are stored using a pluggable storage provider (local filesystem or database) with optional quota enforcement.
+
+**Key Capabilities:**
+- Server-side file storage (upload, update, download, delete)
+- Optional history bundle and audit log attachments per file
+- Direct user-to-user sharing with access roles
+- Token-based share links (requires `system.frontendUrl`)
+- Optional email notifications for shares (requires `mail.enabled`)
+- Access audit trail (tracks who accessed a share link and how)
+- Automatic share link expiration
+- Storage quotas (per-user and total)
+- Pluggable storage backend (local filesystem or database BLOB)
+- Integration with the Shared Signing workflow
+
+## Architecture
+
+### Database Schema
+
+**`stored_files`**
+- One record per uploaded file
+- Stores file metadata (name, content type, size, storage key)
+- Optionally links to a history bundle and audit log as separate stored objects
+- `workflow_session_id` — nullable link to a `WorkflowSession` (signing feature)
+- `file_purpose` — enum classifying the file's role: `GENERIC`, `SIGNING_ORIGINAL`, `SIGNING_SIGNED`, `SIGNING_HISTORY`
+
+**`file_shares`**
+- One record per sharing relationship
+- Two share types, distinguished by which fields are set:
+  - **User share**: `shared_with_user_id` is set, `share_token` is null
+  - **Link share**: `share_token` is set (UUID), `shared_with_user_id` is null
+- `access_role` — `EDITOR`, `COMMENTER`, or `VIEWER`
+- `expires_at` — nullable expiration for link shares
+- `workflow_participant_id` — when set, marks this as a **workflow share** (hidden from the file manager, accessible only via workflow endpoints)
+
+**`file_share_accesses`**
+- One record per access event on a share link
+- Tracks: user, share link, access type (`VIEW` or `DOWNLOAD`), timestamp
+
+**`storage_cleanup_entries`**
+- Queue of storage keys to be deleted asynchronously
+- Used when a file is deleted but the physical storage object cleanup is deferred
+
+### Access Roles
+
+| Role | Can Read | Can Write |
+|------|----------|-----------|
+| `EDITOR` | ✅ | ✅ |
+| `COMMENTER` | ✅ | ❌ |
+| `VIEWER` | ✅ | ❌ |
+
+Default role when none is specified: `EDITOR`.
+
+Owners always have full access regardless of role.
+
+#### Role Semantics: COMMENTER vs VIEWER
+
+In the file storage layer, `COMMENTER` and `VIEWER` are equivalent — both grant read-only access and neither can replace file content. The distinction is meaningful in the **signing workflow** context:
+
+| Context | COMMENTER | VIEWER |
+|---------|-----------|--------|
+| File storage | Read only (same as VIEWER) | Read only |
+| Signing workflow | Can submit a signing action | Read only |
+
+`WorkflowParticipant.canEdit()` returns `true` for `COMMENTER` (and `EDITOR`) roles, which the signing workflow uses to determine if a participant can still submit a signature. Once a participant has signed or declined, their effective role is automatically downgraded to `VIEWER` regardless of their configured role.
+
+The rationale: "annotating" a document (submitting a signature) is not the same as "replacing" it. COMMENTER grants annotation rights without file-replacement rights.
+
+### Backend Architecture
+
+#### Service Layer
+
+**FileStorageService** (`1137 lines`)
+- Core file management service
+- Upload, update, download, and delete operations
+- User share management (share, revoke, leave)
+- Link share management (create, revoke, access)
+- Access recording and listing
+- Storage quota enforcement
+- Configuration feature gate checks
+
+**StorageCleanupService**
+- Scheduled daily: deletes orphaned storage keys from `storage_cleanup_entries`
+- Scheduled daily: purges expired share links from `file_shares`
+- Processes cleanup in batches of 50 entries
+
+#### Storage Providers
+
+**LocalStorageProvider**
+- Files stored on the filesystem under `storage.local.basePath` (default: `./storage`)
+- Storage key is a path relative to the base directory
+
+**DatabaseStorageProvider**
+- Files stored as BLOBs in `stored_file_blobs` table
+- No filesystem dependency
+
+Provider is selected at startup via `storage.provider: local | database`.
+
+#### Controller Layer
+
+**FileStorageController** (`/api/v1/storage`)
+- All endpoints require authentication
+- File CRUD and sharing operations
+
+### Data Flow
+
+```
+User uploads file → StorageProvider stores bytes → StoredFile record created
+       ↓
+Owner shares file → FileShare record created (user or link)
+       ↓
+Recipient accesses file → Access recorded → File bytes streamed
+```
+
+## File Operations
+
+### Upload File
+
+```bash
+POST /api/v1/storage/files
+Content-Type: multipart/form-data
+
+file: document.pdf                # Required — main file
+historyBundle: history.json       # Optional — version history
+auditLog: audit.json              # Optional — audit trail
+```
+
+**Response:**
+```json
+{
+  "id": 42,
+  "fileName": "document.pdf",
+  "contentType": "application/pdf",
+  "sizeBytes": 102400,
+  "owner": "alice",
+  "ownedByCurrentUser": true,
+  "accessRole": "editor",
+  "createdAt": "2025-01-01T12:00:00",
+  "updatedAt": "2025-01-01T12:00:00",
+  "sharedWithUsers": [],
+  "sharedUsers": [],
+  "shareLinks": []
+}
+```
+
+### Update File
+
+Replaces the file content. Only the owner can update.
+
+```bash
+PUT /api/v1/storage/files/{fileId}
+Content-Type: multipart/form-data
+
+file: document_v2.pdf
+historyBundle: history.json       # Optional
+auditLog: audit.json              # Optional
+```
+
+### List Files
+
+Returns all files owned by or shared with the current user. Workflow-shared files (signing participants) are excluded — those are accessible via signing endpoints only.
+
+```bash
+GET /api/v1/storage/files
+```
+
+Response is sorted by `createdAt` descending.
+
+### Download File
+
+```bash
+GET /api/v1/storage/files/{fileId}/download?inline=false
+```
+
+- `inline=false` (default) — `Content-Disposition: attachment`
+- `inline=true` — `Content-Disposition: inline` (for browser preview)
+
+### Delete File
+
+Only the owner can delete. All associated share links and their access records are deleted first, then the database record, then the physical storage object.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}
+```
+
+## Sharing Operations
+
+### Share with User
+
+```bash
+POST /api/v1/storage/files/{fileId}/shares/users
+Content-Type: application/json
+
+{
+  "username": "bob",          # Username or email address
+  "accessRole": "editor"      # "editor", "commenter", or "viewer" (default: "editor")
+}
+```
+
+**Behaviour:**
+- If the target user exists: creates/updates a `FileShare` with `sharedWithUser` set
+- If `username` is an email address and the user doesn't exist: creates a share link and sends a notification email (requires `sharing.emailEnabled` and `sharing.linkEnabled`)
+- If the target user is the owner: returns 400
+- If sharing is disabled: returns 403
+
+### Revoke User Share
+
+Only the owner can revoke.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/users/{username}
+```
+
+### Leave Shared File
+
+The recipient removes themselves from a shared file.
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/self
+```
+
+### Create Share Link
+
+Creates a token-based link for anonymous/authenticated access. Requires `sharing.linkEnabled` and `system.frontendUrl` to be configured.
+
+```bash
+POST /api/v1/storage/files/{fileId}/shares/links
+Content-Type: application/json
+
+{
+  "accessRole": "viewer"      # Optional (default: "editor")
+}
+```
+
+**Response:**
+```json
+{
+  "token": "550e8400-e29b-41d4-a716-446655440000",
+  "accessRole": "viewer",
+  "createdAt": "2025-01-01T12:00:00",
+  "expiresAt": "2025-01-04T12:00:00"
+}
+```
+
+Expiration is set to `now + sharing.linkExpirationDays` (default: 3 days).
+
+### Revoke Share Link
+
+```bash
+DELETE /api/v1/storage/files/{fileId}/shares/links/{token}
+```
+
+Also deletes all access records for that token.
+
+## Share Link Access
+
+### Download via Share Link
+
+Authentication is required (even for share links). Anonymous access is not permitted.
+
+```bash
+GET /api/v1/storage/share-links/{token}?inline=false
+```
+
+- Returns 401 if unauthenticated
+- Returns 403 if authenticated but link doesn't permit access
+- Returns 410 if the link has expired
+- Records a `FileShareAccess` entry on success
+
+> **Token-as-credential semantics:** Any authenticated user who holds the token can access the file — the token is the credential. If you need per-user access control (only a specific person can open it), use "Share with User" instead. Share links are appropriate for broader distribution where possession of the token implies authorization.
+
+### Get Share Link Metadata
+
+```bash
+GET /api/v1/storage/share-links/{token}/metadata
+```
+
+Returns file name, owner, access role, creation/expiry timestamps, and whether the current user owns the file.
+
+### List Accessed Share Links
+
+Returns the most recent access for each non-expired share link the current user has accessed.
+
+```bash
+GET /api/v1/storage/share-links/accessed
+```
+
+### List Accesses for a Link (Owner Only)
+
+```bash
+GET /api/v1/storage/files/{fileId}/shares/links/{token}/accesses
+```
+
+Returns per-user access history (username, VIEW/DOWNLOAD, timestamp), sorted descending by time.
+
+## Workflow Share Integration
+
+Signing workflow participants access documents via their own `WorkflowParticipant.shareToken`. No `FileShare` record is created for participants; access control is self-contained in the `WorkflowParticipant` entity.
+
+The `FileShare.workflow_participant_id` column and the `FileShare.isWorkflowShare()` method are **deprecated**. Legacy data (sessions created before this change) may still have `FileShare` records with `workflow_participant_id` set, which continue to work via the existing token lookup path in `UnifiedAccessControlService`. No new records are created.
+
+`GET /api/v1/storage/files` returns all files owned by or shared with the current user (via `FileShare`). Signing-session PDFs use the `file_purpose` field (`SIGNING_ORIGINAL`, `SIGNING_SIGNED`, etc.) to distinguish them from generic files. The file manager UI can filter on this field if needed.
+
+## API Reference
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/api/v1/storage/files` | Upload file | Required |
+| PUT | `/api/v1/storage/files/{id}` | Update file | Required (owner) |
+| GET | `/api/v1/storage/files` | List accessible files | Required |
+| GET | `/api/v1/storage/files/{id}` | Get file metadata | Required |
+| GET | `/api/v1/storage/files/{id}/download` | Download file | Required |
+| DELETE | `/api/v1/storage/files/{id}` | Delete file | Required (owner) |
+| POST | `/api/v1/storage/files/{id}/shares/users` | Share with user | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/users/{username}` | Revoke user share | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/self` | Leave shared file | Required |
+| POST | `/api/v1/storage/files/{id}/shares/links` | Create share link | Required (owner) |
+| DELETE | `/api/v1/storage/files/{id}/shares/links/{token}` | Revoke share link | Required (owner) |
+| GET | `/api/v1/storage/share-links/{token}` | Download via share link | Required |
+| GET | `/api/v1/storage/share-links/{token}/metadata` | Get share link metadata | Required |
+| GET | `/api/v1/storage/share-links/accessed` | List accessed share links | Required |
+| GET | `/api/v1/storage/files/{id}/shares/links/{token}/accesses` | List share accesses | Required (owner) |
+
+## Configuration
+
+All storage settings live under the `storage:` key in `settings.yml`:
+
+```yaml
+storage:
+  enabled: true                  # Requires security.enableLogin = true
+  provider: local                # 'local' or 'database'
+  local:
+    basePath: './storage'        # Filesystem base directory (local provider only)
+  quotas:
+    maxStorageMbPerUser: -1      # Per-user storage cap in MB; -1 = unlimited
+    maxStorageMbTotal: -1        # Total storage cap in MB; -1 = unlimited
+    maxFileMb: -1                # Max size per upload (main + history + audit) in MB; -1 = unlimited
+  sharing:
+    enabled: false               # Master switch for all sharing (opt-in)
+    linkEnabled: false           # Enable token-based share links (requires system.frontendUrl)
+    emailEnabled: false          # Enable email notifications (requires mail.enabled)
+    linkExpirationDays: 3        # Days until share links expire
+```
+
+**Prerequisites:**
+- `storage.enabled` requires `security.enableLogin = true`
+- `sharing.linkEnabled` requires `system.frontendUrl` to be set (used to build share link URLs)
+- `sharing.emailEnabled` requires `mail.enabled = true`
+
+## Security Considerations
+
+### Access Control
+- All endpoints require authentication — there is no anonymous access
+- Owner-only operations enforced in service layer (not just controller)
+- `requireReadAccess` / `requireEditorAccess` checked on every download
+
+### Share Link Security
+- Tokens are UUIDs (random, not guessable)
+- Expiration enforced on every access
+- Expired links return HTTP 410 Gone
+- Revoked links delete all access records
+
+### Quota Enforcement
+- Checked before storing (not after)
+- Accounts for existing file size when replacing (only the delta counts)
+- Covers main file + history bundle + audit log in a single check
+
+## Automatic Cleanup
+
+`StorageCleanupService` runs two scheduled jobs daily:
+
+1. **Orphaned storage cleanup** — processes up to 50 `StorageCleanupEntry` records, deletes the physical storage object, then removes the entry. Failed attempts increment `attemptCount` for retry.
+
+2. **Expired share link cleanup** — deletes all `FileShare` records where `expiresAt` is in the past and `shareToken` is set.
+
+## Troubleshooting
+
+**"Storage is disabled":**
+- Check `storage.enabled: true` in settings
+- Verify `security.enableLogin: true`
+
+**"Share links are disabled":**
+- Check `sharing.linkEnabled: true`
+- Verify `system.frontendUrl` is set and non-empty
+
+**"Email sharing is disabled":**
+- Check `sharing.emailEnabled: true`
+- Verify `mail.enabled: true` and mail configuration
+
+**Signing-session PDF appearing in the general file list:**
+- This is expected — signing PDFs are accessible to owners and shared users
+- Filter by `file_purpose` (`SIGNING_ORIGINAL`, `SIGNING_SIGNED`) in the UI to distinguish them
+
+**Share link returns 410:**
+- Link has expired — check `expires_at` in `file_shares` table
+- Owner must create a new link
+
+### Debug Queries
+
+```sql
+-- List files and their share counts
+SELECT sf.stored_file_id, sf.original_filename, u.username as owner,
+       COUNT(DISTINCT fs.file_share_id) FILTER (WHERE fs.shared_with_user_id IS NOT NULL) as user_shares,
+       COUNT(DISTINCT fs.file_share_id) FILTER (WHERE fs.share_token IS NOT NULL) as link_shares
+FROM stored_files sf
+LEFT JOIN users u ON sf.owner_id = u.user_id
+LEFT JOIN file_shares fs ON fs.stored_file_id = sf.stored_file_id
+GROUP BY sf.stored_file_id, u.username;
+
+-- Check share link expiration
+SELECT share_token, access_role, created_at, expires_at,
+       expires_at < NOW() as is_expired
+FROM file_shares
+WHERE share_token IS NOT NULL;
+
+-- Check access history for a share link
+SELECT u.username, fsa.access_type, fsa.accessed_at
+FROM file_share_accesses fsa
+JOIN file_shares fs ON fsa.file_share_id = fs.file_share_id
+JOIN users u ON fsa.user_id = u.user_id
+WHERE fs.share_token = '{token}'
+ORDER BY fsa.accessed_at DESC;
+
+-- Pending cleanup entries
+SELECT storage_key, attempt_count, updated_at
+FROM storage_cleanup_entries
+ORDER BY updated_at ASC;
+```
+
+## Summary
+
+The File Sharing feature provides:
+- ✅ Server-side file storage with pluggable backend (local/database)
+- ✅ History bundle and audit log attachments per file
+- ✅ Direct user-to-user sharing with EDITOR/COMMENTER/VIEWER roles
+- ✅ Token-based share links with expiration
+- ✅ Optional email notifications for shares
+- ✅ Per-access audit trail for share links
+- ✅ Storage quotas (per-user, total, per-file)
+- ✅ Automatic cleanup of expired links and orphaned storage
+- ✅ Workflow integration (signing-session PDFs stored via same infrastructure; participant access via `WorkflowParticipant.shareToken`)

LICENSE

@@ -6,10 +6,18 @@ Portions of this software are licensed as follows:
 
 * All content that resides under the "app/proprietary/" directory of this repository,
 if that directory exists, is licensed under the license defined in "app/proprietary/LICENSE".
+* All content that resides under the "app/saas/" directory of this repository,
+if that directory exists, is licensed under the license defined in "app/saas/LICENSE".
+* All content that resides under the "engine/" directory of this repository,
+if that directory exists, is licensed under the license defined in "engine/LICENSE".
 * All content that resides under the "frontend/src/proprietary/" directory of this repository,
 if that directory exists, is licensed under the license defined in "frontend/src/proprietary/LICENSE".
 * All content that resides under the "frontend/src/desktop/" directory of this repository,
 if that directory exists, is licensed under the license defined in "frontend/src/desktop/LICENSE".
+* All content that resides under the "frontend/src/saas/" directory of this repository,
+if that directory exists, is licensed under the license defined in "frontend/src/saas/LICENSE".
+* All content that resides under the "frontend/src/prototypes/" directory of this repository,
+if that directory exists, is licensed under the license defined in "frontend/src/prototypes/LICENSE".
 * Content outside of the above mentioned directories or restrictions above is
 available under the MIT License as defined below.
 

README.md

@@ -60,7 +60,7 @@ For full installation options (including desktop and Kubernetes), see our [Docum
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-For development setup, see the [Developer Guide](DeveloperGuide.md).
+This project uses [Task](https://taskfile.dev/) as a unified command runner for all build, dev, and test commands. Run `task install` to get started, or see the [Developer Guide](DeveloperGuide.md) for full details.
 
 For adding translations, see the [Translation Guide](devGuide/HowToAddNewLanguage.md).
 

SHARED_SIGNING.md

@@ -0,0 +1,691 @@
+# Shared Signing Feature - Architecture & Workflow
+
+## Overview
+
+The Shared Signing feature enables collaborative document signing workflows where a document owner can request signatures from multiple participants. Each participant receives a secure token to access the document, submit their digital signature (with optional wet signature overlay), and track the signing progress.
+
+**Key Capabilities:**
+- Multi-participant signing sessions
+- Digital certificate signatures (P12/PKCS12, JKS, SERVER, USER_CERT, PEM/UPLOAD)
+- Visual wet signature overlays (drawn, typed, or uploaded) — multiple per participant
+- Token-based participant access (no authentication required for participants)
+- Authenticated participant access for registered users via sign-requests API
+- Progress tracking for session owners
+- Optional signature summary page appended to finalized PDF
+- Automatic role downgrade after signing (security)
+- GDPR-compliant wet signature metadata cleanup
+
+## Architecture
+
+### Database Schema
+
+#### Core Tables
+
+**`workflow_sessions`**
+- Tracks signing sessions created by document owners
+- Links to original and processed (signed) PDF files
+- Stores session metadata (message, due date, status)
+
+**`workflow_participants`**
+- One record per participant per session
+- Tracks participant status: PENDING → VIEWED → SIGNED/DECLINED
+  - `NOTIFIED` status is reserved for a future email notification feature; no current code path sets it
+- Stores participant-specific metadata (certificates, wet signatures) as JSONB
+- Each participant holds their own `shareToken` (UUID) for token-based access — no separate `FileShare` record is created
+- `accessRole` controls what actions the participant can perform. `COMMENTER` (and `EDITOR`) allow submitting a signature; `VIEWER` does not. After signing/declining, effective role is automatically downgraded to `VIEWER`
+
+**`user_server_certificates`**
+- Stores auto-generated certificates per user
+- Enables "Use My Personal Certificate" option
+
+#### Extended Tables
+
+**`stored_files`**
+- Added `workflow_session_id` to link files to signing sessions
+- Added `file_purpose` enum (SIGNING_ORIGINAL, SIGNING_SIGNED, etc.)
+
+**`file_shares`**
+- Regular file shares are created when the session owner shares the document with other users via the file manager
+- The `workflow_participant_id` column is deprecated; participant access is self-contained in `WorkflowParticipant.shareToken`
+
+### Backend Architecture
+
+#### Service Layer
+
+**WorkflowSessionService** (`816 lines`)
+- Core workflow management service
+- Creates sessions with participants
+- Handles participant status updates
+- Stores signature metadata (certificates and wet signatures)
+- Finalizes sessions by coordinating signing process
+
+Key responsibilities:
+- Session lifecycle management (create, list, get details, delete)
+- Participant management (add, remove, notify)
+- Certificate submission storage
+- Wet signature metadata storage
+- Session finalization orchestration
+
+**UnifiedAccessControlService**
+- Validates participant tokens
+- Checks session status and expiration
+- Maps participant status to effective access role
+- Automatic role downgrade after signing: SIGNED/DECLINED → VIEWER role
+
+**UserServerCertificateService**
+- Auto-generates personal certificates for users
+- Manages certificate storage and retrieval
+- Enables "Use My Personal Certificate" signing option
+
+#### Controller Layer
+
+**SigningSessionController** (Owner-facing + Authenticated participant endpoints)
+- `POST /api/v1/security/cert-sign/sessions` - Create signing session
+- `GET /api/v1/security/cert-sign/sessions` - List user's sessions
+- `GET /api/v1/security/cert-sign/sessions/{id}` - Get session details
+- `GET /api/v1/security/cert-sign/sessions/{id}/pdf` - Download original PDF
+- `POST /api/v1/security/cert-sign/sessions/{id}/finalize` - Finalize and apply signatures
+- `GET /api/v1/security/cert-sign/sessions/{id}/signed-pdf` - Download signed PDF
+- `DELETE /api/v1/security/cert-sign/sessions/{id}` - Delete session
+- `POST /api/v1/security/cert-sign/sessions/{id}/participants` - Add participants
+- `DELETE /api/v1/security/cert-sign/sessions/{id}/participants/{participantId}` - Remove participant
+- `GET /api/v1/security/cert-sign/sign-requests` - List sign requests for authenticated user
+- `GET /api/v1/security/cert-sign/sign-requests/{id}` - Get sign request details
+- `GET /api/v1/security/cert-sign/sign-requests/{id}/document` - Download document for signing
+- `POST /api/v1/security/cert-sign/sign-requests/{id}/sign` - Sign document (authenticated)
+- `POST /api/v1/security/cert-sign/sign-requests/{id}/decline` - Decline sign request (authenticated)
+
+**WorkflowParticipantController** (Participant-facing, token-based)
+- `GET /api/v1/workflow/participant/session?token={token}` - View session details
+- `GET /api/v1/workflow/participant/details?token={token}` - Get participant details
+- `GET /api/v1/workflow/participant/document?token={token}` - Download PDF
+- `POST /api/v1/workflow/participant/submit-signature` - Submit signature
+- `POST /api/v1/workflow/participant/decline?token={token}` - Decline to sign
+
+#### Data Flow
+
+```
+Owner creates session → Participants receive tokens →
+Participants access via token (or authenticated) → Participants submit signatures →
+Owner finalizes → System applies signatures → [Optional: append summary page] → Signed PDF generated
+```
+
+### Frontend Architecture
+
+#### Quick Access Integration
+
+**SignPopout Component**
+- Displays in Quick Access Bar (top navigation)
+- Shows active and completed signing sessions
+- Auto-refreshes every 15 seconds to show signature progress
+- Badge indicator shows count of pending sessions
+
+**ActiveSessionsPanel**
+- Lists sessions where user is owner or participant
+- Shows signature progress: "X/Y signatures" (e.g., "2/5 signatures")
+- Color-coded badges:
+  - Blue: No signatures yet (0/X)
+  - Yellow: Partial signatures (X/Y)
+  - Green: Ready to finalize (X/X)
+
+**CompletedSessionsPanel**
+- Lists finalized sessions and declined sign requests
+- Allows viewing/downloading signed PDFs
+
+#### Workbench Views
+
+**SignRequestWorkbenchView**
+- Full-screen view for participants to sign documents
+- Integrated PDF viewer with annotation support
+- Certificate selection (Personal/Organization/Custom P12)
+- Wet signature input (draw, type, or upload)
+- Signature placement on PDF pages
+
+**SessionDetailWorkbenchView**
+- Owner's view of session details
+- Participant list with status indicators
+- Ability to add/remove participants
+- Finalize button when all signatures collected
+- Download original/signed PDF
+
+#### State Management
+
+**FileContext Integration**
+- Signing sessions operate within FileContext workflow
+- PDFs loaded once, persist across tool switches
+- Memory management for large files (up to 100GB+)
+
+**ToolWorkflowContext**
+- Registers custom workbench views
+- Manages navigation between viewer and signing tools
+- Preserves file state during signing operations
+
+#### Services & Hooks
+
+**workflowService.ts**
+- API client for all signing endpoints
+- Handles session creation, listing, and management
+- Participant operations (submit, decline)
+
+**useWorkflowSession.ts**
+- React hook for owner session management
+- State management for session list and details
+
+**useParticipantSession.ts**
+- React hook for participant signing workflow
+- Manages signature submission state
+
+## Signing Workflow Process
+
+### 1. Session Creation (Owner)
+
+```
+Owner → Uploads PDF → Selects participants → Creates session
+        ↓
+System creates:
+  - WorkflowSession record
+  - WorkflowParticipant records (one per participant, each with a unique shareToken)
+        ↓
+Participants receive token (via email or share link)
+```
+
+**API Call:**
+```bash
+POST /api/v1/security/cert-sign/sessions
+Content-Type: multipart/form-data
+
+file: document.pdf
+workflowType: SIGNING
+documentName: "contract.pdf"           # Optional display name
+participantUserIds: [1, 2, 3]          # Registered user IDs
+participantEmails: ["a@b.com"]         # External/unregistered users
+participants: [...]                    # Detailed participant configs (optional)
+message: "Please sign this contract"
+dueDate: "2025-12-31"
+ownerEmail: "owner@example.com"        # Optional, for notifications
+workflowMetadata: '{"showSignature": false, "showLogo": false, "includeSummaryPage": true}'
+```
+
+**Session-level `workflowMetadata` fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `showSignature` | boolean | Show visible digital signature block on PDF |
+| `pageNumber` | integer | Page to place digital signature on |
+| `showLogo` | boolean | Show logo in digital signature block |
+| `includeSummaryPage` | boolean | Append a signature summary page before digital signing |
+
+**Response:**
+```json
+{
+  "sessionId": "uuid",
+  "documentName": "contract.pdf",
+  "participants": [
+    {
+      "userId": 1,
+      "email": "user1@example.com",
+      "shareToken": "token1",
+      "status": "PENDING"
+    }
+  ],
+  "participantCount": 3,
+  "signedCount": 0
+}
+```
+
+### 2. Participant Access
+
+```
+Participant → Clicks token link → Views session details
+        ↓
+Status changes: PENDING/NOTIFIED → VIEWED
+        ↓
+Participant downloads PDF to review
+```
+
+**Access URL (unauthenticated):**
+```
+https://app.example.com/sign?token={participant_token}
+```
+
+**Authenticated participants** can also use:
+```
+GET /api/v1/security/cert-sign/sign-requests
+GET /api/v1/security/cert-sign/sign-requests/{sessionId}
+GET /api/v1/security/cert-sign/sign-requests/{sessionId}/document
+```
+
+**Automatic Status Update:**
+- First access: PENDING/NOTIFIED → VIEWED
+- Downloads tracked but don't change status
+
+### 3. Signature Submission
+
+```
+Participant → Selects certificate type → Uploads certificate (if needed)
+           → Draws/uploads wet signatures (optional, multiple supported)
+           → Submits signature
+        ↓
+System stores:
+  - Certificate data (P12/JKS keystore as base64)
+  - Certificate password
+  - Wet signatures metadata (JSON array: base64 image + coordinates per signature)
+        ↓
+Status changes: VIEWED → SIGNED
+Access role: EDITOR → VIEWER (automatic downgrade)
+```
+
+**API Call (token-based, unauthenticated):**
+```bash
+POST /api/v1/workflow/participant/submit-signature
+Content-Type: multipart/form-data
+
+participantToken: {token}
+certType: P12 | JKS | SERVER | USER_CERT
+p12File: certificate.p12 (if certType=P12)
+jksFile: keystore.jks (if certType=JKS)
+password: cert_password
+showSignature: false
+pageNumber: 1
+location: "New York"
+reason: "I approve this contract"
+showLogo: false
+wetSignaturesData: '[{"page":0,"x":100,"y":200,"width":150,"height":50,"type":"IMAGE","data":"base64..."}]'
+```
+
+**API Call (authenticated users):**
+```bash
+POST /api/v1/security/cert-sign/sign-requests/{sessionId}/sign
+Content-Type: multipart/form-data
+
+certType: SERVER | USER_CERT | UPLOAD | PEM | PKCS12 | PFX | JKS
+p12File: certificate.p12 (if applicable)
+password: cert_password
+reason: "I approve this contract"
+location: "New York"
+wetSignaturesData: '[...]'
+```
+
+**Metadata Storage (JSONB):**
+```json
+{
+  "certificateSubmission": {
+    "certType": "P12",
+    "password": "cert_password",
+    "p12Keystore": "base64_encoded_keystore",
+    "showSignature": false,
+    "pageNumber": 1,
+    "location": "New York",
+    "reason": "I approve this contract",
+    "showLogo": false
+  },
+  "wetSignatures": [
+    {
+      "type": "IMAGE",
+      "data": "base64_image",
+      "page": 0,
+      "x": 100,
+      "y": 200,
+      "width": 150,
+      "height": 50
+    }
+  ]
+}
+```
+
+Note: Multiple wet signatures are supported per participant (array).
+
+### 4. Progress Tracking (Owner)
+
+```
+Owner → Views session list → Sees "2/5 signatures"
+      → Clicks session → Views participant status
+        ↓
+Participant list shows:
+  - user1@example.com: SIGNED ✓
+  - user2@example.com: SIGNED ✓
+  - user3@example.com: VIEWED (pending)
+  - user4@example.com: PENDING
+  - user5@example.com: DECLINED ✗
+        ↓
+Auto-refresh every 15 seconds
+```
+
+**Badge Colors:**
+- 🔵 Blue: 0/5 signatures (awaiting)
+- 🟡 Yellow: 2/5 signatures (partial)
+- 🟢 Green: 5/5 signatures (ready to finalize)
+
+### 5. Session Finalization
+
+```
+Owner → Clicks "Finalize" → System processes signatures
+        ↓
+Processing steps:
+  1. Apply wet signatures to PDF (visual overlays)
+  1.5. Append signature summary page (if includeSummaryPage=true)
+  2. Apply digital certificates in participant order
+     - Visual signature block suppressed when summary page is enabled
+  3. Store signed PDF
+  4. Clear wet signature metadata (GDPR compliance)
+        ↓
+Owner downloads signed PDF
+```
+
+**Finalization Process:**
+
+1. **Apply Wet Signatures First**
+   ```java
+   for (WetSignature sig : wetSignatures) {
+     PDPage page = document.getPage(sig.getPage());
+     byte[] imageBytes = Base64.decode(sig.getData());
+     // Convert Y from top-left (UI) to bottom-left (PDF) coordinate system
+     float pdfY = page.getMediaBox().getHeight() - sig.getY() - sig.getHeight();
+     PDImageXObject image = PDImageXObject.createFromByteArray(document, imageBytes, "signature");
+     contentStream.drawImage(image, sig.getX(), pdfY, sig.getWidth(), sig.getHeight());
+   }
+   ```
+
+2. **Append Summary Page (optional, before digital signing)**
+
+   If `includeSummaryPage=true`, a new A4 page is appended showing:
+   - Stirling logo and "Signature Summary" title
+   - Document name and session owner
+   - Finalization timestamp
+   - Per-participant: name, email, status, signed timestamp, reason, location, certificate type
+   - Supports overflow to additional pages
+
+   This step occurs **before** digital certificate signing so signatures are not invalidated.
+   When a summary page is added, the visual digital signature block (`showSignature`) is suppressed — wet signatures (hand-drawn overlays) are unaffected.
+
+3. **Apply Digital Certificates (in participant order)**
+   ```java
+   for (Participant p : participants) {
+     if (p.status == SIGNED) {
+       KeyStore keystore = buildKeystore(p.certificate);
+       // Reason: participant override > owner default > "Document Signing"
+       // Location: participant-provided only (no default)
+       CertSignController.sign(pdfBytes, keystore, password, settings);
+     }
+   }
+   ```
+
+4. **Store and Cleanup**
+   ```java
+   StoredFile signedFile = storeFile(signedPdfBytes, SIGNING_SIGNED);
+   session.setProcessedFile(signedFile);
+   session.setFinalized(true);
+
+   // GDPR: Clear sensitive metadata after finalization
+   for (Participant p : participants) {
+     p.metadata.remove("wetSignatures");         // Clears wet signature image data
+     p.metadata.remove("certificateSubmission"); // Clears keystore bytes + password
+   }
+   ```
+
+**API Call:**
+```bash
+POST /api/v1/security/cert-sign/sessions/{sessionId}/finalize
+Authorization: Bearer {owner_token}
+```
+
+**Response:** Binary PDF file with Content-Disposition header
+
+## Key Technical Features
+
+### 1. Double JSON Encoding Fix (Recent)
+
+**Problem:** JSONB columns were storing JSON strings instead of JSON objects, requiring double-parsing.
+
+**Solution:** Created `JsonMapConverter` JPA AttributeConverter:
+```java
+@Convert(converter = JsonMapConverter.class)
+@Column(name = "participant_metadata", columnDefinition = "jsonb")
+private Map<String, Object> participantMetadata;
+```
+
+**Benefits:**
+- Single parse on read
+- Proper JSON storage in PostgreSQL
+- Type-safe Map access
+- Backward compatible with legacy data
+
+### 2. Signature Progress Display (Recent)
+
+**Implementation:**
+- `WorkflowSessionResponse` includes `participantCount` and `signedCount`
+- `WorkflowMapper` calculates counts when converting to DTO
+- Frontend displays "X/Y signatures" in session list
+- Auto-refresh every 15 seconds keeps counts updated
+
+### 3. Token-Based Security
+
+**No Authentication Required for Participants:**
+- Participants access via secure token (UUID)
+- Token linked to specific participant and session
+- Automatic expiration support
+- One-time signing (cannot sign twice)
+
+**Authenticated Participant Access:**
+- Registered users can also access sign requests via `/api/v1/security/cert-sign/sign-requests`
+- Standard Spring Security authentication required
+- Supports additional cert types: UPLOAD, PEM, PKCS12, PFX
+
+**Automatic Role Downgrade:**
+- After signing: EDITOR → VIEWER
+- After declining: EDITOR → VIEWER
+- Prevents modification after action taken
+
+### 4. Storage Integration
+
+**Unified with File Sharing:**
+- All PDFs stored via `StorageProvider` (Database or Local)
+- Respects storage quotas
+- Supports files up to 100GB+ (with Local storage)
+- Consistent with existing file sharing infrastructure
+
+### 5. Certificate Types
+
+**P12/PKCS12/PFX:** User uploads PKCS#12 file + password
+**JKS:** User uploads Java KeyStore + password
+**PEM/UPLOAD:** User uploads PEM certificate + private key
+**SERVER:** Uses organization's server certificate (no upload needed)
+**USER_CERT:** Uses user's auto-generated personal certificate (one-click)
+
+Note: UPLOAD, PEM, PKCS12, PFX are available on the authenticated (`sign-requests`) path. The token-based path uses P12, JKS, SERVER, USER_CERT.
+
+## Frontend Components Overview
+
+### Owner Workflow Components
+
+1. **CreateSessionPanel** - Form to create new signing session
+2. **ActiveSessionsPanel** - List of pending sessions with progress
+3. **SessionDetailWorkbenchView** - Full session management interface
+4. **CompletedSessionsPanel** - History of finalized sessions
+
+### Participant Workflow Components
+
+1. **SignRequestWorkbenchView** - Main signing interface
+2. **SignatureSettingsInput** - Certificate selection and configuration
+3. **WetSignatureInput** - Draw/type/upload signature overlay
+4. **SignatureSettingsDisplay** - Preview of signature settings
+
+### Shared Components
+
+1. **UserSelector** - Multi-select user picker for participants
+2. **LocalEmbedPDFWithAnnotations** - PDF viewer with signature placement
+
+## Configuration
+
+### Backend Configuration
+
+**application.properties:**
+```properties
+# Database (H2 or PostgreSQL)
+spring.jpa.hibernate.ddl-auto=update
+
+# Security
+DOCKER_ENABLE_SECURITY=true
+
+# Storage Provider (DATABASE or LOCAL)
+storage.provider=LOCAL
+storage.maxFileSize=100GB
+```
+
+### Frontend Configuration
+
+**Quick Access Bar:**
+- Signing popout accessible from top navigation
+- Auto-refresh interval: 15 seconds
+- Badge shows pending session count
+
+## API Reference Summary
+
+### Owner Endpoints (Authenticated)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/v1/security/cert-sign/sessions` | Create session |
+| GET | `/api/v1/security/cert-sign/sessions` | List sessions |
+| GET | `/api/v1/security/cert-sign/sessions/{id}` | Get details |
+| POST | `/api/v1/security/cert-sign/sessions/{id}/finalize` | Finalize session |
+| GET | `/api/v1/security/cert-sign/sessions/{id}/pdf` | Download original |
+| GET | `/api/v1/security/cert-sign/sessions/{id}/signed-pdf` | Download signed |
+| DELETE | `/api/v1/security/cert-sign/sessions/{id}` | Delete session |
+| POST | `/api/v1/security/cert-sign/sessions/{id}/participants` | Add participants |
+| DELETE | `/api/v1/security/cert-sign/sessions/{id}/participants/{pid}` | Remove participant |
+
+### Authenticated Participant Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/security/cert-sign/sign-requests` | List sign requests |
+| GET | `/api/v1/security/cert-sign/sign-requests/{id}` | Get sign request details |
+| GET | `/api/v1/security/cert-sign/sign-requests/{id}/document` | Download document |
+| POST | `/api/v1/security/cert-sign/sign-requests/{id}/sign` | Sign document |
+| POST | `/api/v1/security/cert-sign/sign-requests/{id}/decline` | Decline signing |
+
+### Token-Based Participant Endpoints (No Auth Required)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/workflow/participant/session?token={token}` | View session |
+| GET | `/api/v1/workflow/participant/details?token={token}` | Get participant details |
+| GET | `/api/v1/workflow/participant/document?token={token}` | Download PDF |
+| POST | `/api/v1/workflow/participant/submit-signature` | Submit signature |
+| POST | `/api/v1/workflow/participant/decline?token={token}` | Decline signing |
+
+## Security Considerations
+
+### Data Protection
+- Wet signature image data cleared after finalization (GDPR compliance)
+- Certificate submission data (keystore bytes + password) cleared after finalization (GDPR compliance)
+- Certificate passwords are not encrypted at rest while stored (TODO: encrypt at rest)
+- Token expiration support
+
+### Access Control
+- Owner authentication required for session management
+- Participant access via secure UUID tokens (no auth) or standard auth (sign-requests)
+- Automatic role downgrade prevents re-signing
+- Session status checks prevent unauthorized actions
+
+### Audit Trail
+- All participant actions tracked
+- FileShare access logged
+- Status transitions recorded
+- Notification history maintained
+
+## Performance Characteristics
+
+### Scalability
+- Supports PDFs up to 100GB+ (with Local storage provider)
+- Memory-efficient streaming for large files
+- IndexedDB caching on frontend
+- Database indexes on session_id, share_token, workflow_session_id
+
+### Response Times
+- Session creation: ~500ms (10MB file)
+- Session listing: ~100ms
+- Token validation: ~50ms
+- Finalization: ~2s per MB of PDF (varies by certificate operations)
+
+## Future Enhancements
+
+### Planned Features
+- Email notifications for participants
+- Reminder system for pending signatures
+- Bulk signing operations
+- Template-based signing workflows
+- Signature validation/verification UI
+- Certificate password encryption at rest
+- Certificate keystore cleanup after finalization (GDPR)
+- Webhook support for external integrations
+- Analytics dashboard for signing metrics
+
+### Additional Workflow Types
+- **REVIEW** - Document review with comments
+- **APPROVAL** - Multi-level approval chains
+- **COLLABORATION** - Real-time collaborative editing
+
+## Troubleshooting
+
+### Common Issues
+
+**"Token invalid" error:**
+- Check token exists in workflow_participants table
+- Verify session is not finalized
+- Check expiration date (expires_at)
+
+**Signature not appearing on PDF:**
+- Verify certificate type is correct
+- Check certificate password
+- Review logs for signing errors
+- Ensure PDFDocumentFactory is available
+
+**"Awaiting signatures" not updating:**
+- Backend should return participantCount and signedCount
+- Frontend auto-refresh every 15 seconds
+- Check network tab for API errors
+
+**Wet signatures not visible after finalization:**
+- Wet signatures are applied first as image overlays (Step 1)
+- Check `wetSignaturesData` was sent as valid JSON array
+- Verify page index is within document bounds
+- Note: wet signatures survive regardless of `includeSummaryPage` setting
+
+### Debug Queries
+
+```sql
+-- Check session status
+SELECT session_id, status, finalized,
+       (SELECT COUNT(*) FROM workflow_participants WHERE workflow_session_id = ws.id) as participant_count,
+       (SELECT COUNT(*) FROM workflow_participants WHERE workflow_session_id = ws.id AND status = 'SIGNED') as signed_count
+FROM workflow_sessions ws;
+
+-- Check participant tokens
+SELECT email, status, share_token, expires_at
+FROM workflow_participants
+WHERE workflow_session_id = (SELECT id FROM workflow_sessions WHERE session_id = '{session_id}');
+
+-- Check metadata storage
+SELECT email,
+       participant_metadata->'certificateSubmission'->>'certType' as cert_type,
+       jsonb_array_length(participant_metadata->'wetSignatures') as wet_sig_count
+FROM workflow_participants;
+```
+
+## Summary
+
+The Shared Signing feature provides a complete collaborative signing workflow with:
+- ✅ Multi-participant support with progress tracking
+- ✅ Multiple certificate types (P12/PKCS12/PFX, JKS, PEM, SERVER, USER_CERT)
+- ✅ Visual wet signature overlays (multiple per participant)
+- ✅ Token-based security for unauthenticated participants
+- ✅ Authenticated participant access via sign-requests API
+- ✅ Automatic role management
+- ✅ Large file support (100GB+)
+- ✅ GDPR-compliant wet signature metadata cleanup
+- ✅ Real-time progress updates
+- ✅ Full frontend integration with Quick Access Bar
+- ✅ Optional signature summary page with logo and participant details
+
+The architecture leverages existing file sharing infrastructure while adding workflow-specific features, ensuring consistency and maintainability across the application.

Taskfile.yml

@@ -0,0 +1,161 @@
+version: '3'
+
+output: prefixed
+
+vars:
+  FIND_FREE_PORT_PS: powershell -NoProfile -File scripts/find-free-port.ps1
+  FIND_FREE_PORT_SH: bash scripts/find-free-port.sh
+
+includes:
+  backend:
+    taskfile: .taskfiles/backend.yml
+    dir: .
+  frontend:
+    taskfile: .taskfiles/frontend.yml
+    dir: frontend
+  engine:
+    taskfile: .taskfiles/engine.yml
+    dir: engine
+  docker:
+    taskfile: .taskfiles/docker.yml
+    dir: .
+  desktop:
+    taskfile: .taskfiles/desktop.yml
+    dir: frontend
+  e2e:
+    taskfile: .taskfiles/e2e.yml
+    dir: .
+
+tasks:
+  # ============================================================
+  # Setup & Prerequisites
+  # ============================================================
+
+  install:
+    desc: "Install all project dependencies"
+    cmds:
+      - task: frontend:install
+      - task: engine:install
+
+  # ============================================================
+  # Development
+  # ============================================================
+
+  dev:
+    desc: "Start backend + frontend concurrently on free ports"
+    vars:
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173{{end}}'
+      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+    deps:
+      - task: backend:dev
+        vars:
+          PORT: '{{.BACKEND_PORT}}'
+      - task: frontend:dev
+        vars:
+          PORT: '{{.FRONTEND_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          OPEN: "true"
+
+  dev:all:
+    desc: "Start backend + frontend + engine concurrently on free ports"
+    vars:
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173 5001{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173 5001{{end}}'
+      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      FRONTEND_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+      ENGINE_PORT: '{{index (splitList "\n" .PORTS) 2}}'
+    deps:
+      - task: engine:dev
+        vars:
+          PORT: '{{.ENGINE_PORT}}'
+      - task: backend:dev
+        vars:
+          PORT: '{{.BACKEND_PORT}}'
+          AIENGINE_URL: 'http://localhost:{{.ENGINE_PORT}}'
+      - task: frontend:dev:prototypes
+        vars:
+          PORT: '{{.FRONTEND_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          OPEN: "true"
+
+  # ============================================================
+  # Build
+  # ============================================================
+
+  build:
+    desc: "Build all components"
+    cmds:
+      - task: backend:build
+      - task: frontend:build
+
+  # ============================================================
+  # Test
+  # ============================================================
+
+  test:
+    desc: "Run ALL tests (backend + frontend + engine)"
+    cmds:
+      - task: backend:test
+      - task: frontend:test
+      - task: engine:test
+
+  # ============================================================
+  # Lint & Format
+  # ============================================================
+
+  lint:
+    desc: "Run all linters"
+    cmds:
+      - task: frontend:lint
+      - task: engine:lint
+
+  fix:
+    desc: "Auto-fix all components"
+    cmds:
+      - task: backend:fix
+      - task: frontend:fix
+      - task: engine:fix
+
+  format:
+    desc: "Auto-fix formatting across all components"
+    cmds:
+      - task: backend:format
+      - task: frontend:format
+      - task: engine:format
+
+  format:check:
+    desc: "Check formatting across all components"
+    cmds:
+      - task: backend:format:check
+      - task: frontend:format:check
+      - task: engine:format:check
+
+  # ============================================================
+  # Quality Gate
+  # ============================================================
+
+  check:
+    desc: "Quick quality gate for local development"
+    cmds:
+      - task: backend:check
+      - task: frontend:check
+      - task: engine:check
+
+  check:all:
+    desc: "Full CI quality gate"
+    cmds:
+      - task: backend:check
+      - task: frontend:check:all
+      - task: engine:check
+
+  # ============================================================
+  # Clean
+  # ============================================================
+
+  clean:
+    desc: "Clean all build artifacts"
+    cmds:
+      - task: backend:clean
+      - task: engine:clean

app/common/build.gradle

@@ -5,10 +5,12 @@ bootRun {
 spotless {
     java {
         target 'src/**/java/**/*.java'
+        targetExclude 'src/main/java/org/apache/**'
         googleJavaFormat(googleJavaFormatVersion).aosp().reorderImports(false)
+        // google-java-format 1.28.0 bundles Guava 32.x which crashes Spotless lint on JDK 24/25
+        suppressLintsFor { setStep('google-java-format') }
 
         importOrder("java", "javax", "org", "com", "net", "io", "jakarta", "lombok", "me", "stirling")
-        toggleOffOn()
         trimTrailingWhitespace()
         leadingTabsToSpaces()
         endWithNewline()
@@ -27,25 +29,55 @@ spotless {
     }
 }
 dependencies {
-    api 'org.springframework.boot:spring-boot-starter-web'
-    api 'org.springframework.boot:spring-boot-starter-aop'
-    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20240325.1'
+    api 'com.google.guava:guava:33.6.0-jre'
+    api 'org.springframework.boot:spring-boot-starter-webmvc'
+    api 'org.springframework.boot:spring-boot-starter-aspectj'
+    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20260313.1'
     api 'com.fathzer:javaluator:3.0.6'
     api 'com.posthog.java:posthog:1.2.0'
     api 'org.apache.commons:commons-lang3:3.20.0'
-    api 'com.drewnoakes:metadata-extractor:2.19.0' // Image metadata extractor
+    api 'com.drewnoakes:metadata-extractor:2.20.0' // Image metadata extractor
     api 'com.vladsch.flexmark:flexmark-html2md-converter:0.64.8'
     api "org.apache.pdfbox:pdfbox:$pdfboxVersion"
     api "org.apache.pdfbox:pdfbox-io:$pdfboxVersion"
     api "org.apache.pdfbox:xmpbox:$pdfboxVersion"
     api "org.apache.pdfbox:preflight:$pdfboxVersion"
-    api 'com.github.junrar:junrar:7.5.7' // RAR archive support for CBR files
+    api 'com.github.junrar:junrar:7.5.10' // RAR archive support for CBR files
     api 'jakarta.servlet:jakarta.servlet-api:6.1.0'
     api 'org.snakeyaml:snakeyaml-engine:3.0.1'
-    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.15"
+    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3"
     // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
     api 'org.simplejavamail:simple-java-mail:8.12.6'
     api 'org.simplejavamail:outlook-module:8.12.6' // MSG file support
     api 'jakarta.mail:jakarta.mail-api:2.1.5'
     runtimeOnly 'org.eclipse.angus:angus-mail:2.0.5'
+
+    // Tabula table extraction — used by the shared PDF parser and directly by downstream modules.
+    // api-scoped so downstream modules (core, proprietary) retain it on their compile classpath.
+    api ('technology.tabula:tabula:1.0.5') {
+        exclude group: 'org.slf4j', module: 'slf4j-simple'
+        exclude group: 'org.bouncycastle', module: 'bcprov-jdk15on'
+        exclude group: 'com.google.code.gson', module: 'gson'
+    }
+
+    api 'com.stirling:jpdfium:1.0.0'
+
+    // -PjpdfiumPlatforms=all|<csv of linux-x64,linux-arm64,darwin-x64,darwin-arm64,windows-x64>
+    def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'all').toString().trim()
+    def jpdfiumAllPlatforms = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']
+    def jpdfiumPlatforms = jpdfiumPlatformsProp == 'all'
+            ? jpdfiumAllPlatforms
+            : jpdfiumPlatformsProp.split(',').collect { it.trim() }.findAll { it }
+    def jpdfiumInvalid = jpdfiumPlatforms.findAll { !jpdfiumAllPlatforms.contains(it) }
+    if (jpdfiumInvalid) {
+        throw new GradleException("Unknown jpdfiumPlatforms value(s): ${jpdfiumInvalid.join(', ')}. " +
+                "Valid: ${jpdfiumAllPlatforms.join(', ')} or 'all'.")
+    }
+    logger.lifecycle("JPDFium native platforms: ${jpdfiumPlatforms.join(', ')}")
+    jpdfiumPlatforms.each { platform ->
+        runtimeOnly "com.stirling:jpdfium-natives-${platform}:1.0.0"
+    }
+
+    // ArchUnit: enforces module dependency direction (see ArchitectureTest)
+    testImplementation 'com.tngtech.archunit:archunit-junit5:1.4.2'
 }

app/common/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java

@@ -68,6 +68,36 @@ public class EndpointConfiguration {
         return endpoint.startsWith("/") ? endpoint.substring(1) : endpoint;
     }
 
+    /**
+     * Translate a full request URI like {@code /api/v1/general/remove-pages} into the endpoint key
+     * used by this configuration ({@code remove-pages}). Convert endpoints are a special case -
+     * {@code /api/v1/convert/pdf/img} is registered as {@code pdf-to-img}. Returns {@code null} if
+     * the URI is not an {@code /api/v1/<group>/<endpoint>} path.
+     */
+    public static String endpointKeyForUri(String uri) {
+        if (uri == null || !uri.contains("/api/v1")) {
+            return null;
+        }
+        String[] parts = uri.split("/");
+        if (parts.length <= 4) {
+            return null;
+        }
+        if ("convert".equals(parts[3]) && parts.length > 5) {
+            return parts[4] + "-to-" + parts[5];
+        }
+        return parts[4];
+    }
+
+    /**
+     * Convenience wrapper around {@link #isEndpointEnabled(String)} that accepts a full request URI
+     * and translates it to the endpoint key. Falls back to treating the URI itself as a key for
+     * non-{@code /api/v1/...} paths so callers can pass arbitrary URIs.
+     */
+    public boolean isEndpointEnabledForUri(String uri) {
+        String key = endpointKeyForUri(uri);
+        return isEndpointEnabled(key != null ? key : uri);
+    }
+
     public void enableEndpoint(String endpoint) {
         String normalized = normalizeEndpoint(endpoint);
         endpointStatuses.put(normalized, true);
@@ -103,8 +133,9 @@ public class EndpointConfiguration {
 
         // Rule 2: Functional-group override - check if endpoint belongs to any disabled functional
         // group
-        for (String group : endpointGroups.keySet()) {
-            if (disabledGroups.contains(group) && endpointGroups.get(group).contains(endpoint)) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
+            if (disabledGroups.contains(group) && entry.getValue().contains(endpoint)) {
                 // Skip tool groups (qpdf, OCRmyPDF, Ghostscript, LibreOffice, etc.)
                 if (!isToolGroup(group)) {
                     log.debug(
@@ -131,10 +162,11 @@ public class EndpointConfiguration {
 
         // Rule 4: Single-dependency check - if no alternatives defined, check if endpoint belongs
         // to any disabled tool groups
-        for (String group : endpointGroups.keySet()) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
             if (isToolGroup(group)
                     && disabledGroups.contains(group)
-                    && endpointGroups.get(group).contains(endpoint)) {
+                    && entry.getValue().contains(endpoint)) {
                 log.debug(
                         "isEndpointEnabled('{}') -> false (single tool group '{}' disabled, no alternatives)",
                         original,
@@ -354,6 +386,7 @@ public class EndpointConfiguration {
         addEndpointToGroup("Security", "cert-sign");
         addEndpointToGroup("Security", "remove-cert-sign");
         addEndpointToGroup("Security", "sanitize-pdf");
+        addEndpointToGroup("Security", "timestamp-pdf");
         addEndpointToGroup("Security", "auto-redact");
         addEndpointToGroup("Security", "validate-signature");
         addEndpointToGroup("Security", "add-stamp");
@@ -371,7 +404,6 @@ public class EndpointConfiguration {
         addEndpointToGroup("Other", REMOVE_BLANKS);
         addEndpointToGroup("Other", "remove-annotations");
         addEndpointToGroup("Other", "get-info-on-pdf");
-        addEndpointToGroup("Other", "remove-image-pdf");
         addEndpointToGroup("Other", "add-attachments");
         addEndpointToGroup("Other", "replace-invert-pdf");
         addEndpointToGroup("Other", "edit-table-of-contents");
@@ -471,6 +503,7 @@ public class EndpointConfiguration {
         addEndpointToGroup("Java", "auto-rename");
         addEndpointToGroup("Java", "auto-split-pdf");
         addEndpointToGroup("Java", "sanitize-pdf");
+        addEndpointToGroup("Java", "timestamp-pdf");
         addEndpointToGroup("Java", "crop");
         addEndpointToGroup("Java", "get-info-on-pdf");
         addEndpointToGroup("Java", "pdf-to-single-page");
@@ -486,7 +519,6 @@ public class EndpointConfiguration {
         addEndpointToGroup("Java", REMOVE_BLANKS);
         addEndpointToGroup("Java", "remove-annotations");
         addEndpointToGroup("Java", "pdf-to-text");
-        addEndpointToGroup("Java", "remove-image-pdf");
         addEndpointToGroup("Java", "pdf-to-markdown");
         addEndpointToGroup("Java", "add-attachments");
         addEndpointToGroup("Java", "compress-pdf");
@@ -606,6 +638,12 @@ public class EndpointConfiguration {
         return endpointGroups.getOrDefault(group, new HashSet<>());
     }
 
+    public Set<String> getAllEndpoints() {
+        return endpointGroups.values().stream()
+                .flatMap(Set::stream)
+                .collect(java.util.stream.Collectors.toSet());
+    }
+
     private boolean isToolGroup(String group) {
         return "qpdf".equals(group)
                 || "OCRmyPDF".equals(group)
@@ -639,8 +677,9 @@ public class EndpointConfiguration {
         }
 
         // Check if endpoint belongs to any disabled functional group
-        for (String group : endpointGroups.keySet()) {
-            if (disabledGroups.contains(group) && endpointGroups.get(group).contains(endpoint)) {
+        for (Map.Entry<String, Set<String>> entry : endpointGroups.entrySet()) {
+            String group = entry.getKey();
+            if (disabledGroups.contains(group) && entry.getValue().contains(endpoint)) {
                 if (!isToolGroup(group)) {
                     return false;
                 }

app/common/src/main/java/stirling/software/SPDF/pdf/parser/CompositeTableParser.java

@@ -0,0 +1,73 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.io.IOException;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.context.annotation.Primary;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Chains table parsers in priority order: Tabula lattice → Tabula stream → {@link
+ * LineAlignmentTableParser}. The first parser returning a result above {@link
+ * #TABULA_CONFIDENCE_THRESHOLD} wins; results from different parsers are never mixed on one page.
+ */
+@Service
+@Primary
+@RequiredArgsConstructor
+@Slf4j
+public class CompositeTableParser implements TableParser {
+
+    /** Min Tabula confidence to accept results; below this LineAlignment is tried instead. */
+    static final float TABULA_CONFIDENCE_THRESHOLD = 0.5f;
+
+    private final TabulaTableParser tabulaParser;
+    private final LineAlignmentTableParser lineAlignmentParser;
+
+    @Override
+    public List<TableFragment> parse(PDDocument document, RawPage rawPage) throws IOException {
+        // Step 1: Tabula lattice mode (ruled/bordered tables).
+        List<TableFragment> latticeResults = filterConfident(tabulaParser.parse(document, rawPage));
+        if (!latticeResults.isEmpty()) {
+            log.debug(
+                    "Page {}: using Tabula lattice ({} table(s))",
+                    rawPage.pageNumber(),
+                    latticeResults.size());
+            return latticeResults;
+        }
+
+        // Step 2: Tabula stream mode (borderless/whitespace-delimited tables).
+        // parseStream is not on the TableParser interface — this intentionally couples to the
+        // concrete TabulaTableParser since stream mode is a Tabula-specific concept.
+        List<TableFragment> streamResults =
+                filterConfident(tabulaParser.parseStream(document, rawPage));
+        if (!streamResults.isEmpty()) {
+            log.debug(
+                    "Page {}: using Tabula stream ({} table(s))",
+                    rawPage.pageNumber(),
+                    streamResults.size());
+            return streamResults;
+        }
+
+        // Step 3: Geometry-based line-alignment fallback.
+        List<TableFragment> lineResults = lineAlignmentParser.parse(document, rawPage);
+        if (!lineResults.isEmpty()) {
+            log.debug(
+                    "Page {}: using LineAlignment ({} table(s))",
+                    rawPage.pageNumber(),
+                    lineResults.size());
+            return lineResults;
+        }
+
+        return List.of();
+    }
+
+    private List<TableFragment> filterConfident(List<TableFragment> tables) {
+        return tables.stream().filter(t -> t.confidence() >= TABULA_CONFIDENCE_THRESHOLD).toList();
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/LineAlignmentTableParser.java

@@ -0,0 +1,528 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.TreeMap;
+import java.util.regex.Pattern;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Fallback {@link TableParser} for borderless financial tables using text geometry.
+ *
+ * <p>Identifies "anchor lines" (≥2 numeric tokens), builds a column grid from their right-edge
+ * positions, groups vertically proximate anchor lines into table candidates, then scores each group
+ * on column consistency and anchor density (confidence ceiling 0.85).
+ */
+@Service
+@Slf4j
+public class LineAlignmentTableParser implements TableParser {
+
+    /** Width in points of each column position bucket. */
+    static final float COLUMN_BUCKET_PT = 5f;
+
+    /** Tolerance in buckets when matching a token's right-edge to a confirmed column position. */
+    private static final int COLUMN_MATCH_BUCKETS = 2;
+
+    /** Maximum gap (as a multiple of modal line spacing) before splitting a group. */
+    private static final float MAX_GAP_FACTOR = 2.5f;
+
+    /** Minimum anchor rows (numeric-heavy) to form a valid table. */
+    static final int MIN_TABLE_ROWS = 3;
+
+    /** Minimum confirmed column positions to form a valid table. */
+    static final int MIN_COLUMNS = 2;
+
+    /**
+     * Min fraction of anchor lines a column must appear on to be confirmed (permissive for N/A
+     * rows).
+     */
+    private static final double COLUMN_MIN_FREQUENCY = 0.40;
+
+    /**
+     * Matches financial numeric tokens: integers, decimals, parenthetical negatives, currency,
+     * percent, nil dashes.
+     */
+    private static final Pattern NUMERIC =
+            Pattern.compile("^[\\(\\-\\$£€¥]?\\d[\\d,\\.]*[\\)%]?$|^[-–—]$");
+
+    /**
+     * Lines within this y-distance are merged into one row (restores rows split by LineBuilder's
+     * column-gap logic).
+     */
+    static final float ROW_MERGE_TOLERANCE_PT = 2f;
+
+    // ── public API ───────────────────────────────────────────────────────────────────────────────
+
+    @Override
+    public List<TableFragment> parse(PDDocument document, RawPage rawPage) throws IOException {
+        List<RawLine> lines = rawPage.lines();
+        if (lines.size() < MIN_TABLE_ROWS) return List.of();
+
+        float modalSpacing = computeModalSpacing(lines);
+        List<TokenizedLine> tokenized =
+                mergeCoincidentLines(lines.stream().map(this::tokenize).toList());
+
+        List<TokenizedLine> anchors = tokenized.stream().filter(TokenizedLine::isAnchor).toList();
+
+        if (anchors.size() < MIN_TABLE_ROWS) return List.of();
+
+        List<Float> columnGrid = buildColumnGrid(anchors);
+        if (columnGrid.size() < MIN_COLUMNS) {
+            log.debug(
+                    "Page {}: LineAlignment — fewer than {} confirmed columns, skipping",
+                    rawPage.pageNumber(),
+                    MIN_COLUMNS);
+            return List.of();
+        }
+
+        List<List<TokenizedLine>> groups = groupRows(tokenized, columnGrid, modalSpacing);
+
+        List<TableFragment> results = new ArrayList<>();
+        for (int i = 0; i < groups.size(); i++) {
+            buildFragment(groups.get(i), columnGrid, rawPage.pageNumber(), i)
+                    .ifPresent(results::add);
+        }
+
+        log.debug(
+                "Page {}: LineAlignment detected {} table(s) ({} anchor lines, {} columns)",
+                rawPage.pageNumber(),
+                results.size(),
+                anchors.size(),
+                columnGrid.size());
+        return results;
+    }
+
+    // ── coincident-line merging ──────────────────────────────────────────────────────────────────
+
+    /**
+     * Merges tokenised lines sharing the same y-position into one row, rejoining label/value halves
+     * split by LineBuilder.
+     */
+    List<TokenizedLine> mergeCoincidentLines(List<TokenizedLine> tokenized) {
+        if (tokenized.size() < 2) return tokenized;
+
+        List<TokenizedLine> result = new ArrayList<>();
+        int i = 0;
+
+        while (i < tokenized.size()) {
+            float baseY = tokenized.get(i).line().bounds().y();
+            int j = i + 1;
+            while (j < tokenized.size()
+                    && Math.abs(tokenized.get(j).line().bounds().y() - baseY)
+                            <= ROW_MERGE_TOLERANCE_PT) {
+                j++;
+            }
+
+            if (j == i + 1) {
+                result.add(tokenized.get(i));
+            } else {
+                result.add(mergeGroup(tokenized.subList(i, j)));
+            }
+            i = j;
+        }
+
+        return result;
+    }
+
+    private TokenizedLine mergeGroup(List<TokenizedLine> group) {
+        List<TextFragment> mergedFragments =
+                group.stream()
+                        .flatMap(tl -> tl.line().fragments().stream())
+                        .sorted(Comparator.comparingDouble(f -> f.bounds().x()))
+                        .toList();
+
+        Bounds mergedBounds =
+                group.stream()
+                        .map(tl -> tl.line().bounds())
+                        .reduce(Bounds::merge)
+                        .orElse(group.get(0).line().bounds());
+
+        RawLine mergedLine =
+                new RawLine(
+                        group.get(0).line().lineId(),
+                        mergedFragments,
+                        mergedBounds,
+                        group.get(0).line().pageNumber());
+
+        return tokenize(mergedLine);
+    }
+
+    // ── tokenisation ─────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Splits fragments into word-level tokens; x-positions are estimated linearly within each
+     * fragment.
+     */
+    TokenizedLine tokenize(RawLine line) {
+        List<LineToken> tokens = new ArrayList<>();
+        for (TextFragment frag : line.fragments()) {
+            tokens.addAll(tokensFromFragment(frag));
+        }
+        List<LineToken> numeric = tokens.stream().filter(LineToken::numeric).toList();
+        return new TokenizedLine(line, tokens, numeric);
+    }
+
+    private List<LineToken> tokensFromFragment(TextFragment frag) {
+        String raw = frag.text();
+        if (raw == null || raw.isBlank()) return List.of();
+
+        float fragX = frag.bounds().x();
+        float fragWidth = frag.bounds().width();
+        int rawLen = raw.length();
+
+        List<LineToken> result = new ArrayList<>();
+        int offset = 0;
+        for (String part : raw.split("\\s+")) {
+            if (part.isEmpty()) {
+                offset++;
+                continue;
+            }
+            int idx = raw.indexOf(part, offset);
+            if (idx < 0) idx = offset;
+
+            float tokenX = rawLen > 0 ? fragX + ((float) idx / rawLen) * fragWidth : fragX;
+            float tokenRight =
+                    rawLen > 0
+                            ? fragX + ((float) (idx + part.length()) / rawLen) * fragWidth
+                            : fragX + fragWidth;
+
+            result.add(new LineToken(part, tokenX, tokenRight, NUMERIC.matcher(part).matches()));
+            offset = idx + part.length();
+        }
+        return result;
+    }
+
+    // ── column grid ──────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Returns confirmed column right-edge positions — those appearing on ≥ {@value
+     * #COLUMN_MIN_FREQUENCY} × N anchor lines.
+     */
+    private List<Float> buildColumnGrid(List<TokenizedLine> anchors) {
+        // bucket → set of line indices that contributed a numeric token to that bucket
+        Map<Integer, List<Integer>> bucketLines = new HashMap<>();
+        for (int i = 0; i < anchors.size(); i++) {
+            for (LineToken t : anchors.get(i).numeric()) {
+                int bucket = bucket(t.right());
+                bucketLines.computeIfAbsent(bucket, k -> new ArrayList<>()).add(i);
+            }
+        }
+
+        int minHits =
+                Math.max(MIN_TABLE_ROWS, (int) Math.ceil(anchors.size() * COLUMN_MIN_FREQUENCY));
+
+        // Confirmed buckets → average right-edge for that bucket
+        TreeMap<Integer, Float> confirmed = new TreeMap<>();
+        for (Map.Entry<Integer, List<Integer>> entry : bucketLines.entrySet()) {
+            // Count distinct lines
+            long distinctLines = entry.getValue().stream().distinct().count();
+            if (distinctLines >= minHits) {
+                double avg =
+                        entry.getValue().stream()
+                                .distinct() // weight each line equally regardless of token count
+                                .mapToDouble(
+                                        lineIdx ->
+                                                avgRightEdgeForBucket(
+                                                        anchors, lineIdx, entry.getKey()))
+                                .average()
+                                .orElse(entry.getKey() * (double) COLUMN_BUCKET_PT);
+                confirmed.put(entry.getKey(), (float) avg);
+            }
+        }
+
+        return new ArrayList<>(confirmed.values()); // already sorted by bucket (left to right)
+    }
+
+    /**
+     * Returns the average right-edge position of tokens in {@code line} whose bucket matches {@code
+     * targetBucket}, falling back to the bucket's nominal centre when no tokens match.
+     */
+    private double avgRightEdgeForBucket(
+            List<TokenizedLine> anchors, int lineIdx, int targetBucket) {
+        return anchors.get(lineIdx).numeric().stream()
+                .filter(t -> bucket(t.right()) == targetBucket)
+                .mapToDouble(LineToken::right)
+                .average()
+                .orElse(targetBucket * (double) COLUMN_BUCKET_PT);
+    }
+
+    // ── grouping ─────────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Groups anchor lines into table candidates, including adjacent label rows; a gap &gt;
+     * MAX_GAP_FACTOR × modal spacing splits groups.
+     */
+    private List<List<TokenizedLine>> groupRows(
+            List<TokenizedLine> all, List<Float> columnGrid, float modalSpacing) {
+        float maxGap = modalSpacing > 0 ? modalSpacing * MAX_GAP_FACTOR : 30f;
+
+        List<List<TokenizedLine>> groups = new ArrayList<>();
+        List<TokenizedLine> current = new ArrayList<>();
+
+        for (int i = 0; i < all.size(); i++) {
+            TokenizedLine tl = all.get(i);
+            boolean fits = tl.isAnchor() && matchesGrid(tl, columnGrid);
+
+            if (current.isEmpty()) {
+                if (fits) current.add(tl);
+                continue;
+            }
+
+            float gap =
+                    tl.line().bounds().y()
+                            - current.get(current.size() - 1).line().bounds().bottom();
+
+            if (gap > maxGap) {
+                groups.add(current);
+                current = new ArrayList<>();
+                if (fits) current.add(tl);
+                continue;
+            }
+
+            if (fits) {
+                current.add(tl);
+            } else if (!tl.line().text().isBlank()) {
+                // Include non-anchor lines (labels) only if they have text and are within
+                // proximity.
+                current.add(tl);
+            }
+        }
+
+        if (!current.isEmpty()) groups.add(current);
+
+        return groups.stream().filter(g -> hasEnoughAnchorRows(g, columnGrid)).toList();
+    }
+
+    private boolean hasEnoughAnchorRows(List<TokenizedLine> group, List<Float> columnGrid) {
+        return group.stream().filter(r -> r.isAnchor() && matchesGrid(r, columnGrid)).count()
+                >= MIN_TABLE_ROWS;
+    }
+
+    /** A line "matches" the grid when ≥ 60 % of its numeric tokens land in confirmed columns. */
+    private boolean matchesGrid(TokenizedLine tl, List<Float> columnGrid) {
+        if (tl.numeric().isEmpty()) return false;
+        long matches =
+                tl.numeric().stream()
+                        .filter(t -> nearestColumnIndex(t.right(), columnGrid) >= 0)
+                        .count();
+        return (double) matches / tl.numeric().size() >= 0.60;
+    }
+
+    private boolean hasInconsistentColumnMatch(TokenizedLine tl, List<Float> columnGrid) {
+        if (tl.numeric().isEmpty()) return false;
+        long hits =
+                tl.numeric().stream()
+                        .filter(t -> nearestColumnIndex(t.right(), columnGrid) >= 0)
+                        .count();
+        return (double) hits / tl.numeric().size() < 0.60;
+    }
+
+    // ── fragment assembly ────────────────────────────────────────────────────────────────────────
+
+    private Optional<TableFragment> buildFragment(
+            List<TokenizedLine> group, List<Float> columnGrid, int pageNumber, int tableIndex) {
+
+        long anchorCount =
+                group.stream().filter(r -> r.isAnchor() && matchesGrid(r, columnGrid)).count();
+        if (anchorCount < MIN_TABLE_ROWS) return Optional.empty();
+
+        List<String> warnings = new ArrayList<>();
+        List<List<String>> rawRows = new ArrayList<>();
+        List<TableRow> rows = new ArrayList<>();
+
+        for (int rowIdx = 0; rowIdx < group.size(); rowIdx++) {
+            TokenizedLine tl = group.get(rowIdx);
+            List<String> rawRow = buildRawRow(tl, columnGrid);
+            rawRows.add(Collections.unmodifiableList(rawRow));
+            rows.add(buildTableRow(rowIdx, tl, rawRow, columnGrid));
+        }
+
+        // Column count = 1 label column + confirmed numeric columns
+        int colCount = columnGrid.size() + 1;
+        Bounds bounds = computeGroupBounds(group);
+        float confidence = computeConfidence(group, columnGrid, warnings);
+
+        return Optional.of(
+                new TableFragment(
+                        "tbl-la-p" + pageNumber + "-" + tableIndex,
+                        pageNumber,
+                        bounds,
+                        List.of(),
+                        Collections.unmodifiableList(rows),
+                        Collections.unmodifiableList(rawRows),
+                        colCount,
+                        confidence,
+                        Collections.unmodifiableList(warnings),
+                        null));
+    }
+
+    /**
+     * Builds a raw row as a list of strings: index 0 = label text, indices 1..N = column values.
+     */
+    private List<String> buildRawRow(TokenizedLine tl, List<Float> columnGrid) {
+        String[] cells = new String[columnGrid.size() + 1];
+        Arrays.fill(cells, "");
+
+        // Separate label tokens (those not landing in any confirmed column) from column tokens.
+        List<String> labelParts = new ArrayList<>();
+        for (LineToken token : tl.all()) {
+            int col = nearestColumnIndex(token.right(), columnGrid);
+            if (col >= 0 && token.numeric()) {
+                int cellIdx = col + 1;
+                cells[cellIdx] =
+                        cells[cellIdx].isEmpty()
+                                ? token.text()
+                                : cells[cellIdx] + " " + token.text();
+            } else {
+                labelParts.add(token.text());
+            }
+        }
+        cells[0] = String.join(" ", labelParts).trim();
+        return Arrays.asList(cells);
+    }
+
+    private TableRow buildTableRow(
+            int rowIdx, TokenizedLine tl, List<String> rawRow, List<Float> columnGrid) {
+        List<TableCell> cells = new ArrayList<>(rawRow.size());
+
+        // Label cell: use the line's full bounds as an approximation.
+        cells.add(TableCell.of(0, rawRow.get(0), tl.line().bounds()));
+
+        for (int col = 0; col < columnGrid.size(); col++) {
+            String text = col + 1 < rawRow.size() ? rawRow.get(col + 1) : "";
+            float right = columnGrid.get(col);
+            float left = col > 0 ? columnGrid.get(col - 1) : right - 50f;
+            Bounds cellBounds =
+                    new Bounds(
+                            left,
+                            tl.line().bounds().y(),
+                            right - left,
+                            tl.line().bounds().height());
+            cells.add(TableCell.of(col + 1, text, cellBounds));
+        }
+        return new TableRow(rowIdx, Collections.unmodifiableList(cells));
+    }
+
+    // ── confidence scoring ───────────────────────────────────────────────────────────────────────
+
+    /**
+     * Heuristic score in [0.0, 0.85] (ceiling keeps results below Tabula lattice which starts at
+     * 1.0). Base 0.70; +0.05/col beyond 2 (max +0.10); +0.05 at ≥5 anchors, +0.05 at ≥8; −0.15 if
+     * &gt;30 % of anchors have inconsistent columns; −0.10 if non-anchors outnumber anchors.
+     */
+    private float computeConfidence(
+            List<TokenizedLine> group, List<Float> columnGrid, List<String> warnings) {
+        float score = 0.70f;
+
+        long anchorCount =
+                group.stream().filter(r -> r.isAnchor() && matchesGrid(r, columnGrid)).count();
+        long totalRows = group.size();
+
+        // More columns
+        int extraCols = Math.min(columnGrid.size() - MIN_COLUMNS, 2);
+        score += extraCols * 0.05f;
+
+        // More anchor rows
+        if (anchorCount >= 5) score += 0.05f;
+        if (anchorCount >= 8) score += 0.05f;
+
+        // Inconsistent column matching
+        long inconsistent =
+                group.stream()
+                        .filter(TokenizedLine::isAnchor)
+                        .filter(tl -> hasInconsistentColumnMatch(tl, columnGrid))
+                        .count();
+        if (inconsistent > anchorCount * 0.30) {
+            score -= 0.15f;
+            warnings.add(
+                    "Column match inconsistent on "
+                            + inconsistent
+                            + "/"
+                            + anchorCount
+                            + " anchor rows");
+        }
+
+        // Label-heavy
+        long nonAnchor = totalRows - anchorCount;
+        if (nonAnchor > anchorCount) {
+            score -= 0.10f;
+            warnings.add(
+                    "Non-anchor rows ("
+                            + nonAnchor
+                            + ") outnumber anchor rows ("
+                            + anchorCount
+                            + ")");
+        }
+
+        return Math.max(0f, Math.min(0.85f, score));
+    }
+
+    // ── utility ──────────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Returns the grid index nearest to {@code rightEdge}, or -1 if none is within {@value
+     * #COLUMN_MATCH_BUCKETS} buckets.
+     */
+    private int nearestColumnIndex(float rightEdge, List<Float> grid) {
+        int nearest = -1;
+        float minDist = COLUMN_MATCH_BUCKETS * COLUMN_BUCKET_PT + 1f;
+        for (int i = 0; i < grid.size(); i++) {
+            float dist = Math.abs(rightEdge - grid.get(i));
+            if (dist < minDist) {
+                minDist = dist;
+                nearest = i;
+            }
+        }
+        return nearest;
+    }
+
+    private Bounds computeGroupBounds(List<TokenizedLine> group) {
+        return group.stream()
+                .map(tl -> tl.line().bounds())
+                .reduce(Bounds::merge)
+                .orElse(new Bounds(0, 0, 0, 0));
+    }
+
+    /** Modal gap between consecutive line edges, used to calibrate the group-split threshold. */
+    private float computeModalSpacing(List<RawLine> lines) {
+        if (lines.size() < 2) return 0f;
+        Map<Float, Long> freq = new HashMap<>();
+        for (int i = 1; i < lines.size(); i++) {
+            float gap = lines.get(i).bounds().y() - lines.get(i - 1).bounds().bottom();
+            if (gap > 0) freq.merge(Math.round(gap / 2f) * 2f, 1L, Long::sum);
+        }
+        return freq.entrySet().stream()
+                .max(Map.Entry.comparingByValue())
+                .map(Map.Entry::getKey)
+                .orElse(0f);
+    }
+
+    private static int bucket(float x) {
+        return Math.round(x / COLUMN_BUCKET_PT);
+    }
+
+    // ── private data types ───────────────────────────────────────────────────────────────────────
+
+    /** A word-level token with an approximate right-edge x-position. */
+    record LineToken(String text, float x, float right, boolean numeric) {}
+
+    /** A {@link RawLine} with tokens pre-computed; an "anchor" has ≥ 2 numeric tokens. */
+    record TokenizedLine(RawLine line, List<LineToken> all, List<LineToken> numeric) {
+        boolean isAnchor() {
+            return numeric.size() >= 2;
+        }
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/LineBuilder.java

@@ -0,0 +1,139 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Groups {@link TextFragment} objects into visual {@link RawLine}s using baseline proximity.
+ *
+ * <p>Fragments are on the same line when their baselines are within a font-size-derived tolerance.
+ * A new line starts whenever the horizontal gap exceeds an adaptive column-gap threshold ({@code
+ * max(effectiveWidth * COLUMN_GAP_RATIO, COLUMN_GAP_MIN_PT)}), splitting two-column text.
+ */
+@Service
+@Slf4j
+public class LineBuilder {
+
+    /** Baseline tolerance as a fraction of font size; 0.5 keeps mixed-size text on one line. */
+    private static final float BASELINE_TOLERANCE_FACTOR = 0.5f;
+
+    /** Absolute minimum tolerance so tiny font sizes don't collapse multi-line content. */
+    private static final float MIN_BASELINE_TOLERANCE = 2f;
+
+    /**
+     * Column-gap threshold as a fraction of page width; 0.10 clears tab stops but stays below
+     * two-column gutters.
+     */
+    static final float COLUMN_GAP_RATIO = 0.10f;
+
+    /** Floor for the column-gap threshold so narrow pages don't over-split lines. */
+    static final float COLUMN_GAP_MIN_PT = 40f;
+
+    public List<RawLine> build(List<TextFragment> fragments, int pageNumber) {
+        if (fragments.isEmpty()) return List.of();
+
+        float effectiveWidth = inferEffectiveWidth(fragments);
+        float columnGapThreshold = Math.max(effectiveWidth * COLUMN_GAP_RATIO, COLUMN_GAP_MIN_PT);
+        log.debug(
+                "LineBuilder page {}: effectiveWidth={:.1f}pt, columnGapThreshold={:.1f}pt",
+                pageNumber,
+                effectiveWidth,
+                columnGapThreshold);
+
+        // Sort top-to-bottom first, then left-to-right within the same baseline band.
+        List<TextFragment> sorted =
+                fragments.stream()
+                        .sorted(
+                                Comparator.comparingDouble(TextFragment::baseline)
+                                        .thenComparingDouble(f -> f.bounds().x()))
+                        .toList();
+
+        List<List<TextFragment>> groups = groupByBaseline(sorted, columnGapThreshold);
+
+        List<RawLine> lines = new ArrayList<>(groups.size());
+        for (int i = 0; i < groups.size(); i++) {
+            List<TextFragment> group =
+                    groups.get(i).stream()
+                            .sorted(Comparator.comparingDouble(f -> f.bounds().x()))
+                            .toList();
+
+            Bounds lineBounds =
+                    group.stream()
+                            .map(TextFragment::bounds)
+                            .reduce(Bounds::merge)
+                            .orElse(new Bounds(0, 0, 0, 0));
+
+            lines.add(new RawLine("ln-p" + pageNumber + "-" + i, group, lineBounds, pageNumber));
+        }
+        return lines;
+    }
+
+    private List<List<TextFragment>> groupByBaseline(
+            List<TextFragment> sorted, float columnGapThreshold) {
+        List<List<TextFragment>> groups = new ArrayList<>();
+        List<TextFragment> current = new ArrayList<>();
+        float currentBaseline = Float.NaN;
+
+        for (TextFragment fragment : sorted) {
+            if (current.isEmpty()) {
+                current.add(fragment);
+                currentBaseline = fragment.baseline();
+                continue;
+            }
+
+            float maxFontSize =
+                    Math.max(
+                            fragment.fontSize(),
+                            (float)
+                                    current.stream()
+                                            .mapToDouble(TextFragment::fontSize)
+                                            .max()
+                                            .orElse(0));
+            float tolerance =
+                    Math.max(maxFontSize * BASELINE_TOLERANCE_FACTOR, MIN_BASELINE_TOLERANCE);
+
+            boolean sameBaseline = Math.abs(fragment.baseline() - currentBaseline) <= tolerance;
+            boolean columnGap = sameBaseline && hasColumnGap(fragment, current, columnGapThreshold);
+
+            if (sameBaseline && !columnGap) {
+                current.add(fragment);
+                // Anchor to the weighted mean baseline so long lines stay stable.
+                currentBaseline =
+                        (currentBaseline * (current.size() - 1) + fragment.baseline())
+                                / current.size();
+            } else {
+                groups.add(current);
+                current = new ArrayList<>();
+                current.add(fragment);
+                currentBaseline = fragment.baseline();
+            }
+        }
+
+        if (!current.isEmpty()) groups.add(current);
+        return groups;
+    }
+
+    /**
+     * True when the gap from the rightmost fragment in {@code group} to {@code next} exceeds {@code
+     * threshold}.
+     */
+    private static boolean hasColumnGap(
+            TextFragment next, List<TextFragment> group, float threshold) {
+        float lastRight = group.get(group.size() - 1).bounds().right();
+        return next.bounds().x() - lastRight > threshold;
+    }
+
+    /** Infers effective page width from the rightmost fragment right-edge plus a 10 % margin. */
+    private static float inferEffectiveWidth(List<TextFragment> fragments) {
+        double maxRight =
+                fragments.stream().mapToDouble(f -> f.bounds().right()).max().orElse(500.0);
+        return (float) maxRight * 1.10f;
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/PdfIngester.java

@@ -0,0 +1,79 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Runs the per-page ingestion pipeline: {@link WordExtractingStripper} → {@link LineBuilder} →
+ * {@link TableParser}, producing a {@link PdfModels.ParsedPage} per page. The caller owns the
+ * {@link PDDocument} lifecycle.
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class PdfIngester {
+
+    private final LineBuilder lineBuilder;
+    private final TableParser tableParser;
+
+    public List<ParsedPage> parse(PDDocument document) throws IOException {
+        return parse(document, document.getNumberOfPages());
+    }
+
+    public List<ParsedPage> parse(PDDocument document, int maxPages) throws IOException {
+        int pageCount = Math.min(document.getNumberOfPages(), maxPages);
+        List<ParsedPage> pages = new ArrayList<>(pageCount);
+        long fragmentsMs = 0;
+        long tablesMs = 0;
+        long t0 = System.currentTimeMillis();
+
+        for (int p = 1; p <= pageCount; p++) {
+            long ft = System.currentTimeMillis();
+            List<TextFragment> fragments = extractFragments(document, p);
+            fragmentsMs += System.currentTimeMillis() - ft;
+
+            PDPage page = document.getPage(p - 1);
+            PDRectangle mediaBox = page.getMediaBox();
+            List<RawLine> lines = lineBuilder.build(fragments, p);
+            RawPage rawPage = new RawPage(p, mediaBox.getWidth(), mediaBox.getHeight(), lines);
+
+            long tt = System.currentTimeMillis();
+            List<TableFragment> tables = tableParser.parse(document, rawPage);
+            tablesMs += System.currentTimeMillis() - tt;
+
+            log.debug(
+                    "Page {}: {} fragments → {} lines, {} table(s)",
+                    p,
+                    fragments.size(),
+                    lines.size(),
+                    tables.size());
+            pages.add(new ParsedPage(p, mediaBox.getWidth(), mediaBox.getHeight(), tables, lines));
+        }
+
+        log.info(
+                "[timing] parse pages={} total={}ms fragments={}ms tables={}ms",
+                pageCount,
+                System.currentTimeMillis() - t0,
+                fragmentsMs,
+                tablesMs);
+        return pages;
+    }
+
+    private List<TextFragment> extractFragments(PDDocument document, int pageNumber)
+            throws IOException {
+        WordExtractingStripper stripper = new WordExtractingStripper(pageNumber);
+        stripper.getText(document);
+        return stripper.getFragments();
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/PdfModels.java

@@ -0,0 +1,148 @@
+package stirling.software.SPDF.pdf.parser;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+
+/**
+ * All PDF parser model types and the table-parser contract in one place.
+ *
+ * <p>Import as {@code import static stirling.software.SPDF.pdf.parser.PdfModels.*;} to use all
+ * nested types without qualification.
+ */
+public final class PdfModels {
+
+    private PdfModels() {}
+
+    // ── Geometry ──────────────────────────────────────────────────────────────
+
+    public record Bounds(float x, float y, float width, float height) {
+
+        public float right() {
+            return x + width;
+        }
+
+        public float bottom() {
+            return y + height;
+        }
+
+        public static Bounds merge(Bounds a, Bounds b) {
+            float x = Math.min(a.x, b.x);
+            float y = Math.min(a.y, b.y);
+            return new Bounds(
+                    x, y, Math.max(a.right(), b.right()) - x, Math.max(a.bottom(), b.bottom()) - y);
+        }
+    }
+
+    // ── Text fragments and lines ──────────────────────────────────────────────
+
+    /**
+     * A contiguous run of text from a single PDF content-stream string operation. {@code baseline}
+     * is preserved separately from bounds for line-grouping — characters of different sizes on the
+     * same visual line share a baseline but differ in top Y.
+     */
+    public record TextFragment(
+            String fragmentId,
+            String text,
+            Bounds bounds,
+            float baseline,
+            float fontSize,
+            String fontName,
+            boolean bold) {}
+
+    public record RawLine(
+            String lineId, List<TextFragment> fragments, Bounds bounds, int pageNumber) {
+
+        public String text() {
+            if (fragments.isEmpty()) return "";
+            StringBuilder sb = new StringBuilder();
+            TextFragment prev = null;
+            for (TextFragment f : fragments) {
+                if (prev != null) {
+                    float gap = f.bounds().x() - prev.bounds().right();
+                    float avgCharWidth = prev.bounds().width() / Math.max(prev.text().length(), 1);
+                    if (gap > avgCharWidth * 0.5f) sb.append(' ');
+                }
+                sb.append(f.text());
+                prev = f;
+            }
+            return sb.toString();
+        }
+
+        public float dominantFontSize() {
+            return fragments.stream()
+                    .collect(Collectors.groupingBy(TextFragment::fontSize, Collectors.counting()))
+                    .entrySet()
+                    .stream()
+                    .max(Map.Entry.comparingByValue())
+                    .map(Map.Entry::getKey)
+                    .orElse(0f);
+        }
+
+        public boolean hasBold() {
+            return fragments.stream().anyMatch(TextFragment::bold);
+        }
+    }
+
+    public record RawPage(int pageNumber, float widthPt, float heightPt, List<RawLine> lines) {}
+
+    // ── Table model ───────────────────────────────────────────────────────────
+
+    /**
+     * A single cell within a {@link TableRow}. {@code colSpan} and {@code rowSpan} are always 1 in
+     * v1 — span detection is deferred but the fields keep the schema stable.
+     */
+    public record TableCell(int colIndex, String text, Bounds bounds, int colSpan, int rowSpan) {
+
+        public static TableCell of(int colIndex, String text, Bounds bounds) {
+            return new TableCell(colIndex, text, bounds, 1, 1);
+        }
+    }
+
+    public record TableRow(int rowIndex, List<TableCell> cells) {}
+
+    /**
+     * A table as it appears on a single page. {@code headers} is empty in v1 — all rows are in
+     * {@code rows}. {@code rawRows} preserves exact Tabula text output for diagnostics. {@code
+     * confidence} is a heuristic score in [0.0, 1.0]. {@code continuedFromPage} is null in v1.
+     */
+    public record TableFragment(
+            String tableId,
+            int pageNumber,
+            Bounds bounds,
+            List<TableRow> headers,
+            List<TableRow> rows,
+            List<List<String>> rawRows,
+            int columnCount,
+            float confidence,
+            List<String> warnings,
+            Integer continuedFromPage) {}
+
+    // ── Page output ───────────────────────────────────────────────────────────
+
+    public record ParsedPage(
+            int pageNumber,
+            float widthPt,
+            float heightPt,
+            List<TableFragment> tables,
+            List<RawLine> layoutLines) {}
+
+    // ── Parser contract ───────────────────────────────────────────────────────
+
+    /**
+     * Extracts tables from a single page of a PDF. The caller owns the document lifecycle;
+     * implementations must not close it.
+     */
+    public interface TableParser {
+
+        /**
+         * @param document open PDF; must not be closed by the implementation
+         * @param rawPage page metadata and lines for the page to process
+         * @return zero or more table fragments found on the page, never null
+         */
+        List<TableFragment> parse(PDDocument document, RawPage rawPage) throws IOException;
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/TabulaTableParser.java

@@ -0,0 +1,256 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import technology.tabula.ObjectExtractor;
+import technology.tabula.Page;
+import technology.tabula.RectangularTextContainer;
+import technology.tabula.Table;
+import technology.tabula.extractors.BasicExtractionAlgorithm;
+import technology.tabula.extractors.ExtractionAlgorithm;
+import technology.tabula.extractors.SpreadsheetExtractionAlgorithm;
+
+/**
+ * Primary {@link TableParser} implementation using Tabula's lattice-mode extraction.
+ *
+ * <h3>Algorithm</h3>
+ *
+ * Uses {@link SpreadsheetExtractionAlgorithm} (lattice mode), which detects tables from ruled lines
+ * (horizontal and vertical PDF path operators). This is reliable for tables with visible borders.
+ * Borderless or whitespace-delimited tables will not be detected — that requires stream mode, which
+ * is deferred to a later iteration.
+ *
+ * <h3>Coordinate system</h3>
+ *
+ * Tabula normalises page coordinates so that (0,0) is the top-left corner and Y increases downward,
+ * matching the {@link Bounds} convention used throughout this parser. No coordinate transformation
+ * is needed when mapping Tabula cell bounds to {@link Bounds}.
+ *
+ * <h3>Known limitations</h3>
+ *
+ * <ul>
+ *   <li>Borderless tables are not detected (use stream mode, deferred).
+ *   <li>Colspan and rowspan are not detected; all cells report colSpan=1, rowSpan=1.
+ *   <li>Header rows are not identified; all rows appear in {@code rows}, headers is empty.
+ *   <li>Cross-page table linking is not performed; each page is independent.
+ *   <li>Rotated tables (90°/270° pages) may produce incorrect bounds.
+ * </ul>
+ */
+@Service
+@Slf4j
+public class TabulaTableParser implements TableParser {
+
+    /** Lattice mode — reliable for tables with visible ruled borders. */
+    @Override
+    public List<TableFragment> parse(PDDocument document, RawPage rawPage) throws IOException {
+        return parseWithAlgorithm(
+                document, rawPage, new SpreadsheetExtractionAlgorithm(), "lattice");
+    }
+
+    /**
+     * Convenience overload for callers that only have a page number, not a full {@link RawPage}.
+     */
+    public List<TableFragment> parse(PDDocument document, int pageNumber) throws IOException {
+        return parse(document, new RawPage(pageNumber, 0f, 0f, List.of()));
+    }
+
+    /** Stream mode — whitespace-based column detection for borderless tables. */
+    public List<TableFragment> parseStream(PDDocument document, RawPage rawPage)
+            throws IOException {
+        return parseWithAlgorithm(document, rawPage, new BasicExtractionAlgorithm(), "stream");
+    }
+
+    private List<TableFragment> parseWithAlgorithm(
+            PDDocument document, RawPage rawPage, ExtractionAlgorithm algorithm, String modeName)
+            throws IOException {
+        int pageNumber = rawPage.pageNumber();
+
+        List<Table> tabulaTables;
+        try {
+            // Do NOT use try-with-resources: ObjectExtractor.close() closes the underlying
+            // PDDocument, which we don't own. The extractor holds no resources of its own.
+            ObjectExtractor extractor = new ObjectExtractor(document);
+            Page page = extractor.extract(pageNumber);
+            tabulaTables = new ArrayList<>(algorithm.extract(page));
+        } catch (Exception e) {
+            log.warn(
+                    "Tabula {} extraction failed on page {}: {}",
+                    modeName,
+                    pageNumber,
+                    e.getMessage());
+            return List.of();
+        }
+
+        if (tabulaTables.isEmpty()) {
+            log.debug("Page {}: no tables detected by Tabula ({})", pageNumber, modeName);
+            return List.of();
+        }
+
+        log.debug(
+                "Page {}: Tabula ({}) detected {} table(s)",
+                pageNumber,
+                modeName,
+                tabulaTables.size());
+
+        List<TableFragment> fragments = new ArrayList<>(tabulaTables.size());
+        for (int i = 0; i < tabulaTables.size(); i++) {
+            fragments.add(toFragment(tabulaTables.get(i), pageNumber, i));
+        }
+        return fragments;
+    }
+
+    // ── private helpers ──────────────────────────────────────────────────────────────────────────
+
+    private TableFragment toFragment(Table table, int pageNumber, int tableIndex) {
+        List<List<RectangularTextContainer>> tabulaRows = table.getRows();
+        List<String> warnings = new ArrayList<>();
+
+        List<List<String>> rawRows = buildRawRows(tabulaRows);
+        int colCount = inferColumnCount(rawRows, warnings);
+        List<TableRow> rows = buildRows(tabulaRows, colCount, warnings);
+        float confidence = computeConfidence(rawRows, colCount, warnings);
+        Bounds bounds = tableBounds(table);
+
+        String tableId = "tbl-p" + pageNumber + "-" + tableIndex;
+
+        if (!warnings.isEmpty()) {
+            log.warn("Page {}, table {}: {}", pageNumber, tableIndex, warnings);
+        }
+
+        return new TableFragment(
+                tableId,
+                pageNumber,
+                bounds,
+                List.of(), // headers: deferred to v2
+                rows,
+                rawRows,
+                colCount,
+                confidence,
+                Collections.unmodifiableList(warnings),
+                null); // continuedFromPage: deferred to v2
+    }
+
+    private List<List<String>> buildRawRows(List<List<RectangularTextContainer>> tabulaRows) {
+        List<List<String>> rawRows = new ArrayList<>(tabulaRows.size());
+        for (List<RectangularTextContainer> tabulaRow : tabulaRows) {
+            List<String> cells = new ArrayList<>(tabulaRow.size());
+            for (RectangularTextContainer cell : tabulaRow) {
+                cells.add(normaliseText(cell.getText()));
+            }
+            rawRows.add(Collections.unmodifiableList(cells));
+        }
+        return rawRows;
+    }
+
+    private List<TableRow> buildRows(
+            List<List<RectangularTextContainer>> tabulaRows, int colCount, List<String> warnings) {
+        List<TableRow> rows = new ArrayList<>(tabulaRows.size());
+        for (int rowIdx = 0; rowIdx < tabulaRows.size(); rowIdx++) {
+            List<RectangularTextContainer> tabulaRow = tabulaRows.get(rowIdx);
+            List<TableCell> cells = new ArrayList<>(tabulaRow.size());
+
+            for (int colIdx = 0; colIdx < tabulaRow.size(); colIdx++) {
+                RectangularTextContainer c = tabulaRow.get(colIdx);
+                Bounds cellBounds =
+                        new Bounds(
+                                (float) c.getX(),
+                                (float) c.getY(),
+                                (float) c.getWidth(),
+                                (float) c.getHeight());
+                cells.add(TableCell.of(colIdx, normaliseText(c.getText()), cellBounds));
+            }
+
+            if (tabulaRow.size() != colCount) {
+                warnings.add(
+                        "Row "
+                                + rowIdx
+                                + " has "
+                                + tabulaRow.size()
+                                + " cells; expected "
+                                + colCount);
+            }
+
+            rows.add(new TableRow(rowIdx, Collections.unmodifiableList(cells)));
+        }
+        return rows;
+    }
+
+    /**
+     * The canonical column count for a table is the size of the widest row. Tabula can produce
+     * uneven rows when a cell's ruling lines are partially missing.
+     */
+    private int inferColumnCount(List<List<String>> rawRows, List<String> warnings) {
+        if (rawRows.isEmpty()) return 0;
+        int max = rawRows.stream().mapToInt(List::size).max().orElse(0);
+        int mode =
+                rawRows.stream()
+                        .collect(
+                                java.util.stream.Collectors.groupingBy(
+                                        List::size, java.util.stream.Collectors.counting()))
+                        .entrySet()
+                        .stream()
+                        .max(java.util.Map.Entry.comparingByValue())
+                        .map(java.util.Map.Entry::getKey)
+                        .orElse(0);
+        if (max != mode) {
+            warnings.add("Inconsistent column count: modal=" + mode + " max=" + max);
+        }
+        return mode > 0 ? mode : max;
+    }
+
+    /**
+     * Heuristic confidence score in [0.0, 1.0].
+     *
+     * <ul>
+     *   <li>Starts at 1.0.
+     *   <li>-0.3 if only one column (single-column tables are usually not real tables).
+     *   <li>-0.1 per row with an inconsistent column count, capped at -0.4.
+     *   <li>-0.3 if the empty-cell ratio across all cells exceeds 80%.
+     * </ul>
+     */
+    private float computeConfidence(
+            List<List<String>> rawRows, int colCount, List<String> warnings) {
+        if (rawRows.isEmpty() || colCount == 0) return 0f;
+
+        float score = 1.0f;
+
+        if (colCount == 1) score -= 0.3f;
+
+        long inconsistentRows = rawRows.stream().filter(r -> r.size() != colCount).count();
+        score -= Math.min(inconsistentRows * 0.1f, 0.4f);
+
+        long totalCells = rawRows.stream().mapToLong(List::size).sum();
+        long emptyCells =
+                rawRows.stream().flatMap(Collection::stream).filter(String::isBlank).count();
+        if (totalCells > 0 && (float) emptyCells / totalCells > 0.8f) {
+            score -= 0.3f;
+        }
+
+        return Math.max(0f, Math.min(1f, score));
+    }
+
+    private Bounds tableBounds(Table table) {
+        return new Bounds(
+                (float) table.getX(),
+                (float) table.getY(),
+                (float) table.getWidth(),
+                (float) table.getHeight());
+    }
+
+    private String normaliseText(String raw) {
+        if (raw == null) return "";
+        // Tabula wraps multi-line cell content with \r\n — collapse to a single space.
+        return raw.replace("\r\n", " ").replace("\n", " ").replace("\r", " ").trim();
+    }
+}

app/common/src/main/java/stirling/software/SPDF/pdf/parser/WordExtractingStripper.java

@@ -0,0 +1,113 @@
+package stirling.software.SPDF.pdf.parser;
+
+import static stirling.software.SPDF.pdf.parser.PdfModels.*;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.font.PDFont;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.apache.pdfbox.text.TextPosition;
+
+/**
+ * Extends {@link PDFTextStripper} to capture per-fragment geometry and font metadata.
+ *
+ * <p>Overrides {@link #writeString} to split each content-stream string into word-level {@link
+ * TextFragment}s with bounding boxes, baseline, font name, and bold flag. Coordinates are in
+ * PDFTextStripper space: (0,0) top-left, Y increases downward, {@code getY()} is the baseline.
+ */
+class WordExtractingStripper extends PDFTextStripper {
+
+    private final int targetPage;
+    private final List<TextFragment> fragments = new ArrayList<>();
+    private int fragmentIndex = 0;
+
+    WordExtractingStripper(int pageNumber) throws IOException {
+        this.targetPage = pageNumber;
+        setStartPage(pageNumber);
+        setEndPage(pageNumber);
+        setSortByPosition(true);
+    }
+
+    @Override
+    protected void startPage(PDPage page) throws IOException {
+        super.startPage(page);
+        fragments.clear();
+        fragmentIndex = 0;
+    }
+
+    @Override
+    protected void writeString(String text, List<TextPosition> textPositions) throws IOException {
+        if (text == null || text.isBlank()) return;
+
+        // Fast path: no whitespace → emit one fragment (most financial PDFs have each
+        // number as its own string operation, so this is the common case).
+        if (text.indexOf(' ') < 0) {
+            emitFragment(text, textPositions);
+            return;
+        }
+
+        // Per-word splitting requires 1:1 text-char to TextPosition correspondence.
+        // Fall back to one fragment when sizes differ (ligatures, encoding edge cases).
+        if (textPositions.size() != text.length()) {
+            emitFragment(text, textPositions);
+            return;
+        }
+
+        // Emit one TextFragment per whitespace-delimited word with accurate per-word bounds.
+        int start = 0;
+        for (int i = 0; i <= text.length(); i++) {
+            if (i == text.length() || text.charAt(i) == ' ') {
+                if (start < i) {
+                    emitFragment(text.substring(start, i), textPositions.subList(start, i));
+                }
+                start = i + 1;
+            }
+        }
+    }
+
+    private void emitFragment(String text, List<TextPosition> positions) {
+        if (positions.isEmpty()) return;
+
+        float minX = Float.MAX_VALUE;
+        float minY = Float.MAX_VALUE;
+        float maxRight = -Float.MAX_VALUE;
+        float maxBaseline = -Float.MAX_VALUE;
+        TextPosition first = null;
+
+        for (TextPosition tp : positions) {
+            if (tp == null) continue;
+            if (first == null) first = tp;
+
+            float x = tp.getX();
+            // getY() is the baseline; top of character = getY() - getHeight().
+            float top = tp.getY() - tp.getHeight();
+            float right = x + tp.getWidth();
+            float baseline = tp.getY();
+
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, top);
+            maxRight = Math.max(maxRight, right);
+            maxBaseline = Math.max(maxBaseline, baseline);
+        }
+
+        if (first == null) return;
+
+        PDFont font = first.getFont();
+        String fontName = font != null ? font.getName() : "";
+        boolean bold = fontName != null && fontName.toLowerCase().contains("bold");
+        // getHeight() gives the rendered glyph height, which is the most reliable visual size.
+        float fontSize = first.getHeight();
+
+        Bounds bounds = new Bounds(minX, minY, maxRight - minX, maxBaseline - minY);
+        String id = "tf-p" + targetPage + "-" + fragmentIndex++;
+        fragments.add(new TextFragment(id, text, bounds, maxBaseline, fontSize, fontName, bold));
+    }
+
+    List<TextFragment> getFragments() {
+        return Collections.unmodifiableList(fragments);
+    }
+}

app/common/src/main/java/stirling/software/common/annotations/AutoJobPostMapping.java

@@ -75,8 +75,8 @@ public @interface AutoJobPostMapping {
     boolean queueable() default false;
 
     /**
-     * Relative resource weight (1–100) used by the scheduler to prioritise / throttle jobs. Values
-     * below 1 are clamped to 1, values above 100 to 100.
+     * Relative resource weight (1-100). See {@link
+     * stirling.software.common.enumeration.ResourceWeight} for the standard tiers.
      */
-    int resourceWeight() default 50;
+    int resourceWeight() default 1;
 }

app/common/src/main/java/stirling/software/common/aop/AutoJobAspect.java

@@ -2,12 +2,14 @@ package stirling.software.common.aop;
 
 import java.io.IOException;
 import java.time.Duration;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.TimeUnit;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;
 
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.*;
+import org.slf4j.MDC;
 import org.springframework.core.annotation.Order;
 import org.springframework.stereotype.Component;
 import org.springframework.web.multipart.MultipartFile;
@@ -26,7 +28,7 @@ import stirling.software.common.service.JobExecutorService;
 @Component
 @RequiredArgsConstructor
 @Slf4j
-@Order(0) // Highest precedence - executes before audit aspects
+@Order(20) // Lower precedence - executes AFTER audit aspects populate MDC
 public class AutoJobAspect {
 
     private static final Duration RETRY_BASE_DELAY = Duration.ofMillis(100);
@@ -70,26 +72,29 @@ public class AutoJobAspect {
             // No retries needed, simple execution
             return jobExecutorService.runJobGeneric(
                     async,
-                    () -> {
-                        try {
-                            // Note: Progress tracking is handled in TaskManager/JobExecutorService
-                            // The trackProgress flag controls whether detailed progress is stored
-                            // for REST API queries, not WebSocket notifications
-                            return joinPoint.proceed(args);
-                        } catch (Throwable ex) {
-                            log.error(
-                                    "AutoJobAspect caught exception during job execution: {}",
-                                    ex.getMessage(),
-                                    ex);
-                            // Rethrow RuntimeException as-is to preserve exception type
-                            if (ex instanceof RuntimeException) {
-                                throw (RuntimeException) ex;
-                            }
-                            // Wrap checked exceptions - GlobalExceptionHandler will unwrap
-                            // BaseAppException
-                            throw new RuntimeException(ex);
-                        }
-                    },
+                    wrapWithMDC(
+                            () -> {
+                                try {
+                                    // Note: Progress tracking is handled in
+                                    // TaskManager/JobExecutorService
+                                    // The trackProgress flag controls whether detailed progress is
+                                    // stored
+                                    // for REST API queries, not WebSocket notifications
+                                    return joinPoint.proceed(args);
+                                } catch (Throwable ex) {
+                                    log.error(
+                                            "AutoJobAspect caught exception during job execution: {}",
+                                            ex.getMessage(),
+                                            ex);
+                                    // Rethrow RuntimeException as-is to preserve exception type
+                                    if (ex instanceof RuntimeException) {
+                                        throw (RuntimeException) ex;
+                                    }
+                                    // Wrap checked exceptions - GlobalExceptionHandler will unwrap
+                                    // BaseAppException
+                                    throw new RuntimeException(ex);
+                                }
+                            }),
                     timeout,
                     queueable,
                     resourceWeight);
@@ -123,114 +128,108 @@ public class AutoJobAspect {
 
         return jobExecutorService.runJobGeneric(
                 async,
-                () -> {
-                    // Use iterative approach instead of recursion to avoid stack overflow
-                    Throwable lastException = null;
+                wrapWithMDC(
+                        () -> {
+                            // Use iterative approach instead of recursion to avoid stack overflow
+                            Throwable lastException = null;
 
-                    // Attempt counter starts at 1 for first try
-                    for (int currentAttempt = 1; currentAttempt <= maxRetries; currentAttempt++) {
-                        try {
-                            if (trackProgress && async) {
-                                // Get jobId for progress tracking in TaskManager
-                                // This enables REST API progress queries, not WebSocket
-                                if (jobIdRef.get() == null) {
-                                    jobIdRef.set(getJobIdFromContext());
-                                }
-                                String jobId = jobIdRef.get();
-                                if (jobId != null) {
-                                    log.debug(
-                                            "Tracking progress for job {} (attempt {}/{})",
-                                            jobId,
+                            // Attempt counter starts at 1 for first try
+                            for (int currentAttempt = 1;
+                                    currentAttempt <= maxRetries;
+                                    currentAttempt++) {
+                                try {
+                                    if (trackProgress && async) {
+                                        // Get jobId for progress tracking in TaskManager
+                                        // This enables REST API progress queries, not WebSocket
+                                        if (jobIdRef.get() == null) {
+                                            jobIdRef.set(getJobIdFromContext());
+                                        }
+                                        String jobId = jobIdRef.get();
+                                        if (jobId != null) {
+                                            log.debug(
+                                                    "Tracking progress for job {} (attempt {}/{})",
+                                                    jobId,
+                                                    currentAttempt,
+                                                    maxRetries);
+                                            // Progress is tracked in TaskManager for REST API
+                                            // access
+                                            // No WebSocket notifications sent here
+                                        }
+                                    }
+
+                                    // Attempt to execute the operation
+                                    return joinPoint.proceed(args);
+
+                                } catch (Throwable ex) {
+                                    lastException = ex;
+                                    log.error(
+                                            "AutoJobAspect caught exception during job execution (attempt"
+                                                    + " {}/{}): {}",
                                             currentAttempt,
-                                            maxRetries);
-                                    // Progress is tracked in TaskManager for REST API access
-                                    // No WebSocket notifications sent here
-                                }
-                            }
+                                            maxRetries,
+                                            ex.getMessage(),
+                                            ex);
 
-                            // Attempt to execute the operation
-                            return joinPoint.proceed(args);
+                                    // Check if we should retry
+                                    if (currentAttempt < maxRetries) {
+                                        log.info(
+                                                "Retrying operation, attempt {}/{}",
+                                                currentAttempt + 1,
+                                                maxRetries);
 
-                        } catch (Throwable ex) {
-                            lastException = ex;
-                            log.error(
-                                    "AutoJobAspect caught exception during job execution (attempt"
-                                            + " {}/{}): {}",
-                                    currentAttempt,
-                                    maxRetries,
-                                    ex.getMessage(),
-                                    ex);
+                                        if (trackProgress && async) {
+                                            String jobId = jobIdRef.get();
+                                            if (jobId != null) {
+                                                log.debug(
+                                                        "Recording retry attempt for job {} in TaskManager",
+                                                        jobId);
+                                                // Retry info is tracked in TaskManager for REST API
+                                                // access
+                                            }
+                                        }
 
-                            // Check if we should retry
-                            if (currentAttempt < maxRetries) {
-                                log.info(
-                                        "Retrying operation, attempt {}/{}",
-                                        currentAttempt + 1,
-                                        maxRetries);
+                                        // Use sleep for retry delay
+                                        // For sync jobs, both sleep and async are blocking at this
+                                        // point
+                                        // For async jobs, the delay occurs in the executor thread
+                                        long delayMs = RETRY_BASE_DELAY.toMillis() * currentAttempt;
 
-                                if (trackProgress && async) {
-                                    String jobId = jobIdRef.get();
-                                    if (jobId != null) {
-                                        log.debug(
-                                                "Recording retry attempt for job {} in TaskManager",
-                                                jobId);
-                                        // Retry info is tracked in TaskManager for REST API access
+                                        try {
+                                            Thread.sleep(delayMs);
+                                        } catch (InterruptedException e) {
+                                            Thread.currentThread().interrupt();
+                                            log.debug(
+                                                    "Retry delay interrupted for attempt {}/{}",
+                                                    currentAttempt,
+                                                    maxRetries);
+                                            break;
+                                        }
+                                    } else {
+                                        // No more retries, we'll throw the exception after the loop
+                                        break;
                                     }
                                 }
-
-                                // Use non-blocking delay for all retry attempts to avoid blocking
-                                // threads
-                                // For sync jobs this avoids starving the tomcat thread pool under
-                                // load
-                                long delayMs = RETRY_BASE_DELAY.toMillis() * currentAttempt;
-
-                                // Execute the retry after a delay through the JobExecutorService
-                                // rather than blocking the current thread with sleep
-                                CompletableFuture<Object> delayedRetry = new CompletableFuture<>();
-
-                                // Use a delayed executor for non-blocking delay
-                                CompletableFuture.delayedExecutor(delayMs, TimeUnit.MILLISECONDS)
-                                        .execute(
-                                                () -> {
-                                                    // Continue the retry loop in the next iteration
-                                                    // We can't return from here directly since
-                                                    // we're in a Runnable
-                                                    delayedRetry.complete(null);
-                                                });
-
-                                // Wait for the delay to complete before continuing
-                                try {
-                                    delayedRetry.join();
-                                } catch (Exception e) {
-                                    Thread.currentThread().interrupt();
-                                    break;
-                                }
-                            } else {
-                                // No more retries, we'll throw the exception after the loop
-                                break;
                             }
-                        }
-                    }
 
-                    // If we get here, all retries failed
-                    if (lastException != null) {
-                        // Rethrow RuntimeException as-is to preserve exception type
-                        if (lastException instanceof RuntimeException) {
-                            throw (RuntimeException) lastException;
-                        }
-                        // Wrap checked exceptions - GlobalExceptionHandler will unwrap
-                        // BaseAppException
-                        throw new RuntimeException(
-                                "Job failed after "
-                                        + maxRetries
-                                        + " attempts: "
-                                        + lastException.getMessage(),
-                                lastException);
-                    }
+                            // If we get here, all retries failed
+                            if (lastException != null) {
+                                // Rethrow RuntimeException as-is to preserve exception type
+                                if (lastException instanceof RuntimeException) {
+                                    throw (RuntimeException) lastException;
+                                }
+                                // Wrap checked exceptions - GlobalExceptionHandler will unwrap
+                                // BaseAppException
+                                throw new RuntimeException(
+                                        "Job failed after "
+                                                + maxRetries
+                                                + " attempts: "
+                                                + lastException.getMessage(),
+                                        lastException);
+                            }
 
-                    // This should never happen if lastException is properly tracked
-                    throw new RuntimeException("Job failed but no exception was recorded");
-                },
+                            // This should never happen if lastException is properly tracked
+                            throw new RuntimeException("Job failed but no exception was recorded");
+                        }),
                 timeout,
                 queueable,
                 resourceWeight);
@@ -299,4 +298,32 @@ public class AutoJobAspect {
             return null;
         }
     }
+
+    /**
+     * Wraps a supplier to propagate MDC context to background threads. Captures MDC on request
+     * thread and restores it in the background thread. Ensures proper cleanup to prevent context
+     * leakage across jobs in thread pools.
+     */
+    private <T> Supplier<T> wrapWithMDC(Supplier<T> supplier) {
+        final Map<String, String> captured = MDC.getCopyOfContextMap();
+        return () -> {
+            final Map<String, String> previous = MDC.getCopyOfContextMap();
+            try {
+                // Set the captured context (or clear if none was captured)
+                if (captured != null) {
+                    MDC.setContextMap(new HashMap<>(captured));
+                } else {
+                    MDC.clear();
+                }
+                return supplier.get();
+            } finally {
+                // Restore previous state (or clear if there was none)
+                if (previous != null) {
+                    MDC.setContextMap(previous);
+                } else {
+                    MDC.clear();
+                }
+            }
+        };
+    }
 }

app/common/src/main/java/stirling/software/common/configuration/InstallationPathConfig.java

@@ -59,6 +59,18 @@ public class InstallationPathConfig {
     }
 
     private static String initializeBasePath() {
+        // Allow tests / harnesses to redirect the entire state tree (configs,
+        // backups, customFiles, pipeline, logs) to an isolated location via
+        // -Dstirling.base-path=... or STIRLING_BASE_PATH=... so a Playwright
+        // run never touches a developer's working state.
+        String override = System.getProperty("stirling.base-path");
+        if (override == null || override.isBlank()) {
+            override = System.getenv("STIRLING_BASE_PATH");
+        }
+        if (override != null && !override.isBlank()) {
+            boolean hasTrailingSeparator = override.endsWith("/") || override.endsWith("\\");
+            return hasTrailingSeparator ? override : override + File.separator;
+        }
         return "." + File.separator;
     }
 

app/common/src/main/java/stirling/software/common/configuration/RuntimePathConfig.java

@@ -91,9 +91,9 @@ public class RuntimePathConfig {
 
         // Initialize Operation paths
         String defaultWeasyPrintPath = isDocker ? "/opt/venv/bin/weasyprint" : "weasyprint";
-        String defaultUnoConvertPath = isDocker ? "/opt/venv/bin/unoconvert" : "unoconvert";
+        String defaultUnoConvertPath = isDocker ? "/usr/local/bin/unoconvert" : "unoconvert";
         String defaultCalibrePath = isDocker ? "/opt/calibre/ebook-convert" : "ebook-convert";
-        String defaultOcrMyPdfPath = isDocker ? "/usr/bin/ocrmypdf" : "ocrmypdf";
+        String defaultOcrMyPdfPath = isDocker ? "/opt/venv/bin/ocrmypdf" : "ocrmypdf";
         String defaultSOfficePath = isDocker ? "/usr/bin/soffice" : "soffice";
 
         Operations operations = customPaths.getOperations();

app/common/src/main/java/stirling/software/common/configuration/SchedulingConfig.java

@@ -0,0 +1,23 @@
+package stirling.software.common.configuration;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.TaskScheduler;
+import org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler;
+
+/**
+ * Configures the scheduler used by all {@code @Scheduled} methods. Uses virtual threads so that
+ * long-running scheduled tasks (e.g. cleanup, license checks, file monitoring) never block each
+ * other — each runs on its own lightweight virtual thread.
+ */
+@Configuration
+public class SchedulingConfig {
+
+    @Bean
+    public TaskScheduler taskScheduler() {
+        SimpleAsyncTaskScheduler scheduler = new SimpleAsyncTaskScheduler();
+        scheduler.setVirtualThreads(true);
+        scheduler.setThreadNamePrefix("scheduled-vt-");
+        return scheduler;
+    }
+}

app/common/src/main/java/stirling/software/common/enumeration/ResourceWeight.java

@@ -0,0 +1,22 @@
+package stirling.software.common.enumeration;
+
+/**
+ * Standard resource-weight tiers for {@link
+ * stirling.software.common.annotations.AutoJobPostMapping#resourceWeight()}.
+ */
+public final class ResourceWeight {
+
+    /** Lightweight: rotate, page numbers, extract pages, permissions, etc. */
+    public static final int SMALL_WEIGHT = 1;
+
+    /** Medium: merge, split, multi-tool batch. */
+    public static final int MEDIUM_WEIGHT = 3;
+
+    /** Heavy: compress, OCR (small), conversions, raster. */
+    public static final int LARGE_WEIGHT = 5;
+
+    /** Extra heavy: OCR on large files, full-document re-render, AI-assisted edits. */
+    public static final int XLARGE_WEIGHT = 10;
+
+    private ResourceWeight() {}
+}

app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java

@@ -58,6 +58,7 @@ public class ApplicationProperties {
     private Legal legal = new Legal();
     private Security security = new Security();
     private System system = new System();
+    private Storage storage = new Storage();
     private Ui ui = new Ui();
     private Endpoints endpoints = new Endpoints();
     private Metrics metrics = new Metrics();
@@ -74,6 +75,8 @@ public class ApplicationProperties {
     private AutoPipeline autoPipeline = new AutoPipeline();
     private ProcessExecutor processExecutor = new ProcessExecutor();
     private PdfEditor pdfEditor = new PdfEditor();
+    private AiEngine aiEngine = new AiEngine();
+    private InternalApi internalApi = new InternalApi();
 
     @Bean
     public PropertySource<?> dynamicYamlPropertySource(ConfigurableEnvironment environment)
@@ -94,7 +97,14 @@ public class ApplicationProperties {
         EncodedResource encodedResource = new EncodedResource(resource);
         PropertySource<?> propertySource =
                 new YamlPropertySourceFactory().createPropertySource(null, encodedResource);
-        environment.getPropertySources().addFirst(propertySource);
+
+        boolean saasActive = Arrays.asList(environment.getActiveProfiles()).contains("saas");
+        if (saasActive) {
+            // Saas-pinned values in application-saas.properties must beat settings.yml.
+            environment.getPropertySources().addLast(propertySource);
+        } else {
+            environment.getPropertySources().addFirst(propertySource);
+        }
 
         log.debug("Loaded properties: {}", propertySource.getSource());
 
@@ -150,6 +160,44 @@ public class ApplicationProperties {
     @Data
     public static class AutoPipeline {
         private String outputFolder;
+        private FileReadiness fileReadiness = new FileReadiness();
+
+        /**
+         * Configuration for the {@link stirling.software.common.util.FileReadinessChecker}.
+         * Controls how the pipeline determines whether a file is fully written and stable before
+         * processing begins.
+         */
+        @Data
+        public static class FileReadiness {
+            /**
+             * Master toggle. When {@code false} every readiness check is skipped and all files are
+             * considered immediately ready (preserves legacy behaviour).
+             */
+            private boolean enabled = true;
+
+            /**
+             * How long (in milliseconds) a file must remain unmodified before it is considered
+             * stable. Files modified more recently than this threshold are skipped and retried on
+             * the next scan cycle. Default: 5 000 ms (5 seconds).
+             */
+            private long settleTimeMillis = 5000;
+
+            /**
+             * How long (in milliseconds) to pause between two consecutive file-size reads when
+             * checking whether a file is still being written. If the size differs between the two
+             * reads the file is considered unstable. This catches active copies on Linux/macOS
+             * where advisory locking alone cannot detect a mid-copy file. Default: 500 ms.
+             */
+            private long sizeCheckDelayMillis = 500;
+
+            /**
+             * Optional list of file extensions (without the leading dot, case-insensitive) that are
+             * allowed through the readiness check. An empty list means all extensions are accepted.
+             * Example: {@code ["pdf", "tiff"]} will skip any file whose extension is not {@code
+             * pdf} or {@code tiff}.
+             */
+            private List<String> allowedExtensions = new java.util.ArrayList<>();
+        }
     }
 
     @Data
@@ -192,6 +240,33 @@ public class ApplicationProperties {
         }
     }
 
+    @Data
+    public static class AiEngine {
+        private boolean enabled = false;
+        private String url = "http://localhost:5001";
+        private int timeoutSeconds = 120;
+
+        /**
+         * Longer timeout for heavy operations like RAG ingestion, which embeds the whole document
+         * and can take multiple minutes for large books. Applied per-call when the caller
+         * explicitly requests it via {@code AiEngineClient.postWithTimeout}.
+         */
+        private int longRunningTimeoutSeconds = 600;
+    }
+
+    /**
+     * HTTP timeouts for loopback calls to internal Stirling API endpoints, used by the AI workflow
+     * executor and the pipeline processor. A bounded read timeout prevents a hung tool (e.g. an
+     * infinite loop in a PDF processing service) from stalling the entire chat workflow forever.
+     * Tools that legitimately need longer than the read timeout should be invoked through the async
+     * job executor instead of synchronously.
+     */
+    @Data
+    public static class InternalApi {
+        private int connectTimeoutSeconds = 10;
+        private int readTimeoutSeconds = 300;
+    }
+
     @Data
     public static class Legal {
         private String termsAndConditions;
@@ -213,6 +288,7 @@ public class ApplicationProperties {
         private String customGlobalAPIKey;
         private Jwt jwt = new Jwt();
         private Validation validation = new Validation();
+        private Timestamp timestamp = new Timestamp();
         private String xFrameOptions = "DENY";
 
         public Boolean isAltLogin() {
@@ -365,11 +441,11 @@ public class ApplicationProperties {
             }
 
             public boolean isSettingsValid() {
-                return !ValidationUtils.isStringEmpty(this.getIssuer())
-                        && !ValidationUtils.isStringEmpty(this.getClientId())
-                        && !ValidationUtils.isStringEmpty(this.getClientSecret())
-                        && !ValidationUtils.isCollectionEmpty(this.getScopes())
-                        && !ValidationUtils.isStringEmpty(this.getUseAsUsername());
+                return !ValidationUtils.isStringEmpty(this.issuer)
+                        && !ValidationUtils.isStringEmpty(this.clientId)
+                        && !ValidationUtils.isStringEmpty(this.clientSecret)
+                        && !ValidationUtils.isCollectionEmpty(this.scopes)
+                        && !ValidationUtils.isStringEmpty(this.useAsUsername);
             }
 
             @Data
@@ -531,6 +607,12 @@ public class ApplicationProperties {
                 private boolean hardFail = false;
             }
         }
+
+        @Data
+        public static class Timestamp {
+            private String defaultTsaUrl = "http://timestamp.digicert.com";
+            private List<String> customTsaUrls = new ArrayList<>();
+        }
     }
 
     @Data
@@ -575,19 +657,52 @@ public class ApplicationProperties {
         }
 
         public boolean isAnalyticsEnabled() {
-            return this.getEnableAnalytics() != null && this.getEnableAnalytics();
+            return this.enableAnalytics != null && this.enableAnalytics;
         }
 
         public boolean isPosthogEnabled() {
             // Treat null as enabled when analytics is enabled
-            return this.isAnalyticsEnabled()
-                    && (this.getEnablePosthog() == null || this.getEnablePosthog());
+            return this.isAnalyticsEnabled() && (this.enablePosthog == null || this.enablePosthog);
         }
 
         public boolean isScarfEnabled() {
             // Treat null as enabled when analytics is enabled
-            return this.isAnalyticsEnabled()
-                    && (this.getEnableScarf() == null || this.getEnableScarf());
+            return this.isAnalyticsEnabled() && (this.enableScarf == null || this.enableScarf);
+        }
+    }
+
+    @Data
+    public static class Storage {
+        private boolean enabled = false;
+        private String provider = "local";
+        private Local local = new Local();
+        private Quotas quotas = new Quotas();
+        private Sharing sharing = new Sharing();
+        private Signing signing = new Signing();
+
+        @Data
+        public static class Local {
+            private String basePath = InstallationPathConfig.getPath() + "storage";
+        }
+
+        @Data
+        public static class Sharing {
+            private boolean enabled = false;
+            private boolean linkEnabled = false;
+            private boolean emailEnabled = false;
+            private int linkExpirationDays = 3;
+        }
+
+        @Data
+        public static class Quotas {
+            private long maxStorageMbPerUser = -1;
+            private long maxStorageMbTotal = -1;
+            private long maxFileMb = -1;
+        }
+
+        @Data
+        public static class Signing {
+            private boolean enabled = false;
         }
     }
 
@@ -714,6 +829,7 @@ public class ApplicationProperties {
         private String logoStyle = "classic"; // Options: "classic" (default) or "modern"
         private boolean defaultHideUnavailableTools = false;
         private boolean defaultHideUnavailableConversions = false;
+        private HideDisabledTools hideDisabledTools = new HideDisabledTools();
 
         public String getAppNameNavbar() {
             return appNameNavbar != null && !appNameNavbar.trim().isEmpty() ? appNameNavbar : null;
@@ -726,6 +842,12 @@ public class ApplicationProperties {
             }
             return "classic"; // default
         }
+
+        @Data
+        public static class HideDisabledTools {
+            private boolean googleDrive = false;
+            private boolean mobileQRScanner = false;
+        }
     }
 
     @Data
@@ -913,6 +1035,15 @@ public class ApplicationProperties {
             private boolean ssoAutoLogin;
             private boolean database;
             private CustomMetadata customMetadata = new CustomMetadata();
+            private GoogleDrive googleDrive = new GoogleDrive();
+
+            @Data
+            public static class GoogleDrive {
+                private boolean enabled = false;
+                private String clientId = "";
+                private String apiKey = "";
+                private String appId = "";
+            }
 
             @Data
             public static class CustomMetadata {
@@ -962,6 +1093,12 @@ public class ApplicationProperties {
                 private boolean enabled = true;
                 private int level = 2; // 0=OFF, 1=BASIC, 2=STANDARD, 3=VERBOSE
                 private int retentionDays = 90;
+                private boolean captureFileHash =
+                        false; // Capture SHA-256 hash of files (increases processing time)
+                private boolean capturePdfAuthor =
+                        false; // Capture PDF author metadata (increases processing time)
+                private boolean captureOperationResults =
+                        false; // Capture operation return values (not recommended, high volume)
             }
 
             @Data

app/common/src/main/java/stirling/software/common/model/api/PDFFile.java

@@ -14,7 +14,6 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @EqualsAndHashCode
-@Schema(description = "PDF file input - either upload a file or provide a server-side file ID")
 public class PDFFile {
 
     @Schema(

app/common/src/main/java/stirling/software/common/model/api/comments/AnnotationLocation.java

@@ -0,0 +1,15 @@
+package stirling.software.common.model.api.comments;
+
+/**
+ * Absolute position of a PDF annotation in the document.
+ *
+ * <p>Coordinates are in PDF user-space with the origin at the page's bottom-left, consistent with
+ * PDFBox's {@code PDRectangle} convention.
+ *
+ * @param pageIndex 0-indexed page number the annotation lives on.
+ * @param x bottom-left x coordinate of the annotation rectangle.
+ * @param y bottom-left y coordinate of the annotation rectangle.
+ * @param width width of the annotation rectangle, in user-space units.
+ * @param height height of the annotation rectangle, in user-space units.
+ */
+public record AnnotationLocation(int pageIndex, float x, float y, float width, float height) {}

app/common/src/main/java/stirling/software/common/model/api/comments/StickyNoteSpec.java

@@ -0,0 +1,15 @@
+package stirling.software.common.model.api.comments;
+
+/**
+ * Description of a single sticky-note (PDF Text) annotation to place on a document.
+ *
+ * <p>{@code author} and {@code subject} are optional — callers that pass {@code null} get a default
+ * author/subject from {@code PdfAnnotationService}.
+ *
+ * @param location where to anchor the annotation icon, in PDF user-space.
+ * @param text the comment body shown in the popup (required, non-blank).
+ * @param author optional author label shown in the popup; {@code null} → service default.
+ * @param subject optional subject line shown in the popup; {@code null} → service default.
+ */
+public record StickyNoteSpec(
+        AnnotationLocation location, String text, String author, String subject) {}

app/common/src/main/java/stirling/software/common/model/api/general/EditTextOperation.java

@@ -0,0 +1,19 @@
+package stirling.software.common.model.api.general;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@Data
+@EqualsAndHashCode
+public class EditTextOperation {
+
+    @Schema(description = "The literal text to find.", requiredMode = Schema.RequiredMode.REQUIRED)
+    private String find;
+
+    @Schema(
+            description = "The replacement text. May be empty to delete the matched text.",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private String replace;
+}

app/common/src/main/java/stirling/software/common/model/api/security/UserSummaryDTO.java

@@ -0,0 +1,16 @@
+package stirling.software.common.model.api.security;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class UserSummaryDTO {
+    private Long userId;
+    private String username;
+    private String displayName;
+    private String teamName;
+    private boolean enabled;
+}

app/common/src/main/java/stirling/software/common/model/enumeration/InvitationStatus.java

@@ -0,0 +1,26 @@
+package stirling.software.common.model.enumeration;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+/** Team invitation status */
+@Getter
+@RequiredArgsConstructor
+public enum InvitationStatus {
+    PENDING("PENDING"),
+    ACCEPTED("ACCEPTED"),
+    REJECTED("REJECTED"),
+    CANCELLED("CANCELLED"),
+    EXPIRED("EXPIRED");
+
+    private final String statusName;
+
+    public static InvitationStatus fromString(String statusName) {
+        for (InvitationStatus status : InvitationStatus.values()) {
+            if (status.getStatusName().equalsIgnoreCase(statusName)) {
+                return status;
+            }
+        }
+        throw new IllegalArgumentException("No InvitationStatus defined for name: " + statusName);
+    }
+}

app/common/src/main/java/stirling/software/common/model/enumeration/Role.java

@@ -16,6 +16,9 @@ public enum Role {
     // Unlimited access
     USER("ROLE_USER", Integer.MAX_VALUE, Integer.MAX_VALUE, "adminUserSettings.user"),
 
+    // Paid tier; set by Stripe webhooks under saas mode.
+    PRO_USER("ROLE_PRO_USER", Integer.MAX_VALUE, Integer.MAX_VALUE, "adminUserSettings.proUser"),
+
     // 40 API calls Per Day, 40 web calls
     LIMITED_API_USER("ROLE_LIMITED_API_USER", 40, 40, "adminUserSettings.apiUser"),
 
@@ -42,7 +45,7 @@ public enum Role {
         // Using the fromString method to get the Role enum based on the roleId
         Role role = fromString(roleId);
         // Return the roleName of the found Role enum
-        return role.getRoleName();
+        return role.roleName;
     }
 
     // Method to retrieve all role IDs and role names
@@ -50,14 +53,14 @@ public enum Role {
         // Using LinkedHashMap to preserve order
         Map<String, String> roleDetails = new LinkedHashMap<>();
         for (Role role : Role.values()) {
-            roleDetails.put(role.getRoleId(), role.getRoleName());
+            roleDetails.put(role.roleId, role.roleName);
         }
         return roleDetails;
     }
 
     public static Role fromString(String roleId) {
         for (Role role : Role.values()) {
-            if (role.getRoleId().equalsIgnoreCase(roleId)) {
+            if (role.roleId.equalsIgnoreCase(roleId)) {
                 return role;
             }
         }

app/common/src/main/java/stirling/software/common/model/enumeration/TeamRole.java

@@ -0,0 +1,26 @@
+package stirling.software.common.model.enumeration;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+/**
+ * Team membership roles LEADER: Can invite/remove members, manage settings, view usage, manage
+ * billing MEMBER: Regular team member with standard access
+ */
+@Getter
+@RequiredArgsConstructor
+public enum TeamRole {
+    LEADER("LEADER"),
+    MEMBER("MEMBER");
+
+    private final String roleName;
+
+    public static TeamRole fromString(String roleName) {
+        for (TeamRole role : TeamRole.values()) {
+            if (role.getRoleName().equalsIgnoreCase(roleName)) {
+                return role;
+            }
+        }
+        throw new IllegalArgumentException("No TeamRole defined for name: " + roleName);
+    }
+}

app/common/src/main/java/stirling/software/common/model/oauth2/Provider.java

@@ -117,13 +117,13 @@ public class Provider {
                 + ", clientName="
                 + getClientName()
                 + ", clientId="
-                + getClientId()
+                + clientId
                 + ", clientSecret="
-                + (getClientSecret() != null && !getClientSecret().isEmpty() ? "*****" : "NULL")
+                + (clientSecret != null && !clientSecret.isEmpty() ? "*****" : "NULL")
                 + ", scopes="
                 + getScopes()
                 + ", useAsUsername="
-                + getUseAsUsername()
+                + useAsUsername
                 + "]";
     }
 }

app/common/src/main/java/stirling/software/common/service/FileStorage.java

@@ -1,13 +1,19 @@
 package stirling.software.common.service;
 
+import java.io.BufferedInputStream;
+import java.io.BufferedOutputStream;
 import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.UUID;
 
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.Resource;
 import org.springframework.stereotype.Service;
 import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -21,6 +27,9 @@ import lombok.extern.slf4j.Slf4j;
 @Slf4j
 public class FileStorage {
 
+    /** Holds the result of a stream-to-disk store operation: the file ID and the bytes written. */
+    public record StoredFile(String fileId, long size) {}
+
     @Value("${stirling.tempDir:/tmp/stirling-files}")
     private String tempDirPath;
 
@@ -104,6 +113,93 @@ public class FileStorage {
         return Files.readAllBytes(filePath);
     }
 
+    /**
+     * Retrieve a file by its ID as a streaming InputStream. The caller is responsible for closing
+     * the returned stream.
+     *
+     * @param fileId The ID of the file to retrieve
+     * @return A buffered InputStream for the file
+     * @throws IOException If the file doesn't exist or can't be read
+     */
+    public InputStream retrieveInputStream(String fileId) throws IOException {
+        Path filePath = getFilePath(fileId);
+        // Let Files.newInputStream throw NoSuchFileException naturally — avoids TOCTOU race
+        // between exists-check and open when another thread may delete concurrently.
+        return new BufferedInputStream(Files.newInputStream(filePath));
+    }
+
+    /**
+     * Store data from an InputStream as a file and return its unique ID and byte count. Streams
+     * directly to disk without buffering the entire content in heap.
+     *
+     * @param inputStream The input stream to read from
+     * @param originalName The original name of the file (unused, kept for API symmetry)
+     * @return A {@link StoredFile} containing the file ID and the number of bytes written
+     * @throws IOException If there is an error storing the file
+     */
+    public StoredFile storeInputStream(InputStream inputStream, String originalName)
+            throws IOException {
+        String fileId = generateFileId();
+        Path filePath = getFilePath(fileId);
+        Files.createDirectories(filePath.getParent());
+        long size = Files.copy(inputStream, filePath);
+        log.debug("Stored input stream with ID: {}", fileId);
+        return new StoredFile(fileId, size);
+    }
+
+    public String storeFromStreamingBody(StreamingResponseBody body, String originalName)
+            throws IOException {
+        String fileId = generateFileId();
+        Path filePath = getFilePath(fileId);
+        Files.createDirectories(filePath.getParent());
+        boolean success = false;
+        try (OutputStream os = new BufferedOutputStream(Files.newOutputStream(filePath))) {
+            body.writeTo(os);
+            success = true;
+        } finally {
+            if (!success) {
+                try {
+                    Files.deleteIfExists(filePath);
+                } catch (IOException cleanupEx) {
+                    log.warn(
+                            "Failed to clean up partial file {} after store failure",
+                            filePath,
+                            cleanupEx);
+                }
+            }
+        }
+        log.debug("Stored StreamingResponseBody with ID: {}", fileId);
+        return fileId;
+    }
+
+    /**
+     * Persist a {@link Resource} body to disk, returning the generated file ID. Used by the async
+     * job pipeline to capture {@code ResponseEntity<Resource>} results produced by controllers.
+     */
+    public String storeFromResource(Resource resource, String originalName) throws IOException {
+        String fileId = generateFileId();
+        Path filePath = getFilePath(fileId);
+        Files.createDirectories(filePath.getParent());
+        boolean success = false;
+        try (InputStream in = resource.getInputStream()) {
+            Files.copy(in, filePath);
+            success = true;
+        } finally {
+            if (!success) {
+                try {
+                    Files.deleteIfExists(filePath);
+                } catch (IOException cleanupEx) {
+                    log.warn(
+                            "Failed to clean up partial file {} after store failure",
+                            filePath,
+                            cleanupEx);
+                }
+            }
+        }
+        log.debug("Stored Resource with ID: {}", fileId);
+        return fileId;
+    }
+
     /**
      * Delete a file by its ID
      *

app/common/src/main/java/stirling/software/common/service/InternalApiClient.java

@@ -0,0 +1,218 @@
+package stirling.software.common.service;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.time.Duration;
+import java.util.regex.Pattern;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.env.Environment;
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.core.io.Resource;
+import org.springframework.http.*;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.util.MultiValueMap;
+import org.springframework.web.client.RequestCallback;
+import org.springframework.web.client.ResourceAccessException;
+import org.springframework.web.client.RestTemplate;
+
+import jakarta.servlet.ServletContext;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.model.enumeration.Role;
+import stirling.software.common.util.TempFile;
+import stirling.software.common.util.TempFileManager;
+
+/**
+ * Dispatches HTTP POST requests to internal Stirling API endpoints via loopback. Used by
+ * PipelineProcessor and AiWorkflowService to execute tool operations programmatically without
+ * leaving the JVM network stack.
+ */
+@Service
+@Slf4j
+public class InternalApiClient {
+
+    // Allowlist for internal dispatch. Matches fixed namespace prefixes,
+    // but rejects traversal (..), URL-encoding (%), query/fragment, backslashes, and any other
+    // character that could alter the resolved endpoint on the local Spring server.
+    //
+    // The second alternation carves out `/api/v1/ai/tools/*` specifically — AI tools are
+    // dispatchable, but the broader `/api/v1/ai/` surface (orchestrate, health, etc.) is
+    // intentionally NOT permitted to avoid plan steps re-entering the orchestrator.
+    private static final Pattern ALLOWED_ENDPOINT_PATH =
+            Pattern.compile(
+                    "^/api/v1/(general|misc|security|convert|filter)(/[A-Za-z0-9_-]+)+$"
+                            + "|^/api/v1/ai/tools(/[A-Za-z0-9_-]+)+$");
+
+    private final ServletContext servletContext;
+    private final UserServiceInterface userService;
+    private final TempFileManager tempFileManager;
+    private final Environment environment;
+    private final Duration readTimeout;
+    private final RestTemplate restTemplate;
+
+    public InternalApiClient(
+            ServletContext servletContext,
+            @Autowired(required = false) UserServiceInterface userService,
+            TempFileManager tempFileManager,
+            Environment environment,
+            ApplicationProperties applicationProperties) {
+        this.servletContext = servletContext;
+        this.userService = userService;
+        this.tempFileManager = tempFileManager;
+        this.environment = environment;
+        ApplicationProperties.InternalApi internalApi = applicationProperties.getInternalApi();
+        // A bounded read timeout is what protects the workflow when an internal tool hangs
+        // (e.g. an infinite loop in a PDF processing service). The connect timeout is short
+        // because this is a loopback call; if connecting takes longer than a few seconds the
+        // local server is itself unhealthy.
+        this.readTimeout = Duration.ofSeconds(internalApi.getReadTimeoutSeconds());
+        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
+        factory.setConnectTimeout(Duration.ofSeconds(internalApi.getConnectTimeoutSeconds()));
+        factory.setReadTimeout(readTimeout);
+        this.restTemplate = new RestTemplate(factory);
+    }
+
+    /**
+     * POST to an internal API endpoint. The endpointPath must start with one of the allowed
+     * prefixes (e.g. {@code /api/v1/misc/compress-pdf}).
+     *
+     * @param endpointPath API path (e.g. {@code /api/v1/general/rotate-pdf})
+     * @param body multipart form body (fileInput + parameters)
+     * @return response with the result file as a {@link TempFileResource} body
+     */
+    public ResponseEntity<Resource> post(String endpointPath, MultiValueMap<String, Object> body) {
+        validateUrl(endpointPath);
+        String url = getBaseUrl() + endpointPath;
+
+        HttpHeaders headers = new HttpHeaders();
+        String apiKey = getApiKeyForUser();
+        if (apiKey != null && !apiKey.isEmpty()) {
+            headers.add("X-API-KEY", apiKey);
+        }
+
+        HttpEntity<MultiValueMap<String, Object>> entity = new HttpEntity<>(body, headers);
+        RequestCallback requestCallback = restTemplate.httpEntityCallback(entity, Resource.class);
+
+        try {
+            return restTemplate.execute(
+                    url,
+                    HttpMethod.POST,
+                    requestCallback,
+                    response -> {
+                        try {
+                            TempFile tempFile =
+                                    tempFileManager.createManagedTempFile("internal-api");
+                            Files.copy(
+                                    response.getBody(),
+                                    tempFile.getPath(),
+                                    java.nio.file.StandardCopyOption.REPLACE_EXISTING);
+                            String filename = extractFilename(response.getHeaders());
+                            TempFileResource resource = new TempFileResource(tempFile, filename);
+                            return ResponseEntity.status(response.getStatusCode())
+                                    .headers(response.getHeaders())
+                                    .body(resource);
+                        } catch (IOException e) {
+                            throw new UncheckedIOException(e);
+                        }
+                    });
+        } catch (ResourceAccessException e) {
+            // RestTemplate wraps low-level I/O failures in ResourceAccessException. Only the
+            // SocketTimeoutException-rooted case is a real timeout; other I/O failures (connection
+            // refused, DNS, etc.) propagate as-is so the upstream generic handler can describe
+            // them accurately.
+            if (e.getCause() instanceof java.net.SocketTimeoutException) {
+                throw new InternalApiTimeoutException(endpointPath, readTimeout, e);
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * Extract the filename from a response's {@code Content-Disposition} header. Returns {@code
+     * null} if the header is missing or has no filename.
+     */
+    private static String extractFilename(HttpHeaders headers) {
+        String contentDisposition = headers.getFirst(HttpHeaders.CONTENT_DISPOSITION);
+        if (contentDisposition == null || contentDisposition.isBlank()) {
+            return null;
+        }
+        for (String part : contentDisposition.split(";")) {
+            String trimmed = part.trim();
+            if (trimmed.startsWith("filename")) {
+                String[] kv = trimmed.split("=", 2);
+                if (kv.length != 2) {
+                    continue;
+                }
+                String value = kv[1].trim().replace("\"", "");
+                return URLDecoder.decode(value, StandardCharsets.UTF_8);
+            }
+        }
+        return null;
+    }
+
+    private String getBaseUrl() {
+        // Resolve the port lazily so desktop mode (server.port=0, OS-assigned) dispatches to the
+        // actual bound port. Spring publishes local.server.port once the web server is up; fall
+        // back to the configured server.port for early calls (tests, non-web contexts).
+        String port = environment.getProperty("local.server.port");
+        if (port == null) {
+            port = environment.getProperty("server.port", "8080");
+        }
+        return "http://localhost:" + port + servletContext.getContextPath();
+    }
+
+    private String getApiKeyForUser() {
+        if (userService == null) return "";
+        String username = userService.getCurrentUsername();
+        if (username != null && !username.equals("anonymousUser")) {
+            return userService.getApiKeyForUser(username);
+        }
+        return userService.getApiKeyForUser(Role.INTERNAL_API_USER.getRoleId());
+    }
+
+    private void validateUrl(String endpointPath) {
+        if (endpointPath == null || !ALLOWED_ENDPOINT_PATH.matcher(endpointPath).matches()) {
+            log.warn("Blocked internal API request to disallowed path: {}", endpointPath);
+            throw new SecurityException(
+                    "Internal API dispatch not permitted for endpoint: " + endpointPath);
+        }
+    }
+
+    /**
+     * A {@link FileSystemResource} that holds a reference to its backing {@link TempFile}.
+     *
+     * <p>If a display filename is supplied (typically parsed from the upstream response's {@code
+     * Content-Disposition} header), it is returned from {@link #getFilename()} instead of the
+     * underlying temp file's path-based name.
+     */
+    public static class TempFileResource extends FileSystemResource {
+        private final TempFile tempFile;
+        private final String displayFilename;
+
+        public TempFileResource(TempFile tempFile) {
+            this(tempFile, null);
+        }
+
+        public TempFileResource(TempFile tempFile, String displayFilename) {
+            super(tempFile.getFile());
+            this.tempFile = tempFile;
+            this.displayFilename = displayFilename;
+        }
+
+        public TempFile getTempFile() {
+            return tempFile;
+        }
+
+        @Override
+        public String getFilename() {
+            return displayFilename != null ? displayFilename : super.getFilename();
+        }
+    }
+}

app/common/src/main/java/stirling/software/common/service/InternalApiTimeoutException.java

@@ -0,0 +1,36 @@
+package stirling.software.common.service;
+
+import java.time.Duration;
+
+/**
+ * Thrown when an internal Stirling tool invocation exceeds its configured read timeout or otherwise
+ * fails at the transport layer. Distinguishes a hung/timed-out tool from a tool that returned a
+ * non-2xx HTTP response (which is reported via the response status itself), so callers can present
+ * a clear "the tool didn't respond in time" message to the user instead of a generic stack trace.
+ */
+public class InternalApiTimeoutException extends RuntimeException {
+
+    private final String endpointPath;
+    private final Duration readTimeout;
+
+    public InternalApiTimeoutException(String endpointPath, Duration readTimeout, Throwable cause) {
+        super(buildMessage(endpointPath, readTimeout, cause), cause);
+        this.endpointPath = endpointPath;
+        this.readTimeout = readTimeout;
+    }
+
+    public String getEndpointPath() {
+        return endpointPath;
+    }
+
+    public Duration getReadTimeout() {
+        return readTimeout;
+    }
+
+    private static String buildMessage(String endpointPath, Duration readTimeout, Throwable cause) {
+        String reason = cause != null && cause.getMessage() != null ? cause.getMessage() : "";
+        return String.format(
+                "Internal tool %s did not respond within %ds (%s)",
+                endpointPath, readTimeout.toSeconds(), reason);
+    }
+}

app/common/src/main/java/stirling/software/common/service/JobExecutorService.java

@@ -11,11 +11,13 @@ import java.util.function.Supplier;
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.Resource;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Service;
 import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
 
 import jakarta.servlet.http.HttpServletRequest;
 
@@ -35,7 +37,7 @@ public class JobExecutorService {
     private final HttpServletRequest request;
     private final ResourceMonitor resourceMonitor;
     private final JobQueue jobQueue;
-    private final ExecutorService executor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ExecutorService executor = ExecutorFactory.newVirtualThreadExecutor();
     private final long effectiveTimeoutMs;
 
     @Autowired(required = false)
@@ -254,10 +256,13 @@ public class JobExecutorService {
                 return ResponseEntity.internalServerError()
                         .body(Map.of("error", "Job timed out after " + timeoutToUse + " ms"));
             } catch (RuntimeException e) {
-                // Check if this is a wrapped typed exception that should be handled by
-                // GlobalExceptionHandler
+                // Check if this is a typed exception that should be handled by
+                // GlobalExceptionHandler (either directly or wrapped)
                 Throwable cause = e.getCause();
-                if (cause instanceof stirling.software.common.util.ExceptionUtils.BaseAppException
+                if (e instanceof IllegalArgumentException
+                        || cause
+                                instanceof
+                                stirling.software.common.util.ExceptionUtils.BaseAppException
                         || cause
                                 instanceof
                                 stirling.software.common.util.ExceptionUtils
@@ -302,33 +307,28 @@ public class JobExecutorService {
                 Object body = response.getBody();
 
                 if (body instanceof byte[]) {
-                    // Extract filename from content-disposition header if available
-                    String filename = "result.pdf";
-                    String contentType = MediaType.APPLICATION_PDF_VALUE;
+                    String filename = extractResponseFilename(response);
+                    String contentType = extractResponseContentType(response);
 
-                    if (response.getHeaders().getContentDisposition() != null) {
-                        String disposition =
-                                response.getHeaders().getContentDisposition().toString();
-                        if (disposition.contains("filename=")) {
-                            filename =
-                                    disposition.substring(
-                                            disposition.indexOf("filename=") + 9,
-                                            disposition.lastIndexOf("\""));
-                        }
-                    }
-
-                    MediaType mediaType = response.getHeaders().getContentType();
-
-                    if (mediaType != null) {
-                        contentType = mediaType.toString();
-                    }
-
-                    // Store byte array directly to disk
                     String fileId = fileStorage.storeBytes((byte[]) body, filename);
                     taskManager.setFileResult(jobId, fileId, filename, contentType);
                     log.debug("Stored ResponseEntity<byte[]> result with fileId: {}", fileId);
+                } else if (body instanceof StreamingResponseBody streamingBody) {
+                    String filename = extractResponseFilename(response);
+                    String contentType = extractResponseContentType(response);
 
-                    // Let the GC handle the memory naturally
+                    String fileId = fileStorage.storeFromStreamingBody(streamingBody, filename);
+                    taskManager.setFileResult(jobId, fileId, filename, contentType);
+                    log.debug(
+                            "Stored ResponseEntity<StreamingResponseBody> result with fileId: {}",
+                            fileId);
+                } else if (body instanceof Resource resource) {
+                    String filename = extractResponseFilename(response);
+                    String contentType = extractResponseContentType(response);
+
+                    String fileId = fileStorage.storeFromResource(resource, filename);
+                    taskManager.setFileResult(jobId, fileId, filename, contentType);
+                    log.debug("Stored ResponseEntity<Resource> result with fileId: {}", fileId);
                 } else {
                     // Check if the response body contains a fileId
                     if (body != null && body.toString().contains("fileId")) {
@@ -478,6 +478,21 @@ public class JobExecutorService {
         }
     }
 
+    private static String extractResponseFilename(ResponseEntity<?> response) {
+        if (response.getHeaders().getContentDisposition() != null) {
+            String filename = response.getHeaders().getContentDisposition().getFilename();
+            if (filename != null && !filename.isEmpty()) {
+                return filename;
+            }
+        }
+        return "result.pdf";
+    }
+
+    private static String extractResponseContentType(ResponseEntity<?> response) {
+        MediaType mediaType = response.getHeaders().getContentType();
+        return mediaType != null ? mediaType.toString() : MediaType.APPLICATION_PDF_VALUE;
+    }
+
     /**
      * Parse session timeout string (e.g., "30m", "1h") to milliseconds
      *

app/common/src/main/java/stirling/software/common/service/JobQueue.java

@@ -44,8 +44,10 @@ public class JobQueue implements SmartLifecycle {
 
     private volatile BlockingQueue<QueuedJob> jobQueue;
     private final Map<String, QueuedJob> jobMap = new ConcurrentHashMap<>();
-    private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
-    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualOrCachedThreadExecutor();
+    private final ScheduledExecutorService scheduler =
+            Executors.newSingleThreadScheduledExecutor(
+                    Thread.ofVirtual().name("job-queue-scheduler-", 0).factory());
+    private final ExecutorService jobExecutor = ExecutorFactory.newVirtualThreadExecutor();
     private final Object queueLock = new Object(); // Lock for synchronizing queue operations
 
     private boolean shuttingDown = false;
@@ -399,7 +401,7 @@ public class JobQueue implements SmartLifecycle {
      * @throws Exception If there is an execution error
      */
     private <T> T executeWithTimeout(Supplier<T> supplier, long timeoutMs) throws Exception {
-        CompletableFuture<T> future = CompletableFuture.supplyAsync(supplier);
+        CompletableFuture<T> future = CompletableFuture.supplyAsync(supplier, jobExecutor);
 
         try {
             if (timeoutMs <= 0) {

app/common/src/main/java/stirling/software/common/service/MobileScannerService.java

@@ -129,7 +129,7 @@ public class MobileScannerService {
                         FILE_EXTENSION_PATTERN.matcher(safeFilename).replaceFirst("");
                 String ext =
                         safeFilename.contains(".")
-                                ? safeFilename.substring(safeFilename.lastIndexOf("."))
+                                ? safeFilename.substring(safeFilename.lastIndexOf('.'))
                                 : "";
                 safeFilename = nameWithoutExt + "-" + counter + ext;
                 filePath = sessionDir.resolve(safeFilename).normalize().toAbsolutePath();

app/common/src/main/java/stirling/software/common/service/PdfAnnotationService.java

@@ -0,0 +1,157 @@
+package stirling.software.common.service;
+
+import java.util.Calendar;
+import java.util.List;
+
+import org.apache.pdfbox.cos.COSName;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.graphics.color.PDColor;
+import org.apache.pdfbox.pdmodel.graphics.color.PDDeviceRGB;
+import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationText;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.api.comments.AnnotationLocation;
+import stirling.software.common.model.api.comments.StickyNoteSpec;
+
+/**
+ * Shared primitive for adding sticky-note (PDF Text) annotations to a document.
+ *
+ * <p>Used by:
+ *
+ * <ul>
+ *   <li>{@code /api/v1/misc/add-comments} — a deterministic, reusable tool.
+ *   <li>AI-agent flows that generate comment specs (e.g. PDF review agent, math auditor review
+ *       mode) and hand them off to this service for deterministic placement.
+ * </ul>
+ */
+@Slf4j
+@Service
+public class PdfAnnotationService {
+
+    /** Yellow sticky-note fill colour (R, G, B in 0..1 range). */
+    private static final float[] STICKY_NOTE_COLOR_RGB = {1f, 0.95f, 0.4f};
+
+    /** Opacity for the sticky-note icon. */
+    private static final float ANNOTATION_OPACITY = 0.9f;
+
+    /** PDF Text-annotation icon name — {@code "Comment"} is one of the standard icons. */
+    private static final String ANNOTATION_ICON_NAME = "Comment";
+
+    /** Default subject shown in the annotation popup when a spec does not supply one. */
+    private static final String DEFAULT_SUBJECT = "Stirling AI Comment";
+
+    /** Default author label shown in the annotation popup when a spec does not supply one. */
+    private static final String DEFAULT_AUTHOR = "Stirling AI";
+
+    /**
+     * Cap on sticky-note text length. PDF annotation bodies can technically be much longer, but
+     * anything beyond this is almost certainly pathological (accidental document-dump or malicious
+     * payload) and would bloat the output file.
+     */
+    private static final int MAX_COMMENT_TEXT_LENGTH = 100_000;
+
+    /**
+     * Add a list of sticky notes to {@code doc}. Specs that reference an out-of-range page or
+     * contain blank text are logged and skipped; this method never throws for a single bad spec.
+     *
+     * @return the number of annotations actually applied
+     */
+    public int addStickyNotes(PDDocument doc, List<StickyNoteSpec> specs) {
+        if (specs == null || specs.isEmpty()) {
+            return 0;
+        }
+        int totalPages = doc.getNumberOfPages();
+        Calendar now = Calendar.getInstance();
+        int applied = 0;
+        for (int i = 0; i < specs.size(); i++) {
+            StickyNoteSpec spec = specs.get(i);
+            if (!isValid(spec, totalPages, i)) {
+                continue;
+            }
+            apply(doc, spec, now);
+            applied++;
+        }
+        if (applied < specs.size()) {
+            log.warn(
+                    "Applied {}/{} sticky notes; {} skipped due to invalid specs.",
+                    applied,
+                    specs.size(),
+                    specs.size() - applied);
+        }
+        return applied;
+    }
+
+    /**
+     * Add a single sticky note. Convenience wrapper; prefer {@link #addStickyNotes(PDDocument,
+     * List)} when placing multiple annotations so log output is batched.
+     */
+    public void addStickyNote(PDDocument doc, StickyNoteSpec spec) {
+        addStickyNotes(doc, List.of(spec));
+    }
+
+    private boolean isValid(StickyNoteSpec spec, int totalPages, int index) {
+        if (spec == null || spec.location() == null) {
+            log.warn("Skipping sticky-note[{}]: spec or location is null.", index);
+            return false;
+        }
+        if (spec.text() == null || spec.text().isBlank()) {
+            log.warn("Skipping sticky-note[{}]: text is blank.", index);
+            return false;
+        }
+        if (spec.text().length() > MAX_COMMENT_TEXT_LENGTH) {
+            log.warn(
+                    "Skipping sticky-note[{}]: text length {} exceeds limit {}.",
+                    index,
+                    spec.text().length(),
+                    MAX_COMMENT_TEXT_LENGTH);
+            return false;
+        }
+        AnnotationLocation loc = spec.location();
+        if (loc.width() <= 0f || loc.height() <= 0f) {
+            log.warn(
+                    "Skipping sticky-note[{}]: non-positive dimensions width={} height={}.",
+                    index,
+                    loc.width(),
+                    loc.height());
+            return false;
+        }
+        int page = loc.pageIndex();
+        if (page < 0 || page >= totalPages) {
+            log.warn(
+                    "Skipping sticky-note[{}]: pageIndex={} out of range [0, {}).",
+                    index,
+                    page,
+                    totalPages);
+            return false;
+        }
+        return true;
+    }
+
+    private void apply(PDDocument doc, StickyNoteSpec spec, Calendar now) {
+        AnnotationLocation loc = spec.location();
+
+        PDAnnotationText annot = new PDAnnotationText();
+        annot.setContents(spec.text());
+        annot.setRectangle(new PDRectangle(loc.x(), loc.y(), loc.width(), loc.height()));
+        annot.setSubject(nonBlankOr(spec.subject(), DEFAULT_SUBJECT));
+        annot.setTitlePopup(nonBlankOr(spec.author(), DEFAULT_AUTHOR));
+        annot.setColor(new PDColor(STICKY_NOTE_COLOR_RGB, PDDeviceRGB.INSTANCE));
+        annot.setCreationDate(now);
+        annot.setConstantOpacity(ANNOTATION_OPACITY);
+        annot.getCOSObject().setName(COSName.NAME, ANNOTATION_ICON_NAME);
+
+        try {
+            doc.getPage(loc.pageIndex()).getAnnotations().add(annot);
+        } catch (java.io.IOException e) {
+            log.warn(
+                    "Failed to attach sticky note to page {}: {}", loc.pageIndex(), e.getMessage());
+        }
+    }
+
+    private static String nonBlankOr(String value, String fallback) {
+        return value != null && !value.isBlank() ? value : fallback;
+    }
+}

app/common/src/main/java/stirling/software/common/service/PdfMetadataService.java

@@ -169,7 +169,10 @@ public class PdfMetadataService {
                             .getAuthor();
 
             if (userService != null) {
-                author = author.replace("username", userService.getCurrentUsername());
+                String username = userService.getCurrentUsername();
+                if (username != null) {
+                    author = author.replace("username", username);
+                }
             }
         }
         pdf.getDocumentInformation().setAuthor(author);

app/common/src/main/java/stirling/software/common/service/PdfSigningService.java

@@ -0,0 +1,37 @@
+package stirling.software.common.service;
+
+import java.security.KeyStore;
+
+/**
+ * Abstraction for PDF digital signature operations. Defined in common so that proprietary services
+ * can use it without creating a circular dependency on core.
+ */
+public interface PdfSigningService {
+
+    /**
+     * Signs a PDF document using the provided KeyStore.
+     *
+     * @param pdfBytes raw PDF bytes to sign
+     * @param keystore the KeyStore containing the signing key and certificate chain
+     * @param password keystore password
+     * @param showSignature whether to render a visible signature block
+     * @param pageNumber 0-indexed page on which to render the visible signature (may be null)
+     * @param name signer name embedded in the signature
+     * @param location location string embedded in the signature
+     * @param reason reason string embedded in the signature
+     * @param showLogo whether to include the Stirling-PDF logo in the visible signature
+     * @return signed PDF bytes
+     * @throws Exception on any signing failure
+     */
+    byte[] signWithKeystore(
+            byte[] pdfBytes,
+            KeyStore keystore,
+            char[] password,
+            boolean showSignature,
+            Integer pageNumber,
+            String name,
+            String location,
+            String reason,
+            boolean showLogo)
+            throws Exception;
+}