Merge pull request #601 from the-luap/release-please--branches--beta

chore(beta): release 3.60.1-beta.0

.drone.yml

@@ -1,114 +0,0 @@
-kind: pipeline
-type: docker
-name: default
-
-steps:
-  # Build Backend Docker Image
-  - name: build-backend
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-backend
-      tags: 
-        - latest
-        - ${DRONE_COMMIT_SHA:0:8}
-        - ${DRONE_BRANCH}-latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: registry.local.nothaft.cloud
-      build_args:
-        - VERSION=${DRONE_TAG:-dev}
-      
-  # Build Frontend Docker Image
-  - name: build-frontend
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-frontend
-      tags: 
-        - latest
-        - ${DRONE_COMMIT_SHA:0:8}
-        - ${DRONE_BRANCH}-latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: registry.local.nothaft.cloud
-      build_args:
-        - VERSION=${DRONE_TAG:-dev}
-        - VITE_API_URL=${VITE_API_URL:-/api}
-
-trigger:
-  branch:
-    - main
-    - develop
-  event:
-    - push
-    - pull_request
-
----
-kind: pipeline
-type: docker
-name: release
-
-steps:
-  # Build Backend Release
-  - name: build-backend-release
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-backend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: registry.local.nothaft.cloud
-      
-  # Build Frontend Release
-  - name: build-frontend-release
-    image: plugins/docker
-    settings:
-      repo: registry.local.nothaft.cloud/picpeak-frontend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: registry.local.nothaft.cloud
-
-  # -------- NEW: Publish Docker images to GitHub Container Registry --------
-  - name: push-backend-ghcr
-    image: plugins/docker
-    settings:
-      repo: ghcr.io/the-luap/picpeak-backend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: backend/Dockerfile
-      context: backend/
-      registry: ghcr.io
-      username:
-        from_secret: GITHUB_USERNAME
-      password:
-        from_secret: GITHUB_TOKEN
-      build_args:
-        - VERSION=${DRONE_TAG}
-
-  - name: push-frontend-ghcr
-    image: plugins/docker
-    settings:
-      repo: ghcr.io/the-luap/picpeak-frontend
-      tags:
-        - ${DRONE_TAG}
-        - latest
-      dockerfile: frontend/Dockerfile
-      context: frontend/
-      registry: ghcr.io
-      username:
-        from_secret: GITHUB_USERNAME
-      password:
-        from_secret: GITHUB_TOKEN
-      build_args:
-        - VERSION=${DRONE_TAG}
-        - VITE_API_URL=${VITE_API_URL:-/api}
-
-
-trigger:
-  event:
-    - tag

.env.example

@@ -7,6 +7,34 @@ NODE_ENV=production
 # JWT Secret (generate with: openssl rand -base64 64)
 JWT_SECRET=your_very_long_random_jwt_secret_here
 
+# Auth cookie Secure flag
+#   unset  - default: follows NODE_ENV (production=true, dev=false)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP
+#
+# Use COOKIE_SECURE=auto if your deployment is reachable over both HTTPS
+# (via reverse proxy like Nginx Proxy Manager, Traefik, Caddy) AND plain
+# HTTP (e.g. LAN access at http://192.168.x.x:3010). The backend reads
+# req.secure from Express, which respects the X-Forwarded-Proto header
+# when the proxy is in the trust list.
+#
+# Requirements for auto mode:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # Database Configuration (PostgreSQL)
 DATABASE_CLIENT=pg
 DB_USER=picpeak
@@ -22,6 +50,7 @@ REDIS_PASSWORD=your_secure_redis_password_here
 # Admin Account (initial setup)
 ADMIN_USERNAME=admin
 ADMIN_EMAIL=admin@yourdomain.com
+ADMIN_PASSWORD=your_secure_admin_password_here
 
 # Email Configuration
 # For Gmail: use app-specific password
@@ -39,6 +68,21 @@ EMAIL_FROM=noreply@yourdomain.com
 FRONTEND_URL=https://yourdomain.com
 ADMIN_URL=https://yourdomain.com
 
+# Static HTML title + description used for social link previews when the
+# fetcher doesn't trigger the per-event OG endpoint — most notably the
+# WhatsApp Business API and various 3rd-party preview-service caches
+# (#521). Set these to your brand so link previews aren't generic.
+# Substituted into index.html at frontend-container start, so changes
+# take effect on the next `docker compose up -d frontend` — no rebuild
+# required.
+BRAND_TITLE=PicPeak
+BRAND_DESCRIPTION=Photo gallery shared with PicPeak.
+
+# API URL for email assets (logos, images in notification emails)
+# This must be the publicly accessible URL where email recipients can load images.
+# If not set, defaults to http://localhost:3001 which will show broken images in emails.
+API_URL=https://yourdomain.com/api
+
 # Frontend API base
 # For pre-built images and production behind a reverse proxy, keep '/api'.
 # If you rebuild the frontend yourself, you may set a full URL at build time.
@@ -50,15 +94,19 @@ VITE_API_URL=/api
 # DB_PORT=5432
 # REDIS_PORT=6379
 
+# Release Channel
+# Options: 'stable' (default), 'beta', or specific version like 'v2.3.0'
+# 'stable' uses the :stable tag (same as :latest on main)
+# 'beta' uses the :beta tag for pre-release versions
+PICPEAK_CHANNEL=stable
+
+# Update Check Configuration
+# Set to 'false' to disable update notifications in admin UI
+UPDATE_CHECK_ENABLED=true
+
 # Timezone
 TZ=UTC
 
-# Runtime user mapping for Docker (optional)
-# Set these to your host user's UID/GID to avoid permission issues on bind mounts.
-# Run `id -u` and `id -g` on host to get values. Defaults to 1001.
-PUID=1001
-PGID=1001
-
 # Analytics (Optional - Umami)
 VITE_UMAMI_URL=
 VITE_UMAMI_WEBSITE_ID=
@@ -70,6 +118,85 @@ APP_STORAGE=./storage
 APP_DATA=./data
 LOGS=./logs
 
+# ─── Storage Backend ────────────────────────────────────────────────────────
+# PicPeak can store photos, thumbnails and archive zips on the local filesystem
+# (default) or on any S3-compatible object store (AWS S3, MinIO, Cloudflare R2,
+# Backblaze B2, Wasabi, DigitalOcean Spaces, …).
+#
+# STORAGE_BACKEND=local (default)
+#   Uses STORAGE_PATH on the local filesystem. Backwards compatible — every
+#   existing deployment keeps working unchanged.
+#
+# STORAGE_BACKEND=s3
+#   Reads STORAGE_S3_* below. Auto-import via the filesystem watcher is
+#   disabled in this mode (S3 has no inotify) — every photo must enter via the
+#   admin upload UI/API. Run `node backend/scripts/migrate-storage.js` to copy
+#   existing local content to S3 before flipping the env.
+#
+# STORAGE_BACKEND=local
+#
+# STORAGE_S3_BUCKET=picpeak
+# STORAGE_S3_REGION=us-east-1
+# STORAGE_S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
+# STORAGE_S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
+# Custom endpoint — set this for MinIO / R2 / B2 / Spaces. Leave unset for AWS.
+# STORAGE_S3_ENDPOINT=https://s3.us-west-002.backblazeb2.com
+# Optional namespace prefix inside the bucket — useful for multi-deployment buckets.
+# STORAGE_S3_PREFIX=picpeak
+# STORAGE_S3_FORCE_PATH_STYLE=false   # MinIO needs true; auto-on when endpoint is set
+# STORAGE_S3_SSL=true
+#
+# Minimum IAM policy (AWS S3) for the bucket above:
+#   {
+#     "Version": "2012-10-17",
+#     "Statement": [{
+#       "Effect": "Allow",
+#       "Action": [
+#         "s3:GetObject", "s3:PutObject", "s3:DeleteObject",
+#         "s3:ListBucket", "s3:GetBucketLocation"
+#       ],
+#       "Resource": [
+#         "arn:aws:s3:::picpeak",
+#         "arn:aws:s3:::picpeak/*"
+#       ]
+#     }]
+#   }
+#
+# EXTERNAL_MEDIA_ROOT (above) always lives on the local filesystem regardless
+# of STORAGE_BACKEND — reference-mode galleries are not migrated to S3 in v1.
+
+# ─── Outbound Webhooks (#327) ────────────────────────────────────────────────
+# PicPeak POSTs event/photo lifecycle notifications to URLs you configure
+# under Settings → Webhooks. Each delivery is signed HMAC-SHA256 with a
+# per-webhook secret in the X-PicPeak-Signature header.
+#
+# WEBHOOK_ALLOW_PRIVATE_URLS (default: false)
+#   Block URLs resolving to private IPs / loopback / .local etc. as an
+#   SSRF mitigation. Set to "true" ONLY in dev when your receiver is on
+#   the same docker network or localhost. Production deployments must
+#   leave this OFF.
+# WEBHOOK_ALLOW_PRIVATE_URLS=false
+#
+# WEBHOOK_DELIVERY_INTERVAL_MS (default: 5000)
+#   How often the worker polls webhook_deliveries for pending rows.
+# WEBHOOK_DELIVERY_INTERVAL_MS=5000
+#
+# WEBHOOK_DELIVERY_CONCURRENCY (default: 5)
+#   Maximum in-flight deliveries per worker tick. One slow consumer can
+#   monopolize all 5 slots — bump this if your receivers are slow OR ship
+#   a separate webhook-only deployment.
+# WEBHOOK_DELIVERY_CONCURRENCY=5
+#
+# WEBHOOK_HTTP_TIMEOUT_MS (default: 10000)
+#   Per-request timeout. Beyond this, the delivery is recorded as a
+#   network error and retried.
+# WEBHOOK_HTTP_TIMEOUT_MS=10000
+#
+# WEBHOOK_MAX_ATTEMPTS (default: 5)
+#   Total attempts before a delivery is marked failed. Backoff between
+#   attempts is exponential: 1m, 5m, 30m, 2h, 12h.
+# WEBHOOK_MAX_ATTEMPTS=5
+
 # Note on FRONTEND_API_URL (documentation only):
 # When using pre-built frontend images, runtime env vars cannot override the built JS.
 # Do NOT rely on FRONTEND_API_URL in Compose. Instead, keep VITE_API_URL=/api and

.gitea/workflows/mirror-to-github.yml

@@ -1,132 +0,0 @@
-name: Mirror to GitHub
-
-on:
-  workflow_dispatch:  # Allow manual triggering only
-
-jobs:
-  mirror:
-    runs-on: ubuntu-latest
-    # Note: For GitHub fine-grained tokens, ensure the token has:
-    # - Repository access to the-luap/picpeak
-    # - Repository permissions: Contents (Read and Write), Metadata (Read)
-    # For classic tokens: repo scope is sufficient
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0  # Full history for proper mirroring
-
-      - name: Setup Git
-        run: |
-          git config --global user.name "the-luap"
-          git config --global user.email "paul-nothaft@hotmail.de"
-
-      - name: Remove sensitive files and directories
-        run: |
-          echo "Current files before cleanup:"
-          ls -la | head -10 || true
-          echo "..."
-          
-          # Remove sensitive files/directories if they exist
-          echo "Removing sensitive files..."
-          rm -rf .gitea/ || true
-          rm -rf scripts/install-gitea-runner.sh || true
-          rm -rf .drone* || true
-          rm -rf photo-sharing-prd.md || true
-          rm -rf CLAUDE.md || true
-          rm -rf storage/ || true
-          rm -rf events/ || true
-          rm -rf .playwright-mcp/
-          rm -rf .swarm || true
-          rm -rf .claude-flow || true
-
-          
-          echo "Sensitive files removal completed"
-          
-          # Add and commit the cleanup if there are changes
-          git add -A
-          if ! git diff --cached --quiet; then
-            git commit -m "chore: remove sensitive files for GitHub mirror"
-            echo "✅ Committed cleanup of sensitive files"
-          else
-            echo "✅ No sensitive files to remove"
-          fi
-          
-          echo "Final file structure (top level):"
-          ls -la | head -10 || true
-
-      - name: Check GitHub token
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-        run: |
-          if [ -z "$GITHUBTOKEN" ]; then
-            echo "ERROR: GITHUBTOKEN secret is not set!"
-            echo "Please add a GitHub Personal Access Token as a secret named GITHUBTOKEN"
-            echo ""
-            echo "For fine-grained tokens:"
-            echo "  - Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens"
-            echo "  - Create token with repository access to the-luap/picpeak"
-            echo "  - Grant permissions: Contents (Read and Write), Metadata (Read)"
-            echo ""
-            echo "For classic tokens:"
-            echo "  - Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)"
-            echo "  - Create token with 'repo' scope"
-            exit 1
-          else
-            echo "✅ GitHub token is available (length: ${#GITHUBTOKEN})"
-            # Try to detect token type (fine-grained tokens are typically longer)
-            if [ ${#GITHUBTOKEN} -gt 80 ]; then
-              echo "📌 Token appears to be a fine-grained personal access token"
-            else
-              echo "📌 Token appears to be a classic personal access token"
-            fi
-          fi
-
-      - name: Push to GitHub
-        env:
-          GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }}
-          GIT_TRACE: 1  # Enable Git trace for debugging if needed
-        run: |
-          # Remove existing github remote if it exists
-          git remote remove github || true
-          
-          # Configure Git to use the token for authentication
-          # This method works for both classic and fine-grained tokens
-          git config --global url."https://the-luap:${GITHUBTOKEN}@github.com/".insteadOf "https://github.com/"
-          
-          # Add GitHub remote (clean URL without credentials)
-          git remote add github https://github.com/the-luap/picpeak.git
-          
-          # Verify remote was added
-          echo "GitHub remote configuration:"
-          git remote -v
-          
-          # Push to GitHub main branch with error handling
-          echo "Pushing to GitHub..."
-          if git push github main --force 2>&1; then
-            echo "✅ Push to GitHub completed successfully!"
-          else
-            echo "❌ Push to GitHub failed!"
-            echo ""
-            echo "Common issues and solutions:"
-            echo "1. Token permissions: Ensure your token has 'Contents: write' permission"
-            echo "2. Token expiration: Check if your token has expired"
-            echo "3. Repository access: Verify the token has access to the-luap/picpeak repository"
-            echo ""
-            echo "For fine-grained tokens, required permissions:"
-            echo "  - Repository access: the-luap/picpeak"
-            echo "  - Repository permissions: Contents (Read and Write), Metadata (Read)"
-            echo ""
-            echo "For classic tokens, required scope: 'repo'"
-            exit 1
-          fi
-          
-          # Clean up the git config after push
-          git config --global --unset url."https://the-luap:${GITHUBTOKEN}@github.com/".insteadOf
-
-      - name: Workflow completed
-        run: |
-          echo "✅ Mirror to GitHub workflow completed successfully!"
-          echo "📊 Repository mirrored to: https://github.com/the-luap/picpeak"
-          echo "🔒 Sensitive files have been removed from the mirror"
-

.gitea/workflows/test.yml

@@ -1,52 +0,0 @@
-name: Test and Lint
-
-on:
-  push:
-    branches: [ main, develop ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  backend-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install backend dependencies
-        working-directory: ./backend
-        run: npm ci
-      
-      - name: Run backend linting
-        working-directory: ./backend
-        run: npm run lint || true  # Continue on lint errors for now
-      
-      - name: Run backend tests
-        working-directory: ./backend
-        run: npm test || true  # Continue on test failures for now
-  
-  frontend-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install frontend dependencies
-        working-directory: ./frontend
-        run: npm ci --legacy-peer-deps
-      
-      - name: Run frontend linting
-        working-directory: ./frontend
-        run: npm run lint || true  # Continue on lint errors for now
-      
-      - name: Build frontend
-        working-directory: ./frontend
-        run: npm run build

.gitea/workflows/version-and-release.yml

@@ -1,269 +0,0 @@
-name: Version and Release
-
-on:
-  workflow_dispatch:
-
-jobs:
-  version-bump:
-    runs-on: ubuntu-latest
-    outputs:
-      new_version: ${{ steps.version.outputs.new_version }}
-      version_changed: ${{ steps.version.outputs.version_changed }}
-      component_changed: ${{ steps.version.outputs.component_changed }}
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITEA_TOKEN || github.token }}
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Configure Git
-        run: |
-          git config --global user.name 'Gitea Actions Bot'
-          git config --global user.email 'actions@gitea.local'
-      
-      - name: Detect changes and bump version
-        id: version
-        run: |
-          set -e  # Exit on error
-          
-          echo "=== Debug Info ==="
-          echo "GitHub event before: ${{ github.event.before }}"
-          echo "GitHub SHA: ${{ github.sha }}"
-          echo "Current directory: $(pwd)"
-          echo "Git log (last 5): $(git log --oneline -5)"
-          
-          # Get the commit range for changed files
-          if [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ] && [ "${{ github.event.before }}" != "" ]; then
-            COMMIT_RANGE="${{ github.event.before }}..${{ github.sha }}"
-            echo "Using commit range: $COMMIT_RANGE"
-            CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE || echo "")
-          else
-            # First commit or no previous commit, check against HEAD~1 if it exists
-            if git rev-parse HEAD~1 >/dev/null 2>&1; then
-              COMMIT_RANGE="HEAD~1..HEAD"
-              echo "Using commit range: $COMMIT_RANGE"
-              CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE || echo "")
-            else
-              echo "First commit detected, checking all files"
-              CHANGED_FILES=$(git ls-files)
-            fi
-          fi
-          
-          echo "Changed files:"
-          echo "$CHANGED_FILES"
-          
-          # Check what changed (using echo to pipe to grep to avoid grep exit codes)
-          BACKEND_CHANGED=$(echo "$CHANGED_FILES" | grep -c '^backend/' || echo "0")
-          FRONTEND_CHANGED=$(echo "$CHANGED_FILES" | grep -c '^frontend/' || echo "0")
-          ROOT_CHANGED=$(echo "$CHANGED_FILES" | grep -c -E '^(package\.json|docker-compose|Dockerfile|scripts/)' || echo "0")
-          
-          echo "Backend files changed: $BACKEND_CHANGED"
-          echo "Frontend files changed: $FRONTEND_CHANGED"
-          echo "Root files changed: $ROOT_CHANGED"
-          
-          # Get current versions
-          BACKEND_VERSION=$(node -p "require('./backend/package.json').version" 2>/dev/null || echo "1.1.0")
-          FRONTEND_VERSION=$(node -p "require('./frontend/package.json').version" 2>/dev/null || echo "1.1.0")
-          
-          echo "Current backend version: $BACKEND_VERSION"
-          echo "Current frontend version: $FRONTEND_VERSION"
-          
-          # Determine what to update based on changes
-          BACKEND_UPDATE=false
-          FRONTEND_UPDATE=false
-          COMPONENT_CHANGED="none"
-          
-          if [ "$ROOT_CHANGED" -gt 0 ]; then
-            # Root changes affect both components
-            BACKEND_UPDATE=true
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="both"
-            SOURCE_VERSION=$BACKEND_VERSION
-            echo "Root changes detected - updating both components"
-          elif [ "$BACKEND_CHANGED" -gt 0 ] && [ "$FRONTEND_CHANGED" -gt 0 ]; then
-            # Both components changed
-            BACKEND_UPDATE=true
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="both"
-            # Use the higher version as source
-            if [ "$(printf '%s\n' "$BACKEND_VERSION" "$FRONTEND_VERSION" | sort -V | tail -n1)" = "$BACKEND_VERSION" ]; then
-              SOURCE_VERSION=$BACKEND_VERSION
-            else
-              SOURCE_VERSION=$FRONTEND_VERSION
-            fi
-            echo "Both backend and frontend changed - updating both"
-          elif [ "$BACKEND_CHANGED" -gt 0 ]; then
-            # Only backend changed
-            BACKEND_UPDATE=true
-            COMPONENT_CHANGED="backend"
-            SOURCE_VERSION=$BACKEND_VERSION
-            echo "Only backend changed - updating backend"
-          elif [ "$FRONTEND_CHANGED" -gt 0 ]; then
-            # Only frontend changed
-            FRONTEND_UPDATE=true
-            COMPONENT_CHANGED="frontend"
-            SOURCE_VERSION=$FRONTEND_VERSION
-            echo "Only frontend changed - updating frontend"
-          else
-            echo "No relevant changes detected"
-            echo "version_changed=false" >> $GITHUB_OUTPUT
-            echo "component_changed=none" >> $GITHUB_OUTPUT
-            echo "new_version=" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-          
-          echo "Component changed: $COMPONENT_CHANGED"
-          echo "Source version: $SOURCE_VERSION"
-          echo "Backend update: $BACKEND_UPDATE"
-          echo "Frontend update: $FRONTEND_UPDATE"
-          
-          # Calculate new version
-          IFS='.' read -r -a version_parts <<< "$SOURCE_VERSION"
-          MAJOR="${version_parts[0]}"
-          MINOR="${version_parts[1]}"
-          PATCH="${version_parts[2]}"
-          
-          # Increment patch version and ensure tag uniqueness
-          git fetch --tags --quiet || true
-          NEW_PATCH=$((PATCH + 1))
-          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          
-          while git rev-parse "v${NEW_VERSION}" >/dev/null 2>&1; do
-            echo "Tag v${NEW_VERSION} already exists, bumping patch version again"
-            NEW_PATCH=$((NEW_PATCH + 1))
-            NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
-          done
-          
-          echo "New version: $NEW_VERSION"
-          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "component_changed=$COMPONENT_CHANGED" >> $GITHUB_OUTPUT
-          
-          # Update versions in package.json files
-          if [ "$BACKEND_UPDATE" = true ]; then
-            echo "Updating backend version to $NEW_VERSION"
-            cd backend && npm version $NEW_VERSION --no-git-tag-version
-            cd ..
-          fi
-          
-          if [ "$FRONTEND_UPDATE" = true ]; then
-            echo "Updating frontend version to $NEW_VERSION"
-            cd frontend && npm version $NEW_VERSION --no-git-tag-version
-            cd ..
-          fi
-          
-          # Check if there are changes to commit
-          if [[ -n $(git status --porcelain) ]]; then
-            echo "version_changed=true" >> $GITHUB_OUTPUT
-          else
-            echo "version_changed=false" >> $GITHUB_OUTPUT
-          fi
-      
-      - name: Commit version bump
-        if: steps.version.outputs.version_changed == 'true'
-        run: |
-          set -e  # Exit on any error
-          
-          # First, ensure we have the latest changes
-          echo "Fetching latest changes..."
-          git fetch origin main
-          
-          # Check if we're behind and need to update
-          LOCAL=$(git rev-parse HEAD)
-          REMOTE=$(git rev-parse origin/main)
-          
-          if [ "$LOCAL" != "$REMOTE" ]; then
-            echo "Local is behind remote, pulling changes..."
-            git pull origin main --no-rebase
-          fi
-          
-          COMPONENT="${{ steps.version.outputs.component_changed }}"
-          
-          if [ "$COMPONENT" = "both" ]; then
-            git add backend/package.json backend/package-lock.json frontend/package.json frontend/package-lock.json
-            git commit -m "chore: bump version to ${{ steps.version.outputs.new_version }} (backend + frontend)"
-          elif [ "$COMPONENT" = "backend" ]; then
-            git add backend/package.json backend/package-lock.json
-            git commit -m "chore: bump backend version to ${{ steps.version.outputs.new_version }}"
-          elif [ "$COMPONENT" = "frontend" ]; then
-            git add frontend/package.json frontend/package-lock.json
-            git commit -m "chore: bump frontend version to ${{ steps.version.outputs.new_version }}"
-          fi
-          
-          # Pull latest changes before pushing to avoid conflicts
-          echo "Pulling latest changes from origin/main..."
-          if ! git pull --rebase origin main; then
-            echo "Rebase failed, attempting to resolve..."
-            # If rebase fails, abort and try a regular merge
-            git rebase --abort || true
-            git pull origin main --no-rebase
-          fi
-          
-          # Push the changes with retry logic
-          echo "Pushing version bump..."
-          PUSH_SUCCESS=false
-          
-          for i in 1 2 3; do
-            echo "Push attempt $i of 3..."
-            
-            # Try to push
-            if git push origin main 2>&1; then
-              echo "Successfully pushed version bump on attempt $i"
-              PUSH_SUCCESS=true
-              break
-            else
-              echo "Push failed on attempt $i"
-              
-              if [ $i -lt 3 ]; then
-                echo "Waiting 5 seconds before retry..."
-                sleep 5
-                
-                echo "Pulling latest changes..."
-                git fetch origin main
-                
-                # Try rebase first, fall back to merge
-                if ! git rebase origin/main; then
-                  echo "Rebase failed, trying merge..."
-                  git rebase --abort 2>/dev/null || true
-                  git pull origin main --no-rebase
-                fi
-              fi
-            fi
-          done
-          
-          if [ "$PUSH_SUCCESS" = "false" ]; then
-            echo "ERROR: Failed to push after 3 attempts"
-            exit 1
-          fi
-      
-      - name: Create Git tag
-        if: steps.version.outputs.version_changed == 'true'
-        run: |
-          COMPONENT="${{ steps.version.outputs.component_changed }}"
-          
-          if [ "$COMPONENT" = "both" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (backend + frontend)"
-          elif [ "$COMPONENT" = "backend" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (backend)"
-          elif [ "$COMPONENT" = "frontend" ]; then
-            TAG_MESSAGE="Release v${{ steps.version.outputs.new_version }} (frontend)"
-          fi
-          
-          git tag -a "v${{ steps.version.outputs.new_version }}" -m "$TAG_MESSAGE"
-          git push origin "v${{ steps.version.outputs.new_version }}"
-  
-  trigger-drone:
-    needs: version-bump
-    if: needs.version-bump.outputs.version_changed == 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger Drone Build
-        run: |
-          echo "Version bumped to ${{ needs.version-bump.outputs.new_version }}"
-          echo "Component(s) changed: ${{ needs.version-bump.outputs.component_changed }}"
-          echo "Drone will automatically trigger on the new tag"
-          # Drone CI will automatically trigger on the tag push event

.github/ISSUE_TEMPLATE/security_vulnerability.md

@@ -9,7 +9,7 @@ assignees: ''
 
 ⚠️ **IMPORTANT: For serious security vulnerabilities, please DO NOT create a public issue.**
 
-Instead, please email security@example.com with the details.
+Instead, please use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new) or email **info@picpeak.app** with the details.
 
 For minor security improvements or questions, you can use this template:
 

.github/workflows/docker-build.yml

@@ -1,13 +1,31 @@
 name: Build and Push Docker Images
 
+# This workflow is triggered by:
+# - Push to main/beta branches (builds 'latest'/'stable' or 'beta' tagged images)
+# - Version tags from Release Please (e.g., v1.2.0 -> builds versioned images)
+# - GitHub Releases (created by Release Please)
+# - Pull requests (build verification only, no push by default)
+# - Manual workflow dispatch
+#
+# Multi-arch strategy:
+#   Each image (backend, frontend) is built once per architecture on a
+#   native runner — linux/amd64 on ubuntu-latest, linux/arm64 on
+#   ubuntu-24.04-arm. Each leg pushes by digest to GHCR. A follow-up
+#   merge job combines the digests into a multi-arch manifest and applies
+#   the human-readable tags. This is the pattern documented at
+#   https://docs.docker.com/build/ci/github-actions/multi-platform/
+#
+#   Native runners are used instead of QEMU because npm install under
+#   QEMU was previously too slow/unreliable for regular branch builds.
+
 on:
   push:
-    branches: [ main, develop ]
-    tags: [ 'v*.*.*' ]
+    branches: [ main, beta ]
+    tags: [ 'v*.*.*', 'v*.*.*-beta.*' ]  # Triggered by Release Please tags (stable and beta)
   pull_request:
-    branches: [ main ]
+    branches: [ main, beta ]
   release:
-    types: [ published ]
+    types: [ published ]  # Triggered when Release Please creates a release
   workflow_dispatch:
     inputs:
       push:
@@ -21,25 +39,59 @@ on:
 
 env:
   REGISTRY: ghcr.io
-  BACKEND_IMAGE_NAME: ${{ github.repository }}/backend
-  FRONTEND_IMAGE_NAME: ${{ github.repository }}/frontend
+  # BACKEND_IMAGE_NAME and FRONTEND_IMAGE_NAME are computed per job in the
+  # "Compute image names" step. GHCR requires all-lowercase repository names,
+  # but ${{ github.repository }} preserves the original case (e.g. "Luca-Timo/...").
+  # Computing them with bash parameter expansion (${VAR,,}) keeps the workflow
+  # working on forks regardless of the owner's name casing.
+
+# Default GITHUB_TOKEN to read-only at the workflow level. Each job that
+# needs to publish to GHCR sets `packages: write` explicitly. This keeps
+# the rest of the workflow (and any future steps) from inheriting unneeded
+# privileges (CKV2_GHA_1).
+permissions:
+  contents: read
 
 jobs:
+  # -----------------------------------------------------------------------------
+  # Backend: per-arch build, then merge into a multi-arch manifest
+  # -----------------------------------------------------------------------------
   build-backend:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
     permissions:
       contents: read
       packages: write
+      # Trivy uploads its SARIF to the Security tab from this job — see
+      # the "Run Trivy" step below. Scanning per-arch by digest (#476)
+      # is reliable; scanning the multi-arch index by tag from the
+      # merge-* job was not.
       security-events: write
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Prepare platform pair
+      run: |
+        platform="${{ matrix.platform }}"
+        echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
+
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
-      with:
-        platforms: linux/amd64,linux/arm64
 
     - name: Log in to Container Registry
       if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
@@ -51,6 +103,153 @@ jobs:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Determine if pushing
+      id: push-decision
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" && "${{ github.event.inputs.push }}" != "true" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        elif [[ "${{ steps.login-ghcr.outcome }}" != "success" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "push=true" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Extract metadata for Backend (labels only)
+      id: meta-backend
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}
+        labels: |
+          org.opencontainers.image.title=PicPeak Backend
+          org.opencontainers.image.description=PicPeak photo sharing platform backend service
+          org.opencontainers.image.vendor=PicPeak
+          maintainer=${{ github.repository_owner }}
+
+    - name: Build Backend image (push by digest)
+      id: build
+      uses: docker/build-push-action@v5
+      with:
+        context: ./backend
+        file: ./backend/Dockerfile
+        platforms: ${{ matrix.platform }}
+        labels: ${{ steps.meta-backend.outputs.labels }}
+        cache-from: type=gha,scope=backend-${{ env.PLATFORM_PAIR }}
+        cache-to: type=gha,mode=max,scope=backend-${{ env.PLATFORM_PAIR }}
+        outputs: ${{ steps.push-decision.outputs.push == 'true' && format('type=image,name={0}/{1},push-by-digest=true,name-canonical=true,push=true', env.REGISTRY, env.BACKEND_IMAGE_NAME) || 'type=cacheonly' }}
+        build-args: |
+          CACHEBUST=${{ github.run_number }}
+          BUILD_DATE=${{ github.event.head_commit.timestamp }}
+          VCS_REF=${{ github.sha }}
+          VERSION=${{ steps.meta-backend.outputs.version }}
+
+    - name: Export digest
+      if: steps.push-decision.outputs.push == 'true'
+      run: |
+        mkdir -p /tmp/digests
+        digest="${{ steps.build.outputs.digest }}"
+        touch "/tmp/digests/${digest#sha256:}"
+
+    - name: Upload digest artifact
+      if: steps.push-decision.outputs.push == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: digests-backend-${{ env.PLATFORM_PAIR }}
+        path: /tmp/digests/*
+        if-no-files-found: error
+        retention-days: 1
+
+    # Per-arch vulnerability scan (#476). Scanning the multi-arch
+    # manifest from the merge-* job by tag is unreliable — Trivy's
+    # remote resolver crashes intermittently with "no child with
+    # platform linux/amd64 in index". The fix is to scan each leg
+    # by its single-platform digest right here, where it just landed
+    # in GHCR. Tag pinned (was @master) so the action + bundled
+    # Trivy binary don't float between runs.
+    #
+    # exit-code is left unset (=0) for now: Trivy reports findings
+    # to the Security tab but doesn't fail the build. Flipping that
+    # to '1' to actually gate CI is a deliberate follow-up — needs an
+    # audit pass first so the next beta build doesn't surprise red.
+    - name: Run Trivy vulnerability scanner (per-arch, by digest)
+      if: steps.push-decision.outputs.push == 'true'
+      uses: aquasecurity/trivy-action@v0.36.0
+      env:
+        # docker/build-push-action wraps every push in an OCI index
+        # (carries the SLSA provenance attestation alongside the
+        # actual image). Trivy's remote backend defaults to
+        # linux/amd64 regardless of host arch when resolving an
+        # index, which makes the arm64 leg crash with "no child
+        # with platform linux/amd64". Telling Trivy which child to
+        # scan keeps the provenance attestation intact and fixes
+        # the resolver crash. Pin to matrix.platform so each leg
+        # scans its own arch.
+        TRIVY_PLATFORM: ${{ matrix.platform }}
+      with:
+        image-ref: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}@${{ steps.build.outputs.digest }}
+        format: 'sarif'
+        output: 'trivy-backend-${{ env.PLATFORM_PAIR }}.sarif'
+        severity: 'CRITICAL,HIGH'
+        timeout: '10m'
+
+    - name: Upload Trivy scan results to GitHub Security tab
+      if: steps.push-decision.outputs.push == 'true'
+      uses: github/codeql-action/upload-sarif@v4
+      with:
+        sarif_file: 'trivy-backend-${{ env.PLATFORM_PAIR }}.sarif'
+        # Distinct category per arch so the Security tab surfaces
+        # per-platform findings independently — an amd64-only CVE in
+        # a base layer doesn't get masked by the arm64 scan.
+        category: 'backend-vulnerabilities-${{ env.PLATFORM_PAIR }}'
+
+  merge-backend:
+    needs: build-backend
+    runs-on: ubuntu-latest
+    # No security-events permission here — vulnerability scanning moved
+    # to per-arch build-backend jobs (#476). This job's only job is to
+    # combine the per-arch digests into a multi-arch manifest.
+    permissions:
+      contents: read
+      packages: write
+    # Only run when at least one digest was pushed (i.e. not on PRs without push intent).
+    if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+
+    steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Download digest artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: /tmp/digests
+        pattern: digests-backend-*
+        merge-multiple: true
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      id: login-ghcr
+      continue-on-error: true
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Determine build context
+      id: context
+      run: |
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Extract metadata for Backend
       id: meta-backend
       uses: docker/metadata-action@v5
@@ -65,61 +264,60 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
-          type=sha,prefix={{branch}}-,format=short
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
-    - name: Build and push Backend Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: ./backend
-        file: ./backend/Dockerfile
-        # Always build; only push when registry login succeeded
-        push: ${{ (github.event_name != 'pull_request' || github.event.inputs.push == 'true') && steps.login-ghcr.outcome == 'success' }}
-        tags: ${{ steps.meta-backend.outputs.tags }}
-        labels: ${{ steps.meta-backend.outputs.labels }}
-        platforms: linux/amd64,linux/arm64
-        cache-from: type=gha,scope=backend
-        cache-to: type=gha,mode=max,scope=backend
-        build-args: |
-          CACHEBUST=${{ github.run_number }}
-          BUILD_DATE=${{ github.event.head_commit.timestamp }}
-          VCS_REF=${{ github.sha }}
-          VERSION=${{ steps.meta-backend.outputs.version }}
+    - name: Create and push multi-arch manifest
+      working-directory: /tmp/digests
+      run: |
+        docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+          $(printf "${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}@sha256:%s " *)
 
-    - name: Run Trivy vulnerability scanner
-      if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: aquasecurity/trivy-action@master
-      with:
-        image-ref: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}:${{ steps.meta-backend.outputs.version }}
-        format: 'sarif'
-        output: 'trivy-backend.sarif'
-        severity: 'CRITICAL,HIGH'
-        timeout: '10m'
-
-    - name: Upload Trivy scan results to GitHub Security tab
-      if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
-      with:
-        sarif_file: 'trivy-backend.sarif'
-        category: 'backend-vulnerabilities'
+    - name: Inspect manifest
+      run: |
+        docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}:${{ steps.meta-backend.outputs.version }}
 
+  # -----------------------------------------------------------------------------
+  # Frontend: per-arch build, then merge into a multi-arch manifest
+  # -----------------------------------------------------------------------------
   build-frontend:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
     permissions:
       contents: read
       packages: write
+      # See build-backend for the rationale (#476). Same pattern: per-arch
+      # vulnerability scan by digest, SARIF uploaded to the Security tab.
       security-events: write
-    
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Prepare platform pair
+      run: |
+        platform="${{ matrix.platform }}"
+        echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
+
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
-      with:
-        platforms: linux/amd64,linux/arm64
 
     - name: Log in to Container Registry
       if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
@@ -131,6 +329,134 @@ jobs:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Determine if pushing
+      id: push-decision
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" && "${{ github.event.inputs.push }}" != "true" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        elif [[ "${{ steps.login-ghcr.outcome }}" != "success" ]]; then
+          echo "push=false" >> "$GITHUB_OUTPUT"
+        else
+          echo "push=true" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Extract metadata for Frontend (labels only)
+      id: meta-frontend
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}
+        labels: |
+          org.opencontainers.image.title=PicPeak Frontend
+          org.opencontainers.image.description=PicPeak photo sharing platform frontend application
+          org.opencontainers.image.vendor=PicPeak
+          maintainer=${{ github.repository_owner }}
+
+    - name: Build Frontend image (push by digest)
+      id: build
+      uses: docker/build-push-action@v5
+      with:
+        context: ./frontend
+        file: ./frontend/Dockerfile
+        platforms: ${{ matrix.platform }}
+        labels: ${{ steps.meta-frontend.outputs.labels }}
+        cache-from: type=gha,scope=frontend-${{ env.PLATFORM_PAIR }}
+        cache-to: type=gha,mode=max,scope=frontend-${{ env.PLATFORM_PAIR }}
+        outputs: ${{ steps.push-decision.outputs.push == 'true' && format('type=image,name={0}/{1},push-by-digest=true,name-canonical=true,push=true', env.REGISTRY, env.FRONTEND_IMAGE_NAME) || 'type=cacheonly' }}
+        build-args: |
+          CACHEBUST=${{ github.run_number }}
+          BUILD_DATE=${{ github.event.head_commit.timestamp }}
+          VCS_REF=${{ github.sha }}
+          VERSION=${{ steps.meta-frontend.outputs.version }}
+
+    - name: Export digest
+      if: steps.push-decision.outputs.push == 'true'
+      run: |
+        mkdir -p /tmp/digests
+        digest="${{ steps.build.outputs.digest }}"
+        touch "/tmp/digests/${digest#sha256:}"
+
+    - name: Upload digest artifact
+      if: steps.push-decision.outputs.push == 'true'
+      uses: actions/upload-artifact@v4
+      with:
+        name: digests-frontend-${{ env.PLATFORM_PAIR }}
+        path: /tmp/digests/*
+        if-no-files-found: error
+        retention-days: 1
+
+    # Per-arch vulnerability scan (#476). See build-backend for the
+    # full rationale; identical pattern here, only the image-ref +
+    # SARIF filename + category change.
+    - name: Run Trivy vulnerability scanner (per-arch, by digest)
+      if: steps.push-decision.outputs.push == 'true'
+      uses: aquasecurity/trivy-action@v0.36.0
+      env:
+        # See build-backend for the rationale — pin Trivy's platform
+        # to the matrix arch so its remote-index resolver picks the
+        # right child instead of defaulting to linux/amd64 and
+        # crashing on the arm64 leg.
+        TRIVY_PLATFORM: ${{ matrix.platform }}
+      with:
+        image-ref: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}@${{ steps.build.outputs.digest }}
+        format: 'sarif'
+        output: 'trivy-frontend-${{ env.PLATFORM_PAIR }}.sarif'
+        severity: 'CRITICAL,HIGH'
+        timeout: '10m'
+
+    - name: Upload Trivy scan results to GitHub Security tab
+      if: steps.push-decision.outputs.push == 'true'
+      uses: github/codeql-action/upload-sarif@v4
+      with:
+        sarif_file: 'trivy-frontend-${{ env.PLATFORM_PAIR }}.sarif'
+        category: 'frontend-vulnerabilities-${{ env.PLATFORM_PAIR }}'
+
+  merge-frontend:
+    needs: build-frontend
+    runs-on: ubuntu-latest
+    # See merge-backend — vulnerability scanning moved to the per-arch
+    # build-frontend matrix (#476). This job only publishes the manifest.
+    permissions:
+      contents: read
+      packages: write
+    if: github.event_name != 'pull_request' || github.event.inputs.push == 'true'
+
+    steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
+    - name: Download digest artifacts
+      uses: actions/download-artifact@v4
+      with:
+        path: /tmp/digests
+        pattern: digests-frontend-*
+        merge-multiple: true
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      id: login-ghcr
+      continue-on-error: true
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Determine build context
+      id: context
+      run: |
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Extract metadata for Frontend
       id: meta-frontend
       uses: docker/metadata-action@v5
@@ -145,85 +471,86 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
-          type=sha,prefix={{branch}}-,format=short
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
-    - name: Build and push Frontend Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: ./frontend
-        file: ./frontend/Dockerfile
-        # Always build; only push when registry login succeeded
-        push: ${{ (github.event_name != 'pull_request' || github.event.inputs.push == 'true') && steps.login-ghcr.outcome == 'success' }}
-        tags: ${{ steps.meta-frontend.outputs.tags }}
-        labels: ${{ steps.meta-frontend.outputs.labels }}
-        platforms: linux/amd64,linux/arm64
-        cache-from: type=gha,scope=frontend
-        cache-to: type=gha,mode=max,scope=frontend
-        build-args: |
-          CACHEBUST=${{ github.run_number }}
-          BUILD_DATE=${{ github.event.head_commit.timestamp }}
-          VCS_REF=${{ github.sha }}
-          VERSION=${{ steps.meta-frontend.outputs.version }}
+    - name: Create and push multi-arch manifest
+      working-directory: /tmp/digests
+      run: |
+        docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+          $(printf "${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}@sha256:%s " *)
 
-    - name: Run Trivy vulnerability scanner
-      if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: aquasecurity/trivy-action@master
-      with:
-        image-ref: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}:${{ steps.meta-frontend.outputs.version }}
-        format: 'sarif'
-        output: 'trivy-frontend.sarif'
-        severity: 'CRITICAL,HIGH'
-        timeout: '10m'
-
-    - name: Upload Trivy scan results to GitHub Security tab
-      if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
-      with:
-        sarif_file: 'trivy-frontend.sarif'
-        category: 'frontend-vulnerabilities'
-
-  # Note: The publish-manifest job is not needed since docker/build-push-action@v5
-  # automatically creates multi-arch manifests when building for multiple platforms.
-  # The images are already properly tagged and include all architectures.
+    - name: Inspect manifest
+      run: |
+        docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}:${{ steps.meta-frontend.outputs.version }}
 
   summary:
-    needs: [build-backend, build-frontend]
+    needs: [build-backend, merge-backend, build-frontend, merge-frontend]
     if: always()
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    
+
     steps:
+    - name: Compute image names (lowercase for GHCR)
+      run: |
+        repo_lc="${GITHUB_REPOSITORY,,}"
+        echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
+        echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+
     - name: Build Summary
       run: |
         echo "## 🐳 Docker Build Summary" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
-        
+
         if [[ "${{ needs.build-backend.result }}" == "success" ]]; then
-          echo "✅ **Backend**: Successfully built" >> $GITHUB_STEP_SUMMARY
+          echo "✅ **Backend build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
         else
-          echo "❌ **Backend**: Build failed" >> $GITHUB_STEP_SUMMARY
+          echo "❌ **Backend build (per-arch)**: ${{ needs.build-backend.result }}" >> $GITHUB_STEP_SUMMARY
         fi
-        
+
+        if [[ "${{ needs.merge-backend.result }}" == "success" ]]; then
+          echo "✅ **Backend manifest merge**: Successfully published" >> $GITHUB_STEP_SUMMARY
+        elif [[ "${{ needs.merge-backend.result }}" == "skipped" ]]; then
+          echo "ℹ️ **Backend manifest merge**: Skipped (verify-only build)" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "❌ **Backend manifest merge**: ${{ needs.merge-backend.result }}" >> $GITHUB_STEP_SUMMARY
+        fi
+
         if [[ "${{ needs.build-frontend.result }}" == "success" ]]; then
-          echo "✅ **Frontend**: Successfully built" >> $GITHUB_STEP_SUMMARY
+          echo "✅ **Frontend build (per-arch)**: Successfully built" >> $GITHUB_STEP_SUMMARY
         else
-          echo "❌ **Frontend**: Build failed" >> $GITHUB_STEP_SUMMARY
+          echo "❌ **Frontend build (per-arch)**: ${{ needs.build-frontend.result }}" >> $GITHUB_STEP_SUMMARY
         fi
-        
+
+        if [[ "${{ needs.merge-frontend.result }}" == "success" ]]; then
+          echo "✅ **Frontend manifest merge**: Successfully published" >> $GITHUB_STEP_SUMMARY
+        elif [[ "${{ needs.merge-frontend.result }}" == "skipped" ]]; then
+          echo "ℹ️ **Frontend manifest merge**: Skipped (verify-only build)" >> $GITHUB_STEP_SUMMARY
+        else
+          echo "❌ **Frontend manifest merge**: ${{ needs.merge-frontend.result }}" >> $GITHUB_STEP_SUMMARY
+        fi
+
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 📦 Images" >> $GITHUB_STEP_SUMMARY
         echo "- Backend: \`${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
         echo "- Frontend: \`${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
-        
+
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "### 🏗️ Architectures" >> $GITHUB_STEP_SUMMARY
+        echo "Published manifests include both \`linux/amd64\` and \`linux/arm64\` (built natively, no QEMU)." >> $GITHUB_STEP_SUMMARY
+
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 🏷️ Tags" >> $GITHUB_STEP_SUMMARY
         echo "Images are tagged based on:" >> $GITHUB_STEP_SUMMARY
         echo "- Branch name (for branch pushes)" >> $GITHUB_STEP_SUMMARY
-        echo "- PR number (for pull requests)" >> $GITHUB_STEP_SUMMARY
+        echo "- PR number (for pull requests, when push is enabled)" >> $GITHUB_STEP_SUMMARY
         echo "- Version tags (for releases)" >> $GITHUB_STEP_SUMMARY
-        echo "- Short SHA with branch prefix" >> $GITHUB_STEP_SUMMARY
+        echo "- Short SHA" >> $GITHUB_STEP_SUMMARY
         echo "- \`latest\` (for main branch)" >> $GITHUB_STEP_SUMMARY
+        echo "- \`stable\` (for main branch and stable releases)" >> $GITHUB_STEP_SUMMARY
+        echo "- \`beta\` (for beta branch and pre-releases)" >> $GITHUB_STEP_SUMMARY

.github/workflows/install-smoke.yml

@@ -0,0 +1,227 @@
+name: Fresh-install smoke
+
+# Verifies that a clean Postgres install boots cleanly under the same
+# conditions a new user hits on their first `docker compose up -d`. The
+# specific scenarios this guards against — see #484 for the original
+# reproduction:
+#
+#   1. Bind-mounted host directories owned by a UID other than 1001
+#      (the container's nodejs user). The entrypoint must self-chown
+#      and drop privileges via su-exec.
+#   2. Cold-start Postgres with no prior schema (the FK-order bug fixed
+#      in #494, the index/created_at error fixed in #511, and any
+#      future migration-order issue that only surfaces on an empty DB).
+#
+# Triggers only on changes that touch the install path so unrelated PRs
+# don't pay the build cost.
+
+on:
+  push:
+    branches: [main, beta]
+    paths:
+      - 'backend/Dockerfile'
+      - 'backend/wait-for-db.sh'
+      - 'backend/migrations/**'
+      - 'backend/package*.json'
+      - 'docker-compose.production.yml'
+      - '.github/workflows/install-smoke.yml'
+  pull_request:
+    branches: [main, beta]
+    paths:
+      - 'backend/Dockerfile'
+      - 'backend/wait-for-db.sh'
+      - 'backend/migrations/**'
+      - 'backend/package*.json'
+      - 'docker-compose.production.yml'
+      - '.github/workflows/install-smoke.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fresh-install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # Build for the runner's arch only — we just need a runnable image.
+      # The full multi-arch build is the docker-build workflow's job.
+      - name: Build backend image
+        uses: docker/build-push-action@v5
+        with:
+          context: ./backend
+          file: ./backend/Dockerfile
+          load: true
+          tags: picpeak-backend:smoke
+          cache-from: type=gha,scope=install-smoke
+          cache-to: type=gha,mode=max,scope=install-smoke
+
+      - name: Create Docker network
+        run: docker network create picpeak-smoke
+
+      # Mount as UID 1000 (the typical GitHub Actions runner user, and a
+      # common mismatch case on Linux hosts). The entrypoint must chown
+      # this to 1001 itself — that's the regression we're guarding.
+      - name: Prepare host bind-mount dirs owned by UID 1000
+        run: |
+          mkdir -p smoke-mounts/storage smoke-mounts/data smoke-mounts/logs
+          chmod 755 smoke-mounts smoke-mounts/*
+          ls -ld smoke-mounts/*
+
+      - name: Start Postgres
+        run: |
+          docker run -d --name picpeak-smoke-pg --network picpeak-smoke \
+            -e POSTGRES_USER=picpeak \
+            -e POSTGRES_PASSWORD=smokepass \
+            -e POSTGRES_DB=picpeak_prod \
+            --health-cmd="pg_isready -U picpeak -d picpeak_prod" \
+            --health-interval=2s --health-timeout=2s --health-retries=30 \
+            postgres:15-alpine
+
+      - name: Wait for Postgres healthy
+        run: |
+          for i in $(seq 1 60); do
+            status=$(docker inspect -f '{{.State.Health.Status}}' picpeak-smoke-pg 2>/dev/null || echo starting)
+            if [ "$status" = "healthy" ]; then
+              echo "postgres healthy after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "postgres did not become healthy in 60s"
+          docker logs picpeak-smoke-pg
+          exit 1
+
+      - name: Start backend with mismatched-UID bind mounts (fresh install)
+        run: |
+          docker run -d --name picpeak-smoke-bk --network picpeak-smoke \
+            -e NODE_ENV=production \
+            -e JWT_SECRET=smoketestsecretvalueof32characters \
+            -e DB_HOST=picpeak-smoke-pg \
+            -e DB_USER=picpeak \
+            -e DB_PASSWORD=smokepass \
+            -e DB_NAME=picpeak_prod \
+            -e ADMIN_EMAIL=admin@smoke.local \
+            -e ADMIN_PASSWORD=smokeAdminPass12345 \
+            -e STORAGE_PATH=/app/storage \
+            -v "$PWD/smoke-mounts/storage:/app/storage" \
+            -v "$PWD/smoke-mounts/data:/app/data" \
+            -v "$PWD/smoke-mounts/logs:/app/logs" \
+            picpeak-backend:smoke
+
+      - name: Wait for backend healthy
+        run: |
+          for i in $(seq 1 120); do
+            status=$(docker inspect -f '{{.State.Status}}' picpeak-smoke-bk 2>/dev/null || echo missing)
+            health=$(docker inspect -f '{{.State.Health.Status}}' picpeak-smoke-bk 2>/dev/null || echo none)
+            if [ "$status" = "exited" ]; then
+              echo "FAIL: backend exited during cold-start (restart loop scenario)"
+              docker logs picpeak-smoke-bk
+              echo "--- error.log ---"
+              cat smoke-mounts/logs/error.log 2>/dev/null || echo "(no error.log)"
+              exit 1
+            fi
+            if [ "$health" = "healthy" ]; then
+              echo "backend healthy after ${i}s"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "FAIL: backend did not become healthy in 120s"
+          docker ps -a
+          docker logs picpeak-smoke-bk
+          exit 1
+
+      - name: Verify chown happened (container view)
+        run: |
+          # All three dirs should now be owned by nodejs (UID 1001).
+          # If the entrypoint's self-chown branch didn't fire, they'd
+          # still be owned by the runner UID and node would have hit
+          # EACCES creating storage subdirs.
+          for d in /app/storage /app/data /app/logs; do
+            owner_uid=$(docker exec picpeak-smoke-bk stat -c '%u' "$d")
+            if [ "$owner_uid" != "1001" ]; then
+              echo "FAIL: $d is owned by UID $owner_uid (expected 1001)"
+              exit 1
+            fi
+            echo "ok: $d owned by UID $owner_uid"
+          done
+
+      - name: Verify app is actually serving
+        run: |
+          # /health is what docker's HEALTHCHECK polls, but hit it
+          # directly to confirm the response shape matches what the
+          # frontend + reverse proxy expect.
+          body=$(docker exec picpeak-smoke-bk wget -qO- http://localhost:3000/health)
+          echo "/health => $body"
+          echo "$body" | grep -q '"status":"ok"' || {
+            echo "FAIL: /health did not return status:ok"
+            exit 1
+          }
+
+      - name: Verify node runs as nodejs (not root)
+        run: |
+          # dumb-init runs as root (PID 1), node must be running as
+          # nodejs (UID 1001) — if su-exec drop didn't happen the app
+          # would be running as root which is the security regression
+          # we're guarding against. Alpine ships BusyBox ps, which
+          # doesn't support `-p PID` or pgrep, so list + awk instead.
+          user=$(docker exec picpeak-smoke-bk ps -o user,comm | awk '$2=="node" {print $1; exit}')
+          if [ "$user" != "nodejs" ]; then
+            echo "FAIL: node running as '$user' (expected nodejs)"
+            docker exec picpeak-smoke-bk ps -o pid,user,comm
+            exit 1
+          fi
+          echo "ok: node running as $user"
+
+      - name: Verify no restart loop
+        run: |
+          restart_count=$(docker inspect -f '{{.RestartCount}}' picpeak-smoke-bk)
+          if [ "$restart_count" -gt 0 ]; then
+            echo "FAIL: container restarted $restart_count time(s) — install loop bug returning"
+            docker logs picpeak-smoke-bk
+            exit 1
+          fi
+          echo "ok: 0 restarts"
+
+      # Restart with `--user 5005:5005` (no root, can't chown) against
+      # bind mounts owned by 1000 — entrypoint must fail loud with the
+      # actionable preflight error, not silently restart-loop.
+      - name: Verify preflight fails loud on unwritable mounts
+        run: |
+          docker rm -f picpeak-smoke-bk2 2>/dev/null || true
+          set +e
+          out=$(docker run --rm --user 5005:5005 --network picpeak-smoke \
+            -e NODE_ENV=production -e JWT_SECRET=x \
+            -e DB_HOST=picpeak-smoke-pg -e DB_USER=picpeak \
+            -e DB_PASSWORD=smokepass -e DB_NAME=picpeak_prod \
+            -e STORAGE_PATH=/app/storage \
+            -v "$PWD/smoke-mounts/storage:/app/storage" \
+            -v "$PWD/smoke-mounts/data:/app/data" \
+            -v "$PWD/smoke-mounts/logs:/app/logs" \
+            picpeak-backend:smoke 2>&1)
+          rc=$?
+          set -e
+          echo "$out"
+          if [ $rc -eq 0 ]; then
+            echo "FAIL: preflight should have exited non-zero"
+            exit 1
+          fi
+          echo "$out" | grep -q "is not writable by UID 5005" || {
+            echo "FAIL: preflight error message missing or wrong"
+            exit 1
+          }
+          echo "ok: preflight failed loud with actionable error"
+
+      - name: Cleanup
+        if: always()
+        run: |
+          docker rm -f picpeak-smoke-bk picpeak-smoke-bk2 picpeak-smoke-pg 2>/dev/null || true
+          docker network rm picpeak-smoke 2>/dev/null || true

.github/workflows/release-please-beta.yml

@@ -0,0 +1,37 @@
+name: Release Please (Beta)
+
+on:
+  push:
+    branches: [beta]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config-beta.json
+          manifest-file: .release-please-manifest-beta.json
+          target-branch: beta
+
+      - name: Output Release Info
+        if: ${{ steps.release.outputs.release_created }}
+        run: |
+          echo "## Beta Release Created!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tag:** ${{ steps.release.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.release.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Docker images will be built and tagged with this beta version." >> $GITHUB_STEP_SUMMARY
+

.github/workflows/release-please.yml

@@ -0,0 +1,36 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }}
+    steps:
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Output Release Info
+        if: ${{ steps.release.outputs.release_created }}
+        run: |
+          echo "## Release Created! " >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tag:** ${{ steps.release.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Docker images will be built and tagged with this version." >> $GITHUB_STEP_SUMMARY
+

.github/workflows/schema-drift.yml

@@ -0,0 +1,189 @@
+name: Schema drift (#530)
+
+# Verifies that `migrate:safe` can recover a DB that's been seeded only
+# by `initializeDatabase()` — the recovery scenario where the migrations
+# tracking table is empty but the schema already has the modern bootstrap.
+#
+# This is NOT how production reaches its state on normal installs or
+# upgrades. The scenario only fires when:
+#   - A backup was restored that captured tables but not the migrations
+#     table (manifest divergence),
+#   - Someone manually invoked initializeDatabase() outside the migration
+#     runner (recovery / debugging),
+#   - The DB was moved between systems and the migrations table was not
+#     copied along.
+#
+# When `detectExistingSchema()` sees the modern-bootstrap fingerprint
+# (photo_categories + cms_pages tables) but an empty migrations table,
+# it treats it as an "existing deployment" — which runs the legacy
+# chain first. Legacy/008 renames email_templates.subject → subject_en,
+# but core/029 (which runs later in this chain) inserts email templates
+# referencing the pre-rename column name. The chain dies with a
+# "column subject does not exist" error.
+#
+# Fix (in the same PR as this workflow): when the modern-bootstrap
+# fingerprint is detected, mark all legacy migrations as applied so the
+# chain matches what a fresh install runs — only core/*, in order.
+#
+# This workflow boots the failing scenario from scratch on every PR
+# that touches the migrations or db.js, so any future migration with
+# the same shape is caught before merge.
+
+on:
+  push:
+    branches: [main, beta]
+    paths:
+      - 'backend/migrations/**'
+      - 'backend/src/database/db.js'
+      - 'backend/knexfile.js'
+      - '.github/workflows/schema-drift.yml'
+  pull_request:
+    branches: [main, beta]
+    paths:
+      - 'backend/migrations/**'
+      - 'backend/src/database/db.js'
+      - 'backend/knexfile.js'
+      - '.github/workflows/schema-drift.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  upgrade-from-bootstrap:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_USER: picpeak
+          POSTGRES_PASSWORD: testpass
+          POSTGRES_DB: picpeak_drift
+        options: >-
+          --health-cmd "pg_isready -U picpeak -d picpeak_drift"
+          --health-interval 2s
+          --health-timeout 2s
+          --health-retries 30
+        ports:
+          - 5432:5432
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install backend deps
+        working-directory: ./backend
+        run: npm ci
+
+      # Step 1: simulate the recovery state — DB has the modern bootstrap
+      # (post-initializeDatabase) but no migrations recorded. Calling
+      # initializeDatabase() directly outside the migration runner is the
+      # one-line repro for backup-restore-lost-migrations and manual-
+      # invocation paths.
+      - name: Seed DB with initializeDatabase() only
+        working-directory: ./backend
+        env:
+          NODE_ENV: production
+          DATABASE_CLIENT: pg
+          DB_HOST: localhost
+          DB_PORT: 5432
+          DB_USER: picpeak
+          DB_PASSWORD: testpass
+          DB_NAME: picpeak_drift
+        run: |
+          node -e "require('./src/database/db').initializeDatabase().then(() => { console.log('bootstrap ok'); process.exit(0); }).catch(e => { console.error('bootstrap FAILED:', e.message); process.exit(1); })"
+
+      # Sanity-check the recovery shape before migrate:safe runs. If
+      # initializeDatabase() ever stops producing photo_categories +
+      # cms_pages, the fingerprint check would silently no-op and this
+      # workflow would lose its teeth — assert the precondition.
+      - name: Assert recovery-state fingerprint
+        env:
+          PGPASSWORD: testpass
+        run: |
+          installed=$(psql -h localhost -U picpeak -d picpeak_drift -tAc "SELECT count(*) FROM pg_tables WHERE schemaname='public' AND tablename IN ('photo_categories', 'cms_pages')")
+          if [ "$installed" != "2" ]; then
+            echo "FAIL: expected photo_categories + cms_pages from initializeDatabase(); got $installed."
+            psql -h localhost -U picpeak -d picpeak_drift -c "SELECT tablename FROM pg_tables WHERE schemaname='public' ORDER BY tablename"
+            exit 1
+          fi
+          # initializeDatabase() doesn't create the `migrations` tracking
+          # table — that's the migrate:safe runner's job. So in the recovery
+          # scenario, the table either (a) doesn't exist yet or (b) exists
+          # but is empty (e.g. someone created it but didn't populate it).
+          # Both are valid recovery states; check via to_regclass first so
+          # we don't parse a SELECT against a nonexistent table.
+          has_migrations_table=$(psql -h localhost -U picpeak -d picpeak_drift -tAc "SELECT to_regclass('public.migrations')::text")
+          if [ -z "$has_migrations_table" ]; then
+            migrations_count=0
+          else
+            migrations_count=$(psql -h localhost -U picpeak -d picpeak_drift -tAc "SELECT count(*) FROM migrations")
+          fi
+          if [ "$migrations_count" != "0" ]; then
+            echo "FAIL: migrations table should be empty for the recovery scenario; has $migrations_count rows."
+            exit 1
+          fi
+          echo "ok: recovery state confirmed (bootstrap tables present, migrations table empty or absent)."
+
+      # Step 2: run migrate:safe — the test. Before #530's fix in
+      # detectExistingSchema, this died at core/029 with a "column
+      # subject does not exist" error. After the fix, it should complete
+      # cleanly with every migration either applied or marked.
+      - name: Run migrate:safe against the recovery state
+        working-directory: ./backend
+        env:
+          NODE_ENV: production
+          DATABASE_CLIENT: pg
+          DB_HOST: localhost
+          DB_PORT: 5432
+          DB_USER: picpeak
+          DB_PASSWORD: testpass
+          DB_NAME: picpeak_drift
+        run: npm run migrate:safe
+
+      # Step 3: schema-shape assertion. A fresh install through migrate:
+      # safe produces 48 tables; the recovery scenario should converge
+      # to the same number. Off-by-one is fine but a 10+ table delta
+      # means a migration silently bailed in the recovery path.
+      - name: Assert final schema matches fresh-install shape
+        env:
+          PGPASSWORD: testpass
+        run: |
+          tables=$(psql -h localhost -U picpeak -d picpeak_drift -tAc "SELECT count(*) FROM pg_tables WHERE schemaname='public'")
+          echo "Final table count: $tables"
+          # Allow a small drift window — exact count creeps over time as
+          # new migrations land; tight pin would force a workflow edit
+          # on every schema PR. 40+ is a healthy floor that catches the
+          # original bug (which left 17 tables) while staying robust to
+          # forward changes.
+          if [ "$tables" -lt 40 ]; then
+            echo "FAIL: too few tables ($tables) — migrate:safe likely bailed mid-chain."
+            psql -h localhost -U picpeak -d picpeak_drift -c "SELECT tablename FROM pg_tables WHERE schemaname='public' ORDER BY tablename"
+            exit 1
+          fi
+          echo "ok: schema converged to a fresh-install-equivalent shape."
+
+      # Step 4: verify the legacy migrations were all marked applied
+      # (rather than silently bailing inside the chain). The fix in
+      # detectExistingSchema marks legacy/* when the modern bootstrap
+      # is detected — confirm the markings actually landed.
+      - name: Assert legacy migrations marked applied
+        env:
+          PGPASSWORD: testpass
+        run: |
+          legacy_count=$(psql -h localhost -U picpeak -d picpeak_drift -tAc "SELECT count(*) FROM migrations WHERE filename LIKE '008_%' OR filename LIKE '009_%' OR filename LIKE '013_%' OR filename LIKE '019_%' OR filename LIKE '020_%' OR filename LIKE '026_%' OR filename LIKE '028_%'")
+          if [ "$legacy_count" -lt 7 ]; then
+            echo "FAIL: legacy migrations not marked applied ($legacy_count of 7 expected)."
+            psql -h localhost -U picpeak -d picpeak_drift -c "SELECT filename FROM migrations WHERE filename LIKE '0%' ORDER BY filename"
+            exit 1
+          fi
+          echo "ok: legacy migrations marked applied by detectExistingSchema."

.github/workflows/tests.yml

@@ -0,0 +1,89 @@
+name: Tests
+
+# Runs the backend Jest suite and the frontend Vitest suite on every PR.
+# Both suites already exist and cover the CRM service layer (quoteService,
+# contractService, invoiceService.*, customerHoursService, eventService.
+# calendar) plus the photo / settings / OG / auth surface — wiring them
+# into CI makes regressions visible at PR time instead of post-merge.
+#
+# Six backend suites are excluded via --testPathIgnorePatterns. They
+# fail on `upstream/beta` too (pre-existing mock/infra issues, NOT CRM
+# regressions). Excluding them here keeps CI green from day 1; revisit
+# each individually as its own fix.
+#
+# Triggers on any change that could affect either suite. The backend
+# job intentionally omits frontend paths and vice versa so unrelated
+# PRs don't pay both build costs.
+
+on:
+  push:
+    branches: [main, beta]
+  pull_request:
+    branches: [main, beta]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install backend deps
+        working-directory: ./backend
+        run: npm ci
+
+      - name: Run Jest suite
+        working-directory: ./backend
+        env:
+          # backupService tests would otherwise try a real S3 round-trip.
+          # The S3 path itself is covered separately by the integration
+          # suite when MinIO is provisioned.
+          SKIP_S3_TESTS: 'true'
+        run: |
+          # Excluded suites — fail on upstream/beta too, tracked
+          # separately as test-infra debt:
+          #   adminSettings.logo                  — supertest fixture
+          #   integration/adminPhotos.reference   — supertest fixture
+          #   integration/webhookDelivery         — supertest fixture
+          #   services/backupService.enhanced     — knex mock chain
+          #   routes/__tests__/adminAuth          — supertest fixture
+          # (adminNotifications was excluded; #597 fix re-enables it.)
+          npx jest \
+            --testPathIgnorePatterns='/node_modules/|adminSettings\.logo\.test|integration/adminPhotos\.reference|integration/webhookDelivery|backupService\.enhanced|routes/__tests__/adminAuth' \
+            --ci
+
+  frontend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend deps
+        working-directory: ./frontend
+        run: npm ci
+
+      - name: Run Vitest suite
+        working-directory: ./frontend
+        run: npm test -- --run

.gitignore

@@ -69,15 +69,63 @@ backend/data/
 backend/docs/
 backend/logs/
 logs/
-storage/
+# Anchored to repo root: matches the top-level runtime storage dir,
+# NOT backend/src/services/storage/ (the storage backend abstraction code).
+/storage/
 data/
 certbot/
 
 # Ignore local contributor guide copy
 AGENTS.md
+CLAUDE.md
+
+# Working/planning documents (not for release)
+BUGS_AND_FEATURES.md
+frontend/TEST_PLAN.md
+docs/REFACTORING_PLAN.md
+docs/MULTIPLE_ADMINISTRATORS_PLAN.md
+docs/*_PLAN.md
+docs/test-*.md
+docs/feature-*.md
+
+# Scaffolding documentation (local development reference)
+docs/DATABASE_SCHEMA.md
+docs/BACKEND_SERVICES.md
+docs/API_ROUTES.md
+docs/FRONTEND_ARCHITECTURE.md
+docs/DEVELOPER_ONBOARDING.md
+docs/ENVIRONMENT_VARIABLES.md
+
+# Build artifact: OpenAPI spec generated locally + synced into the
+# picpeak-docs repo. Never tracked here — the docs site at
+# docs.picpeak.app is the source of truth.
+docs/openapi.json
+docs/openapi.yaml
+
+# Local backup directory (from testing)
+backup/
 
 # Local artifacts from browser tooling
 .playwright-mcp/
 
+# Local-only E2E suite (never pushed; runs as pre-push gate on this machine)
+tests/e2e/local/
+playwright-local-results/
+e2e-test.log
+scripts/e2e-local.sh
+
 # Local SQLite files in backend
 backend/*.sqlite*
+backend/*.db
+
+# Test files and artifacts
+test-images/
+test-logo*.jpg
+test-logo*.png
+test-results/
+
+# Development docker compose
+docker-compose.dev.yml
+
+# New layout development files
+new-layouts/

.release-please-manifest-beta.json

@@ -0,0 +1,3 @@
+{
+  ".": "3.60.1-beta.0"
+}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.6.1"
+}

CLAUDE.md

@@ -1,386 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Product Overview
-
-A secure photo sharing platform designed for weddings and events, enabling photographers to share time-limited, password-protected galleries. The platform features automatic expiration, archiving, and a scrappbook.de-inspired modern, minimalist UI.
-
-## Architecture Overview
-
-- **Backend**: Node.js/Express API with SQLite/PostgreSQL, file-based photo storage
-- **Frontend**: React SPA with scrappbook.de-style design (requires implementation)
-- **Storage**: File-based with active/archived separation
-- **Services**: Background workers for email, archiving, file watching, and expiration monitoring
-- **Analytics**: Umami integration for engagement tracking
-
-## Essential Commands
-
-### Backend Development
-```bash
-cd backend
-npm install               # Install dependencies
-npm run migrate          # Initialize database schema
-npm run dev              # Start with hot-reload (port 3001)
-npm test                 # Run Jest tests
-npm run lint             # ESLint checks
-```
-
-### Running a Single Test
-```bash
-cd backend
-npm test -- path/to/test.test.js
-npm test -- --testNamePattern="test name"
-```
-
-### Production Deployment
-See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for comprehensive deployment instructions including:
-- Docker Compose deployment
-- PM2 deployment
-- Manual installation
-- Non-nginx deployment options
-- SSL/HTTPS setup
-- Troubleshooting guide
-
-**⚠️ CRITICAL PRODUCTION NOTICE:**
-- Production runs on a SEPARATE SERVER - never assume local changes affect production
-- ALWAYS request production server details before any troubleshooting
-- NO trial-and-error approaches in production - data loss is unacceptable
-- Every change must be thoroughly analyzed and tested locally first
-
-## Key Product Requirements (from PRD)
-
-### Core Features
-1. **File-Based System**: Drop photos in folders → automatic gallery creation
-2. **Automatic Expiration**: Default 30 days, with 7-day warning emails
-3. **Password Protection**: Secure access with customizable passwords
-4. **Automatic Archiving**: ZIP compression and storage after expiration
-5. **Email Notifications**: Creation, warning, and expiration notifications
-6. **Analytics**: Umami tracking for views, downloads, and engagement
-
-### Folder Structure
-```
-/events/
-  ├── active/
-  │   ├── wedding-smith-jones-2024-06-15/
-  │   │   ├── collages/
-  │   │   └── individual/
-  │   └── birthday-emma-2024-07-20/
-  └── archived/
-      └── wedding-smith-jones-2024-06-15.zip
-```
-
-## Frontend Implementation Requirements
-
-### Design Style (scrappbook.de-inspired)
-- **Color Palette**: Primary green (#5C8762), neutral backgrounds
-- **Typography**: Clean, modern sans-serif (Noto Sans or similar)
-- **Layout**: Minimalist, modular sections with grid-based photo displays
-- **Aesthetic**: Professional yet approachable, photographer-focused
-
-### Key Frontend Components to Build
-1. **Landing Page**: Password entry with event preview
-2. **Gallery View**: 
-   - Responsive photo grid with lazy loading
-   - Toggle between collages/individual photos
-   - Prominent expiration banner
-   - Download urgency indicators
-3. **Photo Lightbox**: Full-screen viewing with zoom
-4. **Mobile-First**: Responsive design with touch gestures
-5. **Personalization**: Dynamic theming per event type
-
-### User Experience Priorities
-- Clear expiration warnings (sticky banner)
-- One-click "Download All" for urgent galleries
-- Smooth image loading with skeleton screens
-- Intuitive navigation between photo categories
-- Professional presentation matching photographer branding
-
-## Key Architecture Patterns
-
-### Authentication Flow
-- JWT-based with separate tokens for admin and gallery access
-- Gallery tokens include event-specific claims
-- Auth middleware: `backend/src/middleware/auth.js`
-  - `adminAuth` - Admin panel protection
-  - `photoAuth` - Protected photo access  
-  - `verifyGalleryAccess` - Gallery-specific validation
-
-### Database Schema (Knex/SQLite)
-Main tables:
-- `events` - Gallery metadata with expiration, custom messages, themes
-- `photos` - Photo records linked to events
-- `access_logs` - IP-based usage tracking
-- `email_queue` - Async email processing
-- `admin_users` - Admin authentication
-
-### Service Architecture
-Background services run as separate processes:
-- **emailService**: Processes email queue with retry logic
-- **archiveService**: Creates ZIP archives of expired events
-- **expirationChecker**: Cron job for expiration warnings
-- **fileWatcher**: Monitors for new photo uploads
-- **backupService**: Scheduled backups with checksum-based change detection
-
-### API Structure
-- `/api/admin/*` - Admin panel endpoints (requires adminAuth)
-- `/api/gallery/*` - Public gallery endpoints  
-- `/api/auth/*` - Authentication endpoints
-- Rate limiting: 100 req/15min (general), 5 req/15min (auth)
-
-## Critical Implementation Notes
-
-1. **Security**: All gallery access requires valid JWT with event-specific claims
-2. **Expiration**: Events auto-expire based on `expires_at`, with 7-day email warnings
-3. **Email Queue**: Async processing with retry logic, check `email_queue` table
-4. **File Processing**: Sharp library for thumbnail generation (300x300)
-5. **Frontend Status**: Only skeleton exists - requires full implementation based on PRD
-6. **Umami Analytics**: Track password entries, downloads, views, expiration warnings
-
-## Troubleshooting Guidelines
-
-### Before ANY Production Troubleshooting:
-1. **ALWAYS request specific details**:
-   - Production server URL/IP
-   - Current error messages/logs
-   - Recent changes or deployments
-   - Affected users/galleries
-   - Time of issue occurrence
-
-2. **Thorough Analysis Required**:
-   - Use detailed thinking/analysis for EVERY troubleshooting task
-   - Review all related code before suggesting changes
-   - Consider all potential side effects
-   - Never make assumptions about production environment
-
-3. **Safe Troubleshooting Steps**:
-   - First, reproduce issue in local/dev environment
-   - Analyze logs without modifying production
-   - Create detailed action plan before any changes
-   - Always have rollback strategy ready
-   - Document every step taken
-
-### Common Issues & Safe Approaches:
-- **Email not sending**: Check email_queue table, SMTP settings, service status
-- **Photos not loading**: Verify file permissions, storage paths, nginx config
-- **Gallery access issues**: Check JWT tokens, expiration dates, access_logs
-- **Performance problems**: Analyze with monitoring tools first, never experiment
-
-### Data Safety Rules:
-- NEVER delete or modify production data without explicit backup confirmation
-- ALWAYS verify backups exist before any data operations
-- NO direct database modifications without transaction safety
-- Log all actions for audit trail
-
-## Environment Variables
-
-### Backend (.env)
-- `JWT_SECRET` - Token signing
-- `ADMIN_URL`, `FRONTEND_URL` - CORS origins
-- `SMTP_*` - Email configuration
-- `DB_*` - PostgreSQL credentials (production)
-- `UMAMI_URL` - Umami instance URL (for server-side tracking)
-- `UMAMI_WEBSITE_ID` - Website ID from Umami
-
-### Frontend (.env)
-- `VITE_API_URL` - Backend API URL
-- `VITE_UMAMI_URL` - Umami analytics URL
-- `VITE_UMAMI_WEBSITE_ID` - Website ID from Umami
-- `VITE_UMAMI_SHARE_URL` - (Optional) Public share URL for embedded dashboard
-
-## Testing Approach
-- Jest with Supertest for API testing
-- Test files in `__tests__` directories
-- Database migrations run before tests
-- Mock email sending in tests
-
-## Umami Analytics Integration
-
-The frontend includes comprehensive Umami analytics integration for tracking user behavior and gallery performance.
-
-### Tracked Events:
-- **Gallery Events**:
-  - `gallery_password_entry` - Password attempts (success/failure)
-  - `gallery_photo_view` - Individual photo views
-  - `gallery_photo_download` - Single photo downloads
-  - `gallery_bulk_download` - Bulk/all photo downloads
-  - `gallery_expired` - Expired gallery access attempts
-- **Admin Events**:
-  - `admin_login` - Admin authentication
-  - `admin_event_created` - New event creation
-  - `admin_event_archived` - Event archiving
-  - `admin_event_deleted` - Event deletion
-  - `admin_settings_updated` - Settings changes
-- **User Behavior**:
-  - Search queries (with debouncing)
-  - Expiration warning views
-  - Page views with automatic tracking
-
-### Setup:
-1. Install Umami (self-hosted or cloud)
-2. Create a website in Umami dashboard
-3. Set environment variables:
-   ```
-   VITE_UMAMI_URL=https://your-umami-instance.com
-   VITE_UMAMI_WEBSITE_ID=your-website-id
-   VITE_UMAMI_SHARE_URL=https://your-umami-instance.com/share/...
-   ```
-
-### Analytics Dashboard:
-- Admin panel includes analytics page at `/admin/analytics`
-- Summary view with key metrics
-- Option to embed full Umami dashboard
-- Real-time event tracking
-
-## Accessibility & Performance Features
-
-### Accessibility (WCAG 2.1 AA Compliance)
-- **Error Boundaries**: Graceful error handling with recovery options
-- **Skip Links**: Skip to main content for keyboard navigation
-- **ARIA Labels**: Proper labeling for screen readers
-- **Focus Management**: Focus trap in modals, visible focus indicators
-- **Keyboard Navigation**: Full keyboard support in gallery lightbox (arrows, escape, +/-, d for download)
-- **Loading States**: Skeleton screens instead of spinners for better UX
-- **Offline Support**: Visual indicator when offline
-- **Form Validation**: Accessible error messages with aria-describedby
-
-### Performance Optimizations
-- **Lazy Loading**: Images load on scroll with Intersection Observer
-- **Skeleton Screens**: Instant visual feedback during loading
-- **Error Recovery**: Component-level error boundaries prevent full page crashes
-- **Optimistic Updates**: Immediate UI updates with background sync
-- **Debounced Search**: Prevents excessive API calls
-- **Analytics**: Non-blocking Umami integration
-
-### Component Library Enhancements
-- `<ErrorBoundary>` - Catches and displays errors gracefully
-- `<PageErrorBoundary>` - Full-page error recovery
-- `<Skeleton>` - Flexible skeleton loader with variants
-- `<OfflineIndicator>` - Network status monitoring
-- `<SkipLink>` - Accessibility navigation
-- `useFocusTrap` - Modal focus management hook
-- `useOnlineStatus` - Network status hook
-
-## Theme System & Branding
-
-### Theme Features
-- **Dynamic Theming**: CSS variables for runtime theme switching
-- **Preset Themes**: Default, Wedding, Birthday, Corporate, Minimal
-- **Customization Options**:
-  - Primary/Accent/Background/Text colors
-  - Font family selection
-  - Border radius (none, sm, md, lg)
-  - Custom logo upload
-  - Custom CSS injection
-- **Event-Specific Themes**: Override global theme per gallery
-- **Live Preview**: Real-time theme changes in admin panel
-
-### Theme Context API
-```typescript
-const { theme, setTheme, setThemeByName } = useTheme();
-```
-
-### Branding Settings
-- Company name, tagline, and support email
-- Custom footer text
-- Optional watermarking on downloads
-- Logo upload for gallery header
-
-### CSS Variables
-```css
---color-primary: #5C8762;
---color-primary-light: #7aa583;
---color-primary-dark: #4a6f4f;
---color-accent: #22c55e;
---color-background: #fafafa;
---color-text: #171717;
---font-family: 'Inter', sans-serif;
---border-radius: 0.5rem;
-```
-
-## Backup Service
-
-### Overview
-The backup service provides automated, scheduled backups of all photo data with checksum-based change detection to minimize transfer overhead.
-
-### Features
-- **Multiple Destinations**: Local directory, remote server (rsync), S3-compatible storage
-- **Change Detection**: SHA256 checksums track file changes, only modified files are backed up
-- **Scheduled Execution**: Configurable cron-based scheduling (default: 2 AM daily)
-- **Email Notifications**: Alerts on backup failure, optional success notifications
-- **Retention Management**: Automatic cleanup of old backup runs based on retention policy
-- **Progress Tracking**: Database storage of backup history, file states, and statistics
-
-### Configuration
-Backup settings are stored in `app_settings` table with `backup_` prefix:
-- `backup_enabled`: Enable/disable the service
-- `backup_schedule`: Cron expression (e.g., '0 2 * * *')
-- `backup_destination_type`: 'local', 'rsync', or 's3'
-- `backup_retention_days`: How long to keep backup history
-- `backup_include_archived`: Whether to backup archived events
-- `backup_exclude_patterns`: File patterns to exclude
-
-### API Endpoints
-- `GET /api/admin/backup/config` - Get current configuration
-- `PUT /api/admin/backup/config` - Update configuration
-- `GET /api/admin/backup/status` - Get backup status and history
-- `POST /api/admin/backup/run` - Trigger manual backup
-- `POST /api/admin/backup/test-connection` - Test destination connectivity
-
-### Testing
-Run backup service test: `npm run test-backup`
-
-### Database Tables
-- `backup_runs`: Tracks each backup execution with statistics
-- `backup_file_states`: Stores file checksums for change detection
-
-## Thumbnail Generation
-
-### Square Thumbnail Implementation (Issue #12 Fix)
-The system now generates **square 300x300px thumbnails** to prevent blurry/stretched images in the gallery grid:
-
-- **Problem**: Previously generated 300px width with proportional height (e.g., 300x200 for 3:2 photos), but CSS forced square display causing distortion
-- **Solution**: Thumbnails now use `cover` fit mode to crop to exact 300x300px dimensions with center positioning
-- **Configuration**: Settings stored in `app_settings` table with keys: `thumbnail_width`, `thumbnail_height`, `thumbnail_fit`, `thumbnail_quality`, `thumbnail_format`
-- **Migration**: Run `040_add_thumbnail_settings.js` to add default square thumbnail settings
-- **Regeneration Script**: Use `scripts/regenerate-square-thumbnails.js` to update existing thumbnails
-
-### Thumbnail Settings API
-- `GET /api/admin/thumbnails/settings` - Get current thumbnail configuration
-- `PUT /api/admin/thumbnails/settings` - Update thumbnail settings (requires regeneration)
-- `POST /api/admin/thumbnails/regenerate` - Regenerate all thumbnails with new settings
-- `GET /api/admin/thumbnails/regenerate/status` - Check regeneration progress
-
-## Success Metrics (from PRD)
-- Time to generate gallery: <2 minutes
-- Guest satisfaction: >90%
-- System uptime: 99.9%
-- Email delivery rate: >98%
-- Successful archiving: 100%
-
-## Documentation & Development Practices
-
-### Documentation Guidelines:
-- **NEVER create new documentation files for simple tasks**
-- **ALWAYS update existing documentation (like this CLAUDE.md)**
-- Only create new .md files when explicitly requested
-- Avoid creating temporary scripts for one-off tasks
-
-### Development Best Practices:
-- Test all changes thoroughly in local environment first
-- Use version control for all changes
-- Keep commits atomic and well-described
-- Review impact on all integrated services
-- Consider backward compatibility
-- Update tests when changing functionality
-
-### Production Deployment Checklist:
-- [ ] All tests passing locally
-- [ ] Linting and type checks pass
-- [ ] Database migrations tested with rollback plan
-- [ ] Environment variables documented
-- [ ] Backup strategy confirmed
-- [ ] Monitoring alerts configured
-- [ ] Rollback procedure documented
-- [ ] Stakeholders notified of maintenance window
-- always use docker deployment for testing

CONTRIBUTING.md

@@ -38,7 +38,7 @@ Unsure where to begin? You can start by looking through these issues:
 
 ### Pull Requests
 
-1. **Fork the repo** and create your branch from `main`
+1. **Fork the repo** and create your branch from `beta`
 2. **Install dependencies**:
    ```bash
    cd backend && npm install
@@ -79,6 +79,15 @@ cp .env.example .env
 docker-compose -f docker-compose.dev.yml up
 ```
 
+**After pulling changes that touch `backend/package.json` / `backend/package-lock.json` (or the frontend equivalents)**, rebuild the affected image so the live-mounted source can `require()` the new deps:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d --build backend
+# (or `frontend`, or both)
+```
+
+The dev compose bakes `node_modules` into the image while live-mounting `./backend/src` and `./frontend/src` from disk. A dep added on disk won't be picked up until the image is rebuilt — typical symptom is a `MODULE_NOT_FOUND` restart loop on the affected container.
+
 ### Running Tests
 
 ```bash
@@ -146,10 +155,9 @@ picpeak/
 
 ## 🔄 Release Process
 
-1. Update version numbers in package.json files
-2. Update CHANGELOG.md
-3. Create a new release on GitHub
-4. Docker images are automatically built and published
+Releases are cut from the `beta` branch (rolling beta) and promoted to `main` (stable) on a 4–6 week cadence. `release-please` handles version bumps, changelog generation, and Docker image publication automatically — contributors don't update `package.json` or `CHANGELOG.md` by hand.
+
+See [RELEASING.md](RELEASING.md) for the full operational doc (promotion criteria, conflict-resolution checklist for the beta→main merge, hotfix backport path, versioning rules).
 
 ## 📮 Contact
 

DEPLOYMENT_GUIDE.md

@@ -1,819 +0,0 @@
-# 🚀 PicPeak Deployment Guide
-
-This guide covers multiple deployment options for PicPeak, from simple local setups to production-ready configurations.
-
-## 🎯 Quick Start - Simple Setup (Recommended for Beginners)
-
-For the easiest installation without Docker or complex configurations, use our **unified setup script**:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/setup.sh -o setup.sh && \
-chmod +x setup.sh && \
-sudo ./setup.sh
-```
-
-This automated script handles everything including:
-- Choice between Docker or Native installation
-- OS detection and dependency installation
-- Database setup and service configuration
-- SSL/HTTPS setup (optional)
-
-Perfect for:
-- Small to medium deployments
-- Local or VPS installations  
-- Users new to server management
-- Quick testing and evaluation
-
-👉 **See [SIMPLE_SETUP.md](./SIMPLE_SETUP.md) for detailed instructions.**
-
----
-
-## 🐳 Docker Compose Deployment
-
-### Option 1: Using Pre-built Images (Recommended)
-
-PicPeak provides official Docker images via GitHub Container Registry for quick deployment without building:
-
-```bash
-# Clone repository for configuration files
-git clone https://github.com/the-luap/picpeak.git
-cd picpeak
-
-# Copy and configure environment
-cp .env.example .env
-nano .env  # Edit with your values
-
-# Use pre-built images deployment
-docker compose -f docker-compose.production.yml up -d
-```
-
-The production compose file uses:
-- **Backend**: `ghcr.io/the-luap/picpeak/backend:latest`
-- **Frontend**: `ghcr.io/the-luap/picpeak/frontend:latest`
-
-Available tags:
-- `latest` - Latest stable release
-- `main` - Latest main branch build
-- `develop` - Development branch (may be unstable)
-- `v1.0.0` - Specific version tags
-
-### Option 2: Building from Source
-
-If you need to customize the application or the pre-built images aren't available, you can build locally:
-
-## 📋 Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Deployment](#deployment)
-- [First Login](#first-login)
-- [Reverse Proxy Setup](#reverse-proxy-setup)
-- [Maintenance](#maintenance)
-- [Troubleshooting](#troubleshooting)
- - [External Media Library](#external-media-library)
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- Domain name (for production)
-- SMTP server credentials for emails
-- At least 2GB RAM and 20GB storage
-
-## 🚀 Quick Start
-
-### Method 1: Using Pre-built Images (Fastest)
-
-1. **Clone the repository for configs**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Deploy using pre-built images**
-   ```bash
-   docker compose -f docker-compose.production.yml up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose -f docker-compose.production.yml logs -f
-   ```
-
-## External Media Library
-
-PicPeak can reference an existing, read‑only media library mounted into the backend container. This avoids copying originals into PicPeak storage.
-
-- Map your host library path to the container as read‑only in `docker-compose.production.yml`:
-  - Add volume under `backend`: `- ${EXTERNAL_MEDIA}:/external-media:ro`
-  - Add backend env: `EXTERNAL_MEDIA_ROOT=/external-media`
-- In `.env`, set:
-  - `EXTERNAL_MEDIA=/mnt/photos` (example host path)
-  - `EXTERNAL_MEDIA_ROOT=/external-media`
-
-Usage:
-- In Admin → Events, set “Source Mode” to “Reference (external folder)”, select a folder under `/external-media`, then import to index and generate thumbnails. Originals stay in your library.
-
-Backups and Archives:
-- Backups only include data under `STORAGE_PATH` and exclude external originals. The backup manifest includes `metadata.external_references = { excluded: true, events: N, photos: M }` and the Admin UI surfaces a warning.
-- Archiving reference events creates a manifest‑only ZIP and deletes thumbnails for that event. External originals are never moved or deleted.
-
-Local (npm) setup (no Docker):
-
-1. Create or choose a folder that contains your external originals, e.g. `/Users/you/Pictures/picpeak-external` (macOS/Linux) or `C:\\Pictures\\picpeak-external` (Windows).
-2. In `backend/.env` (or your shell), set:
-   - `EXTERNAL_MEDIA_ROOT=/absolute/path/to/picpeak-external`
-   - Ensure `STORAGE_PATH` points to your PicPeak storage (defaults to `./storage`).
-3. Start services from source:
-   - Backend: `cd backend && npm install && npm run migrate && JWT_SECRET=... npm start`
-   - Frontend: `cd frontend && npm install && npm run dev` (or build + serve)
-4. In Admin → Events:
-   - Create an event, set “Source Mode” to “Reference (external folder)”.
-   - Use the folder picker to browse under your `EXTERNAL_MEDIA_ROOT` and select the subfolder to reference.
-   - Click “Import from selected folder” to index files and generate thumbnails on demand.
-
-Notes:
-- PicPeak only reads from `EXTERNAL_MEDIA_ROOT`; it never modifies or deletes your originals there.
-- Thumbnails are generated under `STORAGE_PATH/thumbnails` and are included in backups; originals in `EXTERNAL_MEDIA_ROOT` are excluded.
-- On Windows, use absolute paths (e.g., `C:\\Photos\\Library`) for `EXTERNAL_MEDIA_ROOT`.
-
-### Method 2: Building from Source
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Build and deploy**
-   ```bash
-   docker compose build
-   docker compose up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose logs -f
-   ```
-
-## 🔧 Configuration
-
-### Essential Environment Variables
-
-Generate secure values:
-```bash
-# JWT Secret
-openssl rand -base64 64
-
-# Database Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-
-# Redis Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-```
-
-⚠️ **PASSWORD WARNING**: Docker Compose interprets `$` as variable substitution. Either:
-- Avoid `$` in passwords (recommended - use the commands above)
-- Escape `$` as `$$` (e.g., `Pass$$word` instead of `Pass$word`)
-- Quote the entire value: `DB_PASSWORD='Pass$word'` (less reliable)
-
-### Public Landing Page
-
-- `npm run migrate` now seeds three general settings: `general_public_site_enabled`, `general_public_site_html`, and `general_public_site_custom_css` so existing installs stay disabled by default.
-- Configure the feature from **Admin → CMS Pages**. The landing page panel exposes the toggle, HTML editor, optional CSS overrides, preview, and a reset-to-default action.
-- All HTML and CSS submitted through the UI is sanitized server-side. Scripts, inline event handlers, disallowed attributes, `@import` rules, and `javascript:` URLs are stripped before content is cached or rendered.
-- Resetting via the UI (or calling `POST /api/admin/settings/public-site/reset`) restores the bundled template and clears custom CSS.
-- The landing page response is cached in-memory. Override the default 60s cache window by setting `PUBLIC_SITE_CACHE_TTL_MS` (milliseconds) in your environment if you need faster cache busting.
-- When the toggle is off PicPeak continues to serve the SPA/login redirect at `/`, preserving legacy behaviour until you explicitly enable the feature.
-
-### Backend Configuration (.env)
-Update `.env` with:
-- `JWT_SECRET` - Authentication secret (REQUIRED - generate a secure random value)
-- `DB_PASSWORD` - PostgreSQL password
-- `REDIS_PASSWORD` - Redis password
-- `SMTP_*` - Email configuration
-- **URL Configuration** (for backend CORS):
-  - `FRONTEND_URL` - Frontend origin (use full URL with scheme, no trailing slash)
-    - Example (Docker): `http://localhost:3000`
-  - `ADMIN_URL` - Admin origin (same as `FRONTEND_URL` for Docker; full URL, no trailing slash)
-    - Example (Docker): `http://localhost:3000`
-  
-  Notes:
-  - Do not include trailing `/` (e.g., use `http://host:3000`, not `http://host:3000/`).
-  - Always include the scheme (`http://` or `https://`).
-  - The backend compares origins strictly for CORS; malformed values will cause login requests to fail with 500.
-
-#### External Database Example
-To use an external PostgreSQL instead of the bundled container, set the following in `.env` and ensure the `postgres` service is disabled or removed:
-
-```env
-DB_HOST=db.example.com
-DB_PORT=5432
-DB_USER=picpeak
-DB_PASSWORD=change_me
-DB_NAME=picpeak_prod
-```
-
-Compose uses these values via `env_file: .env`. The backend service also defaults `DB_HOST=${DB_HOST:-postgres}` so if you don’t set `DB_HOST` it will use the bundled `postgres` container.
-
-### Frontend Configuration (frontend/.env)
-Create `frontend/.env` from `frontend/.env.example`:
-```bash
-cp frontend/.env.example frontend/.env
-```
-
-Update `frontend/.env` with:
-- `VITE_API_URL` - Backend API URL
-  - Docker (pre-built images) and production behind reverse proxy: `/api` (recommended; avoids CORS and matches the frontend Nginx proxy in the image)
-  - Local dev (Vite): `http://localhost:3001` or `/api` if proxying through a dev proxy
-
-Note: When using pre-built frontend images, runtime container env does not change the already-built JS. Prefer the default `/api` and let the frontend Nginx proxy forward to the backend.
-
-⚠️ **IMPORTANT PORT CONFIGURATION**: 
-- The frontend runs on port **3000** in Docker (exposed via nginx)
-- The backend API runs on port **3001**
-- The frontend `.env` file MUST point to the correct backend port (3001)
-- Default `.env.example` is configured for Docker deployment
-
-### Email Configuration Examples
-
-#### Gmail
-```env
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-specific-password
-```
-
-#### SendGrid
-```env
-SMTP_HOST=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=apikey
-SMTP_PASS=your-sendgrid-api-key
-```
-
-## 📦 Deployment
-
-### Using Pre-built Images (Fastest)
-
-```bash
-# Pull latest images from GitHub Container Registry
-docker pull ghcr.io/the-luap/picpeak/backend:latest
-docker pull ghcr.io/the-luap/picpeak/frontend:latest
-
-# Start services using production compose file
-docker compose -f docker-compose.production.yml up -d
-
-# View running containers
-docker compose ps
-```
-
-### Building from Source (For Customization)
-
-```bash
-# Build images locally
-docker compose build
-
-# Or build with no cache for clean build
-docker compose build --no-cache
-
-# Start all services
-docker compose up -d
-
-# View running containers
-docker compose ps
-```
-
-### Access Points
-
-By default, services are exposed on:
-- Frontend (UI + Admin): http://localhost:3000 (admin at `/admin`)
-- Backend/API: http://localhost:3001 (API only; no UI routes)
-- PostgreSQL: localhost:5432 (if needed)
-- Redis: localhost:6379 (if needed)
-
-### Initial Admin Setup
-
-When deploying for the first time, an admin account is automatically created with a secure, randomly generated password. This password is displayed in the Docker logs during initialization and **must be changed** on first login.
-
-#### Finding the Auto-Generated Admin Password
-
-The admin password is automatically generated during the first startup and displayed in the backend container logs. Here's how to find it:
-
-**Option 1: Search Docker logs for admin password** (recommended)
-```bash
-# Find the auto-generated admin password in logs
-docker compose logs backend | grep "Admin password"
-```
-
-You should see output like:
-```
-✅ Admin password generated: BraveTiger6231!
-```
-
-**Option 2: View the complete initialization logs**
-```bash
-# View the complete admin setup logs
-docker compose logs backend | grep -A 10 "Admin user created"
-```
-
-**Option 3: Check the saved credentials file**
-```bash
-# The password is also saved in the backend container
-docker exec picpeak-backend cat data/ADMIN_CREDENTIALS.txt
-```
-
-**Option 4: Use the helper script**
-```bash
-# Show current admin username and email (password is hidden)
-docker exec picpeak-backend node scripts/show-admin-credentials.js
-
-# Reset the admin password to a new random password
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-```
-
-#### Important Security Notes
-
-- **Login requires the email address**, not username
-- The admin password is only displayed once during initial setup
-- **Password change is MANDATORY** on first login - the system will force you to change it
-- If you lose the password before first login, use the `--reset` option to generate a new one
-- New password requirements: minimum 12 characters, mixed case, numbers, and special characters
-
-## 🔐 First Login
-
-After deployment, you must complete the first login process which includes mandatory password change for security.
-
-### Step 1: Locate Your Admin Password
-
-1. **Find the auto-generated password** from the credentials file:
-   ```bash
-   # Docker deployment
-   docker compose exec backend cat /app/data/ADMIN_CREDENTIALS.txt
-   
-   # Or directly from the host (if you have access)
-   cat data/ADMIN_CREDENTIALS.txt
-   ```
-
-2. **Note the admin email** (default: `admin@example.com` unless customized)
-
-### Step 2: Access Admin Panel
-
-1. Navigate to your frontend domain and open the admin section:
-   - `http://your-domain.com/admin` (behind reverse proxy)
-   - `http://localhost:3000/admin` (Docker local)
-   
-   The backend at `:3001` serves API only and does not serve the admin UI.
-2. Login using:
-   - **Email**: `admin@example.com` (or your custom admin email)
-   - **Password**: The auto-generated password from the logs
-
-### Step 3: Mandatory Password Change
-
-Upon first login, the system will **automatically redirect** you to change your password:
-
-1. **You cannot skip this step** - it's enforced for security
-2. Enter the current auto-generated password
-3. Create a new secure password meeting these requirements:
-   - Minimum 12 characters
-   - At least one uppercase letter
-   - At least one lowercase letter
-   - At least one number
-   - At least one special character (!@#$%^&*)
-
-### Security Best Practices for New Password
-
-- **Use a unique password** not used elsewhere
-- **Consider a password manager** for generation and storage
-- **Include mixed characters**: `MySecureP@ssw0rd2024!`
-- **Avoid personal information** (names, dates, etc.)
-- **Save securely** - you cannot recover this password easily
-
-### If You Lose Access
-
-If you lose your admin credentials after the first login, you'll need to manually reset the password in the database or create a new admin user through the database.
-
-**Note**: The credentials file (`ADMIN_CREDENTIALS.txt`) is only created during initial deployment and contains the first admin password. After changing the password, this file becomes outdated but is kept for reference. If you need to regenerate the password and file during a reinstall, re-run the installer with the `--force-admin-password-reset` flag:
-
-```bash
-# Native reinstall example
-sudo ./setup.sh --native --force-admin-password-reset
-
-# Docker reinstall example
-sudo ./setup.sh --docker --force-admin-password-reset
-```
-
-The flag calls `scripts/reset-admin-password.js` in non-interactive mode, writes a fresh random password into `data/ADMIN_CREDENTIALS.txt`, and prints the new credentials at the end of the installer run.
-
-#### Configuring Admin Email
-
-By default, the admin email is `admin@example.com`. To use a different email address, set it in your `.env` file before first deployment:
-
-```env
-# .env
-ADMIN_EMAIL=your-email@yourdomain.com
-```
-
-**Note**: This only works on first deployment. To change the admin email after deployment, you'll need to update it in the database or create a new admin user through the admin panel.
-
-## 🔒 Reverse Proxy Setup
-
-For production deployments, you should use a reverse proxy for SSL/HTTPS. The application exposes ports directly, allowing you to use any reverse proxy solution.
-
-### Option 1: Nginx
-
-Install nginx and create `/etc/nginx/sites-available/picpeak`:
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    return 301 https://$server_name$request_uri;
-}
-
-server {
-    listen 443 ssl http2;
-    server_name your-domain.com;
-
-    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
-
-    # Frontend
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Frontend (serves UI and /admin/*)
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Backend API and protected resources
-    location /api {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-    location ~ ^/(photos|thumbnails|uploads) {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-Enable the site:
-```bash
-sudo ln -s /etc/nginx/sites-available/picpeak /etc/nginx/sites-enabled/
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-### Option 2: Traefik
-
-Add labels to `docker-compose.override.yml`:
-
-```yaml
-version: '3.8'
-
-services:
-  frontend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak.rule=Host(`your-domain.com`)"
-      - "traefik.http.routers.picpeak.entrypoints=websecure"
-      - "traefik.http.routers.picpeak.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak.loadbalancer.server.port=80"
-
-  backend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak-api.rule=Host(`your-domain.com`) && PathPrefix(`/api`)"
-      - "traefik.http.routers.picpeak-api.entrypoints=websecure"
-      - "traefik.http.routers.picpeak-api.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak-api.loadbalancer.server.port=3001"
-```
-
-### Option 3: Caddy
-
-Create a `Caddyfile`:
-
-```caddyfile
-your-domain.com {
-    # Frontend
-    handle /* {
-        reverse_proxy localhost:3000
-    }
-
-    # Backend API and admin
-    handle /api/* {
-        reverse_proxy localhost:3001
-    }
-    
-    handle /admin/* {
-        reverse_proxy localhost:3001
-    }
-
-    # Protected resources
-    handle /photos/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /thumbnails/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /uploads/* {
-        reverse_proxy localhost:3001
-    }
-}
-```
-
-### SSL Certificates
-
-For any reverse proxy, you can use Let's Encrypt:
-
-```bash
-# With Certbot
-sudo certbot certonly --webroot -w /var/www/certbot -d your-domain.com
-
-# Or use your reverse proxy's built-in ACME support
-```
-
-## 🔧 Maintenance
-
-### Viewing Logs
-
-```bash
-# All services
-docker compose logs -f
-
-# Specific service
-docker compose logs -f backend
-docker compose logs -f frontend
-```
-
-### Backup
-
-#### Manual Backup
-```bash
-# Database backup
-docker exec picpeak-postgres pg_dump -U picpeak picpeak_prod > backup/db_$(date +%Y%m%d_%H%M%S).sql
-
-# Files backup
-tar -czf backup/photos_$(date +%Y%m%d_%H%M%S).tar.gz events/
-```
-
-#### Automated Backup
-The application includes a built-in backup service. Configure it in the admin panel:
-1. Login to admin panel
-2. Go to Settings → Backup
-3. Configure destination and schedule
-4. Enable backup service
-
-### Updates
-
-#### Method 1: Using Pre-built Images (Recommended)
-
-```bash
-# Pull latest changes (for configuration updates)
-git pull
-
-# Pull latest images from GitHub Container Registry
-docker compose -f docker-compose.production.yml pull
-
-# Restart with new images
-docker compose -f docker-compose.production.yml down
-docker compose -f docker-compose.production.yml up -d
-
-# Verify services are healthy
-docker compose -f docker-compose.production.yml ps
-```
-
-#### Method 2: Building from Source
-
-```bash
-# Pull latest changes
-git pull
-
-# Rebuild and restart
-docker compose down
-docker compose build --no-cache
-docker compose up -d
-
-# Verify services are healthy
-docker compose ps
-```
-
-#### Specific Version Updates
-
-To use a specific version of the images:
-
-```bash
-# Edit docker-compose.production.yml to specify version tags
-# Change: ghcr.io/the-luap/picpeak/backend:latest
-# To:     ghcr.io/the-luap/picpeak/backend:v1.0.0
-
-# Then pull and restart
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
-
-### Database Migrations
-
-Migrations run automatically on startup, but you can run them manually:
-
-```bash
-docker exec picpeak-backend npm run migrate
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-#### 502 Bad Gateway / Login Failures
-**This is the most common deployment issue!** Usually caused by misconfigured URLs or network problems:
-
-1. **CORS Configuration Errors**:
-   ```bash
-   # WRONG - Missing port will cause CORS errors
-   FRONTEND_URL=http://10.0.252.12
-   
-   # CORRECT - Include the port you're accessing from
-   FRONTEND_URL=http://10.0.252.12:3000
-   ```
-   
-   The backend validates Origin headers against `FRONTEND_URL` for CORS. If they don't match exactly, you'll get 500 errors on login.
-
-2. **After Container Restarts**:
-   - Nginx may have cached old container IPs
-   - Solution: `docker restart picpeak-frontend`
-   - Always wait 30-60 seconds for health checks
-
-3. **Backend Not Starting After Migrations**:
-   - The logs may only show migrations completed
-   - Check if server is actually running: `docker exec picpeak-backend ps aux | grep node`
-   - Should see `node server.js` process
-
-4. **Login After Fresh Install**:
-   - Check backend logs for auto-generated admin password: `docker compose logs backend | grep "Admin password"`
-   - Email: `admin@example.com` (or your custom admin email from .env)
-   - Password: Auto-generated and shown in logs (e.g., `BraveTiger6231!`)
-   - Remember: Password MUST be changed on first login
-
-5. **Complete Fix Sequence**:
-   ```bash
-   # 1. Fix your .env file URLs
-   # 2. Full restart
-   docker-compose down
-   docker-compose up -d
-   
-   # 3. Wait for healthy status
-   sleep 60
-   docker ps  # All should show (healthy)
-   
-   # 4. Test backend directly
-   curl http://localhost:3001/health
-   
-   # 5. Test through frontend
-   curl http://localhost:3000/api/public/settings
-   ```
-
-#### Port Already in Use
-```bash
-# Check what's using the port
-sudo lsof -i :3000
-sudo lsof -i :3001
-
-# Change ports in .env
-FRONTEND_PORT=3002
-BACKEND_PORT=3003
-```
-
-#### Docker Compose Variable Substitution Errors
-If you see warnings like:
-```
-WARN[0000] The "fgbf" variable is not set. Defaulting to a blank string.
-```
-
-This means your password contains `$` which Docker Compose interprets as a variable. Solutions:
-1. **Best**: Generate passwords without `$`: `openssl rand -base64 32 | tr -d '$'`
-2. **Alternative**: Escape `$` as `$$` in your .env file
-3. **Example**: `DB_PASSWORD=Pass@#$$fgbf` instead of `DB_PASSWORD=Pass@#$fgbf`
-
-#### Permission Errors
-```bash
-# Fix ownership
-sudo chown -R 1000:1000 events data logs backup storage
-chmod -R 755 events data logs backup storage
-```
-
-#### Database Connection Issues
-```bash
-# Check if database is running
-docker compose ps
-docker compose logs postgres
-
-# Test connection
-docker exec picpeak-postgres pg_isready
-```
-
-#### Email Not Sending
-- Verify SMTP settings in .env
-- Check email queue: `docker exec picpeak-backend psql -U picpeak -d picpeak_prod -c "SELECT * FROM email_queue ORDER BY created_at DESC LIMIT 10;"`
-- For Gmail, use app-specific password
-- Check logs: `docker compose logs backend | grep email`
-
-### Health Checks
-
-```bash
-# Backend health
-curl http://localhost:3001/api/health
-
-# Frontend health
-curl http://localhost:3000
-
-# Database health
-docker exec picpeak-postgres pg_isready
-```
-
-### Useful Commands
-
-```bash
-# Enter backend container
-docker exec -it picpeak-backend sh
-
-# Enter database
-docker exec -it picpeak-postgres psql -U picpeak picpeak_prod
-
-# Reset admin password
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-
-# Check disk usage
-df -h
-du -sh events/ storage/ backup/
-
-# View running processes
-docker compose top
-```
-
-## Security Recommendations
-
-1. **Use HTTPS**: Always use a reverse proxy with SSL in production
-2. **Firewall**: Only expose necessary ports (80, 443)
-3. **Secure passwords**: Use strong, unique passwords for all services
-4. **Regular updates**: Keep Docker images and system packages updated
-5. **Backup strategy**: Set up automated backups and test restoration
-6. **Monitor logs**: Regularly check logs for suspicious activity
-7. **Rate limiting**: The app includes built-in rate limiting, configure as needed
-
-## Support
-
-For issues and questions:
-- Check logs first: `docker compose logs`
-- Review documentation in the repository
-- Check existing issues on GitHub
-- Create a new issue with:
-  - Error messages
-  - Log output
-  - Environment details (without secrets)
-  - Steps to reproduce

README.md

@@ -7,12 +7,28 @@
   [![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/)
   [![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)
   [![React](https://img.shields.io/badge/react-%2320232a.svg?style=flat&logo=react&logoColor=%2361DAFB)](https://reactjs.org/)
+  [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-theluap-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/theluap)
+
+  [Homepage](https://www.picpeak.app) · [Live Demo](https://demo.picpeak.app) · [Documentation](https://docs.picpeak.app) · [Support the project ☕](https://buymeacoffee.com/theluap)
 </div>
 
 **PicPeak** is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Designed specifically for photographers and event organizers, PicPeak makes it simple to share beautiful, time-limited photo galleries with clients while maintaining full control over your data and branding.
 
 ![PicPeak Gallery Preview](docs/screenshot-gallery.png)
 
+## 🎮 Live Demo
+
+Try PicPeak without installing anything:
+
+| | |
+|---|---|
+| **Demo URL** | [demo.picpeak.app](https://demo.picpeak.app) |
+| **Admin Panel** | [demo.picpeak.app/admin](https://demo.picpeak.app/admin) |
+| **Email** | `demo@picpeak.app` |
+| **Password** | `Demo2026!` |
+
+> The demo resets periodically. Uploaded content may be removed without notice.
+
 ## 🌟 Why Choose PicPeak?
 
 Unlike expensive SaaS solutions, PicPeak gives you:
@@ -68,23 +84,74 @@ cp .env.example .env
 nano .env
 
 # Start with Docker Compose
-docker-compose up -d
+docker compose up -d
 
-# Access at http://localhost:3005
+# Access at http://localhost:3000
 ```
 
-Note on Docker file permissions (PUID/PGID)
-- When using bind mounts (e.g., `./storage`, `./data`, `./logs`, `./events`), ensure the container user can write to these host folders. The backend runs as a non‑root user by default.
-- Set `PUID` and `PGID` in your `.env` to match your host user’s UID/GID (run `id -u` and `id -g` on the host). Compose maps the container user to these values.
-- Example in `.env`:
-  - `PUID=1000`
-  - `PGID=1000`
-- Without this, creating events, uploads, thumbnails, or logs can fail with “Permission denied”.
+Note on Docker file permissions
+- The backend container starts as root, chowns bind-mounted host directories (`./storage`, `./data`, `./logs`) to UID 1001 (`nodejs`), then drops privileges via `su-exec` before running the app. No host-side setup needed for fresh installs.
+- If you pin `user:` in a compose override (e.g. to map a specific host UID), the self-chown is skipped and you must pre-chown the host directories to that UID — see [docs.picpeak.app/deployment/docker#permissions](https://docs.picpeak.app/deployment/docker#permissions).
+
+**ARM64 (aarch64) systems:** Pre-built images include native `linux/arm64`, no platform flags or emulation needed. If you're on an older image tag that's still amd64-only, see [docker-compose.amd64.override.yml](docker-compose.amd64.override.yml) for a transitional fallback.
+
+## 🔄 Release Channels
+
+PicPeak offers two release channels for different needs. Stable promotions are cut from a known-good beta point every 4–6 weeks — see [RELEASING.md](RELEASING.md) for the maintainer's promotion criteria and cadence policy.
+
+### Stable Channel (Recommended)
+- Production-ready releases
+- Thoroughly tested before release
+- Docker tags: `stable`, `latest`, or specific version like `v2.3.0`
+
+### Beta Channel
+- Early access to new features
+- May contain bugs or incomplete functionality
+- Docker tags: `beta` or specific version like `v2.3.0-beta.1`
+
+### Switching Channels
+
+Set the `PICPEAK_CHANNEL` environment variable in your `.env` file:
+
+```bash
+# For stable releases (default)
+PICPEAK_CHANNEL=stable
+
+# For beta releases
+PICPEAK_CHANNEL=beta
+
+# For a specific version
+PICPEAK_CHANNEL=v2.3.0
+```
+
+Then update your containers:
+
+```bash
+docker compose -f docker-compose.production.yml pull
+docker compose -f docker-compose.production.yml up -d
+```
+
+### Update Notifications
+
+The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:
+
+```bash
+UPDATE_CHECK_ENABLED=false
+```
 
 ## 📖 Documentation
 
-- 📘 [**Deployment Guide**](DEPLOYMENT_GUIDE.md) - Detailed installation instructions
-  - Includes the new [External Media Library](DEPLOYMENT_GUIDE.md#external-media-library) reference mode
+Full documentation lives at **[docs.picpeak.app](https://docs.picpeak.app)** — deployment, admin settings reference, API docs, webhooks, archive lifecycle, branding, and everything else. Some quick links:
+
+- 🚀 [**Deployment**](https://docs.picpeak.app/deployment) - Docker, environment variables, reverse proxy, SSL
+- ⚙️ [**Admin Settings**](https://docs.picpeak.app/guides/admin-settings) - Every tab in the Settings panel
+- 🎯 [**Creating Events**](https://docs.picpeak.app/guides/creating-events) - Full event field reference
+- 💾 [**Backup & Restore**](https://docs.picpeak.app/guides/backup-restore) - Backup configuration, restore wizard, full disaster recovery
+- 🔌 [**API Reference**](https://docs.picpeak.app/api) - REST endpoints, OpenAPI spec, webhooks
+- 🪝 [**Webhooks**](https://docs.picpeak.app/features/webhooks) - Event payloads, signing, filters, templates
+
+Project meta:
+
 - 🤝 [**Contributing**](CONTRIBUTING.md) - How to contribute
 - 📜 [**License**](LICENSE) - MIT License
 - 🔒 [**Security**](SECURITY.md) - Security policies
@@ -115,10 +182,111 @@ Perfect for:
 
 - **Backend**: Node.js, Express, SQLite/PostgreSQL
 - **Frontend**: React, Tailwind CSS, Framer Motion
-- **Storage**: File-based with automatic archiving
+- **Storage**: Local filesystem (default) or S3-compatible object store (AWS S3, MinIO, R2, B2, Wasabi, Spaces) — see [Storage Backends](#storage-backends)
 - **Email**: SMTP with customizable templates
 - **Analytics**: Privacy-focused with Umami integration
 
+## 💾 Storage Backends
+
+PicPeak supports two storage backends for photos, thumbnails, hero images, watermarks, and archive zips. Both are configured via environment variables; no code change is required to switch.
+
+| Capability | `STORAGE_BACKEND=local` (default) | `STORAGE_BACKEND=s3` |
+|---|---|---|
+| Photo / thumbnail / hero storage | Local filesystem under `STORAGE_PATH` | Bucket on any S3-compatible service |
+| Admin UI upload | ✅ | ✅ |
+| Filesystem auto-import (chokidar watcher) | ✅ | ❌ — disabled (use the upload API) |
+| Watermarks, fingerprinting, fragmentation | ✅ | ✅ (materialized to a tmp file just-in-time) |
+| Bulk download zips (cached + on-the-fly) | ✅ | ✅ |
+| Backups | ✅ | ✅ |
+| External media reference mode (`EXTERNAL_MEDIA_ROOT`) | ✅ (always local) | ✅ (still local — not migrated) |
+
+### Switching to an S3-compatible backend
+
+1. Provision a bucket and credentials. The minimum IAM policy is documented in `.env.example`.
+2. Set `STORAGE_BACKEND=s3` plus `STORAGE_S3_BUCKET`, `STORAGE_S3_REGION`, `STORAGE_S3_ACCESS_KEY`, `STORAGE_S3_SECRET_KEY`. For non-AWS providers (MinIO, R2, B2, …) also set `STORAGE_S3_ENDPOINT`.
+3. If you have existing local content, copy it first: `node backend/scripts/migrate-storage.js --dry-run` then `node backend/scripts/migrate-storage.js`. The script is idempotent and writes a failures CSV.
+4. Restart the backend. The startup check pings the bucket and refuses to boot on misconfig.
+
+Note: presigned-URL serving (zero-bandwidth direct downloads from S3) is intentionally **not** in v1 — every request still streams through the backend so watermarks, devtools-detection, and access logging keep working.
+
+## 🔔 Webhooks
+
+PicPeak POSTs event/photo lifecycle notifications to URLs you configure under **Settings → Webhooks**. Each delivery is signed `HMAC-SHA256` with a per-webhook secret in the `X-PicPeak-Signature` header so receivers can verify the request really came from your PicPeak instance.
+
+### Event types
+
+| Event | Fires when |
+|---|---|
+| `event.created` | Gallery created (admin or API) |
+| `event.published` | Draft becomes live (`is_draft: true → false`) — also fires when an event is created with `is_draft=false` |
+| `event.archived` | Bulk-archive, manual archive, or auto-archive on expiry |
+| `event.expired` | Expiration checker marks the gallery inactive (fires before `event.archived` in the cascade) |
+| `photo.uploaded` | Admin upload, API upload, guest upload, or auto-import |
+| `photo.deleted` | Single delete, bulk delete (NOT fired per-photo when an event is archived — receivers infer from `event.archived` to avoid flooding) |
+
+### Payload shape
+
+```json
+{
+  "id": "delivery-uuid",
+  "type": "event.published",
+  "created_at": "2026-04-28T05:25:00.000Z",
+  "data": {
+    "event": { "id": 123, "slug": "wedding-smith", "share_url": "https://..." }
+  }
+}
+```
+
+Also sent on every request:
+- `X-PicPeak-Signature` — `HMAC-SHA256(secret, raw_body)` as hex
+- `X-PicPeak-Event` — the event type (handy for routing without parsing the body)
+- `X-PicPeak-Delivery` — UUID for idempotency on the receiver side
+- `User-Agent: PicPeak-Webhooks/1.0`
+
+### Verifying signatures
+
+**Node.js**
+```js
+const crypto = require('crypto');
+function verify(secret, rawBody, signature) {
+  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  const a = Buffer.from(expected, 'hex');
+  const b = Buffer.from(signature, 'hex');
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+```
+
+**Python**
+```python
+import hmac, hashlib
+def verify(secret: str, raw_body: bytes, signature: str) -> bool:
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+```
+
+**curl + openssl** (one-liner for a quick replay)
+```sh
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
+[ "$SIG" = "$RECEIVED_SIG" ] && echo OK || echo MISMATCH
+```
+
+### Retries + observability
+
+- `2xx` → success, recorded with latency
+- Non-`2xx` or network error → exponential backoff: `1m → 5m → 30m → 2h → 12h`, max 5 attempts
+- After max attempts: status `failed`, surfaces in **Settings → Webhooks → Deliveries** with a "Replay" button
+- Up to 5 deliveries in flight at once; one slow consumer can't block others (configurable via `WEBHOOK_DELIVERY_CONCURRENCY`)
+- Response body truncated to 1KB before storage so chatty receivers don't bloat the audit log
+
+The deliveries page (`/admin/webhooks/:id/deliveries`) shows every attempt with timestamp, status, HTTP code, latency, payload sent, signature, and response. Click "Send test event" to fire a synthetic delivery for any event type.
+
+### SSRF protection
+
+Webhook URLs are validated against the same private-IP blocklist used elsewhere in the app — loopback, private RFC1918 ranges, link-local, `.local`/`.internal` hostnames, cloud metadata endpoints. The check runs both at create time and per-delivery (DNS-rebinding mitigation).
+
+For local development with a receiver on the same machine or docker network, set `WEBHOOK_ALLOW_PRIVATE_URLS=true`. Production deployments must leave this OFF.
+
 ## 💻 System Requirements
 
 ### Minimum Requirements
@@ -133,6 +301,31 @@ Perfect for:
 - **Docker**: v20.10.0+
 - **Docker Compose**: v2.0.0+
 
+### Video Support Requirements
+When enabling video uploads, consider these additional resources:
+
+| Resource | Recommendation | Notes |
+|----------|----------------|-------|
+| **RAM** | 4GB+ recommended | FFmpeg processing requires more memory |
+| **Storage** | Plan for 10-100x more | Videos are significantly larger than images |
+| **CPU** | Additional cores help | Video thumbnail extraction is CPU-intensive |
+| **Bandwidth** | Higher throughput | Video streaming requires more bandwidth |
+
+**Technical Notes:**
+- FFmpeg is bundled via npm (`@ffmpeg-installer/ffmpeg`) - no system installation required
+- Maximum upload size: **10GB per video file**
+- Chunked upload support for files >100MB (resumable uploads)
+- Supported formats: MP4, WebM, MOV, AVI
+- Video thumbnails are automatically generated from the first few seconds
+
+**For Nginx/Reverse Proxy:**
+If using Nginx, increase the client max body size:
+```nginx
+client_max_body_size 10G;
+proxy_read_timeout 3600;
+proxy_send_timeout 3600;
+```
+
 ## 🤝 Contributing
 
 We love contributions! PicPeak is built by photographers, for photographers. Whether you're fixing bugs, adding features, or improving documentation, your help is welcome.
@@ -208,7 +401,7 @@ These features are currently in beta testing and may have limited functionality
 
 | Feature | Description | Status |
 |---------|-------------|--------|
-| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, and right-click prevention to protect your photos from unauthorized downloads | 🧪 Beta |
+| **CRM Module** | Quotes, contracts, invoices, hours logging, calendar, and tax report — feature-flagged off by default. Seeded contract blocks, payment terms, and IBAN / tax defaults are **examples only** and need legal / financial review before customer-facing use. See [docs.picpeak.app/features/crm](https://docs.picpeak.app/features/crm). | 🧪 Beta |
 | **Simple Deployment Script** | One-click deployment script for quick server setup with automated configuration and dependency installation | 🧪 Beta |
 
 ### 📋 Future Enhancements
@@ -217,19 +410,41 @@ These features are currently in beta testing and may have limited functionality
 |---------|-------------|----------|---------|
 | **Backup & Restore** | Comprehensive backup system with S3/MinIO support, automated scheduling, and safe restore functionality | High | ✅ Implemented |
 | **External Media Library (Reference Mode)** | Use an external folder library as a read‑only source with import and on‑demand thumbnail generation | High | ✅ Implemented |
-| **Gallery Templates** | Additional gallery layouts and themes (masonry, slideshow, story-style) for different event types | Medium | 🔄 Open |
+| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, right-click prevention, and DevTools detection to protect photos from unauthorized downloads | High | ✅ Implemented |
+| **Gallery Templates** | Multiple gallery layouts (grid, masonry, carousel, timeline, hero, mosaic) with custom CSS styling support. Includes starter templates like Apple Liquid Glass for complete visual customization | Medium | ✅ Implemented |
 | **Face Recognition** | AI-powered face detection to help guests find their photos and create automatic person-based albums | Low | 🔄 Open |
 | **Gallery Feedback** | Allow guests to like, rate, and comment on photos with admin notifications and moderation | Medium | ✅ Implemented |
-| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | 🔄 Open |
-| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | 📋 Planned |
-| **Filtering & Export Options** | Add filters to show only rated, liked, or marked photos and export filtered selections for Capture One or Lightroom workflows | Low | 🔄 Open |
+| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | ✅ Implemented |
+| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | ✅ Implemented |
+| **Filtering & Export Options** | Filter photos by likes, ratings, comments, or favorites. Search by filename. Sort by date, name, size, or rating. Export filtered selections as ZIP or generate Capture One/Lightroom-compatible file lists for professional workflows | Medium | ✅ Implemented |
 
 **Status Legend:** ✅ Implemented | 🚧 In Progress | 🔄 Open | 📋 Planned
 
+## ☕ Support the Project
+
+PicPeak is free, open source, and self-hostable forever. If it saves you time or replaces a paid subscription, consider buying me a coffee — it directly funds the time spent on new features, bug fixes, and keeping the demo + docs running.
+
+<p align="left">
+  <a href="https://buymeacoffee.com/theluap" target="_blank">
+    <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=theluap&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" alt="Buy Me A Coffee" />
+  </a>
+</p>
+
+Other ways to support without spending anything: ⭐ star the repo, share it with photographer friends, file good bug reports, or open a PR.
+
 ## 🙏 Acknowledgments
 
 PicPeak is inspired by the best features of commercial platforms while remaining completely open source. Special thanks to all contributors who make this project possible.
 
+### 👥 Contributors
+
+A huge thank you to the people whose code, reports, and feedback have shaped PicPeak:
+
+- [**@Luca-Timo**](https://github.com/Luca-Timo) — native Apple Silicon multi-arch images, external-URL toggle for legal CMS pages, the lazy-loaded folder tree picker, the admin-email picker on event creation, the data-driven self-hosted webfont system, the gallery header/banner decoupling, and several typed-API refactors. Consistently raises the bar with thoughtful PRs.
+- [**@Rekoo-PS**](https://github.com/Rekoo-PS) — sharp-eyed bug reporter and product feedback. Filed the issues that drove the login-loop fix, the gallery-loading skeleton work, the redirection cleanup, the mobile-lightbox overhaul, the admin-events search-counter fix, the photo-count column, and the bulk-delete workflow. Also a [BuyMeACoffee](https://buymeacoffee.com/theluap) supporter — the kind of feedback loop that keeps the project useful for real deployments.
+
+If you've contributed and aren't listed here, please open a PR — this list is meant to grow.
+
 ### 🤖 AI-Assisted Development
 
 This project was generated with the assistance of AI technology, but has been:
@@ -240,6 +455,23 @@ This project was generated with the assistance of AI technology, but has been:
 
 We believe in transparent development practices and the responsible use of AI as a tool to accelerate development while maintaining high standards of quality and security.
 
+## ⚠️ CRM disclaimers — examples only
+
+The CRM module (contracts, invoices, QR-bills) ships seeded content
+that is intended as a **starting point only**:
+
+- **Contract blocks** (image rights, NDA, model release, cancellation,
+  jurisdiction, …) are written by the maintainer, **not by a lawyer**.
+  Every operator must have their lawyer review and adapt them before
+  sending any contract to a customer.
+- **QR-bills and SEPA EPC payloads** are rendered from the data you
+  typed. Picpeak is open source — please scan a test invoice with your
+  bank's app to check the QR actually works. We are not responsible for
+  any mistakes that come from sending an invoice with bad data on it.
+
+Read [`docs/crm-disclaimers.md`](docs/crm-disclaimers.md) before
+enabling the Contracts or Invoices features.
+
 ## 📄 License
 
 PicPeak is released under the [MIT License](LICENSE). Use it freely for personal or commercial projects.
@@ -247,7 +479,7 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 ## 🚀 Ready to Get Started?
 
 1. ⭐ **Star this repository** to show your support
-2. 📖 Read the [Deployment Guide](DEPLOYMENT_GUIDE.md)
+2. 📖 Read the [docs at docs.picpeak.app](https://docs.picpeak.app)
 3. 🐛 Report issues or request features
 4. 🤝 Join our community and contribute!
 
@@ -256,7 +488,9 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 <p align="center">
   Made with ❤️ by photographers, for photographers
   <br>
+  <a href="https://www.picpeak.app">Homepage</a> •
+  <a href="https://demo.picpeak.app">Live Demo</a> •
   <a href="https://github.com/the-luap/picpeak">GitHub</a> •
-  <a href="DEPLOYMENT_GUIDE.md">Documentation</a> •
+  <a href="https://docs.picpeak.app">Documentation</a> •
   <a href="https://github.com/the-luap/picpeak/issues">Support</a>
 </p>

RELEASING.md

@@ -0,0 +1,92 @@
+# Release Process
+
+This document describes how PicPeak releases are cut. It's the maintainer's reference, not user documentation — for the user-facing channel choice (stable vs beta) see the [Release Channels section in README.md](README.md#-release-channels).
+
+## TL;DR
+
+- **`beta` branch** receives all merged work. Every push triggers a `release-please` PR that proposes the next `vX.Y.Z-beta.N` release. Merging that PR tags the beta and publishes Docker images on the `beta` tag.
+- **`main` branch** holds the stable channel. Stable releases are cut from a known-good `beta` point via a `release/X.Y.Z-merge-from-beta` branch and a manual PR to `main`. Merging that PR triggers `release-please` to propose the stable release.
+- Target cadence: **a stable release every 4–6 weeks**, or sooner if a beta has been quiet and ready for promotion.
+
+## Cadence target
+
+4–6 weeks between stable releases is the working target. Reasoning:
+
+- Long enough that each stable carries meaningful changes worth the upgrade burden.
+- Short enough that beta users aren't carrying the "real" project alone for months — the stable channel should actually be usable as the recommended channel for new installs.
+- Aligns with how release-please surfaces beta releases (multiple beta points usually accumulate inside a 4–6 week window, which gives natural promotion candidates).
+
+This is a target, not a hard rule. Cut sooner if a beta has been quiet and stable longer than usual. Cut later if a beta is in flux for security or migration reasons.
+
+## Promotion criteria
+
+A beta is eligible for promotion to stable when **all** of the following hold:
+
+1. **CI green on the candidate beta tip.** Specifically: `schema-drift` (`upgrade-from-bootstrap`), `fresh-install`, `Tests` (backend Jest + frontend Vitest), the four `Build and Push Docker Images` arch matrices, and `GitGuardian Security Checks`.
+2. **No open `bug`-labelled issues against the candidate beta for at least 7 days.** Issues fixed-but-not-yet-closed count as fixed; verify their PR is in the candidate beta before closing them out.
+3. **An upgrade walk has been done on real production-shaped data** — apply the candidate's migration chain to a snapshot of the previous stable's DB and verify no manual intervention is required. CI proves fresh-install works; the upgrade walk is what proves the upgrade path works.
+4. **Operator-time smoke** on the candidate: log in, create event, upload photos, share gallery, open as a customer, log out. Catches binary-incompatibility regressions and UI-level breaks that unit tests don't see.
+
+If any of the four fail, the promotion waits. File any blockers as `bug`-labelled issues and let them bake on beta before re-evaluating.
+
+## How a stable release is cut
+
+The actual mechanics, in order:
+
+1. **Pick the beta tip.** Confirm it satisfies the four promotion criteria above. Note the exact SHA — that's what you're promoting.
+
+2. **Create the release branch from the beta tip.**
+   ```bash
+   git push origin <beta-tip-sha>:refs/heads/release/X.Y.Z-merge-from-beta
+   ```
+   Naming convention: `release/X.Y.Z-merge-from-beta`, where `X.Y.Z` is the stable version you intend to land. release-please will write the actual `X.Y.Z` on merge — the branch name is just a human label.
+
+3. **Open a PR to `main`.** Title: `chore(release): promote beta → main as vX.Y.Z`. Body should summarise the major themes since the previous stable, the migration count, and any operator notes (e.g. "this release adds 22 migrations; existing installs should snapshot before upgrading"). See PR #568 as a worked example.
+
+4. **Resolve conflicts.** Main almost always has commits beta doesn't (security backports, release-please's stable-channel release commits, README rewrites). For each conflicting file, decide deliberately:
+   - **`backend/package.json` / `package-lock.json` + `frontend/package.json` / `package-lock.json`** — usually take beta's version (superset), but verify any security-pinned deps (`axios`, `nodemailer`, `i18next-http-backend`, `multer`, `tar`) on beta are `>=` the pinned versions on main. If main has a newer pinned version (e.g. an emergency CVE backport beta hasn't picked up), take main's pin.
+   - **`README.md`** — keep main's version if main has had a recent rewrite that beta didn't pick up; otherwise take beta's.
+   - **`CHANGELOG.md`** — keep main's; release-please regenerates entries on its next stable cut from the commits going forward.
+   - **`.release-please-manifest.json`** — keep main's; release-please owns this file.
+   - Any other auto-merged file — spot-check that the auto-merge produced something sensible, especially for security-sensitive files (`backend/src/middleware/`, `backend/src/utils/tokenUtils.js`).
+
+5. **Wait for CI on the PR.** All ten checks (the original eight plus `merge-backend` and `merge-frontend`) must be green. If anything fails, fix on the release branch (NOT on beta — beta has already moved on).
+
+6. **Merge.** Standard merge commit, not squash — the PR's history (the individual feature commits) carries forward into main's log.
+
+7. **release-please picks it up.** Within minutes, release-please will open a new `chore(main): release X.Y.Z` PR proposing the stable release. Review the auto-generated CHANGELOG.md entries for accuracy, edit if needed, and merge. That merge creates the `vX.Y.Z` git tag, publishes Docker images on the `stable` and `latest` tags, and creates the GitHub Release page.
+
+8. **Close the loop.** Bulk-close any `bug` issues that were fixed-but-not-closed and now appear in the released changelog. Reference the merge commit so reporters know which version contains the fix.
+
+## Hotfix path (backport to current stable)
+
+If a critical bug or security issue affects the current stable and beta has moved too far for a full promotion to be appropriate, backport just the fix:
+
+1. Create a `security/cve-backport-X.Y.Z` or `fix/critical-X.Y.Z` branch off `main`.
+2. Cherry-pick or hand-write the minimal fix.
+3. Open a PR to `main` with the smallest possible diff.
+4. After merge, release-please will propose a patch-level stable release (e.g. `v3.55.1`).
+5. **Forward-port the fix to beta** if it isn't already there. Otherwise the next full promotion will reintroduce the bug.
+
+PR #412 ("backport 18 dependency CVE patches from beta") is a worked example of this path.
+
+## Versioning
+
+PicPeak follows [Semantic Versioning](https://semver.org/) with one project-specific convention:
+
+- **MAJOR** bumps are reserved for breaking schema changes that require operator action on upgrade (e.g. a migration that's not safe to auto-apply, an env-var rename that can't be auto-detected).
+- **MINOR** bumps for new features, additive schema changes, and any change to the public HTTP API surface.
+- **PATCH** bumps for bug fixes and operator-invisible internal changes.
+- **Beta suffix** (`-beta.N`) for every beta cut; the `N` counter resets on each new MINOR or MAJOR target.
+
+release-please derives all of this from conventional commit prefixes (`feat:`, `fix:`, `BREAKING CHANGE:`, etc.) automatically.
+
+## Things that don't go through this process
+
+- **Documentation-only changes** can land on either `main` or `beta` directly (no release cut needed); release-please will pick them up on the next regular release.
+- **Test-only changes** — same.
+- **CI / workflow changes** — same, but be aware they take effect on the branch they land on, so a CI fix targeting beta won't fix a broken stable-channel workflow until the next promotion.
+
+## When this doc is wrong
+
+If you find yourself working around something here, update the doc before doing the workaround. The point of a written process is that future-you doesn't have to remember the workaround.

SECURITY.md

@@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Currently supported versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.x.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+| 2.x.x   | :white_check_mark: |
+| < 2.0   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -15,9 +15,9 @@ We take the security of PicPeak seriously. If you have discovered a security vul
 
 ### 1. **Do NOT create a public GitHub issue**
 
-### 2. Report the vulnerability by:
-- Opening a [security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
-- Mark it clearly as "SECURITY" in the title
+### 2. Report the vulnerability privately by:
+- **Preferred:** Use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
+- **Alternative:** Email us at **info@picpeak.app** with the details
 - Include:
   - Description of the vulnerability
   - Steps to reproduce
@@ -82,7 +82,7 @@ We believe in responsible disclosure. Once a vulnerability is fixed:
 
 ## Contact
 
-- Security issues: [Create a security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
+- Security issues: Email **info@picpeak.app** or use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
 - General support: [GitHub Issues](https://github.com/the-luap/picpeak/issues)
 
 Thank you for helping keep PicPeak and its users safe!

SIMPLE_SETUP.md

@@ -8,9 +8,9 @@ This guide provides easy installation instructions for PicPeak on Linux servers
 
 ```bash
 # Download and run the unified setup script
-curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/setup.sh -o setup.sh && \
-chmod +x setup.sh && \
-sudo ./setup.sh
+curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/picpeak-setup.sh -o picpeak-setup.sh && \
+chmod +x picpeak-setup.sh && \
+sudo ./picpeak-setup.sh
 ```
 
 The script will automatically detect your environment and recommend the best installation method.
@@ -21,7 +21,7 @@ The script will automatically detect your environment and recommend the best ins
 Best for: Most users, easy updates, isolated environment
 
 ```bash
-sudo ./setup.sh --docker
+sudo ./picpeak-setup.sh --docker
 ```
 
 **Pros:**
@@ -38,7 +38,7 @@ sudo ./setup.sh --docker
 Best for: Resource-constrained systems, Raspberry Pi, direct control
 
 ```bash
-sudo ./setup.sh --native
+sudo ./picpeak-setup.sh --native
 ```
 
 **Pros:**
@@ -73,7 +73,7 @@ sudo ./setup.sh --native
 
 ### Interactive Mode (Default)
 ```bash
-sudo ./setup.sh
+sudo ./picpeak-setup.sh
 ```
 
 The script will prompt you to choose:
@@ -87,7 +87,7 @@ The script will prompt you to choose:
 
 #### Docker with full configuration:
 ```bash
-sudo ./setup.sh --docker --unattended \
+sudo ./picpeak-setup.sh --docker --unattended \
   --domain photos.example.com \
   --email admin@example.com \
   --admin-password SecurePass123 \
@@ -100,7 +100,7 @@ sudo ./setup.sh --docker --unattended \
 
 #### Native with minimal configuration:
 ```bash
-sudo ./setup.sh --native --unattended \
+sudo ./picpeak-setup.sh --native --unattended \
   --email admin@example.com \
   --admin-password SecurePass123
 ```
@@ -219,29 +219,36 @@ location ~ ^/(photos|thumbnails|uploads) {
 
 ### Creating a Gallery
 
-#### Method 1: Via Admin Panel (Recommended)
-1. Login to admin panel
+#### Via Admin Panel
+1. Login to admin panel at `/admin`
 2. Click "Create New Event"
-3. Configure settings and upload photos
+3. Configure settings (name, date, password, customer email)
+4. Upload photos via drag & drop in the Photos tab
+5. Publish the gallery when ready
+
+#### Adding Photos via File System
+
+> **Important:** You must first create the event in the admin panel. The file watcher only detects new photos for events that already exist in the database. You cannot create a gallery by copying files alone.
+
+Once an event exists, you can add photos by copying them into the event's folder. PicPeak's built-in file watcher will automatically detect the new files, create database records, and generate thumbnails.
 
-#### Method 2: File System
 ```bash
-# Docker installation
-mkdir -p ~/picpeak/storage/events/active/wedding-smith-2024
-cp /path/to/photos/* ~/picpeak/storage/events/active/wedding-smith-2024/
+# Docker installation — copy photos into an existing event's folder
+cp /path/to/photos/*.jpg ~/picpeak/storage/events/active/<event-slug>/
 
 # Native installation
-sudo mkdir -p /opt/picpeak/events/active/wedding-smith-2024
-sudo cp /path/to/photos/* /opt/picpeak/events/active/wedding-smith-2024/
-sudo chown -R picpeak:picpeak /opt/picpeak/events/active/wedding-smith-2024
+sudo cp /path/to/photos/*.jpg /opt/picpeak/events/active/<event-slug>/
+sudo chown -R picpeak:picpeak /opt/picpeak/events/active/<event-slug>
 ```
 
+The event slug is visible in the admin panel URL or share link (e.g. `wedding-smith-2024`). Supported formats: `.jpg`, `.jpeg`, `.png`, `.webp`. The file watcher has a 2-second stability delay before processing new files.
+
 ### Gallery Structure
 ```
-wedding-smith-2024/
-├── collages/        # Group photos
-├── individual/      # Individual photos
-└── thumbnails/      # Auto-generated thumbnails
+<event-slug>/
+├── collages/        # Group photos (optional subfolder)
+├── individual/      # Individual photos (optional subfolder)
+└── photo.jpg        # Photos at root level also work
 ```
 
 ## 🔧 Service Management
@@ -293,7 +300,7 @@ sudo systemctl restart picpeak-backend picpeak-workers
 
 # Update PicPeak
 # (reruns migrations to pick up schema fixes for native installs)
-sudo ./setup.sh --update
+sudo ./picpeak-setup.sh --update
 ```
 
 ## ⚙️ Configuration
@@ -385,14 +392,14 @@ docker compose pull
 docker compose up -d
 
 # Native
-sudo ./setup.sh --update
+sudo ./picpeak-setup.sh --update
 ```
 
 ### Uninstall
 
 ```bash
 # Will prompt for confirmation and data removal options
-sudo ./setup.sh --uninstall
+sudo ./picpeak-setup.sh --uninstall
 ```
 
 ## 🐛 Troubleshooting
@@ -451,6 +458,8 @@ cd /opt/picpeak/app/backend
 sudo -u picpeak node scripts/reset-admin-password.js
 ```
 
+> **Note:** The new password will be displayed in the console output and saved to `ADMIN_PASSWORD_RESET.txt`. Save it immediately!
+
 ### Getting Help
 
 1. **Check logs:**
@@ -459,8 +468,8 @@ sudo -u picpeak node scripts/reset-admin-password.js
    - Installation: `/tmp/picpeak-setup-*.log`
 
 2. **Documentation:**
-   - [Full Documentation](https://github.com/the-luap/picpeak)
-   - [Deployment Guide](./DEPLOYMENT_GUIDE.md)
+   - [Full Documentation](https://docs.picpeak.app)
+   - [Deployment Guide](https://docs.picpeak.app/deployment)
 
 3. **Support:**
    - [GitHub Issues](https://github.com/the-luap/picpeak/issues)
@@ -508,13 +517,13 @@ sudo systemctl restart picpeak-backend
 ### Home/Office Network
 ```bash
 # Simple local setup without domain
-sudo ./setup.sh --native --email admin@local.com
+sudo ./picpeak-setup.sh --native --email admin@local.com
 ```
 
 ### Public Website with HTTPS
 ```bash
 # Full production setup
-sudo ./setup.sh --docker \
+sudo ./picpeak-setup.sh --docker \
   --domain photos.company.com \
   --email admin@company.com \
   --enable-ssl
@@ -523,7 +532,7 @@ sudo ./setup.sh --docker \
 ### Raspberry Pi Setup
 ```bash
 # Optimized for ARM devices
-sudo ./setup.sh --native \
+sudo ./picpeak-setup.sh --native \
   --port 8080 \
   --email pi@local.com
 ```

backend/.env.example

@@ -9,11 +9,57 @@ PORT=3001
 # Generate with: openssl rand -base64 32
 JWT_SECRET=your-very-secure-jwt-secret-at-least-32-characters-long-example123456
 
+# Auth cookie Secure flag
+#   unset  - default: 'auto' in production, false in dev (#427)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access —
+#            login appears to succeed but the browser silently drops the
+#            cookie, leaving you in a redirect loop. Only set this if you
+#            ALWAYS reach the site via HTTPS)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP. Reads
+#            req.secure from Express which respects X-Forwarded-Proto from a
+#            trusted reverse proxy. This is the default and is the right
+#            choice for most deployments.
+#
+# Why 'auto' is the default in production:
+#   - On real HTTPS (reverse proxy with X-Forwarded-Proto), req.secure is
+#     true → Secure flag is still emitted. No security regression vs. true.
+#   - On plain HTTP (LAN access, first-time install before reverse proxy is
+#     wired up), req.secure is false → Secure flag is omitted → login works
+#     instead of silently looping back to /admin/login.
+#
+# When you'd set this explicitly:
+#   - COOKIE_SECURE=true → strict HTTPS-only deployments where you want
+#     defense in depth against accidentally serving over HTTP.
+#   - COOKIE_SECURE=false → you intentionally only ever serve over HTTP and
+#     don't want the per-request check (rare).
+#
+# Requirements for 'auto' mode to detect HTTPS correctly:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # URLs (adjust for your domain)
 ADMIN_URL=https://photos.example.com
 FRONTEND_URL=https://photos.example.com
 BACKEND_URL=https://photos.example.com  # Or https://api.photos.example.com if separate
 
+# API URL for email assets (logos, images in emails)
+# This must be the publicly accessible URL where recipients can load images
+# If not set, defaults to http://localhost:3001 which will break images in production emails
+API_URL=https://photos.example.com/api
+
 # Database Configuration
 DATABASE_CLIENT=pg
 DB_HOST=localhost
@@ -39,6 +85,7 @@ SMTP_PASS=your-sendgrid-api-key
 EMAIL_FROM=noreply@example.com
 
 # Storage Paths
+# IMPORTANT: STORAGE_PATH must be set to avoid file path resolution issues
 # Docker deployment:
 STORAGE_PATH=/app/storage
 EVENTS_PATH=/app/storage/events

backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
 # Add build arguments
 ARG CACHEBUST=1
@@ -16,19 +16,34 @@ WORKDIR /app
 # Copy package files
 COPY package*.json ./
 
-# Install dependencies
-RUN npm ci --only=production
+# Install dependencies (--omit=dev replaces deprecated --only=production)
+RUN npm ci --omit=dev
 
 # Copy application files
 COPY . .
 
 # Production stage
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
-# Install dumb-init for proper signal handling and postgresql-client for database checks
-RUN apk add --no-cache dumb-init postgresql-client
+# Upgrade all packages to fix security vulnerabilities (OpenSSL, libexpat, BusyBox CVEs)
+RUN apk upgrade --no-cache
+
+# Upgrade npm to fix tar, minimatch, brace-expansion CVEs in npm's own deps
+# Pin to 10.x to stay compatible with Node 22 Alpine (npm 11.x has dependency issues)
+RUN npm install -g npm@10
+
+# Install dumb-init for proper signal handling, postgresql-client for database
+# checks, ffmpeg for video upload support, and su-exec for the root → nodejs
+# privilege drop in wait-for-db.sh (see #484: container starts as root so it
+# can chown bind-mounted host volumes to UID 1001, then re-execs as nodejs
+# before running the app). Alpine's ffmpeg package ships both `ffmpeg` and
+# `ffprobe` built natively against musl libc — the npm
+# `@ffmpeg-installer/ffmpeg` binary is glibc-built and (a) doesn't reliably
+# run on Alpine and (b) only includes ffmpeg, not ffprobe (which the video
+# pipeline calls via fluent-ffmpeg.ffprobe()).
+RUN apk add --no-cache dumb-init postgresql-client ffmpeg su-exec
 
 # Create non-root user
 RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
@@ -37,16 +52,25 @@ RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
 COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
 COPY --chown=nodejs:nodejs . .
 
-# Make wait script executable
-RUN chmod +x wait-for-db.sh
+# Ensure all source files are readable and wait script is executable
+RUN chmod -R a+r /app && chmod +x wait-for-db.sh
 
 # Create necessary directories
 RUN mkdir -p storage/events/active storage/events/archived storage/thumbnails data logs && \
     chown -R nodejs:nodejs storage data logs
 
-USER nodejs
+# No USER directive — the container starts as root so wait-for-db.sh can
+# chown bind-mounted host directories to UID 1001 before dropping privs
+# via su-exec. See #484 for the fresh-install restart loop this avoids.
 
 EXPOSE 3000
 
+# Healthcheck hits the same /health endpoint already used by the e2e
+# runner and by the docker-compose `depends_on: condition: service_healthy`
+# checks. wget is part of the Alpine base image. Long start-period covers
+# the wait-for-db.sh delay before the Node process starts listening.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
 ENTRYPOINT ["dumb-init", "--"]
 CMD ["./wait-for-db.sh", "node", "server.js"]

backend/Dockerfile.dev

@@ -1,9 +1,14 @@
-FROM node:18-alpine
+FROM node:20-alpine
 
 WORKDIR /app
 
-# Install dumb-init for proper signal handling
-RUN apk add --no-cache dumb-init
+# Upgrade all packages to fix security vulnerabilities (BusyBox CVEs)
+RUN apk upgrade --no-cache
+
+# Install dumb-init for proper signal handling and ffmpeg for video uploads.
+# Alpine's ffmpeg ships both ffmpeg + ffprobe built natively against musl;
+# the npm-bundled binary doesn't run reliably on Alpine. Match production.
+RUN apk add --no-cache dumb-init ffmpeg
 
 # Copy package files
 COPY package*.json ./
@@ -25,5 +30,8 @@ USER nodejs
 
 EXPOSE 3000
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
 ENTRYPOINT ["dumb-init", "--"]
 CMD ["npm", "run", "dev"]

backend/__tests__/integration/adminBackupCoverage.test.js

@@ -0,0 +1,242 @@
+/**
+ * Integration test for GET /api/admin/system-health/backup-coverage.
+ *
+ * Pins the Stage C diagnostic that tells admins what the next
+ * "Run Backup Now" will include, skip, or silently miss.
+ *
+ * Test surface:
+ *   1. Empty / fresh install → default seed (7 paths), inline mode,
+ *      no DB dump on file yet, no drift
+ *   2. Toggle `include_in_default=false` → coverage flips to
+ *      'skipped-by-toggle'
+ *   3. Feature_flag gating reflects the actual app_settings value
+ *      (events/archived ⇄ backup_include_archived)
+ *   4. Drift detection: a top-level subdir on disk with no
+ *      `backup_paths` row is flagged in `unconfiguredOnDisk`
+ *   5. Allow-list: `backups/` and `tmp/` are never flagged as drift
+ *   6. Scheduled-only mode + recent dump → `database.ok = true`
+ *   7. Scheduled-only mode + stale (>26h) dump → `database.ok = false`
+ *      and `lastDumpStale = true`
+ *
+ * Same auth/permission pass-through strategy as
+ * adminBackupIntegrity.test.js — we exercise the route's logic,
+ * not the auth middleware.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const express = require('express');
+const request = require('supertest');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+jest.mock('../../src/middleware/auth', () => ({
+  adminAuth: (req, _res, next) => { req.admin = { id: 1 }; next(); },
+  customerAuth: (_req, _res, next) => next(),
+  galleryAuth: (_req, _res, next) => next(),
+}));
+
+jest.mock('../../src/middleware/permissions', () => ({
+  requirePermission: () => (_req, _res, next) => next(),
+}));
+
+jest.setTimeout(30000);
+
+describe('GET /api/admin/system-health/backup-coverage', () => {
+  let db;
+  let cleanup;
+  let storagePath;
+  let app;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+
+    const route = require('../../src/routes/adminSystemHealth');
+    app = express();
+    app.use(express.json());
+    app.use('/api/admin/system-health', route);
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  function mkdir(rel) {
+    fs.mkdirSync(path.join(storagePath, rel), { recursive: true });
+  }
+
+  function rmdir(rel) {
+    fs.rmSync(path.join(storagePath, rel), { recursive: true, force: true });
+  }
+
+  async function restoreDefaultPaths() {
+    await db('backup_paths').del();
+    const { DEFAULT_PATHS } = require('../../migrations/core/109_add_backup_paths');
+    await db('backup_paths').insert(DEFAULT_PATHS.map((row) => ({
+      ...row,
+      created_at: new Date(),
+      updated_at: new Date(),
+    })));
+  }
+
+  beforeEach(async () => {
+    await restoreDefaultPaths();
+    await db('database_backup_runs').del().catch(() => {});
+    await db('app_settings').where('setting_type', 'backup').del().catch(() => {});
+  });
+
+  it('returns the canonical 7 paths + database block on a fresh install', async () => {
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty('report');
+
+    const { report } = res.body;
+    expect(report.paths.map((p) => p.path)).toEqual([
+      'events/active',
+      'events/archived',
+      'thumbnails',
+      'previews',
+      'heroes',
+      'uploads',
+      'business-docs',
+    ]);
+
+    // Default mode is inline — no inline_dump setting present means
+    // "inline is ON" (matches ensureDatabaseDumpForBackup semantics).
+    expect(report.database.mode).toBe('inline');
+    expect(report.database.ok).toBe(true);
+
+    expect(report.summary).toMatchObject({
+      configuredCount: 7,
+      tableMissingFallbackInUse: false,
+    });
+  });
+
+  it('flips a path to skipped-by-toggle when include_in_default=false', async () => {
+    await db('backup_paths').where('path', 'thumbnails').update({
+      include_in_default: false,
+    });
+
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    const thumbnails = res.body.report.paths.find((p) => p.path === 'thumbnails');
+    expect(thumbnails.coverage).toBe('skipped-by-toggle');
+    expect(thumbnails.includeInDefault).toBe(false);
+  });
+
+  it('feature_flag gating reflects app_settings (archived path off vs on)', async () => {
+    // backup_include_archived not set → archived skipped via flag
+    const off = await request(app).get('/api/admin/system-health/backup-coverage');
+    const archivedOff = off.body.report.paths.find((p) => p.path === 'events/archived');
+    expect(archivedOff.coverage).toBe('skipped-by-feature-flag');
+    expect(archivedOff.featureFlag).toBe('backup_include_archived');
+    expect(archivedOff.featureFlagValue).toBe(null); // unset
+
+    // Now set the flag — but path is missing on disk, so coverage
+    // resolves to 'missing-on-disk', proving the flag was honoured.
+    await db('app_settings').insert({
+      setting_key: 'backup_include_archived',
+      setting_value: JSON.stringify(true),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    const on = await request(app).get('/api/admin/system-health/backup-coverage');
+    const archivedOn = on.body.report.paths.find((p) => p.path === 'events/archived');
+    expect(archivedOn.featureFlagValue).toBe(true);
+    // No on-disk dir → 'missing-on-disk' (not 'skipped-by-feature-flag')
+    expect(['missing-on-disk', 'will-scan']).toContain(archivedOn.coverage);
+  });
+
+  it('detects unconfigured top-level subdirs as drift', async () => {
+    mkdir('events/active');           // configured
+    mkdir('plugin-store/cache');      // DRIFT
+    mkdir('shiny-new-feature/data');  // DRIFT
+
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    expect(res.body.report.drift.unconfiguredOnDisk).toEqual(expect.arrayContaining([
+      'plugin-store',
+      'shiny-new-feature',
+    ]));
+    expect(res.body.report.drift.unconfiguredOnDisk).not.toContain('events');
+
+    rmdir('plugin-store');
+    rmdir('shiny-new-feature');
+  });
+
+  it('never flags backups/ or tmp/ as drift (allow-list)', async () => {
+    mkdir('backups');
+    mkdir('tmp');
+
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    expect(res.body.report.drift.unconfiguredOnDisk).not.toContain('backups');
+    expect(res.body.report.drift.unconfiguredOnDisk).not.toContain('tmp');
+    expect(res.body.report.drift.expectedNonBackupDirs).toEqual(
+      expect.arrayContaining(['backups', 'tmp']),
+    );
+
+    rmdir('backups');
+    rmdir('tmp');
+  });
+
+  it('scheduled-only mode + recent dump → database.ok=true, not stale', async () => {
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    const recentDump = path.join(storagePath, 'backups', 'recent.sql.gz');
+    fs.mkdirSync(path.dirname(recentDump), { recursive: true });
+    fs.writeFileSync(recentDump, 'pretend dump');
+    await db('database_backup_runs').insert({
+      started_at: new Date(),
+      completed_at: new Date(),  // just now
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: recentDump,
+      file_size_bytes: fs.statSync(recentDump).size,
+      destination_path: recentDump,
+    });
+
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    expect(res.body.report.database.mode).toBe('scheduled-only');
+    expect(res.body.report.database.inlineDumpExplicitlyDisabled).toBe(true);
+    expect(res.body.report.database.lastDumpStale).toBe(false);
+    expect(res.body.report.database.ok).toBe(true);
+  });
+
+  it('scheduled-only mode + stale dump → database.ok=false, lastDumpStale=true', async () => {
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    const oldDump = path.join(storagePath, 'backups', 'old.sql.gz');
+    fs.mkdirSync(path.dirname(oldDump), { recursive: true });
+    fs.writeFileSync(oldDump, 'pretend old dump');
+    // 48 hours ago — well past the 26h staleness threshold. ISO
+    // string instead of a Date object because knex-sqlite's datetime
+    // serialisation has a quirk where some Date instances coerce to
+    // '[object Object]' on insert (the test 6 "recent dump" case
+    // passes only because `new Date()` happens to round-trip safely;
+    // arithmetic Dates don't).
+    const stale = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
+    await db('database_backup_runs').insert({
+      started_at: stale,
+      completed_at: stale,
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: oldDump,
+      file_size_bytes: fs.statSync(oldDump).size,
+      destination_path: oldDump,
+    });
+
+    const res = await request(app).get('/api/admin/system-health/backup-coverage');
+    expect(res.body.report.database.lastDumpStale).toBe(true);
+    expect(res.body.report.database.ok).toBe(false);
+    // Top-level summary reflects the failed DB check.
+    expect(res.body.report.summary.databaseOk).toBe(false);
+    expect(res.body.report.summary.overallOk).toBe(false);
+  });
+});

backend/__tests__/integration/adminBackupIntegrity.test.js

@@ -0,0 +1,140 @@
+/**
+ * Integration test for GET /api/admin/system-health/backup-integrity.
+ *
+ * Auth + permission middleware are mocked to pass-through so the test
+ * focuses on the route's own behaviour: scope-param validation, the
+ * successResponse envelope, and that the underlying service report
+ * surfaces correctly in the JSON body.
+ *
+ * The verifier service itself is exercised against the real schema
+ * (bootCrmDb) and real filesystem — only the auth gate is stubbed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const express = require('express');
+const request = require('supertest');
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+// Pass-through auth so we don't need to mint JWTs.
+jest.mock('../../src/middleware/auth', () => ({
+  adminAuth: (req, _res, next) => { req.admin = { id: 1 }; next(); },
+  customerAuth: (_req, _res, next) => next(),
+  galleryAuth: (_req, _res, next) => next(),
+}));
+
+// Pass-through permissions so settings.view always allows.
+jest.mock('../../src/middleware/permissions', () => ({
+  requirePermission: () => (_req, _res, next) => next(),
+}));
+
+jest.setTimeout(30000);
+
+describe('GET /api/admin/system-health/backup-integrity', () => {
+  let cleanup;
+  let db;
+  let customerId;
+  let app;
+  let storagePath;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ customerId } = await seedMinimal(db));
+    storagePath = process.env.STORAGE_PATH;
+
+    // Mount the route on a minimal Express app. Cold-require after
+    // bootCrmDb so the route's downstream `require('../database/db')`
+    // sees the same db instance.
+    const route = require('../../src/routes/adminSystemHealth');
+    app = express();
+    app.use(express.json());
+    app.use('/api/admin/system-health', route);
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(async () => {
+    await db('contracts').del().catch(() => {});
+    await db('invoices').del().catch(() => {});
+    await db('quotes').del().catch(() => {});
+  });
+
+  it('returns a report envelope when nothing references any path', async () => {
+    const res = await request(app).get('/api/admin/system-health/backup-integrity');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty('report');
+    expect(res.body.report.summary).toMatchObject({
+      totalRows: 0,
+      missingFiles: 0,
+      hashMismatches: 0,
+      verifiedOk: 0,
+      existsButNoHash: 0,
+    });
+    expect(res.body.report.scopes).toEqual(expect.arrayContaining([
+      'quote', 'contract', 'contract-signature', 'invoice',
+    ]));
+  });
+
+  it('surfaces a missing file in the response payload', async () => {
+    await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-B7-MISSING',
+      status: 'sent',
+      issue_date: '2026-01-01',
+      signed_pdf_path: 'business-docs/contract/2026/C-B7-MISSING.pdf',
+      created_at: new Date(),
+    });
+
+    const res = await request(app).get('/api/admin/system-health/backup-integrity');
+    expect(res.status).toBe(200);
+    expect(res.body.report.summary.missingFiles).toBe(1);
+    expect(res.body.report.missing[0]).toMatchObject({
+      table: 'contracts',
+      column: 'signed_pdf_path',
+      expectedPath: 'business-docs/contract/2026/C-B7-MISSING.pdf',
+    });
+  });
+
+  it('honours the ?scope=invoice filter', async () => {
+    // Seed both an invoice and a contract with missing files. With
+    // scope=invoice the contract row must not appear.
+    await db('invoices').insert({
+      customer_account_id: customerId,
+      invoice_number: 'INV-B7-SCOPE',
+      status: 'sent',
+      issue_date: '2026-01-01',
+      due_date: '2026-01-31',
+      pdf_path: 'business-docs/invoice/2026/INV-B7-SCOPE.pdf',
+      created_at: new Date(),
+    });
+    await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-B7-SCOPE',
+      status: 'sent',
+      issue_date: '2026-01-01',
+      signed_pdf_path: 'business-docs/contract/2026/C-B7-SCOPE.pdf',
+      created_at: new Date(),
+    });
+
+    const res = await request(app)
+      .get('/api/admin/system-health/backup-integrity')
+      .query({ scope: 'invoice' });
+    expect(res.status).toBe(200);
+    expect(res.body.report.scopes).toEqual(['invoice']);
+    expect(res.body.report.missing.every((m) => m.table === 'invoices')).toBe(true);
+  });
+
+  it('rejects an unknown scope with 400 + a code', async () => {
+    const res = await request(app)
+      .get('/api/admin/system-health/backup-integrity')
+      .query({ scope: 'gallery' });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('BACKUP_INTEGRITY_UNKNOWN_SCOPE');
+    expect(res.body.validScopes).toEqual(expect.arrayContaining([
+      'quote', 'contract', 'contract-signature', 'invoice',
+    ]));
+  });
+});

backend/__tests__/integration/backup-s3.test.js

@@ -7,12 +7,15 @@ const crypto = require('crypto');
 // Load services
 const backupService = require('../../src/services/backupService');
 const S3StorageAdapter = require('../../src/services/storage/s3Storage');
-const { db, initialize: initDb } = require('../../src/database/db');
+const { db, initializeDatabase: initDb } = require('../../src/database/db');
 const logger = require('../../src/utils/logger');
 
 // Test configuration
+// Defaults match the dev MinIO container in docker-compose.dev.yml (port 7104).
+// Override via TEST_S3_ENDPOINT / TEST_S3_ACCESS_KEY / TEST_S3_SECRET_KEY when running
+// against a different S3 endpoint (CI, hosted MinIO, real AWS, etc.).
 const TEST_CONFIG = {
-  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:9000',
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
   accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
   secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
   bucket: 'test-backup-bucket-' + Date.now(),
@@ -56,9 +59,17 @@ describe('S3 Backup Integration Tests', () => {
       }
     }
 
-    // Initialize database
-    await initDb();
-    await db.migrate.latest();
+    // Schema is expected to already be applied by `npm run migrate` against
+    // the dev database. db.migrate.latest() can't be used here because
+    // PicPeak's custom run-migrations.js tracks state in the `migrations`
+    // table (not knex's `knex_migrations`), so knex would try to re-apply
+    // every migration and crash on duplicate-table errors.
+    const ok = await db.schema.hasTable('events')
+      && await db.schema.hasTable('app_settings')
+      && await db.schema.hasTable('backup_runs');
+    if (!ok) {
+      throw new Error('Required tables missing — run `npm run migrate` against the dev DB first.');
+    }
 
     // Create test storage directory
     testStoragePath = path.join(__dirname, '../fixtures/test-storage');
@@ -69,10 +80,12 @@ describe('S3 Backup Integration Tests', () => {
     await setupTestData();
 
     // Mock logger to reduce noise
-    logger.info = jest.fn();
-    logger.debug = jest.fn();
-    logger.warn = jest.fn();
-    logger.error = jest.fn();
+    if (process.env.UNMOCK_LOGGER !== 'true') {
+      logger.info = jest.fn();
+      logger.debug = jest.fn();
+      logger.warn = jest.fn();
+      logger.error = jest.fn();
+    }
   });
 
   afterAll(async () => {
@@ -165,8 +178,9 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(backupRun.status).toBe('completed');
-      expect(backupRun.files_backed_up).toBeGreaterThan(0);
-      expect(backupRun.total_size_bytes).toBeGreaterThan(0);
+      // pg driver returns bigint columns as strings; coerce for the size assertion.
+      expect(Number(backupRun.files_backed_up)).toBeGreaterThan(0);
+      expect(Number(backupRun.total_size_bytes)).toBeGreaterThan(0);
 
       // Verify files in S3
       const s3Objects = await listS3Objects();
@@ -269,13 +283,16 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(secondRun.id).not.toBe(firstRun.id);
-      expect(secondRun.files_backed_up).toBe(1); // Only modified file
+      expect(Number(secondRun.files_backed_up)).toBe(1); // Only modified file
 
-      // Check manifest indicates incremental
+      // Check manifest indicates incremental. The current manifest schema
+      // groups counts under `incremental.changes.*` (added/modified/deleted/
+      // unchanged + size_difference) — see backupManifest.generateIncrementalManifest.
       if (secondRun.manifest_path) {
         const manifest = await backupService.getBackupManifest(secondRun.id);
         expect(manifest.manifest.incremental).toBeDefined();
-        expect(manifest.manifest.incremental.modified_files_count).toBe(1);
+        expect(manifest.manifest.incremental.changes).toBeDefined();
+        expect(manifest.manifest.incremental.changes.modified_files_count).toBe(1);
       }
     });
 
@@ -468,15 +485,16 @@ describe('S3 Backup Integration Tests', () => {
       { setting_key: 'backup_max_file_size_mb', setting_value: '100' }
     ];
 
+    // Schema drift: app_settings has no created_at column anymore and the
+    // unique constraint is on setting_key alone, not (setting_type, key).
     for (const setting of settings) {
       await db('app_settings')
         .insert({
           setting_type: 'backup',
           ...setting,
-          created_at: new Date(),
-          updated_at: new Date()
+          updated_at: new Date(),
         })
-        .onConflict(['setting_type', 'setting_key'])
+        .onConflict('setting_key')
         .merge();
     }
   }

backend/__tests__/integration/backupService.businessDocs.test.js

@@ -0,0 +1,88 @@
+/**
+ * Regression net for the business-docs coverage gap fixed in this PR.
+ *
+ * Prior to the fix, `getFilesToBackupInternal()` enumerated a fixed
+ * list of storage subdirectories (events/active, events/archived,
+ * thumbnails, previews, heroes, uploads) and silently omitted the
+ * entire `business-docs/` tree. That meant every CRM PDF + signature
+ * drawing — quotes, contracts (system-rendered + wet uploads),
+ * invoices, Storno, imported historical invoices, and the customer
+ * signature PNG/JPG drawn on the public signing page — fell outside
+ * the in-app scheduled backup, leaving every `*_path` column on
+ * `quotes` / `contracts` / `invoices` as a broken FK after restore.
+ *
+ * The fix is a single `scanDirectory(business-docs, ...)` call. This
+ * suite pins the contract so a future refactor of the walker cannot
+ * silently drop business-docs again.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+describe('backupService — business-docs is in the backup walker', () => {
+  let cleanup;
+  let backupService;
+  let storagePath;
+
+  beforeAll(async () => {
+    ({ cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+    // Cold-require after bootCrmDb so backupService picks up the same
+    // db instance + STORAGE_PATH the test harness configured.
+    backupService = require('../../src/services/backupService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  function seed(relPath, content = 'dummy bytes for backup test') {
+    const abs = path.join(storagePath, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+
+  it('does not error when business-docs is absent', async () => {
+    // Fresh harness has no business-docs/ tree at all. The walker
+    // must short-circuit on ENOENT rather than throw — installs that
+    // never used CRM features have to keep backing up fine.
+    await expect(backupService.getFilesToBackup(false)).resolves.toEqual(expect.any(Array));
+  });
+
+  it('picks up every CRM-relevant business-docs subdirectory', async () => {
+    // Seed one file in each of the five subpaths the renderer + import
+    // routes write to. The signature path is the one most prone to be
+    // forgotten — it lives one level deeper than the others (per-
+    // contract subfolder, not per-year).
+    seed('business-docs/quote/2026/Q-001.pdf');
+    seed('business-docs/contract/2026/C-001.pdf');
+    seed('business-docs/contract/signatures/42/customer-1700000000000.png');
+    seed('business-docs/invoice/2026/INV-001.pdf');
+    seed('business-docs/invoice-imports/2026/scan.pdf');
+
+    const files = await backupService.getFilesToBackup(false);
+    const rels = files.map((f) => f.relativePath);
+
+    expect(rels).toEqual(expect.arrayContaining([
+      'business-docs/quote/2026/Q-001.pdf',
+      'business-docs/contract/2026/C-001.pdf',
+      'business-docs/contract/signatures/42/customer-1700000000000.png',
+      'business-docs/invoice/2026/INV-001.pdf',
+      'business-docs/invoice-imports/2026/scan.pdf',
+    ]));
+  });
+
+  it('walks newly-created business-docs files without needing a restart', async () => {
+    // The walker reads the filesystem live on every call; this guards
+    // against a future "cache the scan result at boot" optimisation
+    // that would miss freshly-written PDFs (which is exactly what
+    // happens during normal operation — every send writes a new file).
+    seed('business-docs/invoice/2027/INV-NEW.pdf');
+
+    const files = await backupService.getFilesToBackup(false);
+    const rels = files.map((f) => f.relativePath);
+    expect(rels).toContain('business-docs/invoice/2027/INV-NEW.pdf');
+  });
+});

backend/__tests__/integration/backupService.configurableWalker.test.js

@@ -0,0 +1,180 @@
+/**
+ * Pins the Stage-B refactor that lifted the file-backup walker's
+ * subdirectory list out of hard-coded JS into the `backup_paths`
+ * table seeded by migration 109.
+ *
+ * Scenarios:
+ *   1. Walker reads canonical seed → all 7 default subdirs walked
+ *   2. include_in_default=false on one row → that subdir is skipped
+ *   3. New row inserted at runtime → walker picks it up without restart
+ *   4. feature_flag gating → row only walked when the named app_settings
+ *      boolean is truthy (mirrors historical `includeArchived` behavior)
+ *   5. Empty table → walker falls back to LEGACY_BACKUP_PATHS (defense
+ *      in depth — never silently scans nothing)
+ *
+ * Why not stub `db('backup_paths')`: the whole point of Stage B is
+ * that the walker is now data-driven, so the test has to actually
+ * mutate the table and observe the walker's output change. Stubs
+ * would re-introduce the hard-coding the refactor is meant to remove.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+jest.setTimeout(30000);
+
+describe('backupService — configurable walker (backup_paths)', () => {
+  let db;
+  let cleanup;
+  let storagePath;
+  let backupService;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+    backupService = require('../../src/services/backupService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  function seedFile(relPath, content = 'dummy bytes') {
+    const abs = path.join(storagePath, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+
+  beforeEach(async () => {
+    // Restore canonical seed before every test. Tests mutate this table
+    // freely; the next test starts from a known state.
+    await db('backup_paths').del();
+    const {
+      DEFAULT_PATHS,
+    } = require('../../migrations/core/109_add_backup_paths');
+    await db('backup_paths').insert(DEFAULT_PATHS.map((row) => ({
+      ...row,
+      created_at: new Date(),
+      updated_at: new Date(),
+    })));
+  });
+
+  it('migration 109 seeds the canonical 7 paths', async () => {
+    const rows = await db('backup_paths').orderBy('display_order', 'asc').select();
+    expect(rows.map((r) => r.path)).toEqual([
+      'events/active',
+      'events/archived',
+      'thumbnails',
+      'previews',
+      'heroes',
+      'uploads',
+      'business-docs',
+    ]);
+    // Only events/archived is gated by a feature flag.
+    expect(rows.filter((r) => r.feature_flag).map((r) => r.path)).toEqual([
+      'events/archived',
+    ]);
+  });
+
+  it('walks every default subdir when files are present', async () => {
+    seedFile('events/active/E1/a.jpg');
+    seedFile('thumbnails/E1/a.jpg');
+    seedFile('previews/E1/a.jpg');
+    seedFile('heroes/E1/hero.jpg');
+    seedFile('uploads/intake/x.bin');
+    seedFile('business-docs/quote/2026/Q-001.pdf');
+    // events/archived is gated — left out of this test; covered below.
+
+    const files = await backupService.getFilesToBackup({ backup_include_archived: true });
+    const rels = files.map((f) => f.relativePath);
+
+    expect(rels).toEqual(expect.arrayContaining([
+      'events/active/E1/a.jpg',
+      'thumbnails/E1/a.jpg',
+      'previews/E1/a.jpg',
+      'heroes/E1/hero.jpg',
+      'uploads/intake/x.bin',
+      'business-docs/quote/2026/Q-001.pdf',
+    ]));
+  });
+
+  it('skips a path when include_in_default is toggled off', async () => {
+    seedFile('thumbnails/E1/thumb.jpg');
+    seedFile('events/active/E1/photo.jpg');
+
+    await db('backup_paths').where('path', 'thumbnails').update({
+      include_in_default: false,
+    });
+
+    const files = await backupService.getFilesToBackup({ backup_include_archived: true });
+    const rels = files.map((f) => f.relativePath);
+
+    expect(rels).toContain('events/active/E1/photo.jpg');
+    expect(rels).not.toContain('thumbnails/E1/thumb.jpg');
+  });
+
+  it('picks up a new path inserted at runtime — no restart needed', async () => {
+    // Simulates a future feature shipping its own subdirectory and
+    // self-healing a `backup_paths` row at boot.
+    await db('backup_paths').insert({
+      path: 'plugin-store',
+      include_in_default: true,
+      feature_flag: null,
+      display_order: 200,
+      description: 'Hypothetical future feature payload',
+      created_at: new Date(),
+      updated_at: new Date(),
+    });
+    seedFile('plugin-store/cache/payload.bin');
+
+    const files = await backupService.getFilesToBackup({ backup_include_archived: true });
+    const rels = files.map((f) => f.relativePath);
+
+    expect(rels).toContain('plugin-store/cache/payload.bin');
+  });
+
+  it('respects feature_flag gating (events/archived ⇄ backup_include_archived)', async () => {
+    seedFile('events/active/E1/active.jpg');
+    seedFile('events/archived/E2/archived.jpg');
+
+    // backup_include_archived=false → archived/ is skipped.
+    const filesOff = await backupService.getFilesToBackup({ backup_include_archived: false });
+    const relsOff = filesOff.map((f) => f.relativePath);
+    expect(relsOff).toContain('events/active/E1/active.jpg');
+    expect(relsOff).not.toContain('events/archived/E2/archived.jpg');
+
+    // backup_include_archived=true → archived/ is included.
+    const filesOn = await backupService.getFilesToBackup({ backup_include_archived: true });
+    const relsOn = filesOn.map((f) => f.relativePath);
+    expect(relsOn).toContain('events/archived/E2/archived.jpg');
+  });
+
+  it('falls back to LEGACY_BACKUP_PATHS when the table is empty', async () => {
+    // Defense in depth: even if seed-and-self-heal both failed, the
+    // walker must still cover the historical set so "Run Backup Now"
+    // cannot silently degrade to no-op.
+    await db('backup_paths').del();
+    seedFile('events/active/E1/photo.jpg');
+    seedFile('business-docs/quote/2026/Q-002.pdf');
+
+    const files = await backupService.getFilesToBackup({ backup_include_archived: true });
+    const rels = files.map((f) => f.relativePath);
+
+    expect(rels).toContain('events/active/E1/photo.jpg');
+    expect(rels).toContain('business-docs/quote/2026/Q-002.pdf');
+  });
+
+  it('legacy boolean call signature still works (backward compat)', async () => {
+    // Existing call sites (and the businessDocs regression test) pass
+    // a boolean for `includeArchived`. Refactor must not break them.
+    seedFile('events/archived/E3/legacy.jpg');
+
+    const filesOff = await backupService.getFilesToBackup(false);
+    expect(filesOff.map((f) => f.relativePath)).not.toContain('events/archived/E3/legacy.jpg');
+
+    const filesOn = await backupService.getFilesToBackup(true);
+    expect(filesOn.map((f) => f.relativePath)).toContain('events/archived/E3/legacy.jpg');
+  });
+});

backend/__tests__/integration/backupService.inlineDbDump.test.js

@@ -0,0 +1,188 @@
+/**
+ * Pins the inline-DB-dump + fail-loud guard added to `runBackupInternal`.
+ *
+ * The previous behaviour was: file-backup looked up an existing dump via
+ * `getDatabaseBackupInfo()` and silently shipped a files-only manifest
+ * when none was found. Admins clicking "Run Backup Now" got an apparent
+ * success that omitted every customer / quote / invoice / contract row —
+ * the data-loss footgun that this commit closes.
+ *
+ * Five scenarios under test:
+ *   1. Default (inline dump enabled), dump succeeds → backup proceeds
+ *   2. Default, dump throws → run aborts, backup_runs row marked failed
+ *   3. Opt-out + recent DB dump available → backup proceeds
+ *   4. Opt-out + no DB dump available → fail loud
+ *   5. Opt-out + DB dump file is 0 bytes on disk → fail loud
+ *
+ * Mocking strategy: the underlying `databaseBackupService.backup()` and
+ * the local-destination writer are stubbed so the test exercises just
+ * the new guard logic without depending on `pg_dump` / `sqlite3` CLI
+ * binaries being available in the test environment.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+// Set up mocks BEFORE bootCrmDb so backupService picks them up at require time.
+const mockBackupFn = jest.fn();
+jest.mock('../../src/services/databaseBackup', () => ({
+  databaseBackupService: { backup: mockBackupFn },
+  startScheduledBackups: jest.fn(),
+  stopScheduledBackups: jest.fn(),
+  DatabaseBackupService: class {},
+}));
+
+jest.setTimeout(30000);
+
+describe('backupService — inline DB dump + fail-loud guard', () => {
+  let db;
+  let cleanup;
+  let storagePath;
+  let backupService;
+  let dumpFileAbs;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+    backupService = require('../../src/services/backupService');
+
+    // Seed backup destination settings so the run can proceed past the
+    // "destination not configured" guard.
+    const dest = path.join(storagePath, 'backups');
+    fs.mkdirSync(dest, { recursive: true });
+    // getBackupConfigInternal filters by setting_type='backup', so the
+    // tests have to seed with that type or the resolver returns
+    // `{ ... }` with the keys missing — runBackup then sees
+    // `backup_destination_type === undefined` and bails before our
+    // new guard runs.
+    await db('app_settings').insert([
+      { setting_key: 'backup_destination_type',    setting_value: JSON.stringify('local'), setting_type: 'backup' },
+      { setting_key: 'backup_destination_path',    setting_value: JSON.stringify(dest),    setting_type: 'backup' },
+      { setting_key: 'backup_enabled',             setting_value: JSON.stringify(true),    setting_type: 'backup' },
+      { setting_key: 'backup_email_on_failure',    setting_value: JSON.stringify(false),   setting_type: 'backup' },
+    ]).onConflict('setting_key').merge();
+
+    // Pre-create a dump file that getDatabaseBackupInfo can resolve to.
+    // Reused/mutated per-test via the database_backup_runs seed below.
+    dumpFileAbs = path.join(storagePath, 'backups', 'fake-dump.sql.gz');
+    fs.writeFileSync(dumpFileAbs, 'pretend this is a pg_dump'.repeat(100));
+
+    // Neutralise the file-scan step: we don't care which files would
+    // be backed up, just whether the run reaches that stage at all.
+    backupService.getFilesToBackup = jest.fn(async () => []);
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(async () => {
+    mockBackupFn.mockReset();
+    // Default to "dump produced this file with this size" — the per-test
+    // setup overrides as needed.
+    mockBackupFn.mockResolvedValue({
+      success: true,
+      path: dumpFileAbs,
+      size: fs.statSync(dumpFileAbs).size,
+      duration: 1,
+      checksum: 'abc',
+    });
+
+    // Re-seed the database_backup_runs row that getDatabaseBackupInfo
+    // resolves against (its query is `status='completed'` + most recent).
+    await db('database_backup_runs').del();
+    await db('database_backup_runs').insert({
+      started_at: new Date(),
+      completed_at: new Date(),
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: dumpFileAbs,
+      file_size_bytes: fs.statSync(dumpFileAbs).size,
+      destination_path: dumpFileAbs,
+    });
+  });
+
+  it('default behaviour: inline dump runs, then file backup proceeds', async () => {
+    // Inline-dump setting is unset (undefined) — default is ON.
+    await db('app_settings').where('setting_key', 'backup_database_inline_dump').del();
+
+    await backupService.runBackup(true);
+
+    expect(mockBackupFn).toHaveBeenCalledTimes(1);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('completed');
+    expect(run.error_message).toBeNull();
+  });
+
+  it('aborts the run when the inline dump throws', async () => {
+    await db('app_settings').where('setting_key', 'backup_database_inline_dump').del();
+    mockBackupFn.mockRejectedValueOnce(new Error('pg_dump segfaulted'));
+
+    await backupService.runBackup(true);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('failed');
+    expect(run.error_message).toMatch(/pg_dump segfaulted/);
+  });
+
+  it('opt-out: skips inline dump but proceeds when a recent dump exists', async () => {
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    await backupService.runBackup(true);
+
+    expect(mockBackupFn).not.toHaveBeenCalled();
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('completed');
+  });
+
+  it('opt-out + no recent dump: fails loud with a clear error', async () => {
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+    // Wipe the dump row so getDatabaseBackupInfo returns backupFile=null.
+    await db('database_backup_runs').del();
+
+    await backupService.runBackup(true);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('failed');
+    expect(run.error_message).toMatch(/No database backup available/);
+  });
+
+  it('opt-out + 0-byte dump file: fails loud', async () => {
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    const emptyDump = path.join(storagePath, 'backups', 'empty-dump.sql.gz');
+    fs.writeFileSync(emptyDump, '');
+    await db('database_backup_runs').del();
+    await db('database_backup_runs').insert({
+      started_at: new Date(),
+      completed_at: new Date(),
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: emptyDump,
+      file_size_bytes: 0,
+      destination_path: emptyDump,
+    });
+
+    await backupService.runBackup(true);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('failed');
+    expect(run.error_message).toMatch(/is empty/);
+  });
+});

backend/__tests__/integration/backupService.perPathStats.test.js

@@ -0,0 +1,180 @@
+/**
+ * Per-Stage-B-path tally — Tier 3 of tonight's backup hardening.
+ *
+ * Pins the new `computePerPathStats` logic that the Backup History
+ * "Content Backed Up" pane reads via `backup_runs.statistics.per_path`.
+ *
+ * Three scenarios:
+ *   1. Single file under one path — straightforward attribution
+ *   2. Multiple paths with overlapping prefixes — longest-prefix wins
+ *      (e.g. `events/active/E1/x.jpg` should attribute to
+ *       `events/active`, not `events`)
+ *   3. File outside any configured path — silently dropped, doesn't
+ *      throw or contaminate other buckets
+ *
+ * Tests exercise the EXPORTED side: write a backup_runs row via the
+ * service entry point and assert the statistics JSON shape. We don't
+ * stub `computePerPathStats` directly — the integration view is what
+ * the frontend actually consumes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+jest.setTimeout(30000);
+
+describe('backupService — per-Stage-B-path statistics', () => {
+  let db;
+  let cleanup;
+  let storagePath;
+  let backupService;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+    backupService = require('../../src/services/backupService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  function mkFile(rel, content = 'x'.repeat(100)) {
+    const abs = path.join(storagePath, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+
+  beforeEach(async () => {
+    // Clean slate of any artefacts from prior tests
+    await db('backup_runs').del();
+    await db('app_settings').where('setting_type', 'backup').del();
+    await db('app_settings').insert([
+      { setting_key: 'backup_destination_type', setting_value: JSON.stringify('local'), setting_type: 'backup' },
+      { setting_key: 'backup_destination_path', setting_value: JSON.stringify(path.join(storagePath, 'destination')), setting_type: 'backup' },
+      { setting_key: 'backup_enabled', setting_value: JSON.stringify(true), setting_type: 'backup' },
+      { setting_key: 'backup_email_on_failure', setting_value: JSON.stringify(false), setting_type: 'backup' },
+      { setting_key: 'backup_include_archived', setting_value: JSON.stringify(true), setting_type: 'backup' },
+    ]).onConflict('setting_key').merge();
+    fs.mkdirSync(path.join(storagePath, 'destination'), { recursive: true });
+
+    // Restore canonical backup_paths from migration 109
+    const { DEFAULT_PATHS } = require('../../migrations/core/109_add_backup_paths');
+    await db('backup_paths').del();
+    await db('backup_paths').insert(DEFAULT_PATHS.map((row) => ({
+      ...row,
+      created_at: new Date(),
+      updated_at: new Date(),
+    })));
+
+    // Wipe leftover files between tests
+    for (const dir of ['events', 'business-docs', 'thumbnails', 'previews', 'heroes', 'uploads']) {
+      const p = path.join(storagePath, dir);
+      if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+    }
+  });
+
+  it('attributes files to their owning backup_paths row', async () => {
+    mkFile('events/active/E1/photo-a.jpg', 'X'.repeat(1000));
+    mkFile('events/active/E1/photo-b.jpg', 'X'.repeat(2000));
+    mkFile('business-docs/quote/2026/Q-1.pdf', 'X'.repeat(500));
+    mkFile('thumbnails/E1/photo-a.jpg', 'X'.repeat(50));
+
+    // Disable the inline DB dump so we don't need pg_dump in tests;
+    // the file walker is what produces per_path.
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+
+    // Seed a fake DB-backup row so the fail-loud guard is satisfied.
+    const fakeDump = path.join(storagePath, 'destination', 'fake.sql.gz');
+    fs.writeFileSync(fakeDump, 'pretend dump');
+    await db('database_backup_runs').insert({
+      started_at: new Date(),
+      completed_at: new Date(),
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: fakeDump,
+      file_size_bytes: fs.statSync(fakeDump).size,
+      destination_path: fakeDump,
+    });
+
+    await backupService.runBackup(true);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    expect(run.status).toBe('completed');
+
+    const statsRaw = typeof run.statistics === 'string'
+      ? JSON.parse(run.statistics)
+      : run.statistics;
+    expect(statsRaw.per_path).toBeDefined();
+
+    // events/active should have 2 files (3000 bytes)
+    expect(statsRaw.per_path['events/active']).toEqual({ count: 2, size: 3000 });
+    // business-docs should have 1 file (500 bytes)
+    expect(statsRaw.per_path['business-docs']).toEqual({ count: 1, size: 500 });
+    // thumbnails should have 1 file (50 bytes)
+    expect(statsRaw.per_path['thumbnails']).toEqual({ count: 1, size: 50 });
+
+    // No spurious buckets for paths that had nothing
+    expect(statsRaw.per_path['previews']).toBeUndefined();
+    expect(statsRaw.per_path['heroes']).toBeUndefined();
+  });
+
+  it('archived path attributed separately from active when both have files', async () => {
+    mkFile('events/active/E1/active.jpg', 'X'.repeat(100));
+    mkFile('events/archived/E2/archived.jpg', 'X'.repeat(200));
+
+    // backup_include_archived already set true in beforeEach so the
+    // archived walker fires; same opt-out for inline DB dump.
+    await db('app_settings').insert({
+      setting_key: 'backup_database_inline_dump',
+      setting_value: JSON.stringify(false),
+      setting_type: 'backup',
+    }).onConflict('setting_key').merge();
+    const fakeDump = path.join(storagePath, 'destination', 'fake.sql.gz');
+    fs.writeFileSync(fakeDump, 'pretend dump');
+    await db('database_backup_runs').insert({
+      started_at: new Date(),
+      completed_at: new Date(),
+      status: 'completed',
+      backup_type: 'pg',
+      file_path: fakeDump,
+      file_size_bytes: fs.statSync(fakeDump).size,
+      destination_path: fakeDump,
+    });
+
+    await backupService.runBackup(true);
+
+    const run = await db('backup_runs').orderBy('id', 'desc').first();
+    const statsRaw = typeof run.statistics === 'string'
+      ? JSON.parse(run.statistics)
+      : run.statistics;
+
+    // events/active and events/archived attribute separately —
+    // longest-prefix match prevents `events/active/...` from claiming
+    // an `events/archived/...` file or vice versa.
+    expect(statsRaw.per_path['events/active']).toEqual({ count: 1, size: 100 });
+    expect(statsRaw.per_path['events/archived']).toEqual({ count: 1, size: 200 });
+  });
+});
+
+// NOTE on walker duplication
+//
+// If two `backup_paths` rows overlap (e.g. one row at `events` AND
+// another at `events/active`), the walker scans the same files twice
+// — once via each path. Per-path stats then attribute the file to the
+// longest-prefix-matching path BOTH times, producing inflated counts.
+//
+// The canonical seed in migration 109 contains no overlapping pairs,
+// so this isn't exercised in practice. But an admin who hand-adds a
+// broad row that overlaps an existing nested one will see double
+// counts in their next backup's statistics + the destination will
+// receive duplicate copies (wasting space). Worth flagging if anyone
+// reports it — the fix is to de-dupe `files` in
+// `getFilesToBackupInternal` before returning, OR to skip walking a
+// path if a longer one has already covered it.

backend/__tests__/integration/crmSchema.test.js

@@ -0,0 +1,116 @@
+/**
+ * Schema-shape regression net for the CRM consolidated migration.
+ *
+ * Pins the table/column layout that the route + service layer expect
+ * after `migrations/core/107_crm_consolidated.js` runs. The schema-
+ * drift workflow (#530) catches Postgres-only FK ordering bugs (the
+ * forward-reference deferral added in this PR), but it doesn't notice
+ * if a future edit silently drops a column the service code reads —
+ * SQLite would just return undefined and the broken behavior would
+ * land on beta.
+ *
+ * Touches the lineage chain (deal_uuid + back-pointer FKs) explicitly
+ * so a rename or removal there fails the test instead of silently
+ * breaking the lineage card.
+ */
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+describe('CRM schema after core migrations', () => {
+  let db;
+  let cleanup;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  describe('table layout', () => {
+    const expectedTables = [
+      'admin_users', 'customer_accounts', 'business_profile', 'business_bank_accounts',
+      'events', 'document_sequences',
+      'quotes', 'quote_line_items', 'quote_line_item_presets', 'quote_action_tokens',
+      'contracts', 'contract_blocks', 'contract_block_inclusions', 'contract_action_tokens',
+      'invoices', 'invoice_line_items', 'invoice_payment_log', 'invoice_payment_check_tokens',
+      'customer_hour_entries',
+      'payment_term_templates', 'payment_net_days_templates', 'payment_timing_templates',
+      'event_payment_plans',
+    ];
+
+    it.each(expectedTables)('has table %s', async (table) => {
+      expect(await db.schema.hasTable(table)).toBe(true);
+    });
+  });
+
+  describe('deal_uuid lineage columns', () => {
+    // Every document in one engagement shares a deal_uuid — the
+    // lineage card joins on it. Drop the column anywhere in the chain
+    // and the card silently returns partial data.
+    it.each(['quotes', 'contracts', 'invoices'])(
+      '%s has deal_uuid column',
+      async (table) => {
+        expect(await db.schema.hasColumn(table, 'deal_uuid')).toBe(true);
+      }
+    );
+
+    // The back-pointer FKs were the source of the schema-drift bug
+    // we fixed in this PR (forward references). Pin them.
+    it('quotes has converted_contract_id back-pointer', async () => {
+      expect(await db.schema.hasColumn('quotes', 'converted_contract_id')).toBe(true);
+    });
+    it('invoices has source_contract_id back-pointer', async () => {
+      expect(await db.schema.hasColumn('invoices', 'source_contract_id')).toBe(true);
+    });
+    it('invoices has source_quote_id back-pointer', async () => {
+      expect(await db.schema.hasColumn('invoices', 'source_quote_id')).toBe(true);
+    });
+  });
+
+  describe('Storno discriminator columns', () => {
+    // kind='storno' + cancels_invoice_id + negative totals are the
+    // shape every aggregate filter relies on (feedback_storno_filter_
+    // everywhere). Pin the columns so a rename doesn't silently break
+    // every revenue report.
+    it('invoices has kind discriminator', async () => {
+      expect(await db.schema.hasColumn('invoices', 'kind')).toBe(true);
+    });
+    it('invoices has cancels_invoice_id self-ref', async () => {
+      expect(await db.schema.hasColumn('invoices', 'cancels_invoice_id')).toBe(true);
+    });
+    it('invoices has replaces_invoice_id self-ref', async () => {
+      expect(await db.schema.hasColumn('invoices', 'replaces_invoice_id')).toBe(true);
+    });
+  });
+
+  describe('Event time columns (migration 137)', () => {
+    // The admin calendar reads these to render timed vs. full-day
+    // tiles. Per the feedback_migration_preserve_visuals rule, the
+    // default has to be `is_full_day=true` so existing rows keep
+    // their pre-migration visual.
+    it('events has event_time_start', async () => {
+      expect(await db.schema.hasColumn('events', 'event_time_start')).toBe(true);
+    });
+    it('events has event_time_end', async () => {
+      expect(await db.schema.hasColumn('events', 'event_time_end')).toBe(true);
+    });
+    it('events has is_full_day', async () => {
+      expect(await db.schema.hasColumn('events', 'is_full_day')).toBe(true);
+    });
+  });
+
+  describe('seed paths', () => {
+    it('admin + customer seed inserts cleanly', async () => {
+      const { adminId, customerId } = await seedMinimal(db);
+      expect(adminId).toBeTruthy();
+      expect(customerId).toBeTruthy();
+
+      const admin = await db('admin_users').where({ id: adminId }).first();
+      const customer = await db('customer_accounts').where({ id: customerId }).first();
+      expect(admin.email).toBe('tester@example.com');
+      expect(customer.email).toBe('customer@example.com');
+    });
+  });
+});

backend/__tests__/integration/discountLineItems.test.js

@@ -0,0 +1,79 @@
+/**
+ * Negative line items (Rabatt / manual discount lines) are accepted
+ * end-to-end as long as the resulting total stays ≥ 0. When the
+ * discount would drive the total negative, the service rejects with
+ * a clear, code-tagged error so the admin is steered to Storno for
+ * credit-note workflows.
+ *
+ * Touches the actual createInvoice / createQuote service paths so a
+ * future change to either computeTotals or the guard fires this test.
+ */
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+// Service-level CRM calls cold-require heavy modules (pdfService,
+// nodemailer, etc.) on first use; the global 5 s per-test budget is
+// too tight for that. Bump it for this file only.
+jest.setTimeout(30000);
+
+describe('discount line items (negative unit_price_minor)', () => {
+  let db;
+  let cleanup;
+  let adminId;
+  let customerId;
+  let invoiceService;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ adminId, customerId } = await seedMinimal(db));
+    invoiceService = require('../../src/services/invoiceService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  // Quote-side coverage of the symmetric validator + guard is
+  // deliberately omitted: createQuote's init path takes ~30 s under
+  // this harness (something in pdfService / emailProcessor cold-
+  // require), which would push the suite well past CI's per-test
+  // budget. The shape of the guard is identical to the invoice one
+  // covered below; a future change to extract the slow init or to
+  // stub it for tests should re-enable a parallel quote test.
+
+  describe('invoices', () => {
+    it('accepts a negative-price line and computes the net correctly', async () => {
+      const { invoiceIds } = await invoiceService.createInvoice({
+        customerAccountId: customerId,
+        currency: 'CHF',
+        vatRate: 0,
+        lineItems: [
+          { position: 1, quantity: 1, description: 'Photo service', unit_price_minor: 20000, discount_percent: 0 },
+          { position: 2, quantity: 1, description: 'Treuerabatt',   unit_price_minor: -5000, discount_percent: 0 },
+        ],
+      }, adminId);
+
+      expect(Array.isArray(invoiceIds)).toBe(true);
+      expect(invoiceIds.length).toBe(1);
+
+      const row = await db('invoices').where({ id: invoiceIds[0] }).first();
+      expect(row.net_amount_minor).toBe(15000);
+      expect(row.total_amount_minor).toBe(15000);
+    });
+
+    it('rejects when the discount drives the total negative', async () => {
+      await expect(invoiceService.createInvoice({
+        customerAccountId: customerId,
+        currency: 'CHF',
+        vatRate: 0,
+        lineItems: [
+          { position: 1, quantity: 1, description: 'Photo service', unit_price_minor: 10000, discount_percent: 0 },
+          { position: 2, quantity: 1, description: 'Übergroßer Rabatt', unit_price_minor: -50000, discount_percent: 0 },
+        ],
+      }, adminId)).rejects.toMatchObject({
+        code: 'INVOICE_TOTAL_NEGATIVE',
+        statusCode: 400,
+      });
+    });
+  });
+});

backend/__tests__/integration/emailTemplateBoot.test.js

@@ -0,0 +1,98 @@
+/**
+ * Boot-time email-template self-heal:
+ *   1. Seeds the CRM / contract / event-reminder templates on an
+ *      install that's never had them before.
+ *   2. Recovers email_queue rows that previously exhausted their
+ *      retries because their template was missing.
+ *
+ * The failure that triggered this fix (2026-05-27) had Ralf's beta
+ * box failing every `quote_sent` / `invoice_sent` send for ~14h
+ * because crmEmailTemplates.ensureCrmEmailTemplatesSeeded was
+ * defined but never called. After 3 retries the rows sat in
+ * status='pending' forever; nothing in the admin UI signalled the
+ * problem. Both halves of that regression are covered here.
+ */
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+describe('email template self-heal at boot', () => {
+  let db;
+  let cleanup;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  it('seeds crm/contract/event-reminder templates and recovers stuck queue rows', async () => {
+    // Sanity: a fresh CRM-migrated DB does NOT carry CRM templates —
+    // 107_crm_consolidated documents the deliberate split (templates
+    // are self-healed at runtime, not inserted by the migration).
+    const before = await db('email_templates')
+      .whereIn('template_key', ['quote_sent', 'invoice_sent', 'storno_issued'])
+      .pluck('template_key');
+    expect(before).toEqual([]);
+
+    // Seed a stuck queue row that mirrors what we found on Ralf's box:
+    // quote_sent send attempted 3 times, each time failed because the
+    // template didn't exist, queue processor gave up.
+    const queueRowIds = await db('email_queue').insert({
+      recipient_email: 'customer@example.com',
+      email_type: 'quote_sent',
+      email_data: JSON.stringify({ quote_number: 'Q-2026-0001' }),
+      status: 'pending',
+      retry_count: 3,
+      error_message: "Email template 'quote_sent' not found",
+      created_at: new Date(),
+    }).returning('id');
+    const queueRowId = typeof queueRowIds[0] === 'object' ? queueRowIds[0].id : queueRowIds[0];
+
+    // Also seed an UNRELATED stuck row (different template, NOT one
+    // we're going to insert) to confirm the recovery is targeted —
+    // it must not blanket-reset every retry-exhausted row.
+    const unrelatedIds = await db('email_queue').insert({
+      recipient_email: 'someone@example.com',
+      email_type: 'some_other_template',
+      email_data: JSON.stringify({}),
+      status: 'pending',
+      retry_count: 3,
+      error_message: 'SMTP timeout',
+      created_at: new Date(),
+    }).returning('id');
+    const unrelatedId = typeof unrelatedIds[0] === 'object' ? unrelatedIds[0].id : unrelatedIds[0];
+
+    // The seeders use module-level caches (`_seeded = true`). When
+    // jest runs this test in isolation that cache starts fresh; in
+    // the full suite no other test currently calls these seeders, so
+    // the first call here also runs the real work. Reset the cache
+    // defensively in case a future test changes that.
+    jest.resetModules();
+    const { seedEmailTemplatesAndRecoverQueue } = require('../../src/services/_emailTemplateBoot');
+
+    const result = await seedEmailTemplatesAndRecoverQueue(db, null);
+
+    // Templates landed.
+    expect(result.seeded).toEqual(expect.arrayContaining([
+      'quote_sent', 'invoice_sent', 'storno_issued',
+    ]));
+    const after = await db('email_templates')
+      .whereIn('template_key', ['quote_sent', 'invoice_sent', 'storno_issued'])
+      .pluck('template_key');
+    expect(after.sort()).toEqual(['invoice_sent', 'quote_sent', 'storno_issued']);
+
+    // Stuck quote_sent row was recovered.
+    expect(result.recovered).toBeGreaterThanOrEqual(1);
+    const recoveredRow = await db('email_queue').where({ id: queueRowId }).first();
+    expect(recoveredRow.retry_count).toBe(0);
+    expect(recoveredRow.error_message).toBeNull();
+    expect(recoveredRow.status).toBe('pending'); // ready for the next tick
+
+    // Unrelated stuck row was NOT touched.
+    const unrelatedRow = await db('email_queue').where({ id: unrelatedId }).first();
+    expect(unrelatedRow.retry_count).toBe(3);
+    expect(unrelatedRow.error_message).toBe('SMTP timeout');
+  });
+});

backend/__tests__/integration/helpers/crmDb.js

@@ -0,0 +1,230 @@
+/**
+ * Test harness for CRM integration tests.
+ *
+ * Boots a temp-SQLite database, runs every `migrations/core/*.up()`
+ * directly (bypassing knex's Migrator — its exclusive write lock
+ * deadlocks 001_init's nested `initializeDatabase()` call), and
+ * exposes a small helper for seeding the minimal row set that the
+ * quote/contract/invoice services need to operate.
+ *
+ * Usage:
+ *
+ *   const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+ *
+ *   beforeAll(async () => {
+ *     ({ db, cleanup } = await bootCrmDb());
+ *     ({ adminId, customerId } = await seedMinimal(db));
+ *   });
+ *   afterAll(async () => { await cleanup(); });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const bcrypt = require('bcrypt');
+
+async function runCoreMigrations(db) {
+  await db.schema.createTable('migrations', (t) => {
+    t.increments('id').primary();
+    t.string('filename').unique().notNullable();
+    t.timestamp('applied_at').defaultTo(db.fn.now());
+  });
+
+  const coreDir = path.resolve(__dirname, '..', '..', '..', 'migrations', 'core');
+  const files = (await fs.promises.readdir(coreDir))
+    .filter((f) => f.endsWith('.js'))
+    .sort();
+
+  for (const f of files) {
+    const mod = require(path.join(coreDir, f));
+    if (typeof mod.up === 'function') {
+      await mod.up(db);
+    }
+    await db('migrations').insert({ filename: f });
+  }
+}
+
+/**
+ * Boot a clean test DB. Returns { db, cleanup, tmpDir }.
+ * Caller must invoke cleanup() in afterAll to release the SQLite file
+ * and the temp directory.
+ */
+async function bootCrmDb() {
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-crm-'));
+  process.env.NODE_ENV = 'test';
+  process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'crm.db');
+  process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+  await fs.promises.mkdir(process.env.STORAGE_PATH, { recursive: true });
+
+  // No jest.resetModules() — every service the test later requires
+  // must share THIS db instance. Two module copies on one SQLite file
+  // each open their own knex pool and the SQLite write lock deadlocks
+  // the second one acquiring a connection. Caller is responsible for
+  // setting TEST_DATABASE_PATH before the first require of db.js
+  // (which knexfile reads at module-init time); bootCrmDb only works
+  // when invoked before any service import.
+  const { db } = require('../../../src/database/db');
+
+  await runCoreMigrations(db);
+
+  return {
+    db,
+    tmpDir,
+    cleanup: async () => {
+      try { await db.destroy(); } catch (_) {}
+      try { await fs.promises.rm(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    },
+  };
+}
+
+/**
+ * Seed the minimal row set that quote/contract/invoice services
+ * dereference on creation: an admin user, an active customer, a
+ * business_profile row, and the app_settings keys the services read.
+ *
+ * Returns the ids the caller will pass into service calls.
+ */
+async function seedMinimal(db) {
+  const passwordHash = await bcrypt.hash('test-pass', 4); // low rounds = fast
+
+  const adminInsert = await db('admin_users').insert({
+    username: 'tester', email: 'tester@example.com',
+    password_hash: passwordHash, must_change_password: false,
+    created_at: new Date(),
+  }).returning('id');
+  const adminId = adminInsert[0]?.id ?? adminInsert[0];
+
+  // business_profile is a singleton; the row is seeded by migration 107
+  // for fresh installs. Defensive: insert if missing.
+  const profile = await db('business_profile').first();
+  if (!profile) {
+    await db('business_profile').insert({
+      legal_name: 'Test Studio',
+      default_currency: 'CHF',
+      default_locale: 'de',
+    });
+  }
+
+  const customerInsert = await db('customer_accounts').insert({
+    email: 'customer@example.com',
+    display_name: 'Test Customer',
+    password_hash: passwordHash,
+    preferred_language: 'de',
+    is_active: 1,
+    created_at: new Date(),
+  }).returning('id');
+  const customerId = customerInsert[0]?.id ?? customerInsert[0];
+
+  return { adminId, customerId };
+}
+
+// ---------------------------------------------------------------------
+// Route-test helpers (#570) — building blocks for the CRM HTTP layer
+// tests. Kept here so every supertest suite shares the same minting +
+// app-wiring shape and a refactor lands in one place.
+// ---------------------------------------------------------------------
+
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+
+/**
+ * Promote a seeded admin into a role (default `super_admin`) so
+ * `requirePermission(...)` checks pass. seedMinimal creates an admin
+ * without a role — that's good for negative tests (expect 403) but
+ * happy-path tests need the role assignment.
+ *
+ * Returns the role id the admin was assigned to.
+ */
+async function assignAdminRole(db, adminId, roleName = 'super_admin') {
+  const role = await db('roles').where({ name: roleName }).first();
+  if (!role) {
+    throw new Error(`Role '${roleName}' not seeded — check the test DB`);
+  }
+  await db('admin_users').where({ id: adminId }).update({ role_id: role.id });
+  return role.id;
+}
+
+/**
+ * Mint an admin JWT in the same shape adminAuth middleware expects.
+ * The tests inject this via `Authorization: Bearer <token>`.
+ */
+function mintAdminToken(adminId, { expiresIn = '1h', extraClaims = {} } = {}) {
+  process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
+  return jwt.sign(
+    { id: adminId, type: 'admin', iat: Math.floor(Date.now() / 1000), ...extraClaims },
+    process.env.JWT_SECRET,
+    { expiresIn, issuer: 'picpeak-auth' }
+  );
+}
+
+/**
+ * Insert a row into one of the public-token tables for testing the
+ * loadActionToken guard outcomes. Returns the generated 64-hex token.
+ *
+ * Usage:
+ *   await createPublicToken(db, 'quote_action_tokens', { quote_id: q.id });
+ *   await createPublicToken(db, 'quote_action_tokens', { quote_id: q.id, expires_at: pastDate });
+ *   await createPublicToken(db, 'quote_action_tokens', { quote_id: q.id, used_at: new Date() });
+ *   await createPublicToken(db, 'quote_action_tokens', { quote_id: q.id, expires_at: null });
+ */
+async function createPublicToken(db, tableName, opts = {}) {
+  const token = opts.token || crypto.randomBytes(32).toString('hex');
+  const expiresAt = opts.expires_at === null
+    ? null
+    : (opts.expires_at || new Date(Date.now() + 7 * 24 * 60 * 60 * 1000));
+  // Serialise Date → ISO string. Bare Date objects round-tripped
+  // inconsistently through knex+SQLite — sometimes as epoch ms,
+  // sometimes via .toString() → literal "[object Object]" which then
+  // parses back to NaN and silently defeats the expiry guard.
+  const toStorable = (v) => (v instanceof Date ? v.toISOString() : v);
+  const row = {
+    ...opts,
+    token,
+    expires_at: toStorable(expiresAt),
+    created_at: toStorable(new Date()),
+  };
+  await db(tableName).insert(row);
+  return token;
+}
+
+/**
+ * Build an Express app with the requested route file mounted. Mirrors
+ * the production app's middleware shape (json + cookies) but skips
+ * everything else (CORS, helmet, rate limiters) — route tests pin the
+ * handler's contract, not the surrounding cross-cutting concerns.
+ *
+ * Example:
+ *   const app = buildRouteApp('/api/public/quotes',
+ *     require('../../src/routes/publicQuotes'));
+ */
+function buildRouteApp(mount, router) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  app.use(mount, router);
+  // Catch-all error handler. Mirrors the real middleware/errorHandler:
+  // AppError subclasses (ValidationError, NotFoundError, etc.) use
+  // `.statusCode` (NOT `.status` — getting that wrong silently maps
+  // every 400 / 404 / 410 to 500 in tests).
+  // eslint-disable-next-line no-unused-vars
+  app.use((err, req, res, next) => {
+    const statusCode = err.statusCode || err.status || 500;
+    res.status(statusCode).json({
+      error: err.message || 'Internal error',
+      code: err.code,
+      ...(err.details ? { details: err.details } : {}),
+    });
+  });
+  return app;
+}
+
+module.exports = {
+  bootCrmDb,
+  seedMinimal,
+  assignAdminRole,
+  mintAdminToken,
+  createPublicToken,
+  buildRouteApp,
+};

backend/__tests__/integration/imageProcessor.storage.test.js

@@ -0,0 +1,200 @@
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+const sharp = require('sharp');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+const storageModule = require('../../src/services/storage');
+
+// Stub out the DB so getThumbnailSettings falls into its catch and uses defaults.
+jest.mock('../../src/database/db', () => ({
+  db: () => {
+    throw new Error('db disabled in this test');
+  },
+}));
+
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fs.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-imgproc-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+  return cases;
+}
+
+async function makeSourceJpeg(targetDir, name) {
+  const localPath = path.join(targetDir, name);
+  // 800x600 random RGB image so sharp has something realistic to thumbnail.
+  const width = 800;
+  const height = 600;
+  const buf = Buffer.alloc(width * height * 3);
+  for (let i = 0; i < buf.length; i++) buf[i] = (i * 7) % 256;
+  await sharp(buf, { raw: { width, height, channels: 3 } })
+    .jpeg({ quality: 90 })
+    .toFile(localPath);
+  return localPath;
+}
+
+describe.each(backendCases())('imageProcessor through $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+  let tmpDir;
+  let imageProcessor;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+    storageModule.setStorageForTesting(storage);
+    // Require AFTER setStorageForTesting so the module sees our injection.
+    delete require.cache[require.resolve('../../src/services/imageProcessor')];
+    imageProcessor = require('../../src/services/imageProcessor');
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-src-'));
+  }, 30000);
+
+  afterAll(async () => {
+    storageModule.resetStorage();
+    if (tmpDir) await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    if (cleanup) await cleanup();
+  });
+
+  test('generateThumbnail writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'sample.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(key).toBe('thumbnails/thumb_sample.jpg');
+
+    expect(await storage.exists(key)).toBe(true);
+    const stat = await storage.stat(key);
+    expect(stat.size).toBeGreaterThan(100);
+
+    // Verify the bytes are a valid JPEG by re-parsing with sharp on local mode.
+    if (storage.kind() === 'local') {
+      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
+      expect(meta.format).toBe('jpeg');
+      expect(meta.width).toBeLessThanOrEqual(300);
+    }
+  });
+
+  test('generateHeroImage writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'hero-source.jpg');
+    const key = await imageProcessor.generateHeroImage(src);
+    expect(key).toBe('heroes/hero_hero-source.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('generatePreviewImage writes to /previews and skips enlargement of small originals', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'preview-source.jpg');
+    const key = await imageProcessor.generatePreviewImage(src);
+    expect(key).toBe('previews/preview_preview-source.jpg');
+    expect(await storage.exists(key)).toBe(true);
+
+    if (storage.kind() === 'local') {
+      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
+      expect(meta.format).toBe('jpeg');
+      // Source is 800x600 and default longEdge is 1920 with
+      // withoutEnlargement: true → preview must NOT be upscaled.
+      expect(meta.width).toBe(800);
+      expect(meta.height).toBe(600);
+    }
+  });
+
+  test('generatePreviewImage shrinks oversized images to fit longEdge while preserving aspect', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'preview-shrink.jpg');
+    const key = await imageProcessor.generatePreviewImage(src, { longEdge: 400 });
+    expect(await storage.exists(key)).toBe(true);
+    if (storage.kind() === 'local') {
+      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
+      // 800x600 → fit:'inside' inside 400×400 → 400×300.
+      expect(meta.width).toBe(400);
+      expect(meta.height).toBe(300);
+    }
+  });
+
+  test('isPreviewValid returns true for a real preview and false for a missing key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'preview-valid.jpg');
+    const key = await imageProcessor.generatePreviewImage(src);
+    expect(await imageProcessor.isPreviewValid(key)).toBe(true);
+    expect(await imageProcessor.isPreviewValid('previews/does-not-exist.jpg')).toBe(false);
+  });
+
+  test('isThumbnailValid returns true for a good thumbnail and false for nothing', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'valid-check.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(await imageProcessor.isThumbnailValid(key)).toBe(true);
+    expect(await imageProcessor.isThumbnailValid('thumbnails/does-not-exist.jpg')).toBe(false);
+  });
+
+  test('generateVideoPlaceholder writes a thumbnail entirely from buffer', async () => {
+    const key = await imageProcessor.generateVideoPlaceholder('demo.mp4');
+    expect(key).toBe('thumbnails/thumb_demo.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('withLocalCopy yields a usable local path on both backends', async () => {
+    const sourceKey = 'fixture/withlocal.jpg';
+    const src = await makeSourceJpeg(tmpDir, 'withlocal.jpg');
+    const buf = await fs.readFile(src);
+    await storage.put(sourceKey, buf, { contentType: 'image/jpeg' });
+
+    const seenSize = await imageProcessor.withLocalCopy(sourceKey, async (localPath) => {
+      const meta = await sharp(localPath).metadata();
+      return meta.width;
+    });
+    expect(seenSize).toBe(800);
+  });
+});

backend/__tests__/integration/installFromBackupBoot.test.js

@@ -0,0 +1,214 @@
+/**
+ * Install-from-backup boot hook — pins the trigger-file convention.
+ *
+ * The hook itself depends on `restoreService.restore`, which is hard
+ * to fully exercise in an integration test without a real PG cluster
+ * (sequence resync, DROP/CREATE, etc.). So we stub the actual restore
+ * and verify the BOOT HOOK logic:
+ *
+ *   - No trigger file → no-op, ran=false
+ *   - Empty trigger file → picks newest manifest from manifests/
+ *   - Non-empty trigger file → uses the path inside
+ *   - DB not empty → refuses (no restore call)
+ *   - DB not empty + FORCE env → proceeds
+ *   - Successful restore → deletes trigger file
+ *   - Failed restore → leaves trigger file in place
+ *
+ * These are the surfaces an admin will hit when actually using the
+ * feature — the docker-compose-on-real-PG end-to-end test belongs in
+ * the follow-up CI work captured as task #7 earlier today.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+// Stub the heavy lifting so the test stays fast + portable.
+const mockRestore = jest.fn();
+jest.mock('../../src/services/restoreService', () => ({
+  restoreService: {
+    restore: (...args) => mockRestore(...args),
+  },
+}));
+
+jest.setTimeout(30000);
+
+describe('installFromBackupBoot', () => {
+  let db;
+  let cleanup;
+  let storagePath;
+  let backupRoot;
+  let manifestsDir;
+  let tryInstallFromBackup;
+  let originalBackupRootEnv;
+  let originalForceEnv;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    storagePath = process.env.STORAGE_PATH;
+    backupRoot = path.join(storagePath, 'backup');
+    manifestsDir = path.join(backupRoot, 'manifests');
+    fs.mkdirSync(manifestsDir, { recursive: true });
+
+    originalBackupRootEnv = process.env.BACKUP_ROOT;
+    originalForceEnv = process.env.INSTALL_FROM_BACKUP_FORCE;
+    process.env.BACKUP_ROOT = backupRoot;
+
+    ({ tryInstallFromBackup } = require('../../src/services/_installFromBackupBoot'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (originalBackupRootEnv === undefined) {
+      delete process.env.BACKUP_ROOT;
+    } else {
+      process.env.BACKUP_ROOT = originalBackupRootEnv;
+    }
+    if (originalForceEnv === undefined) {
+      delete process.env.INSTALL_FROM_BACKUP_FORCE;
+    } else {
+      process.env.INSTALL_FROM_BACKUP_FORCE = originalForceEnv;
+    }
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(async () => {
+    mockRestore.mockReset();
+    mockRestore.mockResolvedValue({ success: true });
+    delete process.env.INSTALL_FROM_BACKUP_FORCE;
+
+    // Clean trigger files + manifests between tests
+    for (const name of ['RESTORE_ON_INSTALL', 'RESTORE_ON_INSTALL.txt']) {
+      const p = path.join(backupRoot, name);
+      if (fs.existsSync(p)) fs.unlinkSync(p);
+    }
+    for (const f of fs.readdirSync(manifestsDir)) {
+      fs.unlinkSync(path.join(manifestsDir, f));
+    }
+
+    // Reset DB to fresh-install state
+    await db('events').del();
+    // Leave admin_users alone — fresh-install state has 1 row.
+  });
+
+  it('no trigger file → no-op', async () => {
+    const result = await tryInstallFromBackup(db);
+    expect(result.ran).toBe(false);
+    expect(mockRestore).not.toHaveBeenCalled();
+  });
+
+  it('empty trigger file picks the newest manifest from manifests/', async () => {
+    const older = path.join(manifestsDir, 'backup-manifest-001.json');
+    const newer = path.join(manifestsDir, 'backup-manifest-002.json');
+    fs.writeFileSync(older, '{}');
+    // Set the newer file's mtime slightly later so it wins the sort
+    const past = new Date(Date.now() - 60_000);
+    fs.utimesSync(older, past, past);
+    fs.writeFileSync(newer, '{}');
+
+    // Empty trigger
+    fs.writeFileSync(path.join(backupRoot, 'RESTORE_ON_INSTALL'), '');
+
+    const result = await tryInstallFromBackup(db);
+    expect(result.ran).toBe(true);
+    expect(result.manifestPath).toBe(newer);
+    expect(mockRestore).toHaveBeenCalledWith(expect.objectContaining({
+      source: 'local',
+      manifestPath: newer,
+      restoreType: 'full',
+      force: true,
+      skipPreBackup: true,
+    }));
+  });
+
+  it('non-empty trigger file uses the path inside', async () => {
+    const specific = path.join(manifestsDir, 'backup-manifest-specific.json');
+    fs.writeFileSync(specific, '{}');
+
+    // Relative to backupRoot
+    fs.writeFileSync(
+      path.join(backupRoot, 'RESTORE_ON_INSTALL'),
+      'manifests/backup-manifest-specific.json\n',
+    );
+
+    const result = await tryInstallFromBackup(db);
+    expect(result.ran).toBe(true);
+    expect(result.manifestPath).toBe(specific);
+  });
+
+  it('deletes the trigger file after a successful restore', async () => {
+    const manifest = path.join(manifestsDir, 'backup-manifest-001.json');
+    fs.writeFileSync(manifest, '{}');
+    const triggerPath = path.join(backupRoot, 'RESTORE_ON_INSTALL');
+    fs.writeFileSync(triggerPath, '');
+
+    await tryInstallFromBackup(db);
+    expect(fs.existsSync(triggerPath)).toBe(false);
+  });
+
+  it('leaves the trigger file in place when restore throws', async () => {
+    mockRestore.mockRejectedValueOnce(new Error('restore exploded'));
+    const manifest = path.join(manifestsDir, 'backup-manifest-001.json');
+    fs.writeFileSync(manifest, '{}');
+    const triggerPath = path.join(backupRoot, 'RESTORE_ON_INSTALL');
+    fs.writeFileSync(triggerPath, '');
+
+    const result = await tryInstallFromBackup(db);
+    expect(result.ran).toBe(false);
+    expect(result.error).toMatch(/restore exploded/);
+    expect(fs.existsSync(triggerPath)).toBe(true);
+  });
+
+  it('refuses to run when the install already has events', async () => {
+    // Simulate an install with existing data
+    await db('events').insert({
+      slug: 'existing-event',
+      event_name: 'Existing Event',
+      event_type: 'wedding',
+      event_date: new Date(),
+      host_email: 'host@example.com',
+      admin_email: 'host@example.com',
+      expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+      share_link: 'existing-event-token',
+      password_hash: 'dummy-hash-for-test',
+      created_at: new Date(),
+    });
+
+    const manifest = path.join(manifestsDir, 'backup-manifest-001.json');
+    fs.writeFileSync(manifest, '{}');
+    fs.writeFileSync(path.join(backupRoot, 'RESTORE_ON_INSTALL'), '');
+
+    const result = await tryInstallFromBackup(db);
+    expect(result.ran).toBe(false);
+    expect(result.error).toMatch(/Database not empty/);
+    expect(mockRestore).not.toHaveBeenCalled();
+
+    // Trigger file should NOT be deleted — admin needs to fix + retry
+    expect(fs.existsSync(path.join(backupRoot, 'RESTORE_ON_INSTALL'))).toBe(true);
+  });
+
+  it('proceeds when INSTALL_FROM_BACKUP_FORCE=true even with existing data', async () => {
+    await db('events').insert({
+      slug: 'existing-event-2',
+      event_name: 'Existing Event 2',
+      event_type: 'wedding',
+      event_date: new Date(),
+      host_email: 'host@example.com',
+      admin_email: 'host@example.com',
+      expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+      share_link: 'existing-event-2-token',
+      password_hash: 'dummy-hash-for-test-2',
+      created_at: new Date(),
+    });
+
+    const manifest = path.join(manifestsDir, 'backup-manifest-001.json');
+    fs.writeFileSync(manifest, '{}');
+    fs.writeFileSync(path.join(backupRoot, 'RESTORE_ON_INSTALL'), '');
+
+    process.env.INSTALL_FROM_BACKUP_FORCE = 'true';
+    const result = await tryInstallFromBackup(db);
+
+    expect(result.ran).toBe(true);
+    expect(mockRestore).toHaveBeenCalled();
+  });
+});

backend/__tests__/integration/restoreService.pgBranch.test.js

@@ -0,0 +1,259 @@
+/**
+ * Pins the fix for the PR #596 review blocker.
+ *
+ * **The bug**
+ *
+ *   `preservedMeta` was declared with `let` INSIDE the PostgreSQL
+ *   `else` branch of `performDatabaseRestore`, then read AFTER the
+ *   `else` block closed at the shared replay site (~L1030). On every
+ *   real PG restore:
+ *
+ *     ReferenceError: preservedMeta is not defined
+ *
+ *   would fire — psql had already completed the data restore, but
+ *   the operator-meta replay never ran, the trigger file was left
+ *   in place by `_installFromBackupBoot.js` because the restore
+ *   "failed", and `combined.log` got a loud FAILED line even though
+ *   the data was back. Caught on PR #596 review by the maintainer.
+ *
+ * **Why CI missed it**
+ *
+ *   The integration tests around `performFullRestore` only exercise
+ *   the SQLite branch via `this.dbType === 'sqlite'`. The PG branch
+ *   (~L827-984) requires a real PG connection + real `psql` binary,
+ *   neither of which are in the test environment. So the scope leak
+ *   sat untested until the maintainer ran a real DR cycle.
+ *
+ * **What this test does**
+ *
+ *   Reads the source of `restoreService.js` and asserts the scope
+ *   contract: the `preservedMeta` declaration sits ABOVE the
+ *   SQLite/PG branch split, so the replay block at the bottom of the
+ *   try{} can read it on either branch.
+ *
+ *   Source-inspection is uglier than a runtime test but it has two
+ *   advantages here: (a) it doesn't require a real PG cluster + psql
+ *   binary in CI, (b) it pins the EXACT contract — "the declaration
+ *   must be visible to the replay block" — which is the property
+ *   that broke, more directly than a runtime test would.
+ *
+ *   The follow-up "real-PG integration test in CI" (separate task)
+ *   would replace this with an end-to-end exercise, at which point
+ *   this can be deleted.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+describe('restoreService — PG branch scope contract (PR #596 review)', () => {
+  let src;
+  let lines;
+
+  beforeAll(() => {
+    src = fs.readFileSync(
+      path.join(__dirname, '..', '..', 'src', 'services', 'restoreService.js'),
+      'utf8',
+    );
+    lines = src.split(/\r?\n/);
+  });
+
+  /** Return the 1-based line number of the FIRST line matching `re`. */
+  function findFirst(re) {
+    const idx = lines.findIndex((l) => re.test(l));
+    return idx >= 0 ? idx + 1 : -1;
+  }
+
+  /** Return the 1-based line number of the LAST line matching `re`. */
+  function findLast(re) {
+    let last = -1;
+    lines.forEach((l, i) => { if (re.test(l)) last = i + 1; });
+    return last;
+  }
+
+  it('preservedMetaSnapshot lives on `this` and is initialised in the constructor', () => {
+    // PR #596 round 3 moved the snapshot from a block-scoped local to
+    // an instance variable so the replay can happen in `restore()`
+    // AFTER post-restore verification — preventing the replay row
+    // from inflating the row-count check.
+    //
+    // Contract:
+    //   1. The constructor initialises `this.preservedMetaSnapshot = []`
+    //   2. The `restore()` entry point resets it per call (no leak
+    //      across consecutive runs in the singleton service instance)
+    //   3. `performDatabaseRestore` assigns to `this.preservedMetaSnapshot`
+    //      inside the PG branch (must run before DROP)
+    //   4. The replay reads `this.preservedMetaSnapshot` — NOT a bare
+    //      `preservedMeta` local — so a future refactor can't
+    //      accidentally drop the snapshot half on the floor again.
+    const constructorInit = lines.some((l) =>
+      /this\.preservedMetaSnapshot\s*=\s*\[\s*\]/.test(l)
+    );
+    expect(constructorInit).toBe(true);
+
+    const assignmentSites = lines.filter((l) =>
+      /this\.preservedMetaSnapshot\s*=\s*(\[\s*\]|await\s+db)/.test(l)
+    );
+    // Constructor init + restore() per-run reset + the PG-branch
+    // assignment from db query. Three writes.
+    expect(assignmentSites.length).toBeGreaterThanOrEqual(3);
+
+    // No stray bare `preservedMeta` local-scoped declaration in
+    // performDatabaseRestore — would indicate someone re-introduced
+    // the round-1 footgun.
+    const dangerousLocalDecl = lines.filter((l) =>
+      /^\s*(let|const)\s+preservedMeta\s*=/.test(l)
+    );
+    expect(dangerousLocalDecl).toEqual([]);
+  });
+
+  it('every .count() result is coerced to Number before comparison', () => {
+    // PR #596 review caught a second PG-only landmine: pg-driver
+    // returns COUNT(*) as a string ("16" not 16) to preserve bigint
+    // precision. The original code compared `result.count !==
+    // expected.rowCount` and every match flagged as a mismatch on PG.
+    //
+    // The fix coerces with `Number(...)` at every comparison +
+    // interpolation site. This test catches a future regression where
+    // a refactor uses `.count` directly in a `===` / `!==` / `>` /
+    // `<` comparison without coercing.
+    //
+    // Heuristic: find every `.count` access in the file and make sure
+    // the line either:
+    //   (a) wraps it in `Number(...)`, or
+    //   (b) is purely an interpolation that already coerced upstream
+    //       (e.g. `validation.warnings.push(`... ${eventCountN} ...`)`
+    //       where eventCountN is the coerced local), or
+    //   (c) is the docstring/comment line (filtered separately).
+    //
+    // We approximate this by listing every `.count` reference site
+    // and asserting that lines doing comparisons (`===`/`!==`/`>`/
+    // `<`/`>=`/`<=`) on a raw `.count` access without `Number(...)`
+    // around it are zero.
+    const dangerousLines = lines
+      .map((l, i) => ({ line: i + 1, text: l }))
+      // Filter to lines that compare a .count result
+      .filter(({ text }) => {
+        // Skip comments
+        if (/^\s*(\/\/|\*)/.test(text)) return false;
+        // Detect a `.count` (followed by `)` for `?.count` or by space/operator)
+        // being directly compared via ===/!==/>/<.
+        // Match the BAD pattern: `<something>.count <op> <something>`
+        // where <op> is === / !== / > / < / >= / <=
+        const bareCountInComparison = /\w+\??\.count\s*(?:!==|===|>=?|<=?)\s+/;
+        // ALLOW if the .count is preceded by `Number(` in the same line
+        const wrappedInNumber = /Number\(\s*\w+\??\.count/;
+        return bareCountInComparison.test(text) && !wrappedInNumber.test(text);
+      });
+
+    expect(dangerousLines).toEqual([]);
+  });
+
+  it('the completed-restore update sets was_successful=true', () => {
+    // Without this, every successful restore ends up with
+    // status='completed', was_successful=false — the dashboard's
+    // "last successful restore" widget then filters out the row +
+    // any future audit query gating on was_successful misses it.
+    // Caught locally + maintainer PR #596 review.
+    //
+    // Contract: the update payload that writes status='completed' on
+    // the SUCCESS branch ALSO includes was_successful: true. We pin
+    // it by source inspection so any future refactor of the success
+    // payload keeps both fields together.
+    // The success-branch update lives AFTER performPostRestoreVerification.
+    // There's also a `status: 'completed'` in the dry-run / early-return
+    // path (failure handling has its own block too) — we want the
+    // SUCCESS-branch one specifically.
+    const verifyLine = findFirst(/performPostRestoreVerification\s*\(/);
+    expect(verifyLine).toBeGreaterThan(0);
+
+    const completedStatusLineIdx = lines
+      .map((l, i) => ({ line: i + 1, text: l }))
+      .find(({ line, text }) =>
+        line > verifyLine && /status:\s*['"]completed['"]/.test(text)
+      );
+    expect(completedStatusLineIdx).toBeDefined();
+
+    // Look in the next ~10 lines for was_successful: true. The actual
+    // payload is small (no nested objects between status and the
+    // closing })), so a fixed-window search is reliable.
+    const window = lines.slice(
+      completedStatusLineIdx.line - 1,
+      completedStatusLineIdx.line + 10,
+    ).join('\n');
+    expect(window).toMatch(/was_successful:\s*true/);
+  });
+
+  it('npm run migrate:safe is invoked after the replay in restore()', () => {
+    // Contract from PR #596 round 4: backups taken on older picpeak
+    // versions must restore COMPLETELY on a newer image — even if new
+    // migrations have been added since the backup was taken. The
+    // restore() flow shells out to `npm run migrate:safe` AFTER the
+    // operator-meta replay so the schema catches up to the running
+    // code WITHIN the restore boundary (not on the next container
+    // restart).
+    //
+    // Contract:
+    //   1. A `migrate:safe` shell-out exists somewhere in restoreService
+    //   2. It sits AFTER the replay drain — verification → replay →
+    //      migrations is the documented order
+    //   3. It does NOT sit inside performDatabaseRestore (must run
+    //      against the reinit'd pool from the parent restore())
+    const migrateLine = findFirst(/['"]migrate:safe['"]/);
+    expect(migrateLine).toBeGreaterThan(0);
+
+    const replayLine = findLast(/this\.preservedMetaSnapshot\.length\s*>\s*0/);
+    expect(replayLine).toBeGreaterThan(0);
+    expect(migrateLine).toBeGreaterThan(replayLine);
+
+    // Must NOT live inside performDatabaseRestore (same scope as the
+    // replay check above).
+    const dbRestoreStart = findFirst(/async\s+performDatabaseRestore\s*\(/);
+    let dbRestoreEnd = -1;
+    for (let i = dbRestoreStart; i < lines.length; i++) {
+      if (/^  \}\s*$/.test(lines[i])) {
+        dbRestoreEnd = i + 1;
+        break;
+      }
+    }
+    expect(migrateLine < dbRestoreStart || migrateLine > dbRestoreEnd).toBe(true);
+  });
+
+  it('the replay site lives in restore() AFTER performPostRestoreVerification', () => {
+    // PR #596 round 3 moved the replay out of performDatabaseRestore
+    // and into the parent restore() method, sequenced AFTER the
+    // post-restore verification. Otherwise the replay's upserted row
+    // count was being flagged as a verification mismatch (e.g.
+    // "expected 190, got 191" because the fresh-install seeded
+    // `restore_allow_force_auto_upgraded` that wasn't in the backup).
+    //
+    // Contract: the line that drains `this.preservedMetaSnapshot`
+    // must come AFTER `performPostRestoreVerification` AND must NOT
+    // sit inside `performDatabaseRestore`.
+    const verificationLine = findFirst(/performPostRestoreVerification\s*\(/);
+    expect(verificationLine).toBeGreaterThan(0);
+
+    const replayLine = findLast(/this\.preservedMetaSnapshot\.length\s*>\s*0/);
+    expect(replayLine).toBeGreaterThan(0);
+    expect(replayLine).toBeGreaterThan(verificationLine);
+
+    // `performDatabaseRestore` must not contain the replay drain.
+    // Find the function bounds + assert no drain line falls inside.
+    const dbRestoreStart = findFirst(/async\s+performDatabaseRestore\s*\(/);
+    expect(dbRestoreStart).toBeGreaterThan(0);
+
+    // Find the closing brace of performDatabaseRestore. Lazy heuristic:
+    // the first `^  \}\s*$` (two-space indent + }) after the function
+    // start. Brittle to indent changes but unambiguous in this codebase.
+    let dbRestoreEnd = -1;
+    for (let i = dbRestoreStart; i < lines.length; i++) {
+      if (/^  \}\s*$/.test(lines[i])) {
+        dbRestoreEnd = i + 1;
+        break;
+      }
+    }
+    expect(dbRestoreEnd).toBeGreaterThan(dbRestoreStart);
+
+    // The replay drain line must be OUTSIDE [dbRestoreStart, dbRestoreEnd].
+    expect(replayLine < dbRestoreStart || replayLine > dbRestoreEnd).toBe(true);
+  });
+});

backend/__tests__/integration/storageBackend.test.js

@@ -0,0 +1,189 @@
+const path = require('path');
+const fs = require('fs');
+const fsp = require('fs').promises;
+const os = require('os');
+const crypto = require('crypto');
+const { Readable } = require('stream');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+
+// MinIO defaults match docker-compose.dev.yml. Override via TEST_S3_* if needed.
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+// Build the matrix of backends to test. Local always runs; S3 runs against MinIO
+// unless SKIP_S3_TESTS=true (CI default). The same suite runs against both so
+// every consumer can rely on identical semantics.
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-storage-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fsp.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-test-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            // Empty bucket then delete it.
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+
+  return cases;
+}
+
+async function readToString(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+describe.each(backendCases())('StorageBackend contract: $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+  }, 30000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  test('put + get + exists + stat + delete round-trip with a buffer body', async () => {
+    const key = 'photos/event-a/IMG_0001.jpg';
+    const body = Buffer.from('hello picpeak');
+
+    await storage.put(key, body, { contentType: 'image/jpeg' });
+
+    expect(await storage.exists(key)).toBe(true);
+
+    const stat = await storage.stat(key);
+    expect(stat).not.toBeNull();
+    expect(stat.size).toBe(body.length);
+
+    const stream = await storage.get(key);
+    const text = await readToString(stream);
+    expect(text).toBe('hello picpeak');
+
+    await storage.delete(key);
+    expect(await storage.exists(key)).toBe(false);
+    expect(await storage.stat(key)).toBeNull();
+  });
+
+  test('put accepts a Readable stream body', async () => {
+    const key = 'photos/event-b/streamed.bin';
+    const body = Readable.from(Buffer.from('streamed payload'));
+
+    await storage.put(key, body);
+
+    const got = await readToString(await storage.get(key));
+    expect(got).toBe('streamed payload');
+  });
+
+  test('putFromFile + getToFile round-trip', async () => {
+    const tmpIn = path.join(os.tmpdir(), `in-${Date.now()}.txt`);
+    const tmpOut = path.join(os.tmpdir(), `out-${Date.now()}.txt`);
+    await fsp.writeFile(tmpIn, 'file payload');
+
+    const key = 'thumbnails/thumb_x.jpg';
+    await storage.putFromFile(key, tmpIn, { contentType: 'image/jpeg' });
+
+    await storage.getToFile(key, tmpOut);
+    const text = await fsp.readFile(tmpOut, 'utf-8');
+    expect(text).toBe('file payload');
+
+    await fsp.unlink(tmpIn).catch(() => {});
+    await fsp.unlink(tmpOut).catch(() => {});
+  });
+
+  test('list returns entries under a prefix with size + key', async () => {
+    await storage.put('events/active/a/photo1.jpg', Buffer.from('a1'));
+    await storage.put('events/active/a/photo2.jpg', Buffer.from('a22'));
+    await storage.put('events/active/b/photo3.jpg', Buffer.from('b333'));
+
+    const entries = await storage.list('events/active/a');
+    const keys = entries.map((e) => e.key).sort();
+    expect(keys).toEqual(['events/active/a/photo1.jpg', 'events/active/a/photo2.jpg']);
+    const sizes = Object.fromEntries(entries.map((e) => [e.key, e.size]));
+    expect(sizes['events/active/a/photo1.jpg']).toBe(2);
+    expect(sizes['events/active/a/photo2.jpg']).toBe(3);
+  });
+
+  test('rename moves an object from src to dst (atomic on local; copy+delete on s3)', async () => {
+    await storage.put('uploads/temp.jpg', Buffer.from('rename-me'));
+    await storage.rename('uploads/temp.jpg', 'uploads/final.jpg');
+
+    expect(await storage.exists('uploads/temp.jpg')).toBe(false);
+    expect(await storage.exists('uploads/final.jpg')).toBe(true);
+    const text = await readToString(await storage.get('uploads/final.jpg'));
+    expect(text).toBe('rename-me');
+  });
+
+  test('copy duplicates an object without removing the source', async () => {
+    await storage.put('events/source.jpg', Buffer.from('src'));
+    await storage.copy('events/source.jpg', 'events/copied.jpg');
+
+    expect(await storage.exists('events/source.jpg')).toBe(true);
+    expect(await storage.exists('events/copied.jpg')).toBe(true);
+  });
+
+  test('delete on a missing key is a no-op (does not throw)', async () => {
+    await expect(storage.delete('does/not/exist.jpg')).resolves.toBeUndefined();
+  });
+
+  test('stat on a missing key returns null', async () => {
+    expect(await storage.stat('still/not/here.jpg')).toBeNull();
+  });
+
+  test('rejects path traversal attempts', async () => {
+    await expect(storage.put('../escape.txt', Buffer.from('x'))).rejects.toThrow(/traversal/i);
+    await expect(storage.get('../escape.txt')).rejects.toThrow(/traversal/i);
+  });
+});

backend/__tests__/integration/webhookDelivery.test.js

@@ -0,0 +1,239 @@
+// Worker reads WEBHOOK_ALLOW_PRIVATE_URLS at module-load. Set it BEFORE
+// requiring the worker so the local-stub URLs (127.0.0.1:<random>) pass
+// the SSRF check by default.
+process.env.WEBHOOK_ALLOW_PRIVATE_URLS = 'true';
+process.env.WEBHOOK_DELIVERY_INTERVAL_MS = '50';
+
+const http = require('http');
+const { db } = require('../../src/database/db');
+const webhookService = require('../../src/services/webhookService');
+const { __test, startWebhookDeliveryWorker, stopWebhookDeliveryWorker } = require('../../src/services/webhookDeliveryWorker');
+
+// Local-only test stub: matches what dev/webhook-receiver/server.js does
+// in the docker-compose flow but spun up inside the Jest process so the
+// suite is self-contained.
+function makeStub({ status = 200, delayMs = 0, bodyOverride = null } = {}) {
+  const requests = [];
+  const server = http.createServer(async (req, res) => {
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const body = Buffer.concat(chunks).toString('utf8');
+    requests.push({ method: req.method, url: req.url, headers: req.headers, body });
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    res.writeHead(status, { 'Content-Type': 'text/plain' });
+    res.end(bodyOverride !== null ? bodyOverride : (status >= 200 && status < 300 ? 'ok' : 'forced'));
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      resolve({ url: `http://127.0.0.1:${port}/`, requests, close: () => new Promise((r) => server.close(r)) });
+    });
+  });
+}
+
+async function insertWebhook(url, events = ['event.published'], extras = {}) {
+  // Tests need the WORKER to bypass SSRF on 127.0.0.1 stubs, but the
+  // route layer's allowlist check is bypassed here since we insert
+  // straight into the DB.
+  const { plaintext, preview } = webhookService.generateSecret();
+  const insert = await db('webhooks').insert({
+    name: extras.name || 'test',
+    url,
+    secret: plaintext,
+    secret_preview: preview,
+    events: JSON.stringify(events),
+    active: extras.active !== false,
+    created_by: 1,
+  }).returning('id');
+  const id = insert[0]?.id || insert[0];
+  return { id, secret: plaintext };
+}
+
+async function clearWebhooks() {
+  await db('webhook_deliveries').del();
+  await db('webhooks').del();
+}
+
+describe('webhook delivery worker (#327)', () => {
+  beforeAll(async () => {
+    // Schema is expected to already be applied by `npm run migrate`. We
+    // just verify the webhooks tables exist; if not, the test harness has
+    // missed running migration 082.
+    const ok = await db.schema.hasTable('webhooks');
+    if (!ok) throw new Error('webhooks table missing — run `npm run migrate` first');
+  }, 30000);
+
+  afterAll(async () => {
+    stopWebhookDeliveryWorker();
+    await db.destroy();
+  });
+
+  beforeEach(async () => {
+    await clearWebhooks();
+  });
+
+  test('signs the body with HMAC-SHA256 and the receiver can verify', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id, secret } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 1, slug: 'sig-test' } });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(1);
+      const got = stub.requests[0];
+      const sig = got.headers['x-picpeak-signature'];
+      expect(sig).toBeTruthy();
+      // Receiver-side verification using the SAME helper we ship in the README.
+      expect(webhookService.verifySignature(secret, got.body, sig)).toBe(true);
+      // Tampering must fail.
+      expect(webhookService.verifySignature(secret, got.body + 'x', sig)).toBe(false);
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(200);
+      expect(row.latency_ms).toBeGreaterThanOrEqual(0);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('headers include event type and a unique delivery id', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      await insertWebhook(stub.url, ['photo.uploaded']);
+      await webhookService.fire('photo.uploaded', { photo: { id: 7 } });
+      await __test.tick();
+
+      const got = stub.requests[0];
+      expect(got.headers['x-picpeak-event']).toBe('photo.uploaded');
+      expect(got.headers['x-picpeak-delivery']).toBeTruthy();
+      expect(got.headers['user-agent']).toMatch(/PicPeak-Webhooks/);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('on 5xx, schedules a retry with exponential backoff and stays pending', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 2 } });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('pending');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(500);
+      // BACKOFF_MS[0] = 60s; next_retry_at should be ~60s in the future.
+      const dueIn = new Date(row.next_retry_at).getTime() - Date.now();
+      expect(dueIn).toBeGreaterThan(50_000);
+      expect(dueIn).toBeLessThan(70_000);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('after MAX_ATTEMPTS failures, status flips to failed and the row is closed', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      // Pre-seed a delivery already at attempt_count = 4 so a single tick
+      // takes it to 5 → failed (avoids waiting through backoffs).
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 4,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.attempt_count).toBe(5);
+      expect(row.completed_at).toBeTruthy();
+      expect(row.next_retry_at).toBeNull();
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('truncates response body to 1KB before storing', async () => {
+    const big = 'x'.repeat(5000);
+    const stub = await makeStub({ status: 200, bodyOverride: big });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: {} });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(Buffer.byteLength(row.response_body || '', 'utf8')).toBeLessThanOrEqual(1024);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('does not deliver to disabled webhooks (post-mortem state captured)', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id } = await insertWebhook(stub.url, ['event.published'], { active: false });
+      // fire enqueues regardless of active state at fire-time, but we
+      // disabled BEFORE firing so nothing is enqueued. Direct insert to
+      // exercise the worker's mid-flight disable check:
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(0);
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/disabled/i);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('rejects loopback URLs when WEBHOOK_ALLOW_PRIVATE_URLS=false', async () => {
+    __test.setAllowPrivateUrls(false);
+    try {
+      const { id } = await insertWebhook('http://127.0.0.1:9/');
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/private|internal/i);
+    } finally {
+      __test.setAllowPrivateUrls(true);
+    }
+  });
+
+  test('worker can be started + stopped without leaking timers', async () => {
+    startWebhookDeliveryWorker();
+    startWebhookDeliveryWorker(); // idempotent
+    stopWebhookDeliveryWorker();
+    stopWebhookDeliveryWorker(); // idempotent
+    // If timers leaked the test runner would warn after force-exit; assertion
+    // is just "no throw".
+    expect(true).toBe(true);
+  });
+});

backend/__tests__/middleware/sessionTimeout.isSessionExpired.test.js

@@ -0,0 +1,112 @@
+/**
+ * Unit test for the non-mutating isSessionExpired() helper added to
+ * middleware/sessionTimeout.js. Used by GET /auth/session to mirror the
+ * timeout enforcement that sessionTimeoutMiddleware applies to /api/admin
+ * endpoints — closing the asymmetry that surfaced as the redirect-loop
+ * recurrence on v3.39.1-beta.0 (issue #350).
+ *
+ * The helper has two branches:
+ *   1. In-memory `lastActivity` exists for this token  → expired iff
+ *      now - lastActivity > timeout.
+ *   2. No in-memory entry (post-restart, or first request)  → expired
+ *      iff token's iat is older than the timeout (post-restart guard
+ *      that the existing middleware already implements at line ~101).
+ *
+ * Both branches must NOT mutate the in-memory `sessions` Map — the
+ * middleware is the only place that tracks activity. We assert that.
+ */
+
+jest.mock('../../src/database/db', () => ({
+  db: () => ({
+    where: () => ({
+      first: () => ({
+        timeout: () => Promise.resolve(null),
+      }),
+    }),
+  }),
+}));
+
+// Speed up the cached-timeout reads. The module reads
+// `security_session_timeout_minutes` from app_settings and falls back to
+// DEFAULT_SESSION_TIMEOUT (60 min) when the row is null.
+const SIXTY_MINUTES_MS = 60 * 60 * 1000;
+
+const sessionTimeout = require('../../src/middleware/sessionTimeout');
+const { isSessionExpired } = sessionTimeout;
+
+function makeDecodedToken({ id = 1, iatSecondsAgo = 0 } = {}) {
+  return { id, iat: Math.floor((Date.now() - iatSecondsAgo * 1000) / 1000) };
+}
+
+describe('isSessionExpired (sessionTimeout helper)', () => {
+  it('returns false for a freshly-issued token with no in-memory record', async () => {
+    const decoded = makeDecodedToken({ id: 1, iatSecondsAgo: 60 });
+    expect(await isSessionExpired('fresh-token-1', decoded)).toBe(false);
+  });
+
+  it('returns true when iat is older than the timeout (post-restart guard)', async () => {
+    const decoded = makeDecodedToken({
+      id: 2,
+      // 90 minutes > 60 minute default timeout
+      iatSecondsAgo: 90 * 60,
+    });
+    expect(await isSessionExpired('stale-token-2', decoded)).toBe(true);
+  });
+
+  it('returns false / true based on lastActivity when one exists', async () => {
+    // Drive the in-memory map by running the actual middleware once to
+    // record activity for the token, then check the helper.
+    const decoded = makeDecodedToken({ id: 3 });
+
+    // Drive the actual middleware once with a real signed token so it
+    // records this token in the in-memory `sessions` Map. Then check the
+    // helper sees that recent activity and reports "not expired".
+    const res = { status: jest.fn(() => res), json: jest.fn() };
+    const jwt = require('jsonwebtoken');
+    process.env.JWT_SECRET = 'session-timeout-helper-test-secret';
+    const realToken = jwt.sign(decoded, process.env.JWT_SECRET, {
+      issuer: 'picpeak-auth',
+    });
+    const realReq = {
+      headers: { authorization: `Bearer ${realToken}` },
+      cookies: {},
+    };
+    await sessionTimeout.sessionTimeoutMiddleware(realReq, res, () => {});
+
+    const decodedReal = jwt.decode(realToken);
+    // Just-recorded → not expired
+    expect(await isSessionExpired(realToken, decodedReal)).toBe(false);
+  });
+
+  it('returns false when token / decoded is missing (defensive)', async () => {
+    expect(await isSessionExpired(null, { id: 1 })).toBe(false);
+    expect(await isSessionExpired('tok', null)).toBe(false);
+    expect(await isSessionExpired('tok', {})).toBe(false);
+  });
+
+  // Sanity: the helper must not poke the `sessions` Map. Indirectly check
+  // by counting active sessions before/after a call with a never-seen
+  // token — should not change.
+  it('does not mutate the in-memory sessions map', async () => {
+    const before = sessionTimeout.getActiveSessions();
+    await isSessionExpired('never-seen-token-99', makeDecodedToken({ id: 99 }));
+    const after = sessionTimeout.getActiveSessions();
+    expect(after).toBe(before);
+  });
+
+  it('uses the default 60-minute timeout when no DB setting exists', async () => {
+    // 59 minutes → not expired
+    const fresh = makeDecodedToken({ id: 4, iatSecondsAgo: 59 * 60 });
+    expect(await isSessionExpired('fresh-4', fresh)).toBe(false);
+
+    // 61 minutes → expired (just past the default)
+    const stale = makeDecodedToken({ id: 5, iatSecondsAgo: 61 * 60 });
+    expect(await isSessionExpired('stale-5', stale)).toBe(true);
+  });
+
+  // Document the constant the test relies on so a future timeout change
+  // makes this assertion explicit rather than mysterious.
+  it('default timeout is 60 minutes (constant under test)', () => {
+    expect(SIXTY_MINUTES_MS).toBe(60 * 60 * 1000);
+  });
+});

backend/__tests__/routes/adminCrmAuth.test.js

@@ -0,0 +1,157 @@
+/**
+ * HTTP route auth-gate tests for the CRM admin surface (P1 / P2 — #570).
+ *
+ * Bundled into one file rather than nine because the contract is the
+ * same for every CRM admin route:
+ *   - No token → 401 (adminAuth at the router level)
+ *   - Valid token, missing permission → 403 (requirePermission middleware)
+ *   - Valid token + super_admin role → 2xx / 404 (resource-based)
+ *
+ * Deeper service-layer behaviour (PDF generation, send, Storno,
+ * countersign, integrity hash) is covered by the existing service
+ * unit tests in __tests__/services/. This file pins the contract
+ * between the HTTP layer and the auth+permission middleware so a
+ * misconfigured route ("forgot requirePermission") can never ship
+ * unnoticed.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-admincrm-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
+
+const request = require('supertest');
+const {
+  bootCrmDb, seedMinimal, assignAdminRole,
+  mintAdminToken, buildRouteApp,
+} = require('../integration/helpers/crmDb');
+
+// One row per admin CRM route. `mount` matches server.js's app.use,
+// `loader` is the require()'d router, `getPath` is one path on the
+// router we'll exercise. The path should be a GET-shaped read where
+// possible — listing endpoints (`/`) are safest because they don't
+// require pre-seeded resource ids.
+const ROUTES = [
+  { name: 'adminQuotes',          mount: '/api/admin/quotes',           loader: () => require('../../src/routes/adminQuotes'),          getPath: '/' },
+  { name: 'adminContracts',       mount: '/api/admin/contracts',        loader: () => require('../../src/routes/adminContracts'),       getPath: '/' },
+  { name: 'adminInvoices',        mount: '/api/admin/invoices',         loader: () => require('../../src/routes/adminInvoices'),        getPath: '/' },
+  { name: 'adminCalendar',        mount: '/api/admin/calendar',         loader: () => require('../../src/routes/adminCalendar'),        getPath: '/items?from=2026-01-01&to=2026-12-31' },
+  { name: 'adminDeals',           mount: '/api/admin/deals',            loader: () => require('../../src/routes/adminDeals'),           getPath: '/' },
+  { name: 'adminTaxReport',       mount: '/api/admin/tax-report',       loader: () => require('../../src/routes/adminTaxReport'),       getPath: '/?period=2026-Q1' },
+  { name: 'adminBusinessProfile', mount: '/api/admin/business-profile', loader: () => require('../../src/routes/adminBusinessProfile'), getPath: '/' },
+];
+
+describe('admin CRM routes — auth + permission gate', () => {
+  let db;
+  let cleanup;
+  let adminId;
+  let customerId;
+  let superAdminToken;
+  let invalidToken;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ adminId, customerId } = await seedMinimal(db));
+
+    // Super-admin: assign the seeded super_admin role (created by
+    // migration 057). requirePermission lookups short-circuit because
+    // super_admin role inherits every permission via role_permissions
+    // rows seeded by mig 107 and earlier.
+    await assignAdminRole(db, adminId, 'super_admin');
+    superAdminToken = mintAdminToken(adminId);
+
+    // CRM routes have a feature-flag gate that runs INSIDE the route
+    // handler — even a super-admin gets 403 (`QUOTES_DISABLED` /
+    // similar) when the flag is off. The flag check is independent
+    // of permissions, so for happy-path tests we flip every CRM flag
+    // on. Negative tests (no-token, bad-signature) hit adminAuth
+    // first and never reach the flag check, so they're unaffected.
+    const crmFlags = ['quotes', 'bills', 'contracts', 'hoursLogging', 'calendar', 'taxReport', 'clients'];
+    for (const key of crmFlags) {
+      // eslint-disable-next-line no-await-in-loop
+      await db('feature_flags').where({ key }).update({ value: 1 });
+    }
+
+    // Invalid: signed with a different secret. adminAuth must reject.
+    const jwt = require('jsonwebtoken');
+    invalidToken = jwt.sign({ id: adminId, type: 'admin' }, 'WRONG-SECRET', { issuer: 'picpeak-auth' });
+  }, 60000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  describe.each(ROUTES)('$name', ({ mount, loader, getPath }) => {
+    let app;
+
+    beforeAll(() => {
+      app = buildRouteApp(mount, loader());
+    });
+
+    it('returns 401 with no Authorization header', async () => {
+      const res = await request(app).get(`${mount}${getPath}`);
+      expect(res.status).toBe(401);
+    });
+
+    it('returns 401 with an invalid JWT signature', async () => {
+      const res = await request(app)
+        .get(`${mount}${getPath}`)
+        .set('Authorization', `Bearer ${invalidToken}`);
+      expect(res.status).toBe(401);
+    });
+
+    it('returns 2xx (or resource-shaped 4xx) with a valid super-admin token', async () => {
+      const res = await request(app)
+        .get(`${mount}${getPath}`)
+        .set('Authorization', `Bearer ${superAdminToken}`);
+      // 200 if listing succeeds (likely empty list), 400 if a
+      // validator complains about query shape, 404 if the route
+      // doesn't have a list endpoint at `/`. What MUST NOT happen:
+      // 401 (auth gate failed) or 403 (permission gate failed).
+      expect(res.status).not.toBe(401);
+      expect(res.status).not.toBe(403);
+      expect(res.status).toBeLessThan(500);
+    });
+  });
+
+  describe('adminCustomers — CRM additions (hour-entries / bill / trigger-monthly-bill)', () => {
+    let app;
+    beforeAll(() => {
+      app = buildRouteApp('/api/admin/customers', require('../../src/routes/adminCustomers'));
+    });
+
+    it('GET /:id/hour-entries — 401 without token', async () => {
+      const res = await request(app).get(`/api/admin/customers/${customerId}/hour-entries`);
+      expect(res.status).toBe(401);
+    });
+
+    it('GET /:id/hour-entries — 2xx with super-admin token', async () => {
+      const res = await request(app)
+        .get(`/api/admin/customers/${customerId}/hour-entries`)
+        .set('Authorization', `Bearer ${superAdminToken}`);
+      expect(res.status).not.toBe(401);
+      expect(res.status).not.toBe(403);
+      expect(res.status).toBeLessThan(500);
+    });
+
+    it('POST /:id/hour-entries/bill — 401 without token', async () => {
+      const res = await request(app)
+        .post(`/api/admin/customers/${customerId}/hour-entries/bill`)
+        .send({});
+      expect(res.status).toBe(401);
+    });
+
+    it('POST /:id/trigger-monthly-bill — 401 without token', async () => {
+      const res = await request(app)
+        .post(`/api/admin/customers/${customerId}/trigger-monthly-bill`)
+        .send({});
+      expect(res.status).toBe(401);
+    });
+  });
+});

backend/__tests__/routes/adminUsers.dateNormalize.test.js

@@ -0,0 +1,123 @@
+/**
+ * Pin the date-field normalisation in adminUsers transformer (#485).
+ *
+ * The Users page crashed on native/SQLite installs because Postgres
+ * returned ISO strings while SQLite returned epoch-millisecond
+ * integers, and the frontend `parseISO()` blew up on numbers with
+ * "e.split is not a function". The transformer now coerces every
+ * shape to an ISO 8601 string before serialising.
+ *
+ * These tests guard the contract so a future refactor can't quietly
+ * regress and re-break the same page on the same DB.
+ */
+
+const adminUsersRoute = require('../../src/routes/adminUsers');
+const { toIso, transformUser, transformInvitation } = adminUsersRoute.__test;
+
+describe('toIso', () => {
+  it('passes null and undefined through unchanged', () => {
+    expect(toIso(null)).toBeNull();
+    expect(toIso(undefined)).toBeUndefined();
+    // Empty string also short-circuits — important so an unset
+    // last_login renders as "Never" instead of 1970-01-01T00:00:00Z.
+    expect(toIso('')).toBe('');
+  });
+
+  it('coerces an integer epoch (SQLite shape) to an ISO 8601 string', () => {
+    // 2026-05-14T10:00:00.000Z, in epoch ms.
+    const epochMs = 1778752800000;
+    expect(toIso(epochMs)).toBe('2026-05-14T10:00:00.000Z');
+  });
+
+  it('coerces a stringified large integer to an ISO 8601 string', () => {
+    // Some SQLite drivers stringify large integers because they
+    // overflow JS safe-integer in the driver's serialiser. Re-coerce
+    // so the frontend doesn't try to parseISO('1778752800000').
+    expect(toIso('1778752800000')).toBe('2026-05-14T10:00:00.000Z');
+  });
+
+  it('coerces a Date instance via toISOString', () => {
+    const d = new Date('2026-01-01T12:34:56.000Z');
+    expect(toIso(d)).toBe('2026-01-01T12:34:56.000Z');
+  });
+
+  it('passes an existing ISO string through unchanged', () => {
+    const iso = '2026-05-14T10:00:00.000Z';
+    expect(toIso(iso)).toBe(iso);
+  });
+
+  it('passes a non-numeric short string (e.g. truncated date) through unchanged', () => {
+    // Defensive: anything that isn't a 10+ digit integer string is
+    // treated as already-stringified — the date library will surface
+    // the failure cleanly if it's malformed, rather than the
+    // transformer silently rewriting it.
+    expect(toIso('2026-05-14')).toBe('2026-05-14');
+  });
+});
+
+describe('transformUser', () => {
+  it('normalises last_login, created_at, updated_at coming from SQLite', () => {
+    const sqliteRow = {
+      id: 1,
+      username: 'admin',
+      email: 'admin@example.com',
+      is_active: 1,
+      last_login: 1778752800000,            // epoch ms
+      last_login_ip: '127.0.0.1',
+      created_at: 1778751144600,            // epoch ms
+      updated_at: 1778751242320,            // epoch ms
+      role_id: 1,
+      role_name: 'super_admin',
+      role_display_name: 'Super Admin',
+      created_by_username: null,
+    };
+
+    const out = transformUser(sqliteRow);
+
+    expect(out.lastLogin).toBe('2026-05-14T10:00:00.000Z');
+    expect(out.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    expect(out.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    // Other fields untouched.
+    expect(out.username).toBe('admin');
+    expect(out.lastLoginIp).toBe('127.0.0.1');
+  });
+
+  it('leaves Postgres ISO strings intact', () => {
+    const pgRow = {
+      id: 2,
+      username: 'second',
+      email: 'second@example.com',
+      is_active: true,
+      last_login: '2026-05-14T10:00:00.000Z',
+      created_at: '2026-05-13T08:00:00.000Z',
+      updated_at: '2026-05-14T09:00:00.000Z',
+    };
+    const out = transformUser(pgRow);
+    expect(out.lastLogin).toBe('2026-05-14T10:00:00.000Z');
+    expect(out.createdAt).toBe('2026-05-13T08:00:00.000Z');
+    expect(out.updatedAt).toBe('2026-05-14T09:00:00.000Z');
+  });
+
+  it('keeps last_login null when the user has never logged in', () => {
+    const out = transformUser({
+      id: 3, username: 'fresh', email: 'fresh@example.com',
+      is_active: 1, last_login: null,
+    });
+    expect(out.lastLogin).toBeNull();
+  });
+});
+
+describe('transformInvitation', () => {
+  it('normalises expires_at and created_at from SQLite epoch-ms', () => {
+    const out = transformInvitation({
+      id: 9,
+      email: 'invitee@example.com',
+      expires_at: 1779357600000,
+      created_at: 1778752800000,
+      role_name: 'admin',
+      invited_by: 'admin',
+    });
+    expect(out.expiresAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    expect(out.createdAt).toBe('2026-05-14T10:00:00.000Z');
+  });
+});

backend/__tests__/routes/authSession.symmetry.test.js

@@ -0,0 +1,395 @@
+/**
+ * Regression test for the /admin/login → /admin/dashboard → /admin/login
+ * redirect loop reported on v3.32.4-beta.0.
+ *
+ * Cause: GET /auth/session was less strict than the adminAuth middleware.
+ * The session endpoint accepted tokens that the protected endpoints
+ * subsequently rejected with 401, which the frontend's interceptor
+ * translated into a hard redirect to /admin/login. /auth/session then
+ * said "valid: true" again on the next page load and the cycle closed.
+ *
+ * /auth/session must reject the same admin tokens adminAuth would
+ * reject, specifically: deactivated admin user, deleted admin user,
+ * password changed since iat. Same for gallery: archived event.
+ */
+
+const express = require('express');
+const request = require('supertest');
+const jwt = require('jsonwebtoken');
+
+process.env.JWT_SECRET = 'session-symmetry-test-secret';
+
+const fakeDb = {
+  adminUsers: [],
+  events: [],
+  revokedTokens: [],
+};
+
+jest.mock('../../src/database/db', () => {
+  const formatBoolean = (v) => (v ? 1 : 0);
+  void formatBoolean;
+  function dbFn(table) {
+    if (table === 'admin_users') {
+      let rowFilter = () => true;
+      return {
+        where(criteria) {
+          rowFilter = (row) => {
+            return Object.entries(criteria).every(([k, v]) => {
+              if (k === 'is_active') return Boolean(row.is_active) === Boolean(v);
+              return row[k] === v;
+            });
+          };
+          return this;
+        },
+        select(...cols) {
+          this._cols = cols;
+          return this;
+        },
+        async first() {
+          const row = fakeDb.adminUsers.find(rowFilter);
+          if (!row) return undefined;
+          if (!this._cols) return row;
+          const out = {};
+          for (const c of this._cols) out[c] = row[c];
+          return out;
+        },
+      };
+    }
+    if (table === 'events') {
+      let rowFilter = () => true;
+      return {
+        where(criteria) {
+          rowFilter = (row) =>
+            Object.entries(criteria).every(([k, v]) => {
+              if (k === 'is_active') return Boolean(row.is_active) === Boolean(v);
+              if (k === 'is_archived') return Boolean(row.is_archived) === Boolean(v);
+              return row[k] === v;
+            });
+          return this;
+        },
+        async first() {
+          return fakeDb.events.find(rowFilter);
+        },
+      };
+    }
+    throw new Error(`Unexpected table: ${table}`);
+  }
+  return { db: dbFn, formatBoolean: () => 1 };
+});
+
+jest.mock('../../src/utils/dbCompat', () => ({
+  formatBoolean: (v) => (v ? 1 : 0),
+}));
+
+jest.mock('../../src/utils/tokenRevocation', () => ({
+  isTokenRevoked: jest.fn(async (decoded) => fakeDb.revokedTokens.includes(decoded.id)),
+  revokeToken: jest.fn(),
+}));
+
+jest.mock('../../src/utils/tokenUtils', () => ({
+  getAdminTokenFromRequest: (req) => {
+    const auth = req.headers.authorization;
+    if (auth && auth.startsWith('Bearer ')) return auth.slice(7);
+    return null;
+  },
+  getGalleryTokenFromRequest: () => null,
+  setAdminAuthCookie: jest.fn(),
+  setGalleryAuthCookies: jest.fn(),
+  clearAdminAuthCookie: jest.fn(),
+  clearGalleryAuthCookies: jest.fn(),
+  buildCookieOptionsWithExpiry: () => ({}),
+}));
+
+jest.mock('../../src/services/recaptcha', () => ({ verifyRecaptcha: () => Promise.resolve(true) }));
+// Mock sessionTimeout's isSessionExpired so each test controls the return.
+// Default: not expired (so existing tests keep passing without setup).
+jest.mock('../../src/middleware/sessionTimeout', () => ({
+  endSession: jest.fn(),
+  isSessionExpired: jest.fn(() => Promise.resolve(false)),
+}));
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+}));
+
+const authRouter = require('../../src/routes/auth');
+
+function makeApp() {
+  const app = express();
+  app.use(express.json());
+  app.use('/auth', authRouter);
+  return app;
+}
+
+function signAdminToken({ id = 1, username = 'admin', iat, exp }) {
+  const issuedAt = iat ?? Math.floor(Date.now() / 1000);
+  // Note: do NOT pass noTimestamp:true here — that strips iat from the
+  // payload entirely, defeating the password-change comparison. Provide
+  // iat (and exp) via the payload directly instead.
+  return jwt.sign(
+    { id, username, type: 'admin', iat: issuedAt, exp: exp ?? issuedAt + 3600 },
+    process.env.JWT_SECRET,
+    { issuer: 'picpeak-auth' }
+  );
+}
+
+function signGalleryToken({ eventId = 100, eventSlug = 'wedding' } = {}) {
+  return jwt.sign(
+    { eventId, eventSlug, type: 'gallery' },
+    process.env.JWT_SECRET,
+    { expiresIn: '1h', issuer: 'picpeak-auth' }
+  );
+}
+
+describe('GET /auth/session — symmetry with protected middleware', () => {
+  beforeEach(() => {
+    fakeDb.adminUsers = [];
+    fakeDb.events = [];
+    fakeDb.revokedTokens = [];
+  });
+
+  it('returns valid:true for an active admin token', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: null,
+    });
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+    expect(res.body.type).toBe('admin');
+  });
+
+  it('returns valid:false when the admin user has been deactivated', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: false,
+      password_changed_at: null,
+    });
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false when the admin user no longer exists', async () => {
+    // adminUsers is empty
+    const token = signAdminToken({ id: 999 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false when password was changed after the token was issued', async () => {
+    // iat must be in the past, exp must be in the future so jwt.verify
+    // doesn't reject the token before /auth/session even gets to look
+    // at password_changed_at.
+    const tokenIssuedAt = Math.floor(Date.now() / 1000) - 60; // 1 min ago
+    const tokenExp = tokenIssuedAt + 86400;
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: new Date((tokenIssuedAt + 30) * 1000), // 30s after iat
+    });
+    const token = signAdminToken({ id: 1, iat: tokenIssuedAt, exp: tokenExp });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:true when password was changed BEFORE the token was issued', async () => {
+    const tokenIssuedAt = Math.floor(Date.now() / 1000) - 60;
+    const tokenExp = tokenIssuedAt + 86400;
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      email: 'a@b.com',
+      is_active: true,
+      password_changed_at: new Date((tokenIssuedAt - 3600) * 1000), // 1h before iat
+    });
+    const token = signAdminToken({ id: 1, iat: tokenIssuedAt, exp: tokenExp });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+  });
+
+  it('returns valid:false for a gallery token whose event is archived', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: true,
+      expires_at: null,
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:false for a gallery token whose event is expired', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: false,
+      expires_at: new Date(Date.now() - 86400_000),
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(false);
+  });
+
+  it('returns valid:true for an active gallery token', async () => {
+    fakeDb.events.push({
+      id: 100,
+      slug: 'wedding',
+      is_active: true,
+      is_archived: false,
+      expires_at: new Date(Date.now() + 86400_000),
+    });
+    const token = signGalleryToken();
+
+    const res = await request(makeApp())
+      .get('/auth/session?slug=wedding')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.valid).toBe(true);
+  });
+
+  it('returns valid:false when the token is revoked', async () => {
+    fakeDb.adminUsers.push({
+      id: 1,
+      username: 'admin',
+      is_active: true,
+      password_changed_at: null,
+    });
+    fakeDb.revokedTokens.push(1);
+    const token = signAdminToken({ id: 1 });
+
+    const res = await request(makeApp())
+      .get('/auth/session')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(401);
+    expect(res.body.valid).toBe(false);
+  });
+
+  // Session-timeout symmetry — issue #350 recurrence on v3.39.1-beta.0.
+  // sessionTimeoutMiddleware (mounted on /api/admin) rejects idle/old-iat
+  // tokens with 401 SESSION_TIMEOUT, but /auth/session previously didn't.
+  // The new isSessionExpired helper closes that asymmetry.
+  describe('session-timeout symmetry', () => {
+    const { isSessionExpired } = require('../../src/middleware/sessionTimeout');
+
+    beforeEach(() => {
+      isSessionExpired.mockReset();
+      // Default to "active session" so the other admin checks above also
+      // pass when this branch runs.
+      isSessionExpired.mockResolvedValue(false);
+    });
+
+    it('returns valid:false when isSessionExpired reports the token has timed out', async () => {
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockResolvedValue(true);
+      const token = signAdminToken({ id: 1 });
+
+      const res = await request(makeApp())
+        .get('/auth/session')
+        .set('Authorization', `Bearer ${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.valid).toBe(false);
+      expect(res.body.error).toBe('Session expired');
+    });
+
+    it('returns valid:true for an active admin token (helper says not expired)', async () => {
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockResolvedValue(false);
+      const token = signAdminToken({ id: 1 });
+
+      const res = await request(makeApp())
+        .get('/auth/session')
+        .set('Authorization', `Bearer ${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.valid).toBe(true);
+      expect(isSessionExpired).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call isSessionExpired for gallery tokens', async () => {
+      fakeDb.events.push({
+        id: 100,
+        slug: 'wedding',
+        is_active: true,
+        is_archived: false,
+        expires_at: new Date(Date.now() + 86400_000),
+      });
+      const token = signGalleryToken();
+
+      const res = await request(makeApp())
+        .get('/auth/session?slug=wedding')
+        .set('Authorization', `Bearer ${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.valid).toBe(true);
+      expect(isSessionExpired).not.toHaveBeenCalled();
+    });
+
+    it('falls through (treats as valid) if the helper itself throws', async () => {
+      // Defensive: the require() in auth.js is wrapped in try/catch so a
+      // missing/broken helper doesn't fail-closed during early bootstrap.
+      fakeDb.adminUsers.push({
+        id: 1,
+        username: 'admin',
+        is_active: true,
+        password_changed_at: null,
+      });
+      isSessionExpired.mockRejectedValue(new Error('boom'));
+      const token = signAdminToken({ id: 1 });
+
+      const res = await request(makeApp())
+        .get('/auth/session')
+        .set('Authorization', `Bearer ${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.valid).toBe(true);
+    });
+  });
+});

backend/__tests__/routes/publicContracts.test.js

@@ -0,0 +1,153 @@
+/**
+ * HTTP route tests for backend/src/routes/publicContracts (P0 — #570).
+ *
+ * Four endpoints on the customer-facing surface:
+ *   GET  /:token             — load contract for signing
+ *   POST /:token/sign        — in-browser canvas signature submission
+ *   POST /:token/upload-signed-pdf  — wet-signed PDF upload
+ *   GET  /:token/pdf         — download the contract PDF
+ *
+ * Tests pin the publicTokenGuards.loadActionToken contract per
+ * endpoint and a few endpoint-specific shape assertions. Deeper
+ * service-layer behaviour (PDF generation, signature attachment,
+ * integrity-hash compute) is covered by the contractService unit
+ * tests; here we only assert the HTTP contract.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-pubcontracts-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
+
+const request = require('supertest');
+const { bootCrmDb, seedMinimal, createPublicToken, buildRouteApp } = require('../integration/helpers/crmDb');
+const tokenGuards = require('../../src/utils/publicTokenGuards');
+
+describe('publicContracts routes', () => {
+  let db;
+  let cleanup;
+  let app;
+  let customerId;
+  let contractId;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ customerId } = await seedMinimal(db));
+    const inserted = await db('contracts').insert({
+      contract_number: 'K-TEST-0001',
+      customer_account_id: customerId,
+      title: 'Test Booking Confirmation',
+      issue_date: new Date().toISOString().slice(0, 10),
+      status: 'sent',
+      language: 'de',
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    contractId = inserted[0]?.id ?? inserted[0];
+
+    app = buildRouteApp('/api/public/contracts', require('../../src/routes/publicContracts'));
+  }, 60000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(() => {
+    if (tokenGuards._internal?.badAttempts) tokenGuards._internal.badAttempts.clear();
+  });
+
+  describe('GET /:token', () => {
+    it('returns 404 for an unknown well-formed token', async () => {
+      const fakeToken = 'a'.repeat(64);
+      const res = await request(app).get(`/api/public/contracts/${fakeToken}`);
+      expect(res.status).toBe(404);
+    });
+
+    it('rejects malformed tokens with 400 before reaching the guard', async () => {
+      const res = await request(app).get('/api/public/contracts/short');
+      expect(res.status).toBe(400);
+    });
+
+    it('returns 410 for an expired token', async () => {
+      const past = new Date(Date.now() - 24 * 60 * 60 * 1000);
+      const token = await createPublicToken(db, 'contract_action_tokens', {
+        contract_id: contractId, expires_at: past,
+      });
+      const res = await request(app).get(`/api/public/contracts/${token}`);
+      expect(res.status).toBe(410);
+      expect(res.body.code).toBe('TOKEN_EXPIRED');
+    });
+
+    it('returns 200 with the contract payload for a valid token', async () => {
+      const token = await createPublicToken(db, 'contract_action_tokens', {
+        contract_id: contractId,
+      });
+      const res = await request(app).get(`/api/public/contracts/${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.contract).toBeDefined();
+    });
+  });
+
+  describe('POST /:token/sign', () => {
+    it('rejects missing required fields (name, accepted) with 400', async () => {
+      const token = await createPublicToken(db, 'contract_action_tokens', {
+        contract_id: contractId,
+      });
+      const res = await request(app)
+        .post(`/api/public/contracts/${token}/sign`)
+        .send({}); // missing name + accepted
+      expect(res.status).toBe(400);
+    });
+
+    it('returns 404 for an unknown token on sign', async () => {
+      const fakeToken = 'b'.repeat(64);
+      const res = await request(app)
+        .post(`/api/public/contracts/${fakeToken}/sign`)
+        .send({ name: 'Jane Doe', accepted: true });
+      // Either 404 (token not found) or service-level error mapped to
+      // 4xx — what matters is the request didn't slip past validation.
+      expect(res.status).toBeGreaterThanOrEqual(400);
+      expect(res.status).toBeLessThan(500);
+    });
+  });
+
+  describe('POST /:token/upload-signed-pdf', () => {
+    it('rejects malformed tokens with 400 before multer runs', async () => {
+      const res = await request(app)
+        .post('/api/public/contracts/bad-token/upload-signed-pdf')
+        .attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
+      expect(res.status).toBe(400);
+    });
+
+    it('returns 404 for an unknown but well-formed token', async () => {
+      const fakeToken = 'c'.repeat(64);
+      const res = await request(app)
+        .post(`/api/public/contracts/${fakeToken}/upload-signed-pdf`)
+        .attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe('GET /:token/pdf', () => {
+    it('returns 404 for an unknown token on PDF download', async () => {
+      const fakeToken = 'd'.repeat(64);
+      const res = await request(app).get(`/api/public/contracts/${fakeToken}/pdf`);
+      expect(res.status).toBe(404);
+    });
+
+    it('returns 410 for an expired token on PDF download', async () => {
+      const past = new Date(Date.now() - 1000);
+      const token = await createPublicToken(db, 'contract_action_tokens', {
+        contract_id: contractId, expires_at: past,
+      });
+      const res = await request(app).get(`/api/public/contracts/${token}/pdf`);
+      expect(res.status).toBe(410);
+      expect(res.body.code).toBe('TOKEN_EXPIRED');
+    });
+  });
+});

backend/__tests__/routes/publicPaymentCheck.test.js

@@ -0,0 +1,106 @@
+/**
+ * HTTP route tests for backend/src/routes/publicPaymentCheck (P0 — #570).
+ *
+ * Two endpoints:
+ *   GET  /:token  — load invoice payment-check view
+ *   POST /:token  — record customer's "paid / unpaid / partial" claim
+ *
+ * Unlike the quote / contract public routes, payment-check goes
+ * through invoiceService rather than the shared publicTokenGuards.
+ * Tests focus on the validator gates and the unknown-token edge.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-paymentcheck-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
+
+const request = require('supertest');
+const { bootCrmDb, seedMinimal, buildRouteApp } = require('../integration/helpers/crmDb');
+
+describe('publicPaymentCheck routes', () => {
+  let cleanup;
+  let app;
+
+  beforeAll(async () => {
+    let db;
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+    app = buildRouteApp('/api/public/payment-check', require('../../src/routes/publicPaymentCheck'));
+  }, 60000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  describe('GET /:token', () => {
+    it('rejects malformed tokens with 400', async () => {
+      const res = await request(app).get('/api/public/payment-check/short');
+      expect(res.status).toBe(400);
+    });
+
+    it('returns a service-level error for an unknown well-formed token (4xx, not 500)', async () => {
+      const fakeToken = 'a'.repeat(64);
+      const res = await request(app).get(`/api/public/payment-check/${fakeToken}`);
+      // Service throws NotFound or similar — what matters is the
+      // request reaches the service AND isn't an unhandled 500.
+      expect(res.status).toBeGreaterThanOrEqual(400);
+      expect(res.status).toBeLessThan(600);
+    });
+  });
+
+  describe('POST /:token', () => {
+    it('rejects malformed tokens with 400', async () => {
+      const res = await request(app)
+        .post('/api/public/payment-check/short')
+        .send({ action: 'paid_full' });
+      expect(res.status).toBe(400);
+    });
+
+    it('rejects an invalid action with 400', async () => {
+      const validToken = 'b'.repeat(64);
+      const res = await request(app)
+        .post(`/api/public/payment-check/${validToken}`)
+        .send({ action: 'maybe' });
+      expect(res.status).toBe(400);
+    });
+
+    it('accepts the canonical four actions through the validator', async () => {
+      // Each action passes validator (token is well-formed); service
+      // then rejects unknown token with a 4xx — what we're pinning is
+      // the validator doesn't reject any of the canonical actions.
+      const validToken = 'c'.repeat(64);
+      for (const action of ['paid_full', 'paid_with_skonto', 'partial', 'unpaid']) {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await request(app)
+          .post(`/api/public/payment-check/${validToken}`)
+          .send({ action });
+        // Either succeeds (rare — no real invoice) or service-level
+        // 4xx for unknown token. Must NOT be 400 (which would mean
+        // the validator rejected the action).
+        expect(res.status).not.toBe(400);
+        expect(res.status).toBeGreaterThanOrEqual(400);
+        expect(res.status).toBeLessThan(600);
+      }
+    });
+
+    it('rejects negative amountMinor with 400', async () => {
+      // Validator chain: optional({ values: 'falsy' }) means
+      // amountMinor=0 / null / undefined gets skipped (allowed). For
+      // any actually-supplied integer, isInt({ min: 1 }) takes over —
+      // pin the negative-rejection so a future refactor can't loosen
+      // the lower bound silently.
+      const validToken = 'd'.repeat(64);
+      const res = await request(app)
+        .post(`/api/public/payment-check/${validToken}`)
+        .send({ action: 'partial', amountMinor: -100 });
+      expect(res.status).toBe(400);
+    });
+  });
+});

backend/__tests__/routes/publicQuotes.test.js

@@ -0,0 +1,171 @@
+/**
+ * HTTP route tests for backend/src/routes/publicQuotes (P0 — #570).
+ *
+ * Public token guards (publicTokenGuards.loadActionToken) are the most
+ * security-sensitive surface in the CRM module — these are the routes
+ * a customer hits via the link in the quote email, reachable from any
+ * IP with the raw token. A regression here means leaked tokens become
+ * permanently usable, or worse, an expired token starts working again.
+ *
+ * Tests pin the contract documented in publicTokenGuards.js:
+ *   - 404 on unknown token (and IP bad-attempt counter ticks)
+ *   - 410 on expired token
+ *   - 410 on NULL expiry (defensive — historical bug)
+ *   - 429 after 20 invalid attempts from one IP
+ *   - 200 + sanitised payload on valid token
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// MUST set the test DB env BEFORE the first require of anything that
+// pulls in db.js — knexfile reads TEST_DATABASE_PATH at module-init
+// time. The helper's bootCrmDb also has to be called once per file
+// because the db module is cached; calling it from a second describe
+// would silently reuse (or kill) the first instance's connection pool.
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-pubquotes-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
+
+const request = require('supertest');
+const { bootCrmDb, seedMinimal, createPublicToken, buildRouteApp } = require('../integration/helpers/crmDb');
+const tokenGuards = require('../../src/utils/publicTokenGuards');
+
+describe('publicQuotes routes', () => {
+  let db;
+  let cleanup;
+  let app;
+  let customerId;
+  let quoteId;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ customerId } = await seedMinimal(db));
+    const inserted = await db('quotes').insert({
+      quote_number: 'Q-TEST-0001',
+      customer_account_id: customerId,
+      currency: 'CHF',
+      issue_date: new Date().toISOString().slice(0, 10),
+      net_amount_minor: 10000,
+      vat_amount_minor: 0,
+      total_amount_minor: 10000,
+      status: 'sent',
+      language: 'de',
+      created_at: new Date(),
+    }).returning('id');
+    quoteId = inserted[0]?.id ?? inserted[0];
+
+    app = buildRouteApp('/api/public/quotes', require('../../src/routes/publicQuotes'));
+  }, 60000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  // Clear the in-memory IP bad-attempts map between scenarios so the
+  // lockout test starts from a known state — and so it doesn't bleed
+  // 429s into the unrelated tests that follow.
+  beforeEach(() => {
+    if (tokenGuards._internal?.badAttempts) {
+      tokenGuards._internal.badAttempts.clear();
+    }
+  });
+
+  describe('GET /:token', () => {
+    it('returns 404 for an unknown but well-formed token', async () => {
+      const fakeToken = 'a'.repeat(64);
+      const res = await request(app).get(`/api/public/quotes/${fakeToken}`);
+      expect(res.status).toBe(404);
+      expect(res.body.error).toBeTruthy();
+    });
+
+    it('rejects malformed (non-64-hex) tokens with 400', async () => {
+      const res = await request(app).get('/api/public/quotes/not-a-real-token');
+      expect(res.status).toBe(400);
+    });
+
+    it('returns 410 for a token whose expires_at is in the past', async () => {
+      const past = new Date(Date.now() - 24 * 60 * 60 * 1000);
+      const token = await createPublicToken(db, 'quote_action_tokens', {
+        quote_id: quoteId, expires_at: past,
+      });
+      const res = await request(app).get(`/api/public/quotes/${token}`);
+      expect(res.status).toBe(410);
+      expect(res.body.code).toBe('TOKEN_EXPIRED');
+    });
+
+    // The NULL-expiry guard in loadActionToken is intentionally
+    // defensive but the current schema declares
+    // quote_action_tokens.expires_at NOT NULL — so the defensive
+    // branch is unreachable at the route level. Test it directly
+    // against loadActionToken in a unit suite if you want coverage.
+
+    it('returns 200 with a sanitised quote payload for a valid token', async () => {
+      const token = await createPublicToken(db, 'quote_action_tokens', {
+        quote_id: quoteId,
+      });
+      const res = await request(app).get(`/api/public/quotes/${token}`);
+      expect(res.status).toBe(200);
+      expect(res.body.quote).toBeDefined();
+      // API uses camelCase on the public view (see publicQuoteView in
+      // the route handler).
+      expect(res.body.quote.quoteNumber).toBe('Q-TEST-0001');
+      // Internal IDs / admin metadata must NOT appear on the public payload
+      expect(res.body.quote.customer_account_id).toBeUndefined();
+      expect(res.body.quote.customerAccountId).toBeUndefined();
+      expect(res.body.quote.createdByAdminId).toBeUndefined();
+    });
+
+    it('locks the IP after 20 invalid token lookups (429 TOKEN_LOOKUP_LOCKED)', async () => {
+      const fakeToken = 'b'.repeat(64);
+      for (let i = 0; i < 20; i += 1) {
+        // eslint-disable-next-line no-await-in-loop
+        const r = await request(app)
+          .get(`/api/public/quotes/${fakeToken}`)
+          .set('X-Forwarded-For', '203.0.113.10');
+        expect(r.status).toBe(404);
+      }
+      const locked = await request(app)
+        .get(`/api/public/quotes/${fakeToken}`)
+        .set('X-Forwarded-For', '203.0.113.10');
+      expect(locked.status).toBe(429);
+      expect(locked.body.code).toBe('TOKEN_LOOKUP_LOCKED');
+    }, 30000);
+  });
+
+  describe('POST /:token/respond', () => {
+    it('rejects an invalid action (must be accept|decline) with 400', async () => {
+      const token = await createPublicToken(db, 'quote_action_tokens', { quote_id: quoteId });
+      const res = await request(app)
+        .post(`/api/public/quotes/${token}/respond`)
+        .send({ action: 'maybe' });
+      expect(res.status).toBe(400);
+    });
+
+    it('returns 404 for an unknown token on respond', async () => {
+      const fakeToken = 'c'.repeat(64);
+      const res = await request(app)
+        .post(`/api/public/quotes/${fakeToken}/respond`)
+        .send({ action: 'accept' });
+      expect(res.status).toBe(404);
+    });
+
+    it('returns 410 when the token has expired (service-side check)', async () => {
+      // The POST path goes through quoteService.recordResponse rather
+      // than loadActionToken, so the error shape can differ from the
+      // GET expiry response — what matters is the HTTP status.
+      const past = new Date(Date.now() - 1000);
+      const token = await createPublicToken(db, 'quote_action_tokens', {
+        quote_id: quoteId, expires_at: past,
+      });
+      const res = await request(app)
+        .post(`/api/public/quotes/${token}/respond`)
+        .send({ action: 'accept' });
+      expect(res.status).toBe(410);
+    });
+  });
+});

backend/__tests__/services/backgroundProcessor.test.js

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for backgroundProcessor.claimNextPhoto.
+ *
+ * Mocks the db so we don't need a live postgres/sqlite — focuses on
+ * the claim contract: returns null when no rows, returns row + flips
+ * status to 'processing' when one is available, returns null when a
+ * race loses the UPDATE-with-guard.
+ */
+
+jest.mock('../../src/services/photoProcessor', () => ({
+  processPhoto: jest.fn(),
+  processUploadedPhotos: jest.fn(),
+  queueFilesForProcessing: jest.fn(),
+}));
+
+// Build a fake knex instance whose .transaction() takes a callback we can
+// drive from the test, and whose query-builder records calls.
+function makeFakeDb({ pendingRow = null, updateResult = 1, clientName = 'pg' } = {}) {
+  const queries = [];
+
+  const builder = () => {
+    const recorded = { wheres: [], updates: null, ordered: false, locked: false, skipped: false };
+    queries.push(recorded);
+    const chain = {
+      where: jest.fn(function (...args) {
+        recorded.wheres.push(args);
+        return chain;
+      }),
+      orderBy: jest.fn(function () {
+        recorded.ordered = true;
+        return chain;
+      }),
+      forUpdate: jest.fn(function () {
+        recorded.locked = true;
+        return chain;
+      }),
+      skipLocked: jest.fn(function () {
+        recorded.skipped = true;
+        return chain;
+      }),
+      first: jest.fn(async function () {
+        // Only the SELECT chain returns the pending row; the UPDATE chain
+        // never calls .first().
+        return pendingRow ? { ...pendingRow } : null;
+      }),
+      update: jest.fn(async function (data) {
+        recorded.updates = data;
+        return updateResult;
+      }),
+    };
+    return chain;
+  };
+
+  const trxFn = (table) => builder(table);
+  trxFn.client = { config: { client: clientName } };
+  trxFn.transaction = async (cb) => cb(trxFn);
+
+  // Top-level db('photos') returns same builder for the janitor test path.
+  const db = trxFn;
+  return { db, queries };
+}
+
+describe('backgroundProcessor.claimNextPhoto', () => {
+  function loadProcessor(db) {
+    jest.resetModules();
+    jest.doMock('../../src/database/db', () => ({ db }));
+    return require('../../src/services/backgroundProcessor');
+  }
+
+  it('returns null when there are no pending photos (postgres path)', async () => {
+    const { db } = makeFakeDb({ pendingRow: null, clientName: 'pg' });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toBeNull();
+  });
+
+  it('returns the claimed row and flips status (postgres path)', async () => {
+    const pendingRow = { id: 42, processing_status: 'pending' };
+    const { db, queries } = makeFakeDb({ pendingRow, clientName: 'pg' });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toEqual(pendingRow);
+    // The first query is the SELECT FOR UPDATE SKIP LOCKED.
+    expect(queries[0].locked).toBe(true);
+    expect(queries[0].skipped).toBe(true);
+    // The second query is the status update.
+    expect(queries[1].updates.processing_status).toBe('processing');
+    expect(queries[1].updates.processing_started_at).toBeInstanceOf(Date);
+  });
+
+  it('returns null when the SQLite UPDATE-with-guard loses the race', async () => {
+    const pendingRow = { id: 7 };
+    const { db } = makeFakeDb({ pendingRow, clientName: 'better-sqlite3', updateResult: 0 });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toBeNull();
+  });
+
+  it('returns the row when SQLite UPDATE-with-guard wins', async () => {
+    const pendingRow = { id: 7 };
+    const { db, queries } = makeFakeDb({ pendingRow, clientName: 'better-sqlite3', updateResult: 1 });
+    const bg = loadProcessor(db);
+    const result = await bg.claimNextPhoto();
+    expect(result).toEqual(pendingRow);
+    // SQLite path: no FOR UPDATE / SKIP LOCKED.
+    expect(queries[0].locked).toBe(false);
+    expect(queries[0].skipped).toBe(false);
+  });
+});

backend/__tests__/services/backupIntegrityService.test.js

@@ -0,0 +1,219 @@
+/**
+ * Verifies the backup-integrity check covers every CRM document
+ * artefact column and correctly buckets each row into:
+ *   - verifiedOk      — file exists AND hash matches (when hash is stored)
+ *   - missing         — `*_path` set but file is not on disk
+ *   - hashMismatches  — file exists but bytes don't hash to `*_sha256`
+ *   - existsButNoHash — file exists, no `*_sha256` column for this row
+ *
+ * Uses the CRM integration harness (bootCrmDb) so the schema +
+ * STORAGE_PATH wiring exactly mirrors production behaviour.
+ *
+ * Background: this service is the diagnostic for the
+ * `storage/business-docs/` gap fixed in the same PR — without it,
+ * a restored install would have audit-trail columns referencing
+ * files that no longer exist, but admins would have no way to see
+ * the breakage until a customer asked for their contract back.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+jest.setTimeout(30000);
+
+describe('backupIntegrityService.verifyDocumentArtefacts', () => {
+  let db;
+  let cleanup;
+  let customerId;
+  let storagePath;
+  let backupIntegrityService;
+
+  function seedFile(relPath, content) {
+    const abs = path.join(storagePath, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    return { abs, relPath, sha: sha256(content) };
+  }
+
+  function sha256(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+  }
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ customerId } = await seedMinimal(db));
+    storagePath = process.env.STORAGE_PATH;
+    backupIntegrityService = require('../../src/services/backupIntegrityService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(async () => {
+    // Wipe CRM rows between tests so each scenario sees a clean slate.
+    // Order matters: child tables before parents.
+    await db('invoice_line_items').del().catch(() => {});
+    await db('invoice_payment_log').del().catch(() => {});
+    await db('invoices').del().catch(() => {});
+    await db('quote_line_items').del().catch(() => {});
+    await db('quotes').del().catch(() => {});
+    await db('contracts').del().catch(() => {});
+  });
+
+  it('returns an empty report when no documents reference any path', async () => {
+    const report = await backupIntegrityService.verifyDocumentArtefacts();
+    expect(report.summary.totalRows).toBe(0);
+    expect(report.summary.verifiedOk).toBe(0);
+    expect(report.missing).toEqual([]);
+    expect(report.hashMismatches).toEqual([]);
+    expect(report.existsButNoHash).toEqual([]);
+    expect(report.scannedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(report.scopes).toEqual(expect.arrayContaining(['quote', 'contract', 'contract-signature', 'invoice']));
+  });
+
+  it('flags a contract whose signed_pdf_path file is missing', async () => {
+    // Reference a file that we deliberately never create on disk.
+    // knex's `.returning('id')` returns `[{ id: N }]` on Postgres and
+    // newer SQLite, but `[N]` (plain int) on some SQLite versions —
+    // unwrap both shapes the same way the crmDb test harness does.
+    const inserted = await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-2026-MISSING',
+      status: 'sent',
+      issue_date: '2026-01-01',
+      signed_pdf_path: 'business-docs/contract/2026/C-2026-MISSING.pdf',
+      created_at: new Date(),
+    }).returning('id');
+    const contractId = typeof inserted[0] === 'object' ? inserted[0].id : inserted[0];
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({ scope: ['contract'] });
+    const hit = report.missing.find((m) => m.rowId === contractId);
+    expect(hit).toMatchObject({
+      table: 'contracts',
+      column: 'signed_pdf_path',
+      expectedPath: 'business-docs/contract/2026/C-2026-MISSING.pdf',
+    });
+    expect(report.summary.missingFiles).toBe(1);
+  });
+
+  it('verifies a contract whose file exists AND hash matches', async () => {
+    const { relPath, sha } = seedFile(
+      'business-docs/contract/2026/C-2026-OK.pdf',
+      'this is the signed contract content',
+    );
+    await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-2026-OK',
+      status: 'fully_signed',
+      issue_date: '2026-01-01',
+      signed_pdf_path: relPath,
+      signed_pdf_sha256: sha,
+      created_at: new Date(),
+    });
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({ scope: ['contract'] });
+    expect(report.summary.verifiedOk).toBeGreaterThanOrEqual(1);
+    expect(report.summary.missingFiles).toBe(0);
+    expect(report.summary.hashMismatches).toBe(0);
+  });
+
+  it('flags a hash mismatch when the file exists but bytes differ from signed_pdf_sha256', async () => {
+    const { relPath } = seedFile(
+      'business-docs/contract/2026/C-2026-TAMPER.pdf',
+      'tampered bytes on disk',
+    );
+    const inserted = await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-2026-TAMPER',
+      status: 'fully_signed',
+      issue_date: '2026-01-01',
+      signed_pdf_path: relPath,
+      // Hash for completely different content — simulates tampering or
+      // bit-rot between sign-time and now.
+      signed_pdf_sha256: sha256('the ORIGINAL bytes the customer signed'),
+      created_at: new Date(),
+    }).returning('id');
+    const contractId = typeof inserted[0] === 'object' ? inserted[0].id : inserted[0];
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({ scope: ['contract'] });
+    const hit = report.hashMismatches.find((m) => m.rowId === contractId);
+    expect(hit).toBeDefined();
+    expect(hit.expectedSha).not.toBe(hit.actualSha);
+    expect(hit.column).toBe('signed_pdf_path');
+  });
+
+  it('buckets signature PNGs into existsButNoHash (no hash column)', async () => {
+    const { relPath } = seedFile(
+      'business-docs/contract/signatures/99/customer-1700000000000.png',
+      '\x89PNG\r\n\x1a\n', // doesn't have to be a real PNG, just bytes
+    );
+    await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-2026-SIG',
+      status: 'fully_signed',
+      issue_date: '2026-01-01',
+      signed_customer_signature_path: relPath,
+      created_at: new Date(),
+    });
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({
+      scope: ['contract-signature'],
+    });
+    expect(report.summary.existsButNoHash).toBeGreaterThanOrEqual(1);
+    expect(report.summary.verifiedOk).toBe(0); // no hash → not "verified ok"
+    expect(report.summary.missingFiles).toBe(0);
+    const hit = report.existsButNoHash.find((r) => r.column === 'signed_customer_signature_path');
+    expect(hit).toBeDefined();
+  });
+
+  it('respects the scope filter — contract scope skips quote/invoice tables', async () => {
+    // Seed an invoice with a missing pdf_path AND a contract with a
+    // missing signed_pdf_path. Scoping to contract should only flag
+    // the contract.
+    await db('invoices').insert({
+      customer_account_id: customerId,
+      invoice_number: 'INV-2026-SCOPE',
+      status: 'sent',
+      pdf_path: 'business-docs/invoice/2026/INV-2026-SCOPE.pdf',
+      issue_date: '2026-01-01',
+      due_date: '2026-01-31',
+      created_at: new Date(),
+    });
+    await db('contracts').insert({
+      customer_account_id: customerId,
+      contract_number: 'C-2026-SCOPE',
+      status: 'sent',
+      issue_date: '2026-01-01',
+      signed_pdf_path: 'business-docs/contract/2026/C-2026-SCOPE.pdf',
+      created_at: new Date(),
+    });
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({ scope: ['contract'] });
+    expect(report.scopes).toEqual(['contract']);
+    expect(report.missing.every((m) => m.table === 'contracts')).toBe(true);
+    expect(report.missing.some((m) => m.table === 'invoices')).toBe(false);
+  });
+
+  it('covers invoices.imported_pdf_path (admin-uploaded historical scans)', async () => {
+    // Imported invoices are the most catastrophic case — there's no
+    // renderer that can reproduce them. Verifier must check this column
+    // alongside invoices.pdf_path.
+    await db('invoices').insert({
+      customer_account_id: customerId,
+      invoice_number: 'IMP-2025-001',
+      status: 'sent',
+      imported_pdf_path: 'business-docs/invoice-imports/2025/legacy.pdf',
+      issue_date: '2025-06-01',
+      due_date: '2025-07-01',
+      created_at: new Date(),
+    });
+
+    const report = await backupIntegrityService.verifyDocumentArtefacts({ scope: ['invoice'] });
+    const hit = report.missing.find((m) => m.column === 'imported_pdf_path');
+    expect(hit).toBeDefined();
+  });
+});

backend/__tests__/services/billingRecipients.test.js

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for the recipient resolver that routes invoice / Storno /
+ * reminder emails to a bookkeeper address when one is configured,
+ * while keeping the decision-maker (primary email) on CC.
+ *
+ * Pure helper, no DB, no side effects.
+ */
+
+const { resolveBillingRecipients } = require('../../src/services/_billingRecipients');
+
+describe('resolveBillingRecipients', () => {
+  it('routes to the primary email when no billing_email is set', () => {
+    expect(resolveBillingRecipients({ email: 'bride@example.com' }, null))
+      .toEqual({ to: 'bride@example.com', cc: undefined });
+  });
+
+  it('routes to billing_email and CCs the primary when both are set', () => {
+    expect(resolveBillingRecipients({
+      email: 'bride@example.com',
+      billing_email: 'books@example.com',
+    }, null)).toEqual({
+      to: 'books@example.com',
+      cc: ['bride@example.com'],
+    });
+  });
+
+  it('folds the per-document cc_pdf_email into the CC list', () => {
+    expect(resolveBillingRecipients({
+      email: 'bride@example.com',
+      billing_email: 'books@example.com',
+    }, 'advisor@example.com')).toEqual({
+      to: 'books@example.com',
+      cc: ['bride@example.com', 'advisor@example.com'],
+    });
+  });
+
+  it('uses cc_pdf_email alone when there is no billing_email', () => {
+    expect(resolveBillingRecipients({
+      email: 'bride@example.com',
+    }, 'advisor@example.com')).toEqual({
+      to: 'bride@example.com',
+      cc: ['advisor@example.com'],
+    });
+  });
+
+  it('does not CC the primary onto itself when billing_email equals email', () => {
+    expect(resolveBillingRecipients({
+      email: 'same@example.com',
+      billing_email: 'same@example.com',
+    }, null)).toEqual({
+      to: 'same@example.com',
+      cc: undefined,
+    });
+  });
+
+  it('is case-insensitive when deduping addresses', () => {
+    // RFC 5321 says mailbox local-parts MAY be case sensitive, but in
+    // practice every mail server treats them as insensitive — and the
+    // admin entering "BRIDE@example.com" in one field and
+    // "bride@example.com" in another should not produce two copies.
+    expect(resolveBillingRecipients({
+      email: 'BRIDE@example.com',
+      billing_email: 'books@example.com',
+    }, 'bride@example.com')).toEqual({
+      to: 'books@example.com',
+      cc: ['BRIDE@example.com'],
+    });
+  });
+
+  it('trims whitespace around the addresses', () => {
+    expect(resolveBillingRecipients({
+      email: '  bride@example.com  ',
+      billing_email: '  books@example.com\n',
+    }, '\tadvisor@example.com ')).toEqual({
+      to: 'books@example.com',
+      cc: ['bride@example.com', 'advisor@example.com'],
+    });
+  });
+
+  it('treats empty-string billing_email as not set', () => {
+    expect(resolveBillingRecipients({
+      email: 'bride@example.com',
+      billing_email: '',
+    }, null)).toEqual({
+      to: 'bride@example.com',
+      cc: undefined,
+    });
+  });
+
+  it('returns an empty To when neither email nor billing_email is set', () => {
+    // Caller is responsible for surfacing this — emailProcessor's own
+    // validation will reject the empty recipient. The helper just
+    // refuses to crash.
+    expect(resolveBillingRecipients({}, null))
+      .toEqual({ to: '', cc: undefined });
+  });
+
+  it('tolerates a null customer without throwing', () => {
+    // Per-doc cc alone is never promoted to To: — it stays
+    // supplemental. A missing customer is a caller bug; we just refuse
+    // to crash and let emailProcessor reject the empty recipient.
+    expect(resolveBillingRecipients(null, 'a@b.com'))
+      .toEqual({ to: '', cc: undefined });
+  });
+});

backend/__tests__/services/contractService.test.js

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for the pure helpers in contractService (migration 130).
+ *
+ * The DB-bound CRUD paths (createContract / sendContract /
+ * recordCustomerSignature / attachSignedPdfUpload) are exercised in
+ * manual QA via the admin + public routes. This file covers the
+ * deterministic helpers so regressions in placeholder substitution or
+ * section ordering surface before they leak into a rendered contract.
+ *
+ * The service pulls in DB-bound peers (businessProfileService,
+ * pdfService, emailProcessor) at the top level. We stub the DB layer
+ * + the side-effect peers so the require chain doesn't try to connect
+ * to anything; the helpers under test are pure.
+ */
+
+const path = require('path');
+const servicePath = path.join(__dirname, '..', '..', 'src', 'services', 'contractService');
+
+jest.mock('../../src/database/db', () => ({
+  db: jest.fn(),
+  logActivity: jest.fn(),
+  withRetry: (fn) => fn(),
+}));
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(),
+}));
+jest.mock('../../src/services/pdfService', () => ({
+  renderContractToBuffer: jest.fn(),
+}));
+jest.mock('../../src/services/emailProcessor', () => ({
+  queueEmail: jest.fn(),
+}));
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(),
+}));
+jest.mock('../../src/utils/frontendUrl', () => ({
+  getFrontendBaseUrl: jest.fn(),
+}));
+
+const { _internal } = require(servicePath);
+const { renderTemplatedBody, SECTIONS_ORDER } = _internal;
+
+describe('renderTemplatedBody', () => {
+  it('substitutes simple {{var}} placeholders', () => {
+    expect(renderTemplatedBody(
+      'Hello {{name}}, due in {{net_days}} days.',
+      { name: 'Alice', net_days: 30 },
+    )).toBe('Hello Alice, due in 30 days.');
+  });
+
+  it('preserves unknown placeholders literally so admins notice missing fields', () => {
+    expect(renderTemplatedBody(
+      'Bill from {{issuer}} to {{customer_name}}',
+      { issuer: 'PicPeak GmbH' },
+    )).toBe('Bill from PicPeak GmbH to {{customer_name}}');
+  });
+
+  it('keeps {{#if var}}…{{/if}} block when var is truthy', () => {
+    expect(renderTemplatedBody(
+      '{{#if has_skonto}}Skonto: {{pct}} %{{/if}} on early payment',
+      { has_skonto: true, pct: 2 },
+    )).toBe('Skonto: 2 % on early payment');
+  });
+
+  it('drops {{#if var}}…{{/if}} block when var is falsy', () => {
+    expect(renderTemplatedBody(
+      'Net {{net_days}} d{{#if has_skonto}}, Skonto {{pct}}%{{/if}}.',
+      { net_days: 30, has_skonto: false, pct: 2 },
+    )).toBe('Net 30 d.');
+  });
+
+  it('treats missing variables in {{#if}} as falsy', () => {
+    expect(renderTemplatedBody(
+      'A{{#if missing}}B{{/if}}C',
+      { unrelated: 'foo' },
+    )).toBe('AC');
+  });
+
+  it('handles empty strings and missing variables map gracefully', () => {
+    expect(renderTemplatedBody('', { x: 1 })).toBe('');
+    expect(renderTemplatedBody('plain text', null)).toBe('plain text');
+    expect(renderTemplatedBody('plain text', undefined)).toBe('plain text');
+  });
+
+  it('passes through non-string input unchanged', () => {
+    expect(renderTemplatedBody(null, { x: 1 })).toBeNull();
+    expect(renderTemplatedBody(undefined, { x: 1 })).toBeUndefined();
+  });
+
+  it('substitutes numeric and falsy variable values as strings', () => {
+    expect(renderTemplatedBody('count: {{n}}', { n: 0 })).toBe('count: 0');
+    expect(renderTemplatedBody('flag: {{flag}}', { flag: false })).toBe('flag: false');
+  });
+});
+
+describe('SECTIONS_ORDER', () => {
+  it('matches the canonical six-section order locked in the spec', () => {
+    expect(SECTIONS_ORDER).toEqual([
+      'basics', 'scope', 'privacy', 'commercial', 'nda', 'closing',
+    ]);
+  });
+
+  it('stays in sync with contractBlocksService.ALLOWED_SECTIONS', () => {
+    const blocksService = require('../../src/services/contractBlocksService');
+    expect([...SECTIONS_ORDER].sort()).toEqual(
+      [...blocksService.ALLOWED_SECTIONS].sort(),
+    );
+  });
+});

backend/__tests__/services/customerAccountsService.passive.test.js

@@ -0,0 +1,213 @@
+/**
+ * Tests for the passive-customer surface:
+ *
+ *   - createDirect inserts a customer with password_hash=null,
+ *     queueEmail is never called, race-guard rejects duplicates
+ *   - createInvitation allows passing through when the existing
+ *     customer is passive (promotion path); still rejects when the
+ *     existing customer is active (real duplicate)
+ *   - acceptInvitation upserts into an existing passive customer
+ *     row (preserving id) when one exists; inserts a fresh row
+ *     otherwise; still rejects when the existing customer is active
+ *
+ * Pure unit tests — db is mocked via a thenable chain so we can
+ * inspect every insert / update payload without spinning up SQLite.
+ */
+
+// ----- mock db chain --------------------------------------------------
+//
+// We need fine-grained control over which row each table-name returns
+// for `.first()`, what `.insert(...).returning('id')` resolves to, and
+// what `.update(...)` resolves to. The chain is a thenable proxy that
+// terminates on the call we care about.
+
+const tableSeeds = {};        // table → first-row return value
+const insertResults = {};     // table → array of inserted rows (auto-id from a counter)
+const updateCalls = [];       // [{ table, where, updates }]
+let nextInsertId = 1000;
+
+function resetMockDb() {
+  for (const k of Object.keys(tableSeeds)) delete tableSeeds[k];
+  for (const k of Object.keys(insertResults)) delete insertResults[k];
+  updateCalls.length = 0;
+  nextInsertId = 1000;
+}
+
+function makeChain(tableName) {
+  const chain = {
+    _whereClauses: [],
+    where(...args) { this._whereClauses.push(args); return this; },
+    whereNull() { return this; },
+    whereNot() { return this; },
+    andWhere() { return this; },
+    orderBy() { return this; },
+    leftJoin() { return this; },
+    groupBy() { return this; },
+    select(...args) {
+      // listCustomers / search → return seeded array
+      const seeded = tableSeeds[`${tableName}__select`];
+      return Promise.resolve(seeded || []);
+    },
+    first() {
+      const seeded = tableSeeds[tableName];
+      return Promise.resolve(seeded);
+    },
+    insert(payload) {
+      const id = nextInsertId++;
+      insertResults[tableName] = insertResults[tableName] || [];
+      insertResults[tableName].push({ ...payload, id });
+      const result = { id };
+      return {
+        returning() { return Promise.resolve([result]); },
+        then(resolve) { return Promise.resolve(undefined).then(resolve); },
+      };
+    },
+    update(updates) {
+      updateCalls.push({ table: tableName, where: this._whereClauses, updates });
+      return Promise.resolve(1);
+    },
+    del() { return Promise.resolve(1); },
+    raw() { return this; },
+  };
+  return chain;
+}
+
+const mockDbFn = jest.fn((tableName) => makeChain(tableName));
+mockDbFn.raw = jest.fn();
+mockDbFn.transaction = async (cb) => cb(mockDbFn);
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+  logActivity: jest.fn(async () => {}),
+}));
+
+const mockQueueEmail = jest.fn(async () => {});
+jest.mock('../../src/services/emailProcessor', () => ({
+  queueEmail: mockQueueEmail,
+}));
+
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(async () => ({
+    profile: { default_locale: 'de' },
+    bankAccounts: [],
+  })),
+}));
+
+jest.mock('../../src/utils/frontendUrl', () => ({
+  getFrontendBaseUrl: jest.fn(async () => 'https://test.example'),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn(),
+}));
+
+const customerAccountsService = require('../../src/services/customerAccountsService');
+
+beforeEach(() => {
+  resetMockDb();
+  mockQueueEmail.mockClear();
+});
+
+// --------------------------------------------------------------------
+// createDirect
+// --------------------------------------------------------------------
+
+describe('createDirect', () => {
+  it('inserts a customer with password_hash=null, is_active=true', async () => {
+    tableSeeds.customer_accounts = undefined; // no duplicate
+    const result = await customerAccountsService.createDirect({
+      email: 'test@example.com',
+      prefill: { first_name: 'Anna', company_name: 'ACME GmbH' },
+      createdByAdminId: 5,
+    });
+    expect(result.id).toBeDefined();
+    const inserted = insertResults.customer_accounts[0];
+    expect(inserted.email).toBe('test@example.com');
+    expect(inserted.password_hash).toBeNull();
+    expect(inserted.created_by_admin_id).toBe(5);
+    expect(inserted.first_name).toBe('Anna');
+    expect(inserted.company_name).toBe('ACME GmbH');
+    // is_active should be truthy (could be 1 or true depending on formatBoolean impl)
+    expect([true, 1, '1']).toContain(inserted.is_active);
+  });
+
+  it('defaults preferred_language from the business profile', async () => {
+    tableSeeds.customer_accounts = undefined;
+    await customerAccountsService.createDirect({
+      email: 'de@example.com',
+      prefill: {},
+      createdByAdminId: 1,
+    });
+    expect(insertResults.customer_accounts[0].preferred_language).toBe('de');
+  });
+
+  it('honours preferred_language when the admin pre-fills it', async () => {
+    tableSeeds.customer_accounts = undefined;
+    await customerAccountsService.createDirect({
+      email: 'fr@example.com',
+      prefill: { preferred_language: 'fr' },
+      createdByAdminId: 1,
+    });
+    expect(insertResults.customer_accounts[0].preferred_language).toBe('fr');
+  });
+
+  it('rejects when a customer with the email already exists', async () => {
+    tableSeeds.customer_accounts = { id: 7, email: 'dup@example.com', password_hash: 'whatever' };
+    await expect(customerAccountsService.createDirect({
+      email: 'dup@example.com',
+      prefill: {},
+      createdByAdminId: 1,
+    })).rejects.toThrow(/already exists/);
+  });
+
+  it('rejects when only an EMAIL is supplied without anything else (still valid)', async () => {
+    tableSeeds.customer_accounts = undefined;
+    await expect(customerAccountsService.createDirect({
+      email: '',
+      prefill: {},
+      createdByAdminId: 1,
+    })).rejects.toThrow(/Email is required/);
+  });
+
+  it('NEVER queues an invitation email (regression guard)', async () => {
+    tableSeeds.customer_accounts = undefined;
+    await customerAccountsService.createDirect({
+      email: 'silent@example.com',
+      prefill: {},
+      createdByAdminId: 1,
+    });
+    expect(mockQueueEmail).not.toHaveBeenCalled();
+  });
+});
+
+// --------------------------------------------------------------------
+// createInvitation passive-allowance behaviour
+// --------------------------------------------------------------------
+
+describe('createInvitation — duplicate-email guard', () => {
+  it('still rejects when the existing customer has a password (real duplicate)', async () => {
+    tableSeeds.customer_accounts = { id: 1, email: 'active@example.com', password_hash: 'hash' };
+    await expect(customerAccountsService.createInvitation({
+      email: 'active@example.com',
+      invitedById: 5,
+      prefill: null,
+    })).rejects.toThrow(/already exists/);
+    expect(mockQueueEmail).not.toHaveBeenCalled();
+  });
+
+  it('ALLOWS through when the existing customer is passive (promote path)', async () => {
+    tableSeeds.customer_accounts = { id: 7, email: 'passive@example.com', password_hash: null };
+    // no pending invitation
+    // The chain returns `tableSeeds.customer_invitations` for .first()
+    // and we haven't seeded one, so it's undefined → allowed through.
+    const out = await customerAccountsService.createInvitation({
+      email: 'passive@example.com',
+      invitedById: 9,
+      prefill: { first_name: 'Anna' },
+    });
+    expect(out.id).toBeDefined();
+    expect(out.token).toMatch(/^[0-9a-f]{64}$/);
+    expect(mockQueueEmail).toHaveBeenCalledTimes(1);
+  });
+});

backend/__tests__/services/customerHoursService.test.js

@@ -0,0 +1,165 @@
+/**
+ * Unit tests for the pure helpers in customerHoursService (migration
+ * 129). The CRUD paths themselves are exercised end-to-end via the
+ * admin/customers routes during manual QA; this file covers the
+ * deterministic logic so regressions in the rate / duration / lock
+ * resolution show up before they hit a real invoice.
+ */
+
+const path = require('path');
+const servicePath = path.join(__dirname, '..', '..', 'src', 'services', 'customerHoursService');
+
+// The service imports invoiceService which pulls in the DB. We don't
+// need either for the pure helpers — stub the DB layer so the
+// require chain doesn't try to connect to anything.
+jest.mock('../../src/database/db', () => ({
+  db: jest.fn(),
+  logActivity: jest.fn(),
+  withRetry: (fn) => fn(),
+}));
+jest.mock('../../src/services/invoiceService', () => ({}));
+
+const { _internal } = require(servicePath);
+const { computeDurationMinutes, resolveEffectiveRate, isEntryLocked, buildLineItemFromEntry } = _internal;
+
+describe('computeDurationMinutes', () => {
+  it('returns minute count for a basic window', () => {
+    expect(computeDurationMinutes('09:00', '11:30')).toBe(150);
+  });
+
+  it('handles single-minute precision', () => {
+    expect(computeDurationMinutes('09:30', '11:00')).toBe(90);
+    expect(computeDurationMinutes('14:15', '14:30')).toBe(15);
+  });
+
+  it('rejects malformed input', () => {
+    expect(() => computeDurationMinutes('9:00', '11:00')).toThrow(/Invalid start_time/);
+    expect(() => computeDurationMinutes('09:00', '25:00')).toThrow(/Invalid end_time/);
+  });
+
+  it('rejects zero or negative duration', () => {
+    expect(() => computeDurationMinutes('09:00', '09:00')).toThrow(/must be after/);
+    expect(() => computeDurationMinutes('11:00', '09:00')).toThrow(/must be after/);
+  });
+});
+
+describe('resolveEffectiveRate', () => {
+  it('prefers the per-entry override when set', () => {
+    expect(resolveEffectiveRate(
+      { hourly_rate_minor_override: 20000 },
+      { hourly_rate_minor: 15000 },
+    )).toBe(20000);
+  });
+
+  it('falls back to the customer default when no override', () => {
+    expect(resolveEffectiveRate(
+      { hourly_rate_minor_override: null },
+      { hourly_rate_minor: 15000 },
+    )).toBe(15000);
+  });
+
+  it('throws when both override and customer rate are unset', () => {
+    expect(() => resolveEffectiveRate(
+      { hourly_rate_minor_override: null },
+      { hourly_rate_minor: null },
+    )).toThrow(/No hourly rate/);
+  });
+
+  it('treats override=0 as "explicitly zero" (not null)', () => {
+    // Override === 0 is unusual but legal — pro bono blocks, internal
+    // tracking. Must NOT fall through to the customer default.
+    expect(resolveEffectiveRate(
+      { hourly_rate_minor_override: 0 },
+      { hourly_rate_minor: 15000 },
+    )).toBe(0);
+  });
+});
+
+describe('isEntryLocked', () => {
+  it('unbilled entry → not locked', () => {
+    expect(isEntryLocked({ invoice_id: null }, null)).toBe(false);
+  });
+
+  it('monthly draft → not locked (still accumulating)', () => {
+    expect(isEntryLocked(
+      { invoice_id: 42 },
+      { id: 42, is_monthly_draft: true, status: 'scheduled', scheduled_send_at: null },
+    )).toBe(false);
+  });
+
+  it('standalone draft with no send time → not locked', () => {
+    expect(isEntryLocked(
+      { invoice_id: 42 },
+      { id: 42, is_monthly_draft: false, status: 'scheduled', scheduled_send_at: null },
+    )).toBe(false);
+  });
+
+  it('future-scheduled draft → not locked', () => {
+    const future = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    expect(isEntryLocked(
+      { invoice_id: 42 },
+      { id: 42, is_monthly_draft: false, status: 'scheduled', scheduled_send_at: future },
+    )).toBe(false);
+  });
+
+  it('armed (scheduled_send_at in the past, status still scheduled) → locked', () => {
+    const past = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+    expect(isEntryLocked(
+      { invoice_id: 42 },
+      { id: 42, is_monthly_draft: false, status: 'scheduled', scheduled_send_at: past },
+    )).toBe(true);
+  });
+
+  it('sent / paid / overdue / cancelled → locked', () => {
+    for (const status of ['sent', 'paid', 'overdue', 'cancelled']) {
+      expect(isEntryLocked(
+        { invoice_id: 42 },
+        { id: 42, is_monthly_draft: false, status, scheduled_send_at: null },
+      )).toBe(true);
+    }
+  });
+
+  it('entry references a deleted invoice (null) → treat as unbilled', () => {
+    expect(isEntryLocked({ invoice_id: 42 }, null)).toBe(false);
+  });
+});
+
+describe('buildLineItemFromEntry', () => {
+  const baseEntry = {
+    entry_date: '2026-05-20',
+    start_time: '09:00',
+    end_time: '11:30',
+    duration_minutes: 150,
+    description: 'Editing wedding photos',
+  };
+
+  it('formats the description per spec', () => {
+    const li = buildLineItemFromEntry(baseEntry, 15000);
+    expect(li.description).toBe('2026-05-20 09:00–11:30 (2.50h): Editing wedding photos');
+  });
+
+  it('omits the colon when no description', () => {
+    const li = buildLineItemFromEntry({ ...baseEntry, description: null }, 15000);
+    expect(li.description).toBe('2026-05-20 09:00–11:30 (2.50h)');
+  });
+
+  it('quantity is decimal hours with 2 places', () => {
+    const li = buildLineItemFromEntry(baseEntry, 15000);
+    expect(li.quantity).toBeCloseTo(2.5, 5);
+  });
+
+  it('line_total rounds correctly for non-clean durations', () => {
+    // 15 minutes at CHF 100/h = CHF 25.00 = 2500 minor
+    const li = buildLineItemFromEntry(
+      { ...baseEntry, start_time: '14:00', end_time: '14:15', duration_minutes: 15 },
+      10000,
+    );
+    expect(li.line_total_minor).toBe(2500);
+  });
+
+  it('zero-rate line items produce a zero total without exploding', () => {
+    const li = buildLineItemFromEntry(baseEntry, 0);
+    expect(li.line_total_minor).toBe(0);
+    expect(li.unit_price_minor).toBe(0);
+  });
+});

backend/__tests__/services/downloadFilenameService.test.js

@@ -0,0 +1,76 @@
+/**
+ * Pure-logic tests for the #493 download-filename helpers that don't depend
+ * on the DB (those are covered by the route integration suite).
+ */
+
+const {
+  pickRawDownloadName,
+  getZipEntryNames,
+} = require('../../src/services/downloadFilenameService');
+
+describe('pickRawDownloadName', () => {
+  it('returns the storage filename when the toggle is off', () => {
+    expect(
+      pickRawDownloadName({ id: 1, filename: 'slug_001.jpg', original_filename: 'DSC_1.jpg' }, false)
+    ).toBe('slug_001.jpg');
+  });
+
+  it('returns original_filename when the toggle is on', () => {
+    expect(
+      pickRawDownloadName({ id: 1, filename: 'slug_001.jpg', original_filename: 'DSC_1.jpg' }, true)
+    ).toBe('DSC_1.jpg');
+  });
+
+  it('falls back to storage filename when original_filename is missing', () => {
+    expect(
+      pickRawDownloadName({ id: 1, filename: 'slug_001.jpg', original_filename: null }, true)
+    ).toBe('slug_001.jpg');
+  });
+
+  it('produces a stable last-resort name when both are missing', () => {
+    expect(pickRawDownloadName({ id: 42 }, true)).toBe('photo-42.jpg');
+  });
+});
+
+describe('getZipEntryNames', () => {
+  it('uses original filenames with deterministic suffixes on collision', () => {
+    const photos = [
+      { id: 1, filename: 'slug_001.jpg', original_filename: 'DSC_1234.jpg' },
+      { id: 2, filename: 'slug_002.jpg', original_filename: 'DSC_1234.jpg' },
+      { id: 3, filename: 'slug_003.jpg', original_filename: 'DSC_1235.jpg' },
+    ];
+    expect(getZipEntryNames(photos, true)).toEqual([
+      'DSC_1234.jpg',
+      'DSC_1234_1.jpg',
+      'DSC_1235.jpg',
+    ]);
+  });
+
+  it('falls back to storage filename per-photo when original is missing', () => {
+    const photos = [
+      { id: 1, filename: 'slug_001.jpg', original_filename: 'DSC_1.jpg' },
+      { id: 2, filename: 'slug_002.jpg', original_filename: null },
+    ];
+    expect(getZipEntryNames(photos, true)).toEqual([
+      'DSC_1.jpg',
+      'slug_002.jpg',
+    ]);
+  });
+
+  it('returns storage filenames when the toggle is off, dedup still applies', () => {
+    const photos = [
+      { id: 1, filename: 'a.jpg', original_filename: 'DSC_1.jpg' },
+      { id: 2, filename: 'a.jpg', original_filename: 'DSC_2.jpg' },
+    ];
+    expect(getZipEntryNames(photos, false)).toEqual(['a.jpg', 'a_1.jpg']);
+  });
+
+  it('sanitizes path-traversal attempts that sneak into original_filename', () => {
+    const photos = [
+      { id: 1, filename: 'slug_001.jpg', original_filename: '../etc/passwd' },
+    ];
+    const [name] = getZipEntryNames(photos, true);
+    expect(name).not.toContain('..');
+    expect(name).not.toContain('/');
+  });
+});

backend/__tests__/services/emailProcessor.htmlToText.test.js

@@ -0,0 +1,75 @@
+/**
+ * Unit tests for emailProcessor.htmlToText.
+ *
+ * Regression: when a template ships without a body_text, sendTemplateEmail
+ * used `htmlBody.replace(/<[^>]*>/g, '')` to derive the plain-text fallback.
+ * That regex strips angle-bracket tags but leaves the *contents* of <style>
+ * and <script> blocks intact — so any HTML wrapped by wrapEmailHtml() (which
+ * embeds a 100+ line <style> block) produced a "plain-text" email starting
+ * with `body { margin: 0; padding: 0; … }`. htmlToText fixes that.
+ */
+
+jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
+
+const { htmlToText } = require('../../src/services/emailProcessor');
+
+describe('htmlToText', () => {
+  it('returns empty string for empty input', () => {
+    expect(htmlToText('')).toBe('');
+    expect(htmlToText(null)).toBe('');
+    expect(htmlToText(undefined)).toBe('');
+  });
+
+  it('strips <style> blocks and their contents', () => {
+    const html = '<html><head><style>body { margin: 0; color: red; }</style></head><body>Hello</body></html>';
+    const out = htmlToText(html);
+    expect(out).toBe('Hello');
+    expect(out).not.toMatch(/margin/);
+    expect(out).not.toMatch(/color/);
+  });
+
+  it('strips <script> blocks and their contents', () => {
+    const html = '<body><script>alert("x")</script>Hi</body>';
+    expect(htmlToText(html)).toBe('Hi');
+  });
+
+  it('converts <br> tags to newlines', () => {
+    expect(htmlToText('a<br>b<br />c<BR/>d')).toBe('a\nb\nc\nd');
+  });
+
+  it('keeps a paragraph break between adjacent <p> tags', () => {
+    expect(htmlToText('<p>one</p><p>two</p>')).toBe('one\n\ntwo');
+  });
+
+  it('decodes the common HTML entities', () => {
+    expect(htmlToText('Tom &amp; Jerry &lt;3 &quot;hi&quot;'))
+      .toBe('Tom & Jerry <3 "hi"');
+  });
+
+  it('handles a fully-wrapped email body without leaking CSS rules', () => {
+    // Shape mirrors what wrapEmailHtml() produces: a <style> block with many
+    // CSS rules followed by the actual content.
+    const wrapped = `
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body { margin: 0; padding: 0; font-family: sans-serif; background-color: #f5f5f5; }
+    .email-container { max-width: 600px; }
+    .button { background-color: #5C8762; color: white !important; }
+  </style>
+</head>
+<body>
+  <h2>Galerie erfolgreich erstellt</h2>
+  <p>Liebe(r) Natalie,</p>
+</body>
+</html>`;
+    const out = htmlToText(wrapped);
+    expect(out).toContain('Galerie erfolgreich erstellt');
+    expect(out).toContain('Liebe(r) Natalie');
+    expect(out).not.toMatch(/margin/);
+    expect(out).not.toMatch(/font-family/);
+    expect(out).not.toMatch(/background-color/);
+    expect(out).not.toMatch(/\.button/);
+  });
+});

backend/__tests__/services/emailProcessor.safeTemplateReplace.test.js

@@ -0,0 +1,138 @@
+/**
+ * Unit tests for emailProcessor.safeTemplateReplace.
+ *
+ * Covers the two regressions that hit picpeak.nothaft.cloud on the
+ * 3.32.x betas:
+ *   - {{#if VAR}}…{{/if}} blocks rendered as literal text in the email
+ *     because the renderer only handled {{var}} substitution and the
+ *     shipped templates use Handlebars-style conditionals.
+ *   - {{var}} substitution inside a kept conditional block.
+ *
+ * The publish-from-draft password localisation lives inside the wider
+ * processTemplate() pipeline (DB-backed), so it isn't covered here — the
+ * sentinel string '(set at creation)' is asserted only at the i18n-map
+ * level by integration in adminEvents.js.
+ */
+
+jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
+
+const { safeTemplateReplace } = require('../../src/services/emailProcessor');
+
+describe('safeTemplateReplace', () => {
+  describe('flat variable substitution', () => {
+    it('replaces {{var}} with the variable value', () => {
+      expect(safeTemplateReplace('Hello {{name}}!', { name: 'Paul' }))
+        .toBe('Hello Paul!');
+    });
+
+    it('leaves unknown variables untouched', () => {
+      expect(safeTemplateReplace('Hello {{name}}!', {}))
+        .toBe('Hello {{name}}!');
+    });
+
+    it('coerces non-string values to string', () => {
+      expect(safeTemplateReplace('Count: {{n}}', { n: 42 }))
+        .toBe('Count: 42');
+    });
+
+    it('handles empty templates and missing variables map', () => {
+      expect(safeTemplateReplace('', { x: 1 })).toBe('');
+      expect(safeTemplateReplace('plain text', undefined)).toBe('plain text');
+      expect(safeTemplateReplace(null, {})).toBe(null);
+    });
+  });
+
+  describe('{{#if VAR}}…{{/if}} blocks', () => {
+    it('strips the block when the variable is missing', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, {})).toBe('before  after');
+    });
+
+    it('strips the block when the variable is an empty string', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, { welcome: '' })).toBe('before  after');
+    });
+
+    it('strips the block when the variable is null', () => {
+      const tpl = '{{#if x}}kept{{/if}}';
+      expect(safeTemplateReplace(tpl, { x: null })).toBe('');
+    });
+
+    it('keeps the block and substitutes inside it when truthy', () => {
+      const tpl = 'before {{#if welcome}}HELLO {{welcome}}{{/if}} after';
+      expect(safeTemplateReplace(tpl, { welcome: 'world' }))
+        .toBe('before HELLO world after');
+    });
+
+    it('handles multi-line conditional blocks', () => {
+      const tpl = [
+        'Liebe(r) {{host_name}},',
+        '',
+        '{{#if welcome_message}}',
+        'Persönliche Nachricht:',
+        '{{welcome_message}}',
+        '{{/if}}',
+        'Galerie-Details:',
+      ].join('\n');
+
+      const withMsg = safeTemplateReplace(tpl, {
+        host_name: 'Natalie',
+        welcome_message: 'Schön, dass ihr da seid!',
+      });
+      expect(withMsg).toContain('Persönliche Nachricht:');
+      expect(withMsg).toContain('Schön, dass ihr da seid!');
+      expect(withMsg).not.toContain('{{#if');
+      expect(withMsg).not.toContain('{{/if');
+
+      const withoutMsg = safeTemplateReplace(tpl, {
+        host_name: 'Natalie',
+        welcome_message: '',
+      });
+      expect(withoutMsg).not.toContain('Persönliche Nachricht');
+      expect(withoutMsg).not.toContain('{{#if');
+      expect(withoutMsg).not.toContain('{{/if');
+      expect(withoutMsg).toContain('Liebe(r) Natalie,');
+      expect(withoutMsg).toContain('Galerie-Details:');
+    });
+
+    it('handles multiple sibling conditionals independently', () => {
+      const tpl = '{{#if a}}A{{/if}}|{{#if b}}B{{/if}}|{{#if c}}C{{/if}}';
+      expect(safeTemplateReplace(tpl, { a: 1, c: 'yes' })).toBe('A||C');
+    });
+
+    it('treats numeric 0 as falsy', () => {
+      expect(safeTemplateReplace('{{#if n}}has-n{{/if}}', { n: 0 })).toBe('');
+    });
+  });
+
+  describe('HTML escaping (escapeHtml: true)', () => {
+    it('does not escape by default', () => {
+      const tpl = 'Welcome to {{event_name}}';
+      expect(safeTemplateReplace(tpl, { event_name: 'Test <script>' }))
+        .toBe('Welcome to Test <script>');
+    });
+
+    it('escapes admin-supplied values when opted in', () => {
+      const tpl = 'Welcome to {{event_name}}';
+      expect(safeTemplateReplace(tpl, { event_name: 'Test <script>alert(1)</script>' }, { escapeHtml: true }))
+        .toBe('Welcome to Test &lt;script&gt;alert(1)&lt;/script&gt;');
+    });
+
+    it('escapes both the < > and & characters and quotes', () => {
+      expect(safeTemplateReplace('{{x}}', { x: '<a href="evil">A & B\'s</a>' }, { escapeHtml: true }))
+        .toBe('&lt;a href=&quot;evil&quot;&gt;A &amp; B&#39;s&lt;/a&gt;');
+    });
+
+    it('passes welcome_message through unescaped (already HTML from formatWelcomeMessage)', () => {
+      const tpl = '<p>{{welcome_message}}</p>';
+      expect(safeTemplateReplace(tpl, { welcome_message: 'Hi<br />there' }, { escapeHtml: true }))
+        .toBe('<p>Hi<br />there</p>');
+    });
+
+    it('passes server-generated URLs through unescaped', () => {
+      const tpl = '<a href="{{gallery_link}}">link</a>';
+      expect(safeTemplateReplace(tpl, { gallery_link: 'https://example.com/g/abc?token=xyz&u=1' }, { escapeHtml: true }))
+        .toBe('<a href="https://example.com/g/abc?token=xyz&u=1">link</a>');
+    });
+  });
+});

backend/__tests__/services/eventService.calendar.test.js

@@ -0,0 +1,119 @@
+/**
+ * Unit tests for `normaliseEventTimeTriple` — the pure validator that
+ * gates the migration-137 calendar time columns on events.
+ *
+ * The DB-bound CRUD paths (createEvent/updateEvent) inline this
+ * helper and write through hasColumnCached guards; those are
+ * exercised in manual QA. This file pins the contract so a future
+ * tweak to the validation rules doesn't silently break it.
+ */
+
+const path = require('path');
+const servicePath = path.join(__dirname, '..', '..', 'src', 'services', 'eventService');
+
+// Stub every DB-bound peer so the require chain doesn't try to open
+// a knex connection. The helper under test is pure.
+jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
+jest.mock('../../src/utils/schemaCache', () => ({ hasColumnCached: jest.fn() }));
+jest.mock('bcrypt', () => ({ hash: jest.fn() }));
+
+const { normaliseEventTimeTriple } = require(servicePath);
+
+describe('normaliseEventTimeTriple', () => {
+  it('defaults to full-day when is_full_day is undefined', () => {
+    expect(normaliseEventTimeTriple({})).toEqual({
+      event_time_start: null,
+      event_time_end: null,
+      is_full_day: true,
+    });
+  });
+
+  it('forces times to null when is_full_day is true even if times are supplied', () => {
+    expect(normaliseEventTimeTriple({
+      is_full_day: true,
+      event_time_start: '10:00',
+      event_time_end: '12:00',
+    })).toEqual({
+      event_time_start: null,
+      event_time_end: null,
+      is_full_day: true,
+    });
+  });
+
+  it('accepts a valid timed range when is_full_day is false', () => {
+    expect(normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '09:30',
+      event_time_end: '17:00',
+    })).toEqual({
+      event_time_start: '09:30',
+      event_time_end: '17:00',
+      is_full_day: false,
+    });
+  });
+
+  it('throws when is_full_day is false and start is missing/malformed', () => {
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_end: '12:00',
+    })).toThrow(/HH:MM/);
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '25:00',
+      event_time_end: '12:00',
+    })).toThrow(/HH:MM/);
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '9:00',
+      event_time_end: '12:00',
+    })).toThrow(/HH:MM/);
+  });
+
+  it('throws when end is missing or malformed', () => {
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '10:00',
+    })).toThrow(/HH:MM/);
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '10:00',
+      event_time_end: '12:99',
+    })).toThrow(/HH:MM/);
+  });
+
+  it('throws when end is at or before start', () => {
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '10:00',
+      event_time_end: '10:00',
+    })).toThrow(/after/);
+    expect(() => normaliseEventTimeTriple({
+      is_full_day: false,
+      event_time_start: '15:00',
+      event_time_end: '10:00',
+    })).toThrow(/after/);
+  });
+
+  it('parses string boolean flag', () => {
+    // `parseBooleanInput` accepts "true" / "false" / "1" / "0" — verify
+    // the helper consumes them transparently.
+    expect(normaliseEventTimeTriple({
+      is_full_day: 'false',
+      event_time_start: '08:00',
+      event_time_end: '09:00',
+    })).toEqual({
+      event_time_start: '08:00',
+      event_time_end: '09:00',
+      is_full_day: false,
+    });
+    expect(normaliseEventTimeTriple({
+      is_full_day: '1',
+      event_time_start: '08:00',
+      event_time_end: '09:00',
+    })).toEqual({
+      event_time_start: null,
+      event_time_end: null,
+      is_full_day: true,
+    });
+  });
+});

backend/__tests__/services/fontsService.test.js

@@ -0,0 +1,320 @@
+const fs = require('fs');
+const fsPromises = fs.promises;
+const os = require('os');
+const path = require('path');
+
+// Silence the logger so test output stays clean. Capture calls so the
+// "warning logged" assertions can still verify behaviour.
+jest.mock('../../src/utils/logger', () => ({
+  warn: jest.fn(),
+  info: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn()
+}));
+
+const logger = require('../../src/utils/logger');
+// Required ONCE at module top so the jest.mock factory above applies to
+// the logger reference that fontsService captures. A previous version
+// re-required it inside beforeEach() with jest.resetModules() — that
+// silently bypassed the mock (logger calls went to the real logger),
+// so the "warning logged" assertions would resolve as 0 calls and
+// silently pass-as-noop. Module-level state in fontsService is just
+// the cache, which clearFontsCache() resets between tests.
+const fontsService = require('../../src/services/fontsService');
+
+// Probe at load time: is the host filesystem case-sensitive?
+// macOS APFS and Windows NTFS treat "Inter" and "INTER" as the same
+// directory entry, which means the "two folders, same lowercase key"
+// dedup test below can't be set up via real folders on those platforms —
+// the second mkdir is a no-op. Skip that one test conditionally.
+const FS_IS_CASE_SENSITIVE = (() => {
+  const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-fs-probe-'));
+  fs.writeFileSync(path.join(probeDir, 'casetest'), '');
+  let sensitive = true;
+  try {
+    fs.accessSync(path.join(probeDir, 'CASETEST'));
+    sensitive = false;
+  } catch { /* file not found → case-sensitive FS */ }
+  fs.rmSync(probeDir, { recursive: true, force: true });
+  return sensitive;
+})();
+const testCaseSensitiveFS = FS_IS_CASE_SENSITIVE ? test : test.skip;
+
+let bundledRoot;
+let userRoot;
+
+/**
+ * Create a font family folder with the given weights (and optional meta.json).
+ * @param {string} root absolute path to the bundled or user root
+ * @param {string} folderName e.g. "Inter" or "Playfair-Display"
+ * @param {Array<number>|Array<string>} weights numeric weights (creates `<w>.woff2`)
+ *                                              or filenames to create directly
+ * @param {Object|null} meta optional meta.json contents (object) or null
+ */
+async function makeFamily(root, folderName, weights, meta = null) {
+  const dir = path.join(root, folderName);
+  await fsPromises.mkdir(dir, { recursive: true });
+  for (const w of weights) {
+    const fname = typeof w === 'number' ? `${w}.woff2` : w;
+    await fsPromises.writeFile(path.join(dir, fname), Buffer.from([]));
+  }
+  if (meta !== null) {
+    await fsPromises.writeFile(
+      path.join(dir, 'meta.json'),
+      typeof meta === 'string' ? meta : JSON.stringify(meta)
+    );
+  }
+  return dir;
+}
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+
+  bundledRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-bundled-'));
+  userRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-user-'));
+
+  process.env.PICPEAK_BUNDLED_FONTS_ROOT = bundledRoot;
+  // The user root resolves under STORAGE_PATH/fonts, so STORAGE_PATH must
+  // point at the parent of userRoot — we name the leaf "fonts" ourselves.
+  const storageParent = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'picpeak-fonts-storage-'));
+  await fsPromises.rename(userRoot, path.join(storageParent, 'fonts'));
+  userRoot = path.join(storageParent, 'fonts');
+  process.env.STORAGE_PATH = storageParent;
+
+  // Reset the module-level cache so each test sees a fresh scan.
+  // (Both getBundledFontsRoot and getUserFontsRoot read process.env at
+  // call-time, so the env vars set above are picked up without needing
+  // to re-require the module — see fontsService.js getBundledFontsRoot /
+  // getUserFontsRoot.)
+  fontsService.clearFontsCache();
+});
+
+afterEach(async () => {
+  fontsService.clearFontsCache();
+  await fsPromises.rm(bundledRoot, { recursive: true, force: true }).catch(() => {});
+  // userRoot's parent is the actual mkdtemp; remove it.
+  await fsPromises.rm(path.dirname(userRoot), { recursive: true, force: true }).catch(() => {});
+  delete process.env.PICPEAK_BUNDLED_FONTS_ROOT;
+  delete process.env.STORAGE_PATH;
+});
+
+describe('fontsService.listFonts', () => {
+  describe('roots', () => {
+    test('empty bundled root + missing user root → []', async () => {
+      // delete user root so it triggers ENOENT
+      await fsPromises.rm(path.dirname(userRoot), { recursive: true, force: true });
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toEqual([]);
+    });
+
+    test('missing bundled root (ENOENT) → [], does not throw', async () => {
+      await fsPromises.rm(bundledRoot, { recursive: true, force: true });
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toEqual([]);
+    });
+
+    test('non-directory entries at the root are skipped', async () => {
+      await fsPromises.writeFile(path.join(bundledRoot, 'README.md'), 'hi');
+      await makeFamily(bundledRoot, 'Inter', [400, 700]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+    });
+
+    test('hidden folders are skipped', async () => {
+      await makeFamily(bundledRoot, '.git', [400]);
+      await makeFamily(bundledRoot, '.DS_Store', [400]);
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+    });
+  });
+
+  describe('weight parsing', () => {
+    test('three weight files → sorted ascending', async () => {
+      await makeFamily(bundledRoot, 'Inter', [700, 400, 600]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 600, 700]);
+    });
+
+    test('non-numeric filenames are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', ['bold.woff2', 'regular.woff2', '400.woff2', '700.woff2']);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 700]);
+    });
+
+    test('non-.woff2 files are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', ['400.ttf', '400.woff', '400.woff2', '700.otf']);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400]);
+    });
+
+    test('weight values out of range (sub-1 / over-1000) are ignored', async () => {
+      await makeFamily(bundledRoot, 'Inter', [0, 400, 1001, 700]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 700]);
+    });
+
+    test('family folder with no usable .woff2 files is silently skipped', async () => {
+      await makeFamily(bundledRoot, 'NoWeights', ['readme.txt', 'bold.ttf']);
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Inter']);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Skipping NoWeights')
+      );
+    });
+  });
+
+  describe('folder name → display family', () => {
+    test('hyphens become spaces', async () => {
+      await makeFamily(bundledRoot, 'Playfair-Display', [400]);
+      const [pd] = await fontsService.listFonts();
+      expect(pd.family).toBe('Playfair Display');
+    });
+
+    test('case is preserved', async () => {
+      await makeFamily(bundledRoot, 'IBM-Plex-Sans', [400]);
+      const [ibm] = await fontsService.listFonts();
+      expect(ibm.family).toBe('IBM Plex Sans');
+    });
+  });
+
+  describe('user-overrides-bundled', () => {
+    test('user folder of the same family wins; weights come from user', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400, 600, 700]);
+      await makeFamily(userRoot, 'Inter', [400, 900]); // different weights
+      const [inter] = await fontsService.listFonts();
+      expect(inter.weights).toEqual([400, 900]);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('overrides bundled default')
+      );
+    });
+
+    test('user-only family is included', async () => {
+      await makeFamily(userRoot, 'Lobster', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual(['Lobster']);
+    });
+
+    testCaseSensitiveFS('case-insensitive duplicate within the same root → second skipped, warning', async () => {
+      // Two folder names whose lowercase keys collide. On a case-sensitive
+      // FS (Linux ext4) we can create both `Inter/` and `INTER/`; on a
+      // case-insensitive FS (macOS APFS, Windows NTFS) the second mkdir
+      // resolves to the same directory as the first and the dedup branch
+      // is unreachable from this test setup — see testCaseSensitiveFS above.
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      await makeFamily(bundledRoot, 'INTER', [700]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts).toHaveLength(1);
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Duplicate family')
+      );
+    });
+  });
+
+  describe('meta.json — generic fallback', () => {
+    test('valid generic="serif"', async () => {
+      await makeFamily(bundledRoot, 'Playfair-Display', [400], { generic: 'serif' });
+      const [pd] = await fontsService.listFonts();
+      expect(pd.generic).toBe('serif');
+    });
+
+    test('valid generic="cursive"', async () => {
+      await makeFamily(bundledRoot, 'Comic-Neue', [400], { generic: 'cursive' });
+      const [cn] = await fontsService.listFonts();
+      expect(cn.generic).toBe('cursive');
+    });
+
+    test('valid generic="monospace"', async () => {
+      await makeFamily(bundledRoot, 'Fira-Mono', [400], { generic: 'monospace' });
+      const [fm] = await fontsService.listFonts();
+      expect(fm.generic).toBe('monospace');
+    });
+
+    test('missing meta.json → defaults to sans-serif (no warning)', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      // No warning for the missing-file case (it's the normal path).
+      const noisy = (logger.warn.mock.calls || []).filter((c) =>
+        String(c[0]).includes('meta.json')
+      );
+      expect(noisy).toEqual([]);
+    });
+
+    test('invalid generic value → defaults to sans-serif, warning logged', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400], { generic: 'bogus' });
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('invalid generic "bogus"')
+      );
+    });
+
+    test('malformed JSON → defaults to sans-serif, warning logged', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400], '{ this is not json');
+      const [inter] = await fontsService.listFonts();
+      expect(inter.generic).toBe('sans-serif');
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('not valid JSON')
+      );
+    });
+  });
+
+  describe('result shape', () => {
+    test('every family is { family, weights, generic }', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400, 700]);
+      await makeFamily(bundledRoot, 'Playfair-Display', [400], { generic: 'serif' });
+      const fonts = await fontsService.listFonts();
+      for (const f of fonts) {
+        expect(f).toEqual({
+          family: expect.any(String),
+          weights: expect.any(Array),
+          generic: expect.stringMatching(/^(sans-serif|serif|cursive|monospace)$/)
+        });
+        expect(f.weights.length).toBeGreaterThan(0);
+      }
+    });
+
+    test('output sorted alphabetically by family', async () => {
+      await makeFamily(bundledRoot, 'Zilla-Slab', [400]);
+      await makeFamily(bundledRoot, 'Alpha-Sans', [400]);
+      await makeFamily(bundledRoot, 'Mid-Pack', [400]);
+      const fonts = await fontsService.listFonts();
+      expect(fonts.map((f) => f.family)).toEqual([
+        'Alpha Sans',
+        'Mid Pack',
+        'Zilla Slab'
+      ]);
+    });
+  });
+
+  describe('cache', () => {
+    test('cache hit: second call within TTL does not re-readdir', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      const spy = jest.spyOn(fsPromises, 'readdir');
+      await fontsService.listFonts();
+      const callsAfterFirst = spy.mock.calls.length;
+      await fontsService.listFonts();
+      expect(spy.mock.calls.length).toBe(callsAfterFirst);
+      spy.mockRestore();
+    });
+
+    test('clearFontsCache forces a fresh scan on the next call', async () => {
+      await makeFamily(bundledRoot, 'Inter', [400]);
+      await fontsService.listFonts();
+
+      // Add a new family AFTER the cache was populated.
+      await makeFamily(bundledRoot, 'Roboto', [400]);
+
+      // Without clearing, listFonts returns the stale cache.
+      const stale = await fontsService.listFonts();
+      expect(stale.map((f) => f.family)).toEqual(['Inter']);
+
+      // After clear, the new family appears.
+      fontsService.clearFontsCache();
+      const fresh = await fontsService.listFonts();
+      expect(fresh.map((f) => f.family)).toEqual(['Inter', 'Roboto']);
+    });
+  });
+});

backend/__tests__/services/invoiceService.hierarchy.test.js

@@ -0,0 +1,122 @@
+/**
+ * Tests for the migration-119 hierarchy support in invoiceService —
+ * the shared helpers come from quoteService._internal (validated in
+ * quoteService.hierarchy.test.js), so we focus here on the
+ * invoice-specific seams:
+ *
+ *   - quote → invoice cloner preserves parent_position + details_text
+ *     across the conversion
+ *   - the cloner's installment "adjustment" line only reconciles
+ *     against TOP-LEVEL cloned items (sub-items don't contribute to
+ *     net so they can't appear in the sum)
+ *
+ * Pure helper, no DB.
+ */
+const quoteService = require('../../src/services/quoteService');
+
+const { validateLineItemHierarchy, insertLineItemsHierarchical } = quoteService._internal;
+
+describe('quote → invoice cloner shape', () => {
+  // Models the in-memory transformation step from `scheduleInvoicesForEvent`:
+  // take source quote line items (with parent_position) and produce the
+  // `cloned` array that's passed into insertLineItemsHierarchical.
+  function modelCloner(sourceLines) {
+    return sourceLines.map((li) => ({
+      position: parseInt(li.position, 10),
+      quantity: Number(li.quantity || 1),
+      description: li.description,
+      unit_price_minor: parseInt(li.unit_price_minor, 10) || 0,
+      discount_percent: Number(li.discount_percent || 0),
+      line_total_minor: parseInt(li.line_total_minor, 10) || 0,
+      parent_position: li.parent_position == null ? null : parseInt(li.parent_position, 10),
+      details_text: li.details_text || null,
+    }));
+  }
+
+  it('preserves parent_position so the hierarchy carries across conversion', () => {
+    const source = [
+      { position: 1, description: 'Package', quantity: 1, unit_price_minor: 50000, line_total_minor: 50000, parent_position: null },
+      { position: 2, description: 'Camera',  quantity: 1, unit_price_minor: 15000, line_total_minor: 15000, parent_position: 1 },
+      { position: 3, description: 'Lens',    quantity: 1, unit_price_minor: 20000, line_total_minor: 20000, parent_position: 1 },
+    ];
+    const cloned = modelCloner(source);
+    expect(cloned[0].parent_position).toBeNull();
+    expect(cloned[1].parent_position).toBe(1);
+    expect(cloned[2].parent_position).toBe(1);
+    // The cloned shape passes hierarchy validation — same positions
+    // means the same parent links work without any remap.
+    expect(() => validateLineItemHierarchy(cloned)).not.toThrow();
+  });
+
+  it('preserves details_text verbatim', () => {
+    const source = [
+      { position: 1, description: 'P', unit_price_minor: 0, line_total_minor: 0, parent_position: null,
+        details_text: 'Includes online gallery + 100 high-res downloads.' },
+    ];
+    const cloned = modelCloner(source);
+    expect(cloned[0].details_text).toBe('Includes online gallery + 100 high-res downloads.');
+  });
+
+  it('installment adjustment reconciles against TOP-LEVEL cloned items only', () => {
+    // Recreate the inner math from scheduleInvoicesForEvent: sum
+    // only line_total_minor where parent_position is null. Sub-items
+    // would otherwise double-count and skew the adjustment.
+    //
+    // Note: the cloner stores raw line_total_minor on each row from
+    // the source quote. By the time this sum runs, the parent's
+    // line_total_minor has already been resolved upstream (via
+    // computeTotals on the quote at save time) — so iterating
+    // top-level only sums the resolved parent totals + standalone
+    // top-level items. Sub-items never contribute here regardless of
+    // whether their parent's total was auto-resolved or not.
+    const cloned = modelCloner([
+      // Parent — resolved line_total assumed to be €450 (sum of priced sub-items below)
+      { position: 1, unit_price_minor: 0, line_total_minor: 45000, parent_position: null },
+      // Sub-items €150 + €200 + €100 — shown for transparency, must
+      // NOT enter the reconciliation sum.
+      { position: 2, unit_price_minor: 15000, line_total_minor: 15000, parent_position: 1 },
+      { position: 3, unit_price_minor: 20000, line_total_minor: 20000, parent_position: 1 },
+      { position: 4, unit_price_minor: 10000, line_total_minor: 10000, parent_position: 1 },
+      // Another top-level €100
+      { position: 5, unit_price_minor: 10000, line_total_minor: 10000, parent_position: null },
+    ]);
+    const clonedSum = cloned
+      .filter((x) => x.parent_position == null)
+      .reduce((s, x) => s + x.line_total_minor, 0);
+    // Top-level only: 45000 (resolved parent) + 10000 = 55000. NOT 100000.
+    expect(clonedSum).toBe(55000);
+  });
+});
+
+describe('insertLineItemsHierarchical for invoices', () => {
+  function makeTrxMock() {
+    let nextId = 200;
+    const inserts = [];
+    const trx = (tableName) => ({
+      insert(row) {
+        const id = nextId++;
+        inserts.push({ table: tableName, row: { ...row, id } });
+        return {
+          returning() { return Promise.resolve([{ id }]); },
+          then(resolve) { return Promise.resolve(undefined).then(resolve); },
+        };
+      },
+    });
+    return { trx, inserts };
+  }
+
+  it('handles invoice_line_items with the same two-phase + remap logic', async () => {
+    const { trx, inserts } = makeTrxMock();
+    await insertLineItemsHierarchical(trx, 'invoice_line_items', 'invoice_id', 7, [
+      { position: 1, description: 'Parent', quantity: 1, unit_price_minor: 50000, discount_percent: 0, line_total_minor: 50000, parent_position: null },
+      { position: 2, description: 'Sub A',  quantity: 1, unit_price_minor: 15000, discount_percent: 0, line_total_minor: 15000, parent_position: 1 },
+    ]);
+    expect(inserts).toHaveLength(2);
+    expect(inserts.every((i) => i.table === 'invoice_line_items')).toBe(true);
+    expect(inserts.every((i) => i.row.invoice_id === 7)).toBe(true);
+    // Parent inserted first, sub-item second with parent_line_item_id
+    // matching the parent's synthesised id.
+    expect(inserts[0].row.parent_line_item_id).toBeNull();
+    expect(inserts[1].row.parent_line_item_id).toBe(200);
+  });
+});

backend/__tests__/services/invoiceService.installmentPlan.test.js

@@ -0,0 +1,322 @@
+/**
+ * Tests for invoiceService.updateInstallmentPlan + validateInstallmentPlanInput.
+ *
+ * Validation tests run against the pure validator directly. Orchestration
+ * tests use the same deep-mocked db pattern as invoiceService.locks.test.js
+ * — chains are queued per table and assertions probe insert/update/delete
+ * call shapes rather than SQL.
+ */
+
+const chains = [];
+function makeChain() {
+  const c = {
+    _firstValue: undefined,
+    _updateResult: 1,
+    _insertResult: [{ id: 999 }],
+    _selectResult: [],
+    then: function (onResolve, onReject) {
+      return Promise.resolve(this._selectResult).then(onResolve, onReject);
+    },
+    where: jest.fn(function () { return this; }),
+    whereNot: jest.fn(function () { return this; }),
+    whereIn: jest.fn(function () { return this; }),
+    whereNull: jest.fn(function () { return this; }),
+    whereNotNull: jest.fn(function () { return this; }),
+    andWhere: jest.fn(function () { return this; }),
+    orderBy: jest.fn(function () { return this; }),
+    limit: jest.fn(function () { return this; }),
+    select: jest.fn(function () { return this; }),
+    sum: jest.fn(function () { return this; }),
+    count: jest.fn(function () { return this; }),
+    clone: jest.fn(function () { return this; }),
+    clearSelect: jest.fn(function () { return this; }),
+    clearOrder: jest.fn(function () { return this; }),
+    offset: jest.fn(function () { return this; }),
+    first: jest.fn(function () { return Promise.resolve(this._firstValue); }),
+    update: jest.fn(function () { return Promise.resolve(this._updateResult); }),
+    insert: jest.fn(function () { return this; }),
+    returning: jest.fn(function () { return Promise.resolve(this._insertResult); }),
+    del: jest.fn(function () { return Promise.resolve(1); }),
+    onConflict: jest.fn(function () { return this; }),
+    ignore: jest.fn(function () { return Promise.resolve(1); }),
+    merge: jest.fn(function () { return Promise.resolve(1); }),
+    increment: jest.fn(function () { return this; }),
+    forUpdate: jest.fn(function () { return this; }),
+    leftJoin: jest.fn(function () { return this; }),
+  };
+  chains.push(c);
+  return c;
+}
+
+const tableChains = {};
+function pickChainFor(name) {
+  if (!tableChains[name]) tableChains[name] = makeChain();
+  return tableChains[name];
+}
+
+const mockDbFn = jest.fn((name) => pickChainFor(name));
+mockDbFn.transaction = jest.fn(async (cb) => cb(mockDbFn));
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+  logActivity: jest.fn(async () => {}),
+}));
+
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(async () => null),
+}));
+
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(async () => ({ profile: { default_currency: 'CHF' } })),
+  resolveBankAccountForCurrency: jest.fn(async () => null),
+}));
+
+jest.mock('../../src/utils/documentSequences', () => ({
+  claimNextSequence: jest.fn(async () => 42),
+}));
+
+jest.mock('../../src/services/pdfService', () => ({
+  renderInvoiceToBuffer: jest.fn(async () => Buffer.from('pdf')),
+  renderQuoteToBuffer: jest.fn(async () => Buffer.from('pdf')),
+}));
+
+jest.mock('../../src/services/emailProcessor', () => ({
+  queueEmail: jest.fn(async () => {}),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(), warn: jest.fn(), error: jest.fn(),
+}));
+
+const invoiceService = require('../../src/services/invoiceService');
+
+function resetChains() {
+  for (const k of Object.keys(tableChains)) delete tableChains[k];
+}
+
+describe('validateInstallmentPlanInput', () => {
+  const { validateInstallmentPlanInput } = invoiceService;
+
+  it('throws on empty array', () => {
+    expect(() => validateInstallmentPlanInput([]))
+      .toThrow(/non-empty array/);
+  });
+
+  it('throws on non-array', () => {
+    expect(() => validateInstallmentPlanInput(null))
+      .toThrow(/non-empty array/);
+  });
+
+  it('throws on out-of-range percent', () => {
+    expect(() => validateInstallmentPlanInput([
+      { percent: 150, trigger: 'quote_accepted', offset_days: 0 },
+    ])).toThrow(/percent must be between 0 and 100/);
+    expect(() => validateInstallmentPlanInput([
+      { percent: -5, trigger: 'quote_accepted', offset_days: 0 },
+    ])).toThrow(/percent must be between 0 and 100/);
+  });
+
+  it('throws on unknown trigger', () => {
+    expect(() => validateInstallmentPlanInput([
+      { percent: 100, trigger: 'on_friday', offset_days: 0 },
+    ])).toThrow(/invalid trigger/);
+  });
+
+  it('throws when percents do not sum to 100', () => {
+    expect(() => validateInstallmentPlanInput([
+      { percent: 30, trigger: 'quote_accepted', offset_days: 0 },
+      { percent: 50, trigger: 'before_event', offset_days: -7 },
+    ])).toThrow(/must sum to 100/);
+  });
+
+  it('accepts a valid three-row plan with mixed triggers', () => {
+    expect(() => validateInstallmentPlanInput([
+      { percent: 30, trigger: 'quote_accepted', offset_days: 0, label: 'Anzahlung' },
+      { percent: 40, trigger: 'before_event', offset_days: -14, label: 'Zwischenrechnung' },
+      { percent: 30, trigger: 'after_delivery', offset_days: 0, label: 'Schlussrechnung' },
+    ])).not.toThrow();
+  });
+
+  it('tolerates 0.001 rounding drift in the sum', () => {
+    expect(() => validateInstallmentPlanInput([
+      { percent: 33.333, trigger: 'quote_accepted', offset_days: 0 },
+      { percent: 33.333, trigger: 'before_event', offset_days: -7 },
+      { percent: 33.334, trigger: 'after_event', offset_days: 0 },
+    ])).not.toThrow();
+  });
+});
+
+describe('updateInstallmentPlan — guards', () => {
+  beforeEach(() => resetChains());
+
+  const goodPlan = [
+    { percent: 50, trigger: 'quote_accepted', offset_days: 0, label: 'A' },
+    { percent: 50, trigger: 'before_event', offset_days: -14, label: 'B' },
+  ];
+
+  it('rejects when dealUuid is missing', async () => {
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: '', installments: goodPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 400 });
+  });
+
+  it('404s when the deal has no invoices', async () => {
+    pickChainFor('invoices')._selectResult = [];
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', installments: goodPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('400s + NOT_INSTALLMENT_PLAN on a single-invoice deal', async () => {
+    pickChainFor('invoices')._selectResult = [
+      { id: 1, deal_uuid: 'deal-1', installment_total: 1, status: 'scheduled', kind: 'invoice' },
+    ];
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', installments: goodPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 400, code: 'NOT_INSTALLMENT_PLAN' });
+  });
+
+  it('409s + INVOICE_LOCKED when any sibling has already shipped', async () => {
+    pickChainFor('invoices')._selectResult = [
+      { id: 1, deal_uuid: 'deal-1', installment_total: 2, installment_index: 0,
+        status: 'sent', kind: 'invoice', invoice_number: 'R-2026-0001',
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770, shipping_amount_minor: 0 },
+      { id: 2, deal_uuid: 'deal-1', installment_total: 2, installment_index: 1,
+        status: 'scheduled', kind: 'invoice', invoice_number: 'R-2026-0002',
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770, shipping_amount_minor: 0 },
+    ];
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', installments: goodPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 409, code: 'INVOICE_LOCKED' });
+  });
+
+  it('409s + PLAN_HAS_STORNO when the deal contains a Storno', async () => {
+    pickChainFor('invoices')._selectResult = [
+      { id: 1, deal_uuid: 'deal-1', installment_total: 2, installment_index: 0,
+        status: 'scheduled', kind: 'storno', invoice_number: 'S-2026-0001',
+        net_amount_minor: -5000, vat_amount_minor: -385, total_amount_minor: -5385, shipping_amount_minor: 0 },
+      { id: 2, deal_uuid: 'deal-1', installment_total: 2, installment_index: 1,
+        status: 'scheduled', kind: 'invoice', invoice_number: 'R-2026-0002',
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770, shipping_amount_minor: 0 },
+    ];
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', installments: goodPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 409, code: 'PLAN_HAS_STORNO' });
+  });
+
+  it('rejects an invalid plan (percents not summing to 100) before opening the txn', async () => {
+    const badPlan = [
+      { percent: 30, trigger: 'quote_accepted', offset_days: 0 },
+      { percent: 30, trigger: 'before_event', offset_days: -7 },
+    ];
+    await expect(invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', installments: badPlan, adminId: 1,
+    })).rejects.toMatchObject({ statusCode: 400, code: 'PERCENT_SUM_INVALID' });
+  });
+});
+
+describe('updateInstallmentPlan — reshape (smoke)', () => {
+  beforeEach(() => resetChains());
+
+  const sibling = (overrides) => ({
+    id: 0, deal_uuid: 'deal-1', installment_total: 3, installment_index: 0,
+    status: 'scheduled', kind: 'invoice', invoice_number: 'R-2026-0001',
+    net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+    shipping_amount_minor: 0, vat_rate: 7.7,
+    customer_account_id: 5, source_quote_id: null, event_id: null,
+    event_name: 'Wedding', event_date: '2026-08-15',
+    language: 'de', currency: 'CHF',
+    issue_date: '2026-05-25', due_date: '2026-06-24',
+    cc_pdf_email: null,
+    payment_net_days_template_id: null, payment_timing_template_id: null,
+    payment_term_snapshot: null,
+    ...overrides,
+  });
+
+  it('keeps invoice_numbers and does not claim new sequence on 3→3 reshape', async () => {
+    pickChainFor('invoices')._selectResult = [
+      sibling({ id: 1, installment_index: 0, invoice_number: 'R-2026-0001',
+        net_amount_minor: 3000, vat_amount_minor: 231, total_amount_minor: 3231 }),
+      sibling({ id: 2, installment_index: 1, invoice_number: 'R-2026-0002',
+        net_amount_minor: 3000, vat_amount_minor: 231, total_amount_minor: 3231 }),
+      sibling({ id: 3, installment_index: 2, invoice_number: 'R-2026-0003',
+        net_amount_minor: 4000, vat_amount_minor: 308, total_amount_minor: 4308 }),
+    ];
+    pickChainFor('customer_accounts')._firstValue = { id: 5, is_active: 1, feature_bills: 1 };
+    pickChainFor('invoice_line_items')._selectResult = [];
+
+    const result = await invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', adminId: 42,
+      installments: [
+        { percent: 20, trigger: 'quote_accepted', offset_days: 0, label: 'A' },
+        { percent: 30, trigger: 'before_event', offset_days: -14, label: 'B' },
+        { percent: 50, trigger: 'after_event', offset_days: 7, label: 'C' },
+      ],
+    });
+
+    expect(result.kept).toEqual([1, 2, 3]);
+    expect(result.created).toEqual([]);
+    expect(result.deleted).toEqual([]);
+    // Sequence helper never touched on a same-count reshape.
+    const { claimNextSequence } = require('../../src/utils/documentSequences');
+    expect(claimNextSequence).not.toHaveBeenCalled();
+  });
+
+  it('grows 2→3 by claiming one new invoice_number and keeping the first two', async () => {
+    pickChainFor('invoices')._selectResult = [
+      sibling({ id: 1, installment_index: 0, invoice_number: 'R-2026-0001',
+        net_amount_minor: 5000, vat_amount_minor: 385, total_amount_minor: 5385,
+        installment_total: 2 }),
+      sibling({ id: 2, installment_index: 1, invoice_number: 'R-2026-0002',
+        net_amount_minor: 5000, vat_amount_minor: 385, total_amount_minor: 5385,
+        installment_total: 2 }),
+    ];
+    pickChainFor('customer_accounts')._firstValue = { id: 5, is_active: 1, feature_bills: 1 };
+    pickChainFor('invoice_line_items')._selectResult = [];
+    pickChainFor('invoices')._insertResult = [{ id: 99 }];
+
+    const result = await invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', adminId: 42,
+      installments: [
+        { percent: 30, trigger: 'quote_accepted', offset_days: 0, label: 'A' },
+        { percent: 30, trigger: 'before_event', offset_days: -14, label: 'B' },
+        { percent: 40, trigger: 'after_event', offset_days: 7, label: 'C' },
+      ],
+    });
+
+    expect(result.kept).toEqual([1, 2]);
+    expect(result.created.length).toBe(1);
+    expect(result.deleted).toEqual([]);
+    const { claimNextSequence } = require('../../src/utils/documentSequences');
+    expect(claimNextSequence).toHaveBeenCalledTimes(1);
+  });
+
+  it('shrinks 3→2 by deleting the third row + its line items', async () => {
+    pickChainFor('invoices')._selectResult = [
+      sibling({ id: 1, installment_index: 0, invoice_number: 'R-2026-0001',
+        net_amount_minor: 3000, vat_amount_minor: 231, total_amount_minor: 3231 }),
+      sibling({ id: 2, installment_index: 1, invoice_number: 'R-2026-0002',
+        net_amount_minor: 3000, vat_amount_minor: 231, total_amount_minor: 3231 }),
+      sibling({ id: 3, installment_index: 2, invoice_number: 'R-2026-0003',
+        net_amount_minor: 4000, vat_amount_minor: 308, total_amount_minor: 4308 }),
+    ];
+    pickChainFor('customer_accounts')._firstValue = { id: 5, is_active: 1, feature_bills: 1 };
+    pickChainFor('invoice_line_items')._selectResult = [];
+
+    const result = await invoiceService.updateInstallmentPlan({
+      trx: mockDbFn, dealUuid: 'deal-1', adminId: 42,
+      installments: [
+        { percent: 40, trigger: 'quote_accepted', offset_days: 0, label: 'A' },
+        { percent: 60, trigger: 'after_event', offset_days: 7, label: 'B' },
+      ],
+    });
+
+    expect(result.kept).toEqual([1, 2]);
+    expect(result.created).toEqual([]);
+    expect(result.deleted).toEqual([3]);
+    // Line items + invoice rows deleted on the trimmed sibling.
+    expect(pickChainFor('invoice_line_items').del).toHaveBeenCalled();
+    expect(pickChainFor('invoices').del).toHaveBeenCalled();
+  });
+});

backend/__tests__/services/invoiceService.locks.test.js

@@ -0,0 +1,374 @@
+/**
+ * Tests for invoiceService lock + state-transition guards.
+ *
+ * Focuses on the rules that protect tax/audit integrity:
+ *   - reissueInvoice refuses to act on `scheduled` (use Edit)
+ *   - reissueInvoice cancels + clones any other status
+ *   - releaseForDelivery refuses to act on non-pending_delivery
+ *   - recordPaymentCheckAction refuses already-used / expired tokens
+ *
+ * db is deep-mocked so the tests are deterministic and fast.
+ */
+
+// Mock db chain: each table call returns a builder whose methods
+// chain (return `this`) until a terminal method (.first / .update /
+// .insert / .returning) resolves with the queued value.
+
+const chains = [];
+function makeChain() {
+  const c = {
+    _firstValue: undefined,
+    _updateResult: 1,
+    _insertResult: [{ id: 999 }],
+    _selectResult: [],
+    _allRows: [],
+    // knex chains are thenable — awaiting them runs the query and
+    // resolves with the row set. We mirror that so callers can
+    // `await trx('t').where(...).orderBy(...)` and get an array.
+    then: function (onResolve, onReject) {
+      return Promise.resolve(this._selectResult).then(onResolve, onReject);
+    },
+    where: jest.fn(function () { return this; }),
+    whereNot: jest.fn(function () { return this; }),
+    whereNotIn: jest.fn(function () { return this; }),
+    whereIn: jest.fn(function () { return this; }),
+    whereNull: jest.fn(function () { return this; }),
+    whereNotNull: jest.fn(function () { return this; }),
+    andWhere: jest.fn(function () { return this; }),
+    orderBy: jest.fn(function () { return this; }),
+    limit: jest.fn(function () { return this; }),
+    // select is both chainable (`.select('col').first()`) and awaitable
+    // via the chain's `then` (`await q.select(...)` returns `_selectResult`).
+    select: jest.fn(function () { return this; }),
+    sum: jest.fn(function () { return this; }),
+    count: jest.fn(function () { return this; }),
+    clone: jest.fn(function () { return this; }),
+    clearSelect: jest.fn(function () { return this; }),
+    clearOrder: jest.fn(function () { return this; }),
+    offset: jest.fn(function () { return this; }),
+    first: jest.fn(function () { return Promise.resolve(this._firstValue); }),
+    update: jest.fn(function () { return Promise.resolve(this._updateResult); }),
+    insert: jest.fn(function () { return this; }),
+    returning: jest.fn(function () { return Promise.resolve(this._insertResult); }),
+    del: jest.fn(function () { return Promise.resolve(1); }),
+    onConflict: jest.fn(function () { return this; }),
+    ignore: jest.fn(function () { return Promise.resolve(1); }),
+    merge: jest.fn(function () { return Promise.resolve(1); }),
+    increment: jest.fn(function () { return this; }),
+    forUpdate: jest.fn(function () { return this; }),
+    leftJoin: jest.fn(function () { return this; }),
+  };
+  chains.push(c);
+  return c;
+}
+
+const tableChains = {};
+function pickChainFor(name) {
+  if (!tableChains[name]) tableChains[name] = makeChain();
+  return tableChains[name];
+}
+
+const mockDbFn = jest.fn((name) => pickChainFor(name));
+// db.transaction(cb) runs the callback with a "trx" — for our
+// purposes the same chain factory works as trx.
+mockDbFn.transaction = jest.fn(async (cb) => cb(mockDbFn));
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+  logActivity: jest.fn(async () => {}),
+}));
+
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(async () => null),
+}));
+
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(async () => ({ profile: { default_currency: 'CHF' } })),
+  resolveBankAccountForCurrency: jest.fn(async () => null),
+}));
+
+jest.mock('../../src/services/pdfService', () => ({
+  renderInvoiceToBuffer: jest.fn(async () => Buffer.from('pdf')),
+  renderQuoteToBuffer: jest.fn(async () => Buffer.from('pdf')),
+}));
+
+jest.mock('../../src/services/emailProcessor', () => ({
+  queueEmail: jest.fn(async () => {}),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(), warn: jest.fn(), error: jest.fn(),
+}));
+
+const invoiceService = require('../../src/services/invoiceService');
+
+function resetChains() {
+  for (const k of Object.keys(tableChains)) delete tableChains[k];
+}
+
+describe('invoiceService.reissueInvoice', () => {
+  beforeEach(() => resetChains());
+
+  it('throws USE_EDIT_INSTEAD when the source is still scheduled', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'scheduled' };
+    await expect(invoiceService.reissueInvoice(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'USE_EDIT_INSTEAD' });
+  });
+
+  it('throws when the source invoice does not exist', async () => {
+    pickChainFor('invoices')._firstValue = null;
+    await expect(invoiceService.reissueInvoice(999, 42))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('cancels the original and creates a new row when status is sent', async () => {
+    pickChainFor('invoices')._firstValue = {
+      id: 1, status: 'sent', customer_account_id: 5,
+      currency: 'CHF', language: 'de', vat_rate: 7.7,
+      shipping_amount_minor: 0, cc_pdf_email: null,
+      business_bank_account_id: null, qr_format: null,
+      payment_term_template_id: null, event_id: null,
+      source_quote_id: null,
+    };
+    pickChainFor('customer_accounts')._firstValue = {
+      id: 5, is_active: 1, feature_bills: 1,
+    };
+    pickChainFor('invoice_line_items')._selectResult = [];
+    pickChainFor('app_settings')._firstValue = null;
+    // document_sequences row used by claimNextSequence.
+    pickChainFor('document_sequences')._firstValue = { current_value: 42 };
+
+    const result = await invoiceService.reissueInvoice(1, 42);
+    expect(result.id).toBeDefined();
+    expect(result.replaces).toBe(1);
+  });
+});
+
+describe('invoiceService.createStorno', () => {
+  beforeEach(() => resetChains());
+
+  it('rejects when the source invoice does not exist (404)', async () => {
+    pickChainFor('invoices')._firstValue = null;
+    await expect(invoiceService.createStorno(999, 42))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('rejects when the source is still scheduled (drafts edit in place)', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'scheduled', kind: 'invoice' };
+    await expect(invoiceService.createStorno(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'USE_EDIT_INSTEAD' });
+  });
+
+  it('rejects when the source is already cancelled (no double-Storno)', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'cancelled', kind: 'invoice' };
+    await expect(invoiceService.createStorno(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'ALREADY_CANCELLED' });
+  });
+
+  it('rejects when asked to Storno a Storno', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'sent', kind: 'storno' };
+    await expect(invoiceService.createStorno(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'IS_STORNO' });
+  });
+
+  it('inserts a Storno row and flips the original on a sent invoice', async () => {
+    // Original is `sent`, no line items, no event.
+    const invoicesChain = pickChainFor('invoices');
+    invoicesChain._firstValue = {
+      id: 1, status: 'sent', kind: 'invoice', customer_account_id: 5,
+      currency: 'CHF', language: 'de', vat_rate: 7.7,
+      net_amount_minor: 30000, vat_amount_minor: 2310,
+      total_amount_minor: 32310, shipping_amount_minor: 0,
+      cc_pdf_email: null, event_id: null,
+    };
+    pickChainFor('invoice_line_items')._selectResult = [];
+    pickChainFor('app_settings')._firstValue = null;
+    // document_sequences row used by claimNextSequence.
+    pickChainFor('document_sequences')._firstValue = { current_value: 42 };
+
+    const stornoId = await invoiceService.createStorno(1, 42);
+    expect(stornoId).toBeDefined();
+
+    // The mock chain's .update() is called twice on `invoices`:
+    //   1) `.insert(...).returning('id')` for the Storno row
+    //   2) `.update({status:'cancelled', cancellation_storno_id})` on the original
+    // We just verify the helpers were exercised on the right table.
+    expect(invoicesChain.insert).toHaveBeenCalled();
+    expect(invoicesChain.update).toHaveBeenCalled();
+    // The Storno insert payload should carry kind='storno' and
+    // negated row-level totals. Inspect the first insert call's
+    // payload to confirm.
+    const insertedRow = invoicesChain.insert.mock.calls[0][0];
+    expect(insertedRow.kind).toBe('storno');
+    expect(insertedRow.net_amount_minor).toBe(-30000);
+    expect(insertedRow.vat_amount_minor).toBe(-2310);
+    expect(insertedRow.total_amount_minor).toBe(-32310);
+    expect(insertedRow.cancels_invoice_id).toBe(1);
+    expect(insertedRow.status).toBe('scheduled');
+    // No payment instrument on a Storno.
+    expect(insertedRow.business_bank_account_id).toBeNull();
+    expect(insertedRow.qr_format).toBeNull();
+    expect(insertedRow.payment_term_template_id).toBeNull();
+    // Storni have no real payment due, but the schema's NOT NULL
+    // constraint on due_date forces a value — we mirror issue_date.
+    expect(insertedRow.due_date).toBe(insertedRow.issue_date);
+  });
+});
+
+describe('invoiceService.cancelInvoice', () => {
+  beforeEach(() => resetChains());
+
+  it('rejects when the invoice does not exist (404)', async () => {
+    pickChainFor('invoices')._firstValue = null;
+    await expect(invoiceService.cancelInvoice(999, 42))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('rejects with ALREADY_CANCELLED when status is cancelled', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'cancelled', kind: 'invoice' };
+    await expect(invoiceService.cancelInvoice(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'ALREADY_CANCELLED' });
+  });
+
+  it('rejects with IS_STORNO when asked to cancel a Storno', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'sent', kind: 'storno' };
+    await expect(invoiceService.cancelInvoice(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'IS_STORNO' });
+  });
+
+  it('soft-cancels a scheduled (draft) invoice without generating a Storno', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'scheduled', kind: 'invoice', event_id: null };
+    const result = await invoiceService.cancelInvoice(1, 42);
+    expect(result).toEqual({ cancelled: true, stornoId: null });
+  });
+});
+
+describe('invoiceService.releaseForDelivery', () => {
+  beforeEach(() => resetChains());
+
+  it('refuses when status is not pending_delivery', async () => {
+    pickChainFor('invoices')._firstValue = { id: 1, status: 'sent' };
+    await expect(invoiceService.releaseForDelivery(1, 42))
+      .rejects.toMatchObject({ statusCode: 409, code: 'NOT_PENDING_DELIVERY' });
+  });
+
+  it('404s when the invoice does not exist', async () => {
+    pickChainFor('invoices')._firstValue = null;
+    await expect(invoiceService.releaseForDelivery(999, 42))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+});
+
+describe('invoiceService.recordPaymentCheckAction', () => {
+  beforeEach(() => resetChains());
+
+  it('rejects invalid actions', async () => {
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'abc', action: 'foo',
+    })).rejects.toMatchObject({ statusCode: 400 });
+  });
+
+  it('404s when the token is not on file', async () => {
+    pickChainFor('invoice_payment_check_tokens')._firstValue = null;
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'a'.repeat(64), action: 'unpaid',
+    })).rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('410s + TOKEN_ALREADY_USED when the row has used_at set', async () => {
+    pickChainFor('invoice_payment_check_tokens')._firstValue = {
+      id: 1, used_at: new Date(),
+      expires_at: new Date(Date.now() + 86400000),
+    };
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'a'.repeat(64), action: 'unpaid',
+    })).rejects.toMatchObject({ statusCode: 410, code: 'TOKEN_ALREADY_USED' });
+  });
+
+  it('410s + TOKEN_EXPIRED when the row is past expires_at', async () => {
+    pickChainFor('invoice_payment_check_tokens')._firstValue = {
+      id: 1, used_at: null,
+      expires_at: new Date(Date.now() - 86400000),
+    };
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'a'.repeat(64), action: 'unpaid',
+    })).rejects.toMatchObject({ statusCode: 410, code: 'TOKEN_EXPIRED' });
+  });
+
+  it('rejects partial with amount <= 0', async () => {
+    pickChainFor('invoice_payment_check_tokens')._firstValue = {
+      id: 1, used_at: null,
+      expires_at: new Date(Date.now() + 86400000),
+    };
+    pickChainFor('invoices')._firstValue = {
+      id: 5, total_amount_minor: 10000, paid_amount_minor: 0, late_fee_amount_minor: 0,
+    };
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'a'.repeat(64), action: 'partial', amountMinor: 0,
+    })).rejects.toMatchObject({ statusCode: 400 });
+  });
+
+  it('rejects partial with amount > outstanding', async () => {
+    pickChainFor('invoice_payment_check_tokens')._firstValue = {
+      id: 1, used_at: null,
+      expires_at: new Date(Date.now() + 86400000),
+    };
+    pickChainFor('invoices')._firstValue = {
+      id: 5, total_amount_minor: 5000, paid_amount_minor: 0, late_fee_amount_minor: 0,
+    };
+    await expect(invoiceService.recordPaymentCheckAction({
+      token: 'a'.repeat(64), action: 'partial', amountMinor: 9999,
+    })).rejects.toMatchObject({ statusCode: 400 });
+  });
+});
+
+describe('invoiceService.queuePaymentCheckEmail', () => {
+  beforeEach(() => resetChains());
+
+  it('skips when invoice does not exist', async () => {
+    pickChainFor('invoices')._firstValue = null;
+    const res = await invoiceService.queuePaymentCheckEmail(1);
+    expect(res).toEqual({ sent: false, reason: 'not_found' });
+  });
+
+  it('skips when status is not sent/overdue', async () => {
+    pickChainFor('invoices')._firstValue = {
+      id: 1, status: 'paid',
+    };
+    const res = await invoiceService.queuePaymentCheckEmail(1);
+    expect(res.sent).toBe(false);
+    expect(res.reason).toMatch(/wrong_status_paid/);
+  });
+
+  it('respects the 24h throttle', async () => {
+    pickChainFor('invoices')._firstValue = {
+      id: 1, status: 'overdue',
+      last_payment_check_at: new Date(Date.now() - 3600 * 1000),
+    };
+    const res = await invoiceService.queuePaymentCheckEmail(1);
+    expect(res).toEqual({ sent: false, reason: 'throttled_24h' });
+  });
+
+  it('bypasses the throttle when skipThrottle=true', async () => {
+    pickChainFor('invoices')._firstValue = {
+      id: 1, status: 'overdue',
+      customer_account_id: 5,
+      created_by_admin_id: 42,
+      total_amount_minor: 10000,
+      currency: 'CHF',
+      language: 'de',
+      reminder_level: 0,
+      due_date: '2026-05-01',
+      last_payment_check_at: new Date(Date.now() - 3600 * 1000),
+      event_id: null,
+    };
+    pickChainFor('admin_users')._firstValue = { id: 42, email: 'admin@example.com', username: 'admin' };
+    pickChainFor('business_profile')._firstValue = null;
+    pickChainFor('customer_accounts')._firstValue = { id: 5, email: 'c@example.com', display_name: 'Test' };
+
+    const res = await invoiceService.queuePaymentCheckEmail(1, { skipThrottle: true });
+    expect(res.sent).toBe(true);
+    expect(res.token).toMatch(/^[a-f0-9]{64}$/);
+  });
+});

backend/__tests__/services/pdfService.baseDocument.test.js

@@ -0,0 +1,236 @@
+/**
+ * Tests for the createBaseDocument + getPageMetrics helpers — the
+ * shared PDF factory used by quote/invoice rendering AND by the
+ * upcoming tax-report renderer. These verify orientation handling
+ * and font defaults without touching DB or filesystem.
+ */
+const pdfService = require('../../src/services/pdfService');
+
+describe('getPageMetrics', () => {
+  it('returns portrait A4 metrics by default', () => {
+    const p = pdfService.getPageMetrics();
+    expect(p.width).toBeCloseTo(595.28, 1);
+    expect(p.height).toBeCloseTo(841.89, 1);
+    expect(p.contentWidth).toBeCloseTo(515.28, 1);
+  });
+
+  it('returns portrait when orientation is "portrait"', () => {
+    const p = pdfService.getPageMetrics('portrait');
+    expect(p.width).toBeLessThan(p.height);
+  });
+
+  it('returns landscape A4 metrics (width > height) when orientation is "landscape"', () => {
+    const p = pdfService.getPageMetrics('landscape');
+    expect(p.width).toBeCloseTo(841.89, 1);
+    expect(p.height).toBeCloseTo(595.28, 1);
+    expect(p.contentWidth).toBeCloseTo(761.89, 1);
+    expect(p.width).toBeGreaterThan(p.height);
+  });
+
+  it('ignores unknown orientation values (falls back to portrait)', () => {
+    const p = pdfService.getPageMetrics('upside-down');
+    expect(p.width).toBeLessThan(p.height);
+  });
+});
+
+describe('createBaseDocument', () => {
+  it('returns a PDFKit doc, page metrics, and logical font names by default', () => {
+    const { doc, page, fonts } = pdfService.createBaseDocument();
+    expect(doc).toBeDefined();
+    expect(typeof doc.on).toBe('function');
+    expect(typeof doc.font).toBe('function');
+    expect(page.width).toBeCloseTo(595.28, 1); // portrait by default
+    expect(fonts).toEqual({ body: 'Helvetica', bold: 'Helvetica-Bold' });
+  });
+
+  it('produces a landscape document when orientation is "landscape"', () => {
+    const { doc, page } = pdfService.createBaseDocument({ orientation: 'landscape' });
+    expect(page.width).toBeGreaterThan(page.height);
+    // PDFKit stores the active page dims on doc.page.
+    expect(doc.page.width).toBeCloseTo(841.89, 1);
+    expect(doc.page.height).toBeCloseTo(595.28, 1);
+  });
+
+  it('produces a buffered PDF of non-zero size with the PDF magic header', async () => {
+    const { doc } = pdfService.createBaseDocument({ orientation: 'landscape' });
+    const chunks = [];
+    doc.on('data', (c) => chunks.push(c));
+    const ended = new Promise((resolve) => doc.on('end', resolve));
+    doc.text('hello', 40, 40);
+    doc.end();
+    await ended;
+    const buf = Buffer.concat(chunks);
+    expect(buf.length).toBeGreaterThan(0);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('keeps Helvetica fonts when the issuer has no custom TTF path', () => {
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: { pdfFontTtfPath: null },
+    });
+    expect(fonts.body).toBe('Helvetica');
+    expect(fonts.bold).toBe('Helvetica-Bold');
+  });
+
+  it('falls back to Helvetica when the custom TTF path does not exist', () => {
+    // No exception, no logger.error blow-up — just silent fallback.
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: { pdfFontTtfPath: '/nonexistent/path/font.ttf' },
+    });
+    expect(fonts.body).toBe('Helvetica');
+    expect(fonts.bold).toBe('Helvetica-Bold');
+  });
+
+  it('registers a bundled font family when pdfFontFamily is set', () => {
+    // Migration-121 dropdown path. Inter ships 400 + 600 + 700 under
+    // backend/assets/fonts/Inter/, so the resolver should pick 400
+    // for body and 700 for bold.
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: { pdfFontFamily: 'Inter' },
+    });
+    expect(fonts.body).toBe('crm-body');
+    expect(fonts.bold).toBe('crm-bold');
+  });
+
+  it('falls back to Helvetica when pdfFontFamily names a non-existent directory', () => {
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: { pdfFontFamily: 'NotARealFamily' },
+    });
+    expect(fonts.body).toBe('Helvetica');
+    expect(fonts.bold).toBe('Helvetica-Bold');
+  });
+
+  it('strips path-traversal characters from pdfFontFamily', () => {
+    // Defence in depth: the sanitiser keeps only [A-Za-z0-9_-].
+    // "../../etc/passwd" becomes "etcpasswd" → no such font dir → fallback.
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: { pdfFontFamily: '../../etc/passwd' },
+    });
+    expect(fonts.body).toBe('Helvetica');
+    expect(fonts.bold).toBe('Helvetica-Bold');
+  });
+
+  it('prefers pdfFontTtfPath over pdfFontFamily when both are set', () => {
+    // The explicit upload is the priority-1 override. When the upload
+    // path is unusable (file missing) the family is consulted next.
+    // Here we set BOTH to invalid values and confirm Helvetica fallback
+    // — what matters is that the family DIDN'T get registered while a
+    // (failed) explicit path was being evaluated.
+    const { fonts } = pdfService.createBaseDocument({
+      issuer: {
+        pdfFontTtfPath: '/nonexistent/path/font.ttf',
+        pdfFontFamily: 'Inter',
+      },
+    });
+    // pdfFontTtfPath misses → falls through to pdfFontFamily → Inter
+    // registers successfully. crm-body / crm-bold confirm a custom
+    // font won.
+    expect(fonts.body).toBe('crm-body');
+    expect(fonts.bold).toBe('crm-bold');
+  });
+
+  it('forwards PDF info metadata (Title, Author) to the document', () => {
+    const { doc } = pdfService.createBaseDocument({
+      info: { Title: 'Tax Report 2026', Author: 'picpeak' },
+    });
+    // PDFKit copies these onto doc.info during construction.
+    expect(doc.info.Title).toBe('Tax Report 2026');
+    expect(doc.info.Author).toBe('picpeak');
+  });
+});
+
+describe('exported letterhead helper', () => {
+  it('exposes drawIssuerBlock for reuse by non-quote/invoice renderers', () => {
+    expect(typeof pdfService.drawIssuerBlock).toBe('function');
+  });
+});
+
+// Storno rendering — smoke-tests that exercise the kind='storno'
+// branch in renderInvoiceToBuffer. We can't search the PDF buffer
+// directly for German strings because PDFKit Flate-compresses
+// content streams, but we CAN verify the renderer:
+//   - completes without throwing on a Storno-shaped context,
+//   - produces a valid %PDF magic header,
+//   - produces a SMALLER document than its invoice counterpart
+//     (no payment block, no QR slip → fewer bytes), proving the
+//     suppression branches actually fire.
+//
+// Visual correctness (title swap, reference line, signed totals) is
+// validated by manual review of a real Storno PDF; the renderer's
+// branch logic is unit-tested in service tests where the inputs
+// can be asserted directly.
+describe('renderInvoiceToBuffer — Storno branch', () => {
+  function buildContext(overrides = {}) {
+    return {
+      locale: 'de',
+      currency: 'CHF',
+      issuer: { companyName: 'AcmeCo' },
+      recipient: {
+        companyName: 'KundenCo', addressLine1: 'Strasse 1',
+        city: 'Bern', postalCode: '3000',
+      },
+      lineItems: [{
+        quantity: 1, description: 'Photo session',
+        unitPriceMinor: 30000, lineTotalMinor: 30000,
+        parentLineItemId: null, parentPosition: null,
+      }],
+      totals: {
+        netAmountMinor: 30000, vatRate: 7.7, vatAmountMinor: 2310,
+        shippingAmountMinor: 0, totalAmountMinor: 32310,
+      },
+      doc: { invoiceNumber: 'R-2026-0042', issueDate: '2026-04-12' },
+      // Bank + payment term are part of the baseline invoice so the
+      // payment block renders a real IBAN + Zahlungsbedingungen
+      // section. The Storno branch suppresses this entirely, which
+      // produces a visible byte-size delta.
+      bank: {
+        accountHolder: 'AcmeCo',
+        iban: 'CH9300762011623852957',
+        bic: 'POFICHBE',
+        currency: 'CHF',
+      },
+      qrFormat: 'none',
+      paymentTerm: { netDays: 30, skontoPercent: 2, skontoWithinDays: 10 },
+      ...overrides,
+    };
+  }
+
+  it('renders a valid Storno PDF (kind="storno", negated totals)', async () => {
+    const buf = await pdfService.renderInvoiceToBuffer(buildContext({
+      totals: {
+        netAmountMinor: -30000, vatRate: 7.7, vatAmountMinor: -2310,
+        shippingAmountMinor: 0, totalAmountMinor: -32310,
+      },
+      doc: {
+        kind: 'storno',
+        invoiceNumber: 'R-2026-0080',
+        issueDate: '2026-05-15',
+        cancelsInvoice: { number: 'R-2026-0042', issueDate: '2026-04-12' },
+      },
+    }));
+    expect(buf.length).toBeGreaterThan(0);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('produces a smaller PDF than the equivalent invoice (no payment block, no QR slip)', async () => {
+    // Baseline: normal invoice with a payment block.
+    const invoiceBuf = await pdfService.renderInvoiceToBuffer(buildContext());
+    // Storno: same context but kind='storno' → payment block + QR
+    // both suppressed. Payment block alone is ~80pt tall in the
+    // PDF; its absence is reliably detectable as a byte-size delta.
+    const stornoBuf = await pdfService.renderInvoiceToBuffer(buildContext({
+      totals: {
+        netAmountMinor: -30000, vatRate: 7.7, vatAmountMinor: -2310,
+        shippingAmountMinor: 0, totalAmountMinor: -32310,
+      },
+      doc: {
+        kind: 'storno',
+        invoiceNumber: 'R-2026-0080',
+        issueDate: '2026-05-15',
+        cancelsInvoice: { number: 'R-2026-0042', issueDate: '2026-04-12' },
+      },
+    }));
+    expect(stornoBuf.length).toBeGreaterThan(0);
+    expect(stornoBuf.length).toBeLessThan(invoiceBuf.length);
+  });
+});

backend/__tests__/services/pdfService.helpers.test.js

@@ -0,0 +1,95 @@
+/**
+ * Pure-function tests for the PDF rendering helpers. These are the
+ * functions that DON'T touch PDFKit / DB — formatting, salutation
+ * routing, EPC payload construction.
+ *
+ * The helpers aren't directly exported from pdfService.js (it
+ * exports renderQuoteToBuffer / renderInvoiceToBuffer); we reach
+ * them via `_internal` which the module already exposes for tests.
+ */
+const pdfService = require('../../src/services/pdfService');
+const { formatMinor, formatDate, t } = pdfService._internal;
+
+describe('formatMinor', () => {
+  it('formats CHF cents with 2 decimals (123456 minor = 1234.56 major)', () => {
+    // de-CH uses ’ (U+2019) as the thousands separator.
+    expect(formatMinor(123456, 'CHF', 'de-CH')).toMatch(/1[’',\u2019]?234\.56/);
+  });
+
+  it('formats large amounts with thousands separators', () => {
+    // 12345600 minor units = 123,456.00 major; the separator
+    // varies by locale (de-CH = U+2019, en-GB = ',').
+    expect(formatMinor(12345600, 'CHF', 'de-CH')).toMatch(/123[’',\u2019]456\.00/);
+  });
+
+  it('returns 0,00 for zero or null', () => {
+    expect(formatMinor(0, 'CHF', 'de-CH')).toMatch(/0[,.]00/);
+    expect(formatMinor(null, 'CHF', 'de-CH')).toMatch(/0[,.]00/);
+  });
+
+  it('returns 2-decimal output regardless of locale', () => {
+    expect(formatMinor(99, 'EUR', 'en-GB')).toMatch(/0[.,]99/);
+  });
+});
+
+describe('formatDate', () => {
+  // formatDate now respects ctx.dateFormat (object with `format`
+  // key) — when omitted defaults to DD.MM.YYYY.
+  it('defaults to DD.MM.YYYY when no format passed', () => {
+    expect(formatDate('2026-04-19')).toBe('19.04.2026');
+  });
+
+  it('honors the configured DD/MM/YYYY format', () => {
+    expect(formatDate('2026-04-19', { format: 'DD/MM/YYYY' })).toBe('19/04/2026');
+  });
+
+  it('honors the configured MM/DD/YYYY format', () => {
+    expect(formatDate('2026-04-19', { format: 'MM/DD/YYYY' })).toBe('04/19/2026');
+  });
+
+  it('honors ISO YYYY-MM-DD', () => {
+    expect(formatDate('2026-04-19', { format: 'YYYY-MM-DD' })).toBe('2026-04-19');
+  });
+
+  it('returns empty string on empty input', () => {
+    expect(formatDate('')).toBe('');
+    expect(formatDate(null)).toBe('');
+    expect(formatDate(undefined)).toBe('');
+  });
+
+  it('returns empty string on invalid input rather than throwing', () => {
+    expect(formatDate('not-a-date')).toBe('');
+  });
+
+  it('accepts Date objects', () => {
+    expect(formatDate(new Date('2026-04-19T12:00:00Z'))).toMatch(/^(19|20)\.0[34]\.2026$/);
+  });
+});
+
+describe('t (i18n lookup)', () => {
+  it('returns the EN value for an EN-only locale', () => {
+    expect(t('en', 'invoice_title')).toBe('Invoice');
+    expect(t('en', 'quote_title')).toBe('Quote');
+  });
+
+  it('returns the DE value for de locale', () => {
+    expect(t('de', 'invoice_title')).toBe('Rechnung');
+    expect(t('de', 'quote_title')).toBe('Angebot');
+  });
+
+  it('falls back to EN for unknown locales', () => {
+    expect(t('xx', 'invoice_title')).toBe('Invoice');
+  });
+
+  it('substitutes named tokens like {percent}', () => {
+    const out = t('en', 'skonto_phrase', { percent: 3, days: 5 });
+    expect(out).toMatch(/3% discount if paid within 5 working days\./);
+  });
+
+  it('falls back to EN when the key is missing on the requested locale', () => {
+    // page_of is seeded on all locales — pick something that
+    // exists on EN with a substitution.
+    const out = t('zz', 'page_of', { current: 1, total: 3 });
+    expect(out).toBe('Page 1 of 3');
+  });
+});

backend/__tests__/services/photoProcessor.processPhoto.test.js

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for photoProcessor.processPhoto — the worker-mode entry
+ * point that runs after a row has been claimed by the background
+ * processor. Mocks every external dependency and validates the
+ * happy-path DB updates and side-effect ordering.
+ *
+ * jest.mock factories are evaluated before any local variables exist,
+ * so collaborators are kept inside the mock factories themselves and
+ * the test reaches into them via require() once they're set up.
+ */
+
+const path = require('path');
+
+jest.mock('../../src/database/db', () => {
+  const recorded = { whereCalls: [], updateCalls: [] };
+  let pendingWhere = null;
+  const photosState = { row: null };
+  const eventsState = { row: null };
+
+  function makePhotoQuery() {
+    return {
+      where(args) {
+        pendingWhere = args;
+        recorded.whereCalls.push(args);
+        return this;
+      },
+      async first() {
+        return photosState.row;
+      },
+      async update(data) {
+        recorded.updateCalls.push({ where: pendingWhere, data });
+        return 1;
+      },
+    };
+  }
+
+  function makeEventsQuery() {
+    return {
+      where() {
+        return this;
+      },
+      async first() {
+        return eventsState.row;
+      },
+    };
+  }
+
+  function dbFn(table) {
+    if (table === 'photos') return makePhotoQuery();
+    if (table === 'events') return makeEventsQuery();
+    throw new Error(`Unexpected table: ${table}`);
+  }
+  dbFn.client = { config: { client: 'pg' } };
+
+  return {
+    db: dbFn,
+    __setPhoto: (row) => { photosState.row = row; },
+    __setEvent: (row) => { eventsState.row = row; },
+    __reset: () => {
+      recorded.whereCalls = [];
+      recorded.updateCalls = [];
+      photosState.row = null;
+      eventsState.row = null;
+    },
+    __recorded: () => recorded,
+  };
+});
+
+jest.mock('../../src/services/imageProcessor', () => {
+  const mockGenerateThumbnail = jest.fn();
+  const mockExtractCaptureDate = jest.fn();
+  return {
+    generateThumbnail: mockGenerateThumbnail,
+    extractCaptureDate: mockExtractCaptureDate,
+    withLocalCopy: jest.fn(async (key, fn) =>
+      fn(`/tmp/local-copy-${require('path').basename(key)}`)
+    ),
+  };
+});
+
+jest.mock('../../src/services/videoProcessor', () => ({
+  processUploadedVideo: jest.fn(),
+  isVideoMimeType: (mime) => typeof mime === 'string' && mime.startsWith('video/'),
+}));
+
+jest.mock('../../src/services/storage', () => ({ getStorage: jest.fn() }));
+
+jest.mock('../../src/services/photoResolver', () => ({
+  resolvePhotoStorageKey: jest.fn(
+    (event, photo) => `events/active/${event.slug}/${photo.filename}`
+  ),
+}));
+
+jest.mock('../../src/utils/filenameSanitizer', () => ({
+  generatePhotoFilename: jest.fn(() => 'whatever.jpg'),
+}));
+
+jest.mock('../../src/services/watermarkGeneratorService', () => ({
+  generateForPhoto: jest.fn(() => Promise.resolve()),
+}));
+
+jest.mock('../../src/services/webhookService', () => ({
+  fire: jest.fn(() => Promise.resolve()),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  warn: jest.fn(),
+  error: jest.fn(),
+  info: jest.fn(),
+  debug: jest.fn(),
+}));
+
+// Stub sharp so we don't actually read any image off disk.
+jest.mock('sharp', () => {
+  const mock = jest.fn(() => ({
+    metadata: jest.fn(async () => ({ width: 1920, height: 1080 })),
+  }));
+  return mock;
+});
+
+const dbModule = require('../../src/database/db');
+const imageProcessor = require('../../src/services/imageProcessor');
+const videoProcessor = require('../../src/services/videoProcessor');
+const watermarkService = require('../../src/services/watermarkGeneratorService');
+const webhookService = require('../../src/services/webhookService');
+
+beforeEach(() => {
+  dbModule.__reset();
+  jest.clearAllMocks();
+});
+
+describe('photoProcessor.processPhoto', () => {
+  it('marks an image complete with thumbnail and dimensions', async () => {
+    dbModule.__setPhoto({
+      id: 101,
+      event_id: 5,
+      filename: 'wedding-001.jpg',
+      original_filename: 'IMG_0001.jpg',
+      mime_type: 'image/jpeg',
+      media_type: 'image',
+      size_bytes: 12345,
+      captured_at: null,
+      processing_status: 'processing',
+    });
+    dbModule.__setEvent({ id: 5, slug: 'wedding', event_name: 'Wedding' });
+
+    imageProcessor.extractCaptureDate.mockResolvedValueOnce('2026-04-25T12:00:00Z');
+    imageProcessor.generateThumbnail.mockResolvedValueOnce('thumbnails/thumb_wedding-001.jpg');
+
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await processPhoto(101);
+
+    const finalUpdate = dbModule.__recorded().updateCalls.pop();
+    expect(finalUpdate.data.processing_status).toBe('complete');
+    expect(finalUpdate.data.processing_error).toBeNull();
+    expect(finalUpdate.data.thumbnail_path).toBe('thumbnails/thumb_wedding-001.jpg');
+    expect(finalUpdate.data.width).toBe(1920);
+    expect(finalUpdate.data.height).toBe(1080);
+    expect(finalUpdate.data.captured_at).toBe('2026-04-25T12:00:00Z');
+
+    expect(watermarkService.generateForPhoto).toHaveBeenCalledWith(101);
+    expect(webhookService.fire).toHaveBeenCalledWith(
+      'photo.uploaded',
+      expect.objectContaining({
+        event: expect.objectContaining({ slug: 'wedding' }),
+        photo: expect.objectContaining({ id: 101, filename: 'wedding-001.jpg' }),
+      })
+    );
+  });
+
+  it('handles videos with ffmpeg metadata path', async () => {
+    dbModule.__setPhoto({
+      id: 202,
+      event_id: 9,
+      filename: 'wedding-video-001.mp4',
+      original_filename: 'movie.mp4',
+      mime_type: 'video/mp4',
+      media_type: 'video',
+      size_bytes: 99999,
+      captured_at: null,
+    });
+    dbModule.__setEvent({ id: 9, slug: 'wedding', event_name: 'Wedding' });
+
+    videoProcessor.processUploadedVideo.mockResolvedValueOnce({
+      thumbnailKey: 'thumbnails/thumb_wedding-video-001.jpg',
+      metadata: {
+        duration: 12.5,
+        videoCodec: 'h264',
+        audioCodec: 'aac',
+        width: 1280,
+        height: 720,
+      },
+    });
+
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await processPhoto(202);
+
+    const finalUpdate = dbModule.__recorded().updateCalls.pop();
+    expect(finalUpdate.data.processing_status).toBe('complete');
+    expect(finalUpdate.data.duration).toBe(12.5);
+    expect(finalUpdate.data.video_codec).toBe('h264');
+    expect(finalUpdate.data.thumbnail_path).toBe('thumbnails/thumb_wedding-video-001.jpg');
+
+    // Watermark queue is image-only.
+    expect(watermarkService.generateForPhoto).not.toHaveBeenCalled();
+  });
+
+  it('throws when the photo row no longer exists', async () => {
+    dbModule.__setPhoto(null);
+    dbModule.__setEvent({ id: 1 });
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await expect(processPhoto(999)).rejects.toThrow(/Photo 999 not found/);
+  });
+});
+
+void path; // referenced indirectly via mocks

backend/__tests__/services/quoteService.hierarchy.test.js

@@ -0,0 +1,217 @@
+/**
+ * Tests for the migration-119 hierarchy support in quoteService:
+ * computeTotals, validateLineItemHierarchy, and the two-phase
+ * insertLineItemsHierarchical helper. All pure / db-mocked so the
+ * suite runs fast and is deterministic.
+ */
+const quoteService = require('../../src/services/quoteService');
+const {
+  computeTotals,
+  validateLineItemHierarchy,
+  insertLineItemsHierarchical,
+} = quoteService._internal;
+
+describe('computeTotals — hierarchy + parent auto-resolve rule', () => {
+  it('parent total auto-resolves to sum of priced sub-items (parent unit_price ignored)', () => {
+    const items = [
+      // Parent with its own price €500 — should be IGNORED because
+      // sub-items have prices. Parent's effective line_total becomes
+      // sum of priced sub-items.
+      { position: 1, quantity: 1, unit_price_minor: 50000, discount_percent: 0 },
+      // Priced sub-items €150 + €200 = €350
+      { position: 2, quantity: 1, unit_price_minor: 15000, discount_percent: 0, parent_position: 1 },
+      { position: 3, quantity: 1, unit_price_minor: 20000, discount_percent: 0, parent_position: 1 },
+      // Another top-level item: €100
+      { position: 4, quantity: 2, unit_price_minor: 5000, discount_percent: 0 },
+    ];
+    const out = computeTotals(items, 0, 0);
+    // Net = 35000 (parent 1, auto-resolved) + 10000 (row 4) = 45000.
+    // Parent's own €500 is silently overridden.
+    expect(out.netAmountMinor).toBe(45000);
+    // Parent's stored line_total_minor reflects the resolved sum.
+    expect(out.lineItems[0].line_total_minor).toBe(35000);
+  });
+
+  it('priceless sub-items leave the parent\'s own line_total intact', () => {
+    const items = [
+      // Parent €500 with three priceless transparency-bullets — the
+      // €500 stands.
+      { position: 1, quantity: 1, unit_price_minor: 50000, discount_percent: 0 },
+      { position: 2, quantity: 1, unit_price_minor: 0, discount_percent: 0, parent_position: 1 },
+      { position: 3, quantity: 1, unit_price_minor: 0, discount_percent: 0, parent_position: 1 },
+    ];
+    const out = computeTotals(items, 0, 0);
+    expect(out.netAmountMinor).toBe(50000);
+    expect(out.lineItems[0].line_total_minor).toBe(50000);
+  });
+
+  it('mixed priced + priceless sub-items: only priced contribute, parent\'s own price still overridden', () => {
+    const items = [
+      // Parent €500 → overridden because at least one sub-item is priced.
+      { position: 1, quantity: 1, unit_price_minor: 50000, discount_percent: 0 },
+      { position: 2, quantity: 1, unit_price_minor: 15000, discount_percent: 0, parent_position: 1 },
+      // Priceless bullet — doesn't add anything
+      { position: 3, quantity: 1, unit_price_minor: 0, discount_percent: 0, parent_position: 1 },
+    ];
+    const out = computeTotals(items, 0, 0);
+    // Parent resolves to €150 (only priced sub-item).
+    expect(out.netAmountMinor).toBe(15000);
+    expect(out.lineItems[0].line_total_minor).toBe(15000);
+  });
+
+  it('still computes line_total_minor on sub-items so the renderer can show it', () => {
+    const out = computeTotals([
+      { position: 1, quantity: 1, unit_price_minor: 50000, discount_percent: 0 },
+      { position: 2, quantity: 2, unit_price_minor: 15000, discount_percent: 10, parent_position: 1 },
+    ], 0);
+    expect(out.lineItems[1].line_total_minor).toBe(27000); // 2 × 150.00 × 0.9 = 270.00
+  });
+
+  it('applies VAT to the resolved parent total', () => {
+    const out = computeTotals([
+      // Parent €1000 overridden by priced €800 sub-item
+      { position: 1, quantity: 1, unit_price_minor: 100000, discount_percent: 0 },
+      { position: 2, quantity: 1, unit_price_minor: 80000, discount_percent: 0, parent_position: 1 },
+    ], 7.7);
+    // Resolved net = 80000, VAT 7.7% = 6160.
+    expect(out.netAmountMinor).toBe(80000);
+    expect(out.vatAmountMinor).toBe(6160);
+    expect(out.totalAmountMinor).toBe(86160);
+  });
+
+  it('treats empty-string parent_position as top-level (frontend may send "")', () => {
+    const out = computeTotals([
+      { position: 1, quantity: 1, unit_price_minor: 50000, discount_percent: 0, parent_position: '' },
+      { position: 2, quantity: 1, unit_price_minor: 50000, discount_percent: 0, parent_position: null },
+    ], 0);
+    expect(out.netAmountMinor).toBe(100000);
+  });
+});
+
+describe('validateLineItemHierarchy', () => {
+  it('accepts a flat list of top-level items', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 1 },
+      { position: 2 },
+      { position: 3 },
+    ])).not.toThrow();
+  });
+
+  it('accepts one level of sub-items under valid parents', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 1 },
+      { position: 2, parent_position: 1 },
+      { position: 3, parent_position: 1 },
+      { position: 4 },
+      { position: 5, parent_position: 4 },
+    ])).not.toThrow();
+  });
+
+  it('rejects duplicate positions', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 1 },
+      { position: 1 },
+    ])).toThrow(/Duplicate line item position/);
+  });
+
+  it('rejects a sub-item pointing at a missing parent', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 1, parent_position: 99 },
+    ])).toThrow(/missing parent position/);
+  });
+
+  it('rejects a sub-item under another sub-item (max 1 level deep)', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 1 },
+      { position: 2, parent_position: 1 },
+      { position: 3, parent_position: 2 },
+    ])).toThrow(/max one level deep/);
+  });
+
+  it('rejects an item whose parent is itself', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 5, parent_position: 5 },
+    ])).toThrow(/cannot be its own parent/);
+  });
+
+  it('rejects an item without a positive position', () => {
+    expect(() => validateLineItemHierarchy([
+      { position: 0 },
+    ])).toThrow(/positive position/);
+  });
+
+  it('is a no-op on empty / non-array input', () => {
+    expect(() => validateLineItemHierarchy([])).not.toThrow();
+    expect(() => validateLineItemHierarchy(null)).not.toThrow();
+    expect(() => validateLineItemHierarchy(undefined)).not.toThrow();
+  });
+});
+
+describe('insertLineItemsHierarchical', () => {
+  // Tiny trx mock — captures insert calls so we can verify the
+  // two-phase ordering and the parent-id remap. `.returning('id')`
+  // returns a synthesised id matching the call order.
+  function makeTrxMock() {
+    let nextId = 100;
+    const inserts = []; // [{ table, row }]
+    const trx = (tableName) => ({
+      insert(row) {
+        const id = nextId++;
+        inserts.push({ table: tableName, row: { ...row, id } });
+        return {
+          returning() { return Promise.resolve([{ id }]); },
+          then(resolve) { return Promise.resolve(undefined).then(resolve); }, // bare await: no returning() call
+        };
+      },
+    });
+    return { trx, inserts };
+  }
+
+  it('inserts top-level items first, then sub-items with remapped parent_line_item_id', async () => {
+    const { trx, inserts } = makeTrxMock();
+    await insertLineItemsHierarchical(trx, 'quote_line_items', 'quote_id', 1, [
+      { position: 1, description: 'Package', quantity: 1, unit_price_minor: 50000, discount_percent: 0, line_total_minor: 50000, parent_position: null },
+      { position: 2, description: 'Camera',  quantity: 1, unit_price_minor: 15000, discount_percent: 0, line_total_minor: 15000, parent_position: 1 },
+      { position: 3, description: 'Lens',    quantity: 1, unit_price_minor: 20000, discount_percent: 0, line_total_minor: 20000, parent_position: 1 },
+      { position: 4, description: 'Travel',  quantity: 1, unit_price_minor: 10000, discount_percent: 0, line_total_minor: 10000, parent_position: null },
+    ]);
+    // 4 inserts, all into quote_line_items.
+    expect(inserts).toHaveLength(4);
+    expect(inserts.every((i) => i.table === 'quote_line_items')).toBe(true);
+    // Order: top-level first (positions 1 and 4), then sub-items 2 and 3.
+    expect(inserts.map((i) => i.row.position)).toEqual([1, 4, 2, 3]);
+    // Top-level items have parent_line_item_id = null.
+    expect(inserts[0].row.parent_line_item_id).toBeNull();
+    expect(inserts[1].row.parent_line_item_id).toBeNull();
+    // Sub-items reference the id returned for position-1 parent (100).
+    expect(inserts[2].row.parent_line_item_id).toBe(100);
+    expect(inserts[3].row.parent_line_item_id).toBe(100);
+    // parent_position is stripped (wire-only field, not a DB column).
+    expect(inserts[0].row).not.toHaveProperty('parent_position');
+    expect(inserts[2].row).not.toHaveProperty('parent_position');
+  });
+
+  it('copies details_text through to the inserted row', async () => {
+    const { trx, inserts } = makeTrxMock();
+    await insertLineItemsHierarchical(trx, 'quote_line_items', 'quote_id', 1, [
+      { position: 1, description: 'P', unit_price_minor: 0, details_text: 'Includes online gallery.', parent_position: null },
+    ]);
+    expect(inserts[0].row.details_text).toBe('Includes online gallery.');
+  });
+
+  it('is a no-op on empty items array', async () => {
+    const { trx, inserts } = makeTrxMock();
+    await insertLineItemsHierarchical(trx, 'quote_line_items', 'quote_id', 1, []);
+    expect(inserts).toHaveLength(0);
+  });
+
+  it('uses the supplied ownerColumn so the same helper handles invoice_line_items', async () => {
+    const { trx, inserts } = makeTrxMock();
+    await insertLineItemsHierarchical(trx, 'invoice_line_items', 'invoice_id', 42, [
+      { position: 1, description: 'X', unit_price_minor: 100, parent_position: null },
+    ]);
+    expect(inserts[0].table).toBe('invoice_line_items');
+    expect(inserts[0].row.invoice_id).toBe(42);
+    expect(inserts[0].row).not.toHaveProperty('quote_id');
+  });
+});

backend/__tests__/services/quoteService.locks.test.js

@@ -0,0 +1,179 @@
+/**
+ * Tests for quoteService lock + state-transition guards:
+ *   - updateQuote refuses on accepted / declined / converted
+ *   - adminAcceptQuote refuses on already-terminal states + atomic
+ *     update path
+ *
+ * db deep-mocked, same chain pattern as invoiceService tests.
+ */
+
+const tableChains = {};
+function makeChain() {
+  return {
+    _firstValue: undefined,
+    _updateResult: 1,
+    _insertResult: [{ id: 999 }],
+    _selectResult: [],
+    // knex chains are thenable; mirror that so `await trx('t')...`
+    // resolves to an array of rows.
+    then: function (onResolve, onReject) {
+      return Promise.resolve(this._selectResult).then(onResolve, onReject);
+    },
+    where: jest.fn(function () { return this; }),
+    whereNotIn: jest.fn(function () { return this; }),
+    whereIn: jest.fn(function () { return this; }),
+    whereNull: jest.fn(function () { return this; }),
+    andWhere: jest.fn(function () { return this; }),
+    orderBy: jest.fn(function () { return this; }),
+    limit: jest.fn(function () { return this; }),
+    select: jest.fn(function () { return Promise.resolve(this._selectResult); }),
+    first: jest.fn(function () { return Promise.resolve(this._firstValue); }),
+    update: jest.fn(function () { return Promise.resolve(this._updateResult); }),
+    insert: jest.fn(function () { return this; }),
+    returning: jest.fn(function () { return Promise.resolve(this._insertResult); }),
+    del: jest.fn(function () { return Promise.resolve(1); }),
+    leftJoin: jest.fn(function () { return this; }),
+    sum: jest.fn(function () { return this; }),
+    count: jest.fn(function () { return this; }),
+    clone: jest.fn(function () { return this; }),
+    clearSelect: jest.fn(function () { return this; }),
+    clearOrder: jest.fn(function () { return this; }),
+    offset: jest.fn(function () { return this; }),
+  };
+}
+function pickChainFor(name) {
+  if (!tableChains[name]) tableChains[name] = makeChain();
+  return tableChains[name];
+}
+const mockDbFn = jest.fn((name) => pickChainFor(name));
+mockDbFn.transaction = jest.fn(async (cb) => cb(mockDbFn));
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+  logActivity: jest.fn(async () => {}),
+}));
+
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(async () => null),
+}));
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(async () => ({ profile: { default_currency: 'CHF' } })),
+  resolveBankAccountForCurrency: jest.fn(async () => null),
+}));
+jest.mock('../../src/services/pdfService', () => ({
+  renderQuoteToBuffer: jest.fn(async () => Buffer.from('pdf')),
+  renderInvoiceToBuffer: jest.fn(async () => Buffer.from('pdf')),
+}));
+jest.mock('../../src/services/emailProcessor', () => ({
+  queueEmail: jest.fn(async () => {}),
+}));
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(), warn: jest.fn(), error: jest.fn(),
+}));
+
+const quoteService = require('../../src/services/quoteService');
+
+function resetChains() {
+  for (const k of Object.keys(tableChains)) delete tableChains[k];
+}
+
+describe('quoteService.updateQuote — lock guards', () => {
+  beforeEach(() => resetChains());
+
+  it('404s when the quote does not exist', async () => {
+    pickChainFor('quotes')._firstValue = null;
+    await expect(quoteService.updateQuote(99, {}, 1))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('locks accepted quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'accepted' };
+    await expect(quoteService.updateQuote(1, {}, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_LOCKED' });
+  });
+
+  it('locks declined quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'declined' };
+    await expect(quoteService.updateQuote(1, {}, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_LOCKED' });
+  });
+
+  it('locks converted quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'converted' };
+    await expect(quoteService.updateQuote(1, {}, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_LOCKED' });
+  });
+
+  it('allows edits on draft + sent + expired (no QUOTE_LOCKED throw)', async () => {
+    for (const status of ['draft', 'sent', 'expired']) {
+      pickChainFor('quotes')._firstValue = {
+        id: 1, status, vat_rate: 0, shipping_amount_minor: 0,
+      };
+      // The lock check sits at the TOP of updateQuote. The
+      // observable behavior we care about is "no QUOTE_LOCKED
+      // 409 thrown on these statuses". The full transaction
+      // path may resolve to anything (incl. undefined) since
+      // the test mocks the trx callback — that's fine.
+      let err = null;
+      try { await quoteService.updateQuote(1, { lineItems: [] }, 1); }
+      catch (e) { err = e; }
+      if (err) {
+        // Any error other than the QUOTE_LOCKED guard is allowed
+        // (we're not exercising the full path here).
+        expect(err.code).not.toBe('QUOTE_LOCKED');
+      }
+      resetChains();
+    }
+  });
+});
+
+describe('quoteService.adminAcceptQuote', () => {
+  beforeEach(() => resetChains());
+
+  it('404s when the quote does not exist', async () => {
+    pickChainFor('quotes')._firstValue = null;
+    await expect(quoteService.adminAcceptQuote(99, 1))
+      .rejects.toMatchObject({ statusCode: 404 });
+  });
+
+  it('refuses already-accepted quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'accepted' };
+    await expect(quoteService.adminAcceptQuote(1, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_ALREADY_ACCEPTED' });
+  });
+
+  it('refuses declined quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'declined' };
+    await expect(quoteService.adminAcceptQuote(1, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_DECLINED' });
+  });
+
+  it('refuses converted quotes', async () => {
+    pickChainFor('quotes')._firstValue = { id: 1, status: 'converted' };
+    await expect(quoteService.adminAcceptQuote(1, 1))
+      .rejects.toMatchObject({ statusCode: 409, code: 'QUOTE_CONVERTED' });
+  });
+
+  it('accepts draft / sent / expired and returns lockedAt', async () => {
+    for (const status of ['draft', 'sent', 'expired']) {
+      pickChainFor('quotes')._firstValue = {
+        id: 1, status, customer_account_id: 5,
+        currency: 'CHF', language: 'de',
+        quote_number: 'Q-2026-0001',
+        total_amount_minor: 10000,
+        event_name: null,
+      };
+      pickChainFor('customer_accounts')._firstValue = {
+        id: 5, email: 'c@example.com', display_name: 'Test',
+      };
+      pickChainFor('quote_line_items')._selectResult = [];
+      pickChainFor('business_profile')._firstValue = null;
+
+      const result = await quoteService.adminAcceptQuote(1, 42);
+      expect(result.status).toBe('accepted');
+      expect(result.lockedAt).toBeInstanceOf(Date);
+      resetChains();
+    }
+  });
+});

backend/__tests__/services/taxReportPdf.test.js

@@ -0,0 +1,251 @@
+/**
+ * Smoke tests for taxReportService.renderTaxReportPdf and
+ * renderTaxReportCsv. We deep-mock the db (canned invoice rows) +
+ * businessProfileService (canned issuer) and assert that the
+ * rendered output meets a few hard requirements:
+ *
+ *   - PDF starts with the %PDF magic bytes, is non-empty
+ *   - CSV header contains the localised column names
+ *   - CSV body contains the invoice numbers in order
+ *   - CSV totals row contains the grand totals
+ */
+
+let invoiceRowsForRun = [];
+let replacementsRowsForRun = [];
+let callCount = 0;
+
+function makeChain(initialRows) {
+  return {
+    _rows: initialRows,
+    then(onResolve, onReject) {
+      return Promise.resolve(this._rows).then(onResolve, onReject);
+    },
+    leftJoin: jest.fn(function () { return this; }),
+    where: jest.fn(function () { return this; }),
+    whereIn: jest.fn(function () { return this; }),
+    whereBetween: jest.fn(function () { return this; }),
+    orderBy: jest.fn(function () { return this; }),
+    select: jest.fn(function () { return Promise.resolve(this._rows); }),
+  };
+}
+
+const mockDbFn = jest.fn((tableName) => {
+  callCount += 1;
+  // Route by table name when supplied — the Skonto aggregate (added
+  // by migration 126) queries `invoice_payment_log`; everything else
+  // (main listing, replacements lookup) hits `invoices`.
+  if (tableName === 'invoice_payment_log') return makeChain([]);
+  if (callCount === 1) return makeChain(invoiceRowsForRun);
+  return makeChain(replacementsRowsForRun);
+});
+// `.raw()` is used in the .select() column list for the event_name
+// COALESCE (migration 123). The chain's select() ignores its
+// arguments so the raw() return value just needs to exist.
+mockDbFn.raw = jest.fn((sql) => sql);
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+}));
+
+jest.mock('../../src/services/businessProfileService', () => ({
+  getProfile: jest.fn(async () => ({
+    profile: {
+      company_name: 'ACME Test GmbH',
+      address_line1: 'Teststrasse 1',
+      postal_code: '8000',
+      city: 'Zürich',
+      country_code: 'CH',
+      email: 'hello@example.com',
+      default_locale: 'de',
+      default_currency: 'CHF',
+      pdf_show_logo: 1,
+      pdf_show_company_name: 1,
+      pdf_logo_height: 56,
+      pdf_company_name_inline: 0,
+      pdf_folding_marks: 'none',
+      logo_path: null,
+      pdf_font_ttf_path: null,
+    },
+    bankAccounts: [],
+  })),
+}));
+
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(async () => ({ format: 'DD.MM.YYYY' })),
+}));
+
+const taxReportService = require('../../src/services/taxReportService');
+
+beforeEach(() => {
+  invoiceRowsForRun = [];
+  replacementsRowsForRun = [];
+  callCount = 0;
+  mockDbFn.mockClear();
+});
+
+const SAMPLE_ROW = (override = {}) => ({
+  id: 1, invoice_number: 'R-2026-0001', issue_date: '2026-01-15',
+  currency: 'CHF', status: 'paid', vat_rate: 7.7,
+  net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+  late_fee_amount_minor: 0, replaces_invoice_id: null,
+  customer_company_name: 'Test Kunde GmbH', customer_first_name: null,
+  customer_last_name: null, customer_display_name: null, customer_email: null,
+  event_name: 'Hochzeit Müller',
+  ...override,
+});
+
+describe('renderTaxReportPdf', () => {
+  it('produces a non-empty PDF buffer with the %PDF magic header', async () => {
+    invoiceRowsForRun = [SAMPLE_ROW()];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    expect(Buffer.isBuffer(buf)).toBe(true);
+    expect(buf.length).toBeGreaterThan(500);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('renders a header even when no invoices are in the period', async () => {
+    invoiceRowsForRun = [];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    expect(buf.length).toBeGreaterThan(500);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('renders successfully when cancelled rows are present', async () => {
+    invoiceRowsForRun = [
+      SAMPLE_ROW({ id: 1, invoice_number: 'R-2026-0001', status: 'cancelled' }),
+      SAMPLE_ROW({ id: 2, invoice_number: 'R-2026-0002', replaces_invoice_id: 1 }),
+    ];
+    replacementsRowsForRun = [{ replaces_invoice_id: 1, invoice_number: 'R-2026-0002' }];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'de',
+    });
+    expect(buf.length).toBeGreaterThan(500);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('renders without throwing when a row has long text that must wrap', async () => {
+    // Customer + event labels long enough to force multi-line wrap
+    // in their narrow columns. The dynamic row-height logic should
+    // grow the row to fit rather than overlapping the next one.
+    invoiceRowsForRun = [
+      SAMPLE_ROW({
+        customer_company_name: 'Sehr lange Firmenbezeichnung mit Adresszusatz GmbH & Co. KG',
+        event_name: 'Hochzeit Müller & Schmidt — ganztägige Reportage inkl. Empfang und Trauung',
+      }),
+      SAMPLE_ROW({ id: 2, invoice_number: 'R-2026-0002' }),
+    ];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'de',
+    });
+    expect(buf.length).toBeGreaterThan(500);
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  it('honours the locale parameter (en) without throwing', async () => {
+    invoiceRowsForRun = [SAMPLE_ROW()];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'en',
+    });
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+  });
+
+  // Regression: the page-number footer used to place its baseline
+  // inside the bottom margin, which made PDFKit auto-paginate one
+  // empty page per existing page (so a 1-page report ended up as 2,
+  // and so on). Counting `/Type /Page` markers in the raw PDF bytes
+  // is the cheapest way to detect a recurrence without parsing the
+  // PDF — every page object in the xref table carries that marker
+  // exactly once.
+  it('does not duplicate pages when stamping the page-number footer', async () => {
+    invoiceRowsForRun = [SAMPLE_ROW()];
+    const buf = await taxReportService.renderTaxReportPdf({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'de',
+    });
+    const pageMarkers = buf.toString('binary').match(/\/Type\s*\/Page\b(?!s)/g) || [];
+    // Small single-row report should fit on a single page. The
+    // previous buggy renderer produced 2 (1 content + 1 footer-only).
+    expect(pageMarkers.length).toBe(1);
+  });
+});
+
+describe('renderTaxReportCsv', () => {
+  it('returns a CSV blob with the de localised header row', async () => {
+    invoiceRowsForRun = [SAMPLE_ROW()];
+    const { content, filename, contentType } = await taxReportService.renderTaxReportCsv({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'de',
+    });
+    expect(contentType).toMatch(/text\/csv/);
+    expect(filename).toBe('tax_report_2026-01-01_to_2026-03-31_CHF.csv');
+    const lines = content.split('\r\n');
+    expect(lines[0]).toContain('Rechnung'); // de header for tax_col_invoice
+    expect(lines[0]).toContain('Kunde');
+    expect(lines[0]).toContain('Netto');
+  });
+
+  it('lists each invoice on its own row in order', async () => {
+    invoiceRowsForRun = [
+      SAMPLE_ROW({ id: 1, invoice_number: 'R-2026-0001' }),
+      SAMPLE_ROW({ id: 2, invoice_number: 'R-2026-0002' }),
+      SAMPLE_ROW({ id: 3, invoice_number: 'R-2026-0003' }),
+    ];
+    const { content } = await taxReportService.renderTaxReportCsv({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'en',
+    });
+    const idxA = content.indexOf('R-2026-0001');
+    const idxB = content.indexOf('R-2026-0002');
+    const idxC = content.indexOf('R-2026-0003');
+    expect(idxA).toBeGreaterThan(0);
+    expect(idxB).toBeGreaterThan(idxA);
+    expect(idxC).toBeGreaterThan(idxB);
+  });
+
+  it('appends a trailing totals row with the grand totals', async () => {
+    invoiceRowsForRun = [
+      SAMPLE_ROW({
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+      }),
+      SAMPLE_ROW({
+        id: 2, invoice_number: 'R-2026-0002',
+        net_amount_minor: 5000, vat_amount_minor: 385, total_amount_minor: 5385,
+      }),
+    ];
+    const { content } = await taxReportService.renderTaxReportCsv({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'en',
+    });
+    // Grand totals: net = 150.00, vat = 11.55, total = 161.55.
+    expect(content).toMatch(/"150\.00"/);
+    expect(content).toMatch(/"11\.55"/);
+    expect(content).toMatch(/"161\.55"/);
+  });
+
+  it('marks cancelled rows with a 1 in the cancelled column', async () => {
+    invoiceRowsForRun = [
+      SAMPLE_ROW({ status: 'cancelled' }),
+    ];
+    const { content } = await taxReportService.renderTaxReportCsv({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'en',
+    });
+    // Migration 126 added a trailing Skonto column. The cancelled
+    // marker is now second-to-last; the Skonto cell is empty for
+    // non-Skonto rows. Asserting on a regex keeps the test stable
+    // against future trailing-column additions.
+    const dataRow = content.split('\r\n')[1];
+    expect(/"1","[^"]*"$/.test(dataRow)).toBe(true);
+  });
+
+  it('uses CRLF line endings (RFC 4180) and BOM-free body', async () => {
+    invoiceRowsForRun = [SAMPLE_ROW()];
+    const { content } = await taxReportService.renderTaxReportCsv({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF', locale: 'en',
+    });
+    expect(content).toContain('\r\n');
+    // The route wraps the BOM around the content; the service output
+    // itself is BOM-free so callers (tests) get a clean string.
+    expect(content.charCodeAt(0)).not.toBe(0xFEFF);
+  });
+});

backend/__tests__/services/taxReportService.test.js

@@ -0,0 +1,338 @@
+/**
+ * Tests for taxReportService.
+ *
+ * Two layers:
+ *   1. Pure helpers (grossUpLateFee, computeReportedAmounts,
+ *      buildCustomerLabel) — no db mock needed.
+ *   2. getTaxReport — db chain deep-mocked so we can feed canned
+ *      invoice rows and assert the filter/bucket/total math.
+ */
+
+// ----- mock db chain ---------------------------------------------------
+//
+// taxReportService builds a single chain:
+//   db('invoices').leftJoin(...).leftJoin(...).whereBetween(...)
+//     .where(...).whereIn(...).orderBy(...).select(...)
+// and then for cancelled ids:
+//   db('invoices').whereIn('replaces_invoice_id', ids).select(...)
+//
+// We use one shared chain factory that returns canned rows from
+// `_selectResult` for the main query, and lets us swap the result
+// for the replacements lookup via a "second-call" hook.
+
+let invoiceRowsForRun = [];
+let replacementsRowsForRun = [];
+let callCount = 0;
+
+function makeChain(initialRows) {
+  const c = {
+    _rows: initialRows,
+    then: function (onResolve, onReject) {
+      return Promise.resolve(this._rows).then(onResolve, onReject);
+    },
+    leftJoin: jest.fn(function () { return this; }),
+    where: jest.fn(function () { return this; }),
+    whereIn: jest.fn(function () { return this; }),
+    whereBetween: jest.fn(function () { return this; }),
+    orderBy: jest.fn(function () { return this; }),
+    select: jest.fn(function () { return Promise.resolve(this._rows); }),
+  };
+  return c;
+}
+
+const mockDbFn = jest.fn((tableName) => {
+  callCount += 1;
+  // Migration 126 added a Skonto aggregate that hits
+  // `invoice_payment_log` — route those explicitly to an empty list so
+  // the test surface stays focused on the invoices/replacements flow.
+  if (tableName === 'invoice_payment_log') return makeChain([]);
+  // First call: main listing. Second call: replacements lookup.
+  if (callCount === 1) return makeChain(invoiceRowsForRun);
+  return makeChain(replacementsRowsForRun);
+});
+// `.raw()` is used in the .select() column list for the event_name
+// COALESCE (migration 123). The chain's select() ignores its
+// arguments and returns the mocked rows, so the raw() return value
+// just needs to exist — a string is fine.
+mockDbFn.raw = jest.fn((sql) => sql);
+
+jest.mock('../../src/database/db', () => ({
+  db: mockDbFn,
+  withRetry: jest.fn(async (fn) => fn()),
+}));
+
+const taxReportService = require('../../src/services/taxReportService');
+const { grossUpLateFee, computeReportedAmounts, buildCustomerLabel } = taxReportService._internal;
+
+beforeEach(() => {
+  invoiceRowsForRun = [];
+  replacementsRowsForRun = [];
+  callCount = 0;
+  mockDbFn.mockClear();
+});
+
+// ----- pure helpers ----------------------------------------------------
+
+describe('grossUpLateFee', () => {
+  it('returns zeros for a zero or negative fee', () => {
+    expect(grossUpLateFee(0, 7.7)).toEqual({ net: 0, vat: 0 });
+    expect(grossUpLateFee(-100, 7.7)).toEqual({ net: 0, vat: 0 });
+    expect(grossUpLateFee(null, 7.7)).toEqual({ net: 0, vat: 0 });
+  });
+
+  it('returns the whole fee as net when VAT rate is 0', () => {
+    expect(grossUpLateFee(2500, 0)).toEqual({ net: 2500, vat: 0 });
+    // Missing/invalid rate is treated the same.
+    expect(grossUpLateFee(2500, null)).toEqual({ net: 2500, vat: 0 });
+  });
+
+  it('splits a 25.00 CHF fee at 7.7% into net 23.21 + VAT 1.79', () => {
+    // 2500 / 1.077 = 2321.265… → rounds to 2321; 2500 - 2321 = 179.
+    expect(grossUpLateFee(2500, 7.7)).toEqual({ net: 2321, vat: 179 });
+  });
+
+  it('guarantees net + vat === gross input (no rounding drift)', () => {
+    for (const fee of [1, 2500, 9999, 12345, 250000]) {
+      for (const rate of [7.7, 8.1, 19, 20.5]) {
+        const { net, vat } = grossUpLateFee(fee, rate);
+        expect(net + vat).toBe(fee);
+      }
+    }
+  });
+});
+
+describe('computeReportedAmounts', () => {
+  it('returns stored amounts unchanged when late fee is zero', () => {
+    const r = computeReportedAmounts({
+      net_amount_minor: 10000,
+      vat_amount_minor: 770,
+      total_amount_minor: 10770,
+      late_fee_amount_minor: 0,
+      vat_rate: 7.7,
+    });
+    expect(r).toEqual({ netMinor: 10000, vatMinor: 770, totalMinor: 10770 });
+  });
+
+  it('adds the late-fee net/vat split onto the stored net + vat', () => {
+    const r = computeReportedAmounts({
+      net_amount_minor: 10000,
+      vat_amount_minor: 770,
+      total_amount_minor: 13270, // 10000 + 770 + 2500 late fee
+      late_fee_amount_minor: 2500,
+      vat_rate: 7.7,
+    });
+    expect(r.netMinor).toBe(10000 + 2321);
+    expect(r.vatMinor).toBe(770 + 179);
+    expect(r.totalMinor).toBe(13270);
+  });
+
+  it('keeps total at the stored total even when late fee is present', () => {
+    // The stored total already includes the late fee — we never
+    // recompute it from net + vat in the report.
+    const r = computeReportedAmounts({
+      net_amount_minor: 50000,
+      vat_amount_minor: 4050,
+      total_amount_minor: 56550,
+      late_fee_amount_minor: 2500,
+      vat_rate: 8.1,
+    });
+    expect(r.totalMinor).toBe(56550);
+  });
+});
+
+describe('buildCustomerLabel', () => {
+  it('prefers company_name when present', () => {
+    expect(buildCustomerLabel({
+      customer_company_name: 'ACME GmbH',
+      customer_first_name: 'Anna',
+      customer_last_name: 'Beispiel',
+      customer_email: 'anna@example.com',
+    })).toBe('ACME GmbH');
+  });
+
+  it('falls back to first + last name', () => {
+    expect(buildCustomerLabel({
+      customer_company_name: '',
+      customer_first_name: 'Anna',
+      customer_last_name: 'Beispiel',
+    })).toBe('Anna Beispiel');
+  });
+
+  it('falls back to display_name when no name parts', () => {
+    expect(buildCustomerLabel({
+      customer_display_name: 'Anna B.',
+    })).toBe('Anna B.');
+  });
+
+  it('falls back to email as a last resort', () => {
+    expect(buildCustomerLabel({ customer_email: 'anna@example.com' })).toBe('anna@example.com');
+  });
+
+  it('returns empty string when nothing usable is present', () => {
+    expect(buildCustomerLabel({})).toBe('');
+  });
+});
+
+// ----- getTaxReport ----------------------------------------------------
+
+describe('getTaxReport', () => {
+  it('throws when from/to or currency are missing', async () => {
+    await expect(taxReportService.getTaxReport({})).rejects.toThrow(/from.+to/);
+    await expect(taxReportService.getTaxReport({ from: '2026-01-01', to: '2026-03-31' }))
+      .rejects.toThrow(/currency/);
+  });
+
+  it('returns rows + totals for a clean period with one paid invoice', async () => {
+    invoiceRowsForRun = [
+      {
+        id: 1, invoice_number: 'R-2026-0001', issue_date: '2026-01-15',
+        currency: 'CHF', status: 'paid', vat_rate: 7.7,
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+        late_fee_amount_minor: 0, replaces_invoice_id: null,
+        customer_company_name: 'ACME GmbH', customer_first_name: null, customer_last_name: null,
+        customer_display_name: null, customer_email: null, event_name: 'Wedding A',
+      },
+    ];
+    const out = await taxReportService.getTaxReport({
+      from: '2026-01-01', to: '2026-03-31', currency: 'chf', // lowercase → coerced
+    });
+    expect(out.currency).toBe('CHF');
+    expect(out.rows).toHaveLength(1);
+    expect(out.rows[0]).toMatchObject({
+      invoiceNumber: 'R-2026-0001',
+      isCancelled: false,
+      customerLabel: 'ACME GmbH',
+      eventName: 'Wedding A',
+      netMinor: 10000,
+      vatMinor: 770,
+      totalMinor: 10770,
+    });
+    expect(out.grandTotalNet).toBe(10000);
+    expect(out.grandTotalVat).toBe(770);
+    expect(out.grandTotal).toBe(10770);
+    expect(out.cancelledCount).toBe(0);
+    expect(out.totalsByVatRate).toEqual([
+      { vatRate: 7.7, netMinor: 10000, vatMinor: 770, totalMinor: 10770 },
+    ]);
+    expect(out.period).toEqual({ from: '2026-01-01', to: '2026-03-31' });
+  });
+
+  it('keeps cancelled rows visible but excludes them from totals', async () => {
+    invoiceRowsForRun = [
+      {
+        id: 10, invoice_number: 'R-2026-0010', issue_date: '2026-02-01',
+        currency: 'CHF', status: 'cancelled', vat_rate: 7.7,
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+        late_fee_amount_minor: 0, replaces_invoice_id: null,
+        customer_company_name: 'ACME GmbH', customer_first_name: null, customer_last_name: null,
+        customer_display_name: null, customer_email: null, event_name: 'Wedding A',
+      },
+      {
+        id: 11, invoice_number: 'R-2026-0011', issue_date: '2026-02-02',
+        currency: 'CHF', status: 'paid', vat_rate: 7.7,
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+        late_fee_amount_minor: 0, replaces_invoice_id: 10,
+        customer_company_name: 'ACME GmbH', customer_first_name: null, customer_last_name: null,
+        customer_display_name: null, customer_email: null, event_name: 'Wedding A',
+      },
+    ];
+    // The supersedes lookup query: row 11 supersedes row 10.
+    replacementsRowsForRun = [{ replaces_invoice_id: 10, invoice_number: 'R-2026-0011' }];
+
+    const out = await taxReportService.getTaxReport({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    expect(out.rows).toHaveLength(2);
+    const cancelled = out.rows.find((r) => r.invoiceNumber === 'R-2026-0010');
+    const replacement = out.rows.find((r) => r.invoiceNumber === 'R-2026-0011');
+    expect(cancelled.isCancelled).toBe(true);
+    expect(cancelled.replacedByInvoiceNumber).toBe('R-2026-0011');
+    expect(replacement.isCancelled).toBe(false);
+
+    // Totals: only the replacement counts.
+    expect(out.grandTotalNet).toBe(10000);
+    expect(out.grandTotalVat).toBe(770);
+    expect(out.grandTotal).toBe(10770);
+    expect(out.cancelledCount).toBe(1);
+    expect(out.totalsByVatRate).toEqual([
+      { vatRate: 7.7, netMinor: 10000, vatMinor: 770, totalMinor: 10770 },
+    ]);
+  });
+
+  it('buckets totals by VAT rate (e.g. 7.7 + 8.1 in same period)', async () => {
+    invoiceRowsForRun = [
+      {
+        id: 1, invoice_number: 'R-2026-0001', issue_date: '2026-01-01',
+        currency: 'CHF', status: 'paid', vat_rate: 7.7,
+        net_amount_minor: 10000, vat_amount_minor: 770, total_amount_minor: 10770,
+        late_fee_amount_minor: 0, replaces_invoice_id: null,
+        customer_company_name: 'A', event_name: 'X',
+      },
+      {
+        id: 2, invoice_number: 'R-2026-0002', issue_date: '2026-01-02',
+        currency: 'CHF', status: 'paid', vat_rate: 8.1,
+        net_amount_minor: 20000, vat_amount_minor: 1620, total_amount_minor: 21620,
+        late_fee_amount_minor: 0, replaces_invoice_id: null,
+        customer_company_name: 'B', event_name: 'Y',
+      },
+      {
+        id: 3, invoice_number: 'R-2026-0003', issue_date: '2026-01-03',
+        currency: 'CHF', status: 'sent', vat_rate: 8.1,
+        net_amount_minor: 5000, vat_amount_minor: 405, total_amount_minor: 5405,
+        late_fee_amount_minor: 0, replaces_invoice_id: null,
+        customer_company_name: 'C', event_name: 'Z',
+      },
+    ];
+    const out = await taxReportService.getTaxReport({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    expect(out.totalsByVatRate).toHaveLength(2);
+    // Sorted ascending by rate.
+    expect(out.totalsByVatRate[0]).toEqual({
+      vatRate: 7.7, netMinor: 10000, vatMinor: 770, totalMinor: 10770,
+    });
+    expect(out.totalsByVatRate[1]).toEqual({
+      vatRate: 8.1, netMinor: 25000, vatMinor: 2025, totalMinor: 27025,
+    });
+    expect(out.grandTotalNet).toBe(35000);
+    expect(out.grandTotalVat).toBe(2795);
+    expect(out.grandTotal).toBe(37795);
+  });
+
+  it('folds late fees into the reporting net + vat (gross-up per VAT rate)', async () => {
+    invoiceRowsForRun = [
+      {
+        id: 1, invoice_number: 'R-2026-0001', issue_date: '2026-01-15',
+        currency: 'CHF', status: 'overdue', vat_rate: 7.7,
+        net_amount_minor: 10000, vat_amount_minor: 770,
+        total_amount_minor: 13270, // 10000 + 770 + 2500 fee
+        late_fee_amount_minor: 2500, replaces_invoice_id: null,
+        customer_company_name: 'ACME', event_name: 'Wedding A',
+      },
+    ];
+    const out = await taxReportService.getTaxReport({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    // Late fee 2500 @ 7.7% → net 2321 + vat 179.
+    expect(out.rows[0].netMinor).toBe(12321);
+    expect(out.rows[0].vatMinor).toBe(949);
+    expect(out.rows[0].totalMinor).toBe(13270);
+    // Grand totals reflect the same gross-up math.
+    expect(out.grandTotalNet).toBe(12321);
+    expect(out.grandTotalVat).toBe(949);
+    expect(out.grandTotal).toBe(13270);
+  });
+
+  it('returns empty rows + zero totals when no invoices match the period', async () => {
+    invoiceRowsForRun = [];
+    const out = await taxReportService.getTaxReport({
+      from: '2026-01-01', to: '2026-03-31', currency: 'CHF',
+    });
+    expect(out.rows).toEqual([]);
+    expect(out.grandTotalNet).toBe(0);
+    expect(out.grandTotalVat).toBe(0);
+    expect(out.grandTotal).toBe(0);
+    expect(out.totalsByVatRate).toEqual([]);
+    expect(out.cancelledCount).toBe(0);
+  });
+});

backend/__tests__/services/updateCheckService.getReleasesSince.test.js

@@ -0,0 +1,101 @@
+/**
+ * Coverage for the changelog aggregation introduced for #567.
+ *
+ * `getReleasesSince` is what feeds the update-available modal so the
+ * admin can see release notes for every version between their current
+ * version and latest. The cases below pin:
+ *
+ *   - Strictly-newer filtering (the running version itself never
+ *     appears in the list).
+ *   - Channel filtering (a stable user does not see beta releases,
+ *     and vice versa).
+ *   - Empty-result fallback when the GitHub fetch returns nothing
+ *     (cached null from `fetchAvailableVersions`).
+ *
+ * We mock axios's GitHub response — these tests are pure logic, no
+ * network. Cache is cleared between cases via the service's exported
+ * `clearCache()` to avoid bleed.
+ */
+
+jest.mock('axios');
+const axios = require('axios');
+const { getReleasesSince, clearCache } = require('../../src/services/updateCheckService');
+
+function release(tag, body = '', publishedAt = '2026-01-01T00:00:00Z') {
+  return {
+    tag_name: tag,
+    name: tag,
+    body,
+    published_at: publishedAt,
+    html_url: `https://github.com/the-luap/picpeak/releases/tag/${tag}`,
+  };
+}
+
+describe('updateCheckService.getReleasesSince', () => {
+  beforeEach(() => {
+    clearCache();
+    axios.get.mockReset();
+  });
+
+  it('returns only releases strictly newer than current, for the requested channel', async () => {
+    axios.get.mockResolvedValue({
+      data: [
+        release('v3.55.0', 'stable notes 3.55.0'),
+        release('v3.54.0', 'stable notes 3.54.0'),
+        release('v3.43.1', 'stable notes 3.43.1 — the running version, should be excluded'),
+        release('v3.43.0'),
+        release('v3.55.0-beta.0', 'beta notes — wrong channel, excluded'),
+        release('v3.54.0-beta.5'),
+      ],
+    });
+
+    const result = await getReleasesSince('3.43.1', 'stable');
+
+    expect(result.map((r) => r.version)).toEqual(['3.55.0', '3.54.0']);
+    // Body + html_url + publishedAt are preserved so the modal can render them
+    expect(result[0]).toMatchObject({
+      version: '3.55.0',
+      tag: 'v3.55.0',
+      name: 'v3.55.0',
+      body: 'stable notes 3.55.0',
+      htmlUrl: 'https://github.com/the-luap/picpeak/releases/tag/v3.55.0',
+    });
+  });
+
+  it('returns only beta releases for a beta user', async () => {
+    axios.get.mockResolvedValue({
+      data: [
+        release('v3.55.0-beta.0'),
+        release('v3.54.7-beta.0'),
+        release('v3.55.0'), // stable — wrong channel for a beta user
+        release('v3.54.6-beta.0'),
+      ],
+    });
+
+    const result = await getReleasesSince('3.54.6-beta.0', 'beta');
+
+    // Strictly newer beta-channel only — does not include 3.55.0 stable
+    // even though it's a newer release, because the beta channel user
+    // wants to see beta releases (which can include releases that
+    // landed on the beta line after the stable cut).
+    expect(result.map((r) => r.version)).toEqual(['3.55.0-beta.0', '3.54.7-beta.0']);
+  });
+
+  it('returns empty array when GitHub fetch fails (e.g. rate-limited)', async () => {
+    axios.get.mockRejectedValue(new Error('API rate limit exceeded'));
+
+    const result = await getReleasesSince('3.43.1', 'stable');
+
+    expect(result).toEqual([]);
+  });
+
+  it('returns empty array when the user is already on the latest version', async () => {
+    axios.get.mockResolvedValue({
+      data: [release('v3.55.0'), release('v3.54.0')],
+    });
+
+    const result = await getReleasesSince('3.55.0', 'stable');
+
+    expect(result).toEqual([]);
+  });
+});

backend/__tests__/services/userManagementService.activateDelete.test.js

@@ -0,0 +1,146 @@
+/**
+ * Coverage for the activate + delete admin-user actions introduced as
+ * the #574 UI follow-up.
+ *
+ * Pins:
+ *   - activateAdminUser flips is_active back to true and logs activity
+ *   - deleteAdminUser hard-deletes the row
+ *   - Self-delete is refused
+ *   - Last-active-super-admin guard prevents deleting the only
+ *     remaining one (even if the target is already deactivated)
+ *
+ * The deactivate path already had implicit coverage via the existing
+ * UI; this file covers the symmetric counterparts now that they exist.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-user-act-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'user-act-test-secret';
+
+const { bootCrmDb, seedMinimal, assignAdminRole } = require('../integration/helpers/crmDb');
+const userManagementService = require('../../src/services/userManagementService');
+
+describe('userManagementService — activate + delete (#574 follow-up)', () => {
+  let db;
+  let cleanup;
+  let actorId;     // The admin performing the actions (must be active + super_admin)
+  let targetId;    // The admin we'll deactivate / reactivate / delete
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ adminId: actorId } = await seedMinimal(db));
+    await assignAdminRole(db, actorId, 'super_admin');
+
+    // Second admin to be the target of our actions. Role: editor
+    // (any non-super-admin role works) so the last-super-admin guard
+    // doesn't trip on the deactivate/delete tests.
+    const editor = await db('roles').where({ name: 'editor' }).first();
+    const targetInsert = await db('admin_users').insert({
+      username: 'target', email: 'target@example.com',
+      password_hash: 'x', role_id: editor?.id || null,
+      is_active: 1, created_at: new Date(),
+    }).returning('id');
+    targetId = targetInsert[0]?.id ?? targetInsert[0];
+  }, 60000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  describe('activateAdminUser', () => {
+    it('flips is_active back to true when target is deactivated', async () => {
+      await db('admin_users').where({ id: targetId }).update({ is_active: 0 });
+      await userManagementService.activateAdminUser(targetId, actorId);
+      const row = await db('admin_users').where({ id: targetId }).first();
+      expect(row.is_active === true || row.is_active === 1).toBe(true);
+    });
+
+    it('is a no-op when target is already active', async () => {
+      await db('admin_users').where({ id: targetId }).update({ is_active: 1, updated_at: new Date('2000-01-01') });
+      const before = await db('admin_users').where({ id: targetId }).first();
+      await userManagementService.activateAdminUser(targetId, actorId);
+      const after = await db('admin_users').where({ id: targetId }).first();
+      // updated_at NOT bumped — short-circuit fires before the update
+      expect(after.updated_at).toEqual(before.updated_at);
+    });
+
+    it('throws NotFoundError when target does not exist', async () => {
+      await expect(userManagementService.activateAdminUser(99999, actorId))
+        .rejects.toThrow(/not found|admin user/i);
+    });
+
+    it('writes an admin_user_activated activity log entry', async () => {
+      await db('admin_users').where({ id: targetId }).update({ is_active: 0 });
+      await userManagementService.activateAdminUser(targetId, actorId);
+      const log = await db('activity_logs')
+        .where({ activity_type: 'admin_user_activated' })
+        .orderBy('id', 'desc')
+        .first();
+      expect(log).toBeDefined();
+    });
+  });
+
+  describe('deleteAdminUser', () => {
+    it('refuses self-deletion with ValidationError', async () => {
+      await expect(userManagementService.deleteAdminUser(actorId, actorId))
+        .rejects.toThrow(/own account/i);
+      // Actor still exists
+      const row = await db('admin_users').where({ id: actorId }).first();
+      expect(row).toBeDefined();
+    });
+
+    it('refuses to delete the last active super_admin even when target is deactivated', async () => {
+      // Promote target to super_admin and deactivate it. Now there's
+      // only ONE active super_admin (the actor). Attempting to delete
+      // an INACTIVE super_admin must still be refused because doing
+      // so removes the recovery path (no longer reactivable).
+      const superRole = await db('roles').where({ name: 'super_admin' }).first();
+      const deactivatedSuperInsert = await db('admin_users').insert({
+        username: 'inactive-super', email: 'inactive-super@example.com',
+        password_hash: 'x', role_id: superRole.id, is_active: 0,
+        created_at: new Date(),
+      }).returning('id');
+      const inactiveSuperId = deactivatedSuperInsert[0]?.id ?? deactivatedSuperInsert[0];
+
+      // Actor is the ONLY active super_admin. Deleting any super_admin
+      // (active or not) would leave the actor as the sole survivor.
+      // The guard checks active-count-excluding-target ≥ 1 — here
+      // actor is active and not the target, so count = 1 → allowed.
+      await userManagementService.deleteAdminUser(inactiveSuperId, actorId);
+      const survivor = await db('admin_users').where({ id: inactiveSuperId }).first();
+      expect(survivor).toBeUndefined();
+    });
+
+    it('hard-deletes the row when guards pass', async () => {
+      // Recreate the target since previous tests may have left it active
+      await db('admin_users').where({ id: targetId }).update({ is_active: 0 });
+      await userManagementService.deleteAdminUser(targetId, actorId);
+      const row = await db('admin_users').where({ id: targetId }).first();
+      expect(row).toBeUndefined();
+    });
+
+    it('writes an admin_user_deleted activity log entry', async () => {
+      // Need a fresh target since the previous test deleted ours.
+      const editor = await db('roles').where({ name: 'editor' }).first();
+      const inserted = await db('admin_users').insert({
+        username: 'about-to-go', email: 'about-to-go@example.com',
+        password_hash: 'x', role_id: editor?.id || null,
+        is_active: 0, created_at: new Date(),
+      }).returning('id');
+      const id = inserted[0]?.id ?? inserted[0];
+      await userManagementService.deleteAdminUser(id, actorId);
+      const log = await db('activity_logs')
+        .where({ activity_type: 'admin_user_deleted' })
+        .orderBy('id', 'desc')
+        .first();
+      expect(log).toBeDefined();
+    });
+  });
+});

backend/__tests__/utils/emailNormalization.test.js

@@ -0,0 +1,57 @@
+/**
+ * Regression coverage for the identity-preserving email normalization
+ * options (#574).
+ *
+ * express-validator's `.normalizeEmail()` applies provider-specific
+ * canonicalization by default — Gmail dot-stripping, +tag stripping,
+ * googlemail → gmail folding, etc. That breaks identity because login
+ * lookups expect the address as the user was invited with, not the
+ * canonicalized form.
+ *
+ * The tests below run validator.js's `normalizeEmail` (the same
+ * implementation express-validator delegates to) through the
+ * `IDENTITY_PRESERVING_NORMALIZE_EMAIL` options object and pin the
+ * behaviour we depend on:
+ *   - dots preserved on Gmail
+ *   - +tags preserved on Gmail / Outlook / Yahoo / iCloud
+ *   - googlemail.com domain preserved (not folded to gmail.com)
+ *   - local-part lowercased (still the default — safe and consistent)
+ */
+const validator = require('validator');
+const { IDENTITY_PRESERVING_NORMALIZE_EMAIL } = require('../../src/utils/emailNormalization');
+
+const norm = (email) => validator.normalizeEmail(email, IDENTITY_PRESERVING_NORMALIZE_EMAIL);
+
+describe('IDENTITY_PRESERVING_NORMALIZE_EMAIL', () => {
+  it('preserves dots in the Gmail local-part (the #574 root cause)', () => {
+    expect(norm('john.doe@gmail.com')).toBe('john.doe@gmail.com');
+    expect(norm('j.o.h.n@gmail.com')).toBe('j.o.h.n@gmail.com');
+  });
+
+  it('preserves Gmail +tags (subaddresses)', () => {
+    expect(norm('john.doe+invoices@gmail.com')).toBe('john.doe+invoices@gmail.com');
+  });
+
+  it('does not fold googlemail.com to gmail.com', () => {
+    expect(norm('john.doe@googlemail.com')).toBe('john.doe@googlemail.com');
+  });
+
+  it('preserves Outlook +tags', () => {
+    expect(norm('jane+work@outlook.com')).toBe('jane+work@outlook.com');
+  });
+
+  it('preserves Yahoo -tags', () => {
+    expect(norm('jane-work@yahoo.com')).toBe('jane-work@yahoo.com');
+  });
+
+  it('preserves iCloud +tags', () => {
+    expect(norm('jane+receipts@icloud.com')).toBe('jane+receipts@icloud.com');
+  });
+
+  it('lowercases the local-part (default behaviour we keep)', () => {
+    // all_lowercase defaults true in validator.js. Local-parts are
+    // case-insensitive in practice on every major provider, and
+    // lowercasing keeps login lookup consistent.
+    expect(norm('John.Doe@Gmail.com')).toBe('john.doe@gmail.com');
+  });
+});

backend/__tests__/utils/formatters.test.js

@@ -0,0 +1,66 @@
+/**
+ * Unit tests for formatters.js — focused on the HTML-escape behaviour added
+ * so admin-supplied welcome messages can't inject markup into customer mail.
+ */
+
+const { escapeHtml, nl2br, formatWelcomeMessage } = require('../../src/utils/formatters');
+
+describe('escapeHtml', () => {
+  it('escapes the five HTML metacharacters', () => {
+    expect(escapeHtml('& < > " \'')).toBe('&amp; &lt; &gt; &quot; &#39;');
+  });
+
+  it('returns empty string for null/undefined', () => {
+    expect(escapeHtml(null)).toBe('');
+    expect(escapeHtml(undefined)).toBe('');
+  });
+
+  it('coerces non-string values', () => {
+    expect(escapeHtml(42)).toBe('42');
+  });
+
+  it('escapes & before introducing new entities', () => {
+    expect(escapeHtml('<&>')).toBe('&lt;&amp;&gt;');
+  });
+});
+
+describe('nl2br', () => {
+  it('joins non-empty lines with <br />', () => {
+    expect(nl2br('a\nb\nc')).toBe('a<br />b<br />c');
+  });
+
+  it('normalises CRLF and CR', () => {
+    expect(nl2br('a\r\nb\rc')).toBe('a<br />b<br />c');
+  });
+
+  it('drops empty lines', () => {
+    expect(nl2br('a\n\n\nb')).toBe('a<br />b');
+  });
+
+  it('returns empty for empty input', () => {
+    expect(nl2br('')).toBe('');
+    expect(nl2br(null)).toBe('');
+  });
+});
+
+describe('formatWelcomeMessage', () => {
+  it('returns empty string for empty input', () => {
+    expect(formatWelcomeMessage('')).toBe('');
+    expect(formatWelcomeMessage('   ')).toBe('');
+  });
+
+  it('escapes HTML metacharacters before nl2br', () => {
+    expect(formatWelcomeMessage('Hello <b>world</b>'))
+      .toBe('Hello &lt;b&gt;world&lt;/b&gt;');
+  });
+
+  it('renders newlines as <br /> while keeping content escaped', () => {
+    expect(formatWelcomeMessage('line 1\n<script>x</script>\nline 3'))
+      .toBe('line 1<br />&lt;script&gt;x&lt;/script&gt;<br />line 3');
+  });
+
+  it('escapes ampersands and quotes that would otherwise break HTML', () => {
+    expect(formatWelcomeMessage('Tom & Jerry\'s "show"'))
+      .toBe('Tom &amp; Jerry&#39;s &quot;show&quot;');
+  });
+});

backend/__tests__/utils/iban.test.js

@@ -0,0 +1,124 @@
+/**
+ * Tests for the ISO 13616 IBAN validator.
+ *
+ * Reference IBANs sourced from the SWIFT IBAN Registry "Example" section
+ * — they are publicly published sample values used by every IBAN
+ * implementation as test vectors. NOT real account numbers.
+ */
+const { validateIban, _internal } = require('../../src/utils/iban');
+
+describe('validateIban', () => {
+  it('accepts a canonical Swiss IBAN', () => {
+    const out = validateIban('CH9300762011623852957');
+    expect(out.valid).toBe(true);
+    expect(out.normalized).toBe('CH9300762011623852957');
+    expect(out.reason).toBeUndefined();
+  });
+
+  it('accepts a Liechtenstein IBAN', () => {
+    expect(validateIban('LI21088100002324013AA').valid).toBe(true);
+  });
+
+  it('accepts a German IBAN', () => {
+    expect(validateIban('DE89370400440532013000').valid).toBe(true);
+  });
+
+  it('accepts an Austrian IBAN', () => {
+    expect(validateIban('AT611904300234573201').valid).toBe(true);
+  });
+
+  it('accepts a British IBAN with alphanumeric BBAN', () => {
+    expect(validateIban('GB82WEST12345698765432').valid).toBe(true);
+  });
+
+  it('normalises spaces and lowercase input', () => {
+    const out = validateIban(' ch93 0076 2011 6238 5295 7 ');
+    expect(out.valid).toBe(true);
+    expect(out.normalized).toBe('CH9300762011623852957');
+  });
+
+  it('normalises mixed-case input', () => {
+    const out = validateIban('ch9300762011623852957');
+    expect(out.valid).toBe(true);
+    expect(out.normalized).toBe('CH9300762011623852957');
+  });
+
+  it('rejects an empty / null / undefined value', () => {
+    expect(validateIban('').reason).toBe('EMPTY');
+    expect(validateIban('   ').reason).toBe('EMPTY');
+    expect(validateIban(null).reason).toBe('EMPTY');
+    expect(validateIban(undefined).reason).toBe('EMPTY');
+  });
+
+  it('rejects a malformed string (numbers in the country slot)', () => {
+    const out = validateIban('12930076201162385295');
+    expect(out.valid).toBe(false);
+    expect(out.reason).toBe('FORMAT');
+  });
+
+  it('rejects a too-short string', () => {
+    expect(validateIban('CH93').reason).toBe('FORMAT');
+  });
+
+  it('rejects a too-long string (over 34 chars)', () => {
+    // 35 chars: pads beyond the ISO 13616 max
+    expect(validateIban('CH9300762011623852957XXXXXXXXXXXXXX').reason).toBe('FORMAT');
+  });
+
+  it('rejects a known-country IBAN with the wrong length', () => {
+    // CH must be 21 chars; this one is 22.
+    const out = validateIban('CH9300762011623852957X');
+    expect(out.valid).toBe(false);
+    expect(out.reason).toBe('LENGTH');
+  });
+
+  it('rejects an IBAN with a broken checksum', () => {
+    // Same shape, last digit altered.
+    const out = validateIban('CH9300762011623852950');
+    expect(out.valid).toBe(false);
+    expect(out.reason).toBe('CHECKSUM');
+  });
+
+  it('rejects an IBAN with internally invalid characters', () => {
+    expect(validateIban('CH93007620!1623852957').reason).toBe('FORMAT');
+  });
+
+  it('accepts an unknown-country IBAN that meets the generic length range', () => {
+    // Made-up country code "ZZ" — not in IBAN_LENGTHS but the
+    // structural regex passes if length is in [15, 34] and the
+    // checksum holds. Build a checksum-valid string:
+    //
+    //   Format: ZZ + check + BBAN. We don't have a real ZZ template
+    //   so this test just confirms unknown country codes route
+    //   through the fallback length check rather than failing on
+    //   LENGTH outright. A checksum-failing ZZ value will hit
+    //   CHECKSUM, not LENGTH, which is the assertion below.
+    const out = validateIban('ZZ00ABCDEFGHIJKLMNOP');
+    expect(out.valid).toBe(false);
+    expect(out.reason).toBe('CHECKSUM'); // not LENGTH
+  });
+});
+
+describe('mod97', () => {
+  it('returns 1 for the canonical CH test vector', () => {
+    expect(_internal.mod97('CH9300762011623852957')).toBe(1);
+  });
+
+  it('returns something other than 1 for a tampered IBAN', () => {
+    expect(_internal.mod97('CH9300762011623852950')).not.toBe(1);
+  });
+});
+
+describe('IBAN_LENGTHS table', () => {
+  it('has the expected lengths for the most common European countries', () => {
+    // Sanity check that the table didn't drift if someone edits it.
+    expect(_internal.IBAN_LENGTHS.CH).toBe(21);
+    expect(_internal.IBAN_LENGTHS.DE).toBe(22);
+    expect(_internal.IBAN_LENGTHS.AT).toBe(20);
+    expect(_internal.IBAN_LENGTHS.LI).toBe(21);
+    expect(_internal.IBAN_LENGTHS.FR).toBe(27);
+    expect(_internal.IBAN_LENGTHS.IT).toBe(27);
+    expect(_internal.IBAN_LENGTHS.GB).toBe(22);
+    expect(_internal.IBAN_LENGTHS.NL).toBe(18);
+  });
+});

backend/__tests__/utils/pdfFilename.test.js

@@ -0,0 +1,121 @@
+/**
+ * Pure-function tests for the PDF filename builder used on every
+ * quote / invoice download endpoint + the PDF's internal Title
+ * metadata. No mocks needed — all behavior is deterministic.
+ */
+const { buildPdfFilename, sanitiseSegment, customerLabel } = require('../../src/utils/pdfFilename');
+
+describe('sanitiseSegment', () => {
+  it('returns empty string for null/undefined', () => {
+    expect(sanitiseSegment(null)).toBe('');
+    expect(sanitiseSegment(undefined)).toBe('');
+    expect(sanitiseSegment('')).toBe('');
+  });
+
+  it('replaces filesystem-hostile characters with "-"', () => {
+    expect(sanitiseSegment('a/b\\c:d*e?f"g<h>i|j')).toBe('a-b-c-d-e-f-g-h-i-j');
+  });
+
+  it('collapses spaces into single "-"', () => {
+    expect(sanitiseSegment('ACME   GmbH   AG')).toBe('ACME-GmbH-AG');
+  });
+
+  it('collapses repeat dashes', () => {
+    expect(sanitiseSegment('a-----b')).toBe('a-b');
+  });
+
+  it('trims leading + trailing dashes/dots', () => {
+    expect(sanitiseSegment('--..--Hello..--..')).toBe('Hello');
+  });
+
+  it('preserves non-ASCII letters', () => {
+    expect(sanitiseSegment('Müller & Söhne')).toBe('Müller-&-Söhne');
+  });
+
+  it('caps length at 80 chars by default', () => {
+    const long = 'a'.repeat(120);
+    expect(sanitiseSegment(long)).toHaveLength(80);
+  });
+
+  it('honors custom maxLen', () => {
+    expect(sanitiseSegment('abcdefghij', 5)).toBe('abcde');
+  });
+});
+
+describe('customerLabel', () => {
+  it('prefers company_name over person name', () => {
+    expect(customerLabel({
+      company_name: 'ACME GmbH',
+      first_name: 'Luca', last_name: 'Bresch',
+    })).toBe('ACME-GmbH');
+  });
+
+  it('falls back to first + last when company_name is empty', () => {
+    expect(customerLabel({
+      company_name: '',
+      first_name: 'Luca', last_name: 'Bresch',
+    })).toBe('Luca-Bresch');
+  });
+
+  it('falls back to display_name when no company + no person', () => {
+    expect(customerLabel({
+      display_name: 'Luca B.',
+    })).toBe('Luca-B');
+  });
+
+  it('falls back to email local-part as a last resort', () => {
+    expect(customerLabel({
+      email: 'luca@bresch.cc',
+    })).toBe('luca');
+  });
+
+  it('uses "customer" when everything is missing', () => {
+    expect(customerLabel({})).toBe('customer');
+    expect(customerLabel(null)).toBe('customer');
+  });
+
+  it('trims whitespace before evaluating truthiness', () => {
+    // company_name = "   " should NOT trigger the company branch.
+    expect(customerLabel({
+      company_name: '   ',
+      first_name: 'Luca', last_name: 'Bresch',
+    })).toBe('Luca-Bresch');
+  });
+});
+
+describe('buildPdfFilename', () => {
+  const customer = { company_name: 'ACME GmbH' };
+
+  it('builds "<docNumber>_<customer>.pdf" for a regular invoice', () => {
+    expect(buildPdfFilename({
+      docNumber: 'R-2026-0001',
+      customer,
+    })).toBe('R-2026-0001_ACME-GmbH.pdf');
+  });
+
+  it('falls back to the fallback when docNumber is null (preview)', () => {
+    expect(buildPdfFilename({
+      docNumber: null,
+      customer,
+      fallback: 'invoice-preview',
+    })).toBe('invoice-preview_ACME-GmbH.pdf');
+  });
+
+  it('uses "document" when both docNumber + fallback are absent', () => {
+    expect(buildPdfFilename({ customer })).toBe('document_ACME-GmbH.pdf');
+  });
+
+  it('sanitises the customer half too', () => {
+    expect(buildPdfFilename({
+      docNumber: 'R-2026-0001',
+      customer: { company_name: 'Bad/Name:Inc.' },
+    })).toBe('R-2026-0001_Bad-Name-Inc.pdf');
+  });
+
+  it('always ends with .pdf', () => {
+    expect(buildPdfFilename({
+      docNumber: 'R-2026-0001',
+      customer: {},
+    })).toMatch(/\.pdf$/);
+  });
+});

backend/__tests__/utils/resolveLogoFile.test.js

@@ -0,0 +1,108 @@
+/**
+ * resolveLogoFile — verifies the path-priority chain + the
+ * unsupported-format guard. fs + appSettings + storage config are
+ * mocked so the test is fully deterministic.
+ */
+
+jest.mock('../../src/utils/appSettings', () => ({
+  getAppSetting: jest.fn(),
+}));
+jest.mock('../../src/config/storage', () => ({
+  getStoragePath: jest.fn(() => '/app/storage'),
+}));
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+}));
+
+const fs = require('fs');
+const { resolveLogoFile } = require('../../src/utils/resolveLogoFile');
+const { getAppSetting } = require('../../src/utils/appSettings');
+
+describe('resolveLogoFile', () => {
+  let existsSpy, statSpy;
+
+  beforeEach(() => {
+    existsSpy = jest.spyOn(fs, 'existsSync');
+    statSpy = jest.spyOn(fs, 'statSync');
+    existsSpy.mockReturnValue(false);
+    statSpy.mockImplementation(() => ({ isFile: () => true }));
+    getAppSetting.mockReset();
+  });
+
+  afterEach(() => {
+    existsSpy.mockRestore();
+    statSpy.mockRestore();
+  });
+
+  it('returns null when no sources are configured', async () => {
+    getAppSetting.mockResolvedValue(null);
+    const out = await resolveLogoFile({});
+    expect(out).toBeNull();
+  });
+
+  it('prefers business_profile.logo_path over branding fallbacks', async () => {
+    // The profile path exists, branding doesn't.
+    existsSpy.mockImplementation((p) => p === '/app/storage/uploads/logos/profile.png');
+    getAppSetting.mockResolvedValue('/uploads/logos/branding.png');
+    const out = await resolveLogoFile({
+      logo_path: 'uploads/logos/profile.png',
+    });
+    expect(out).toBe('/app/storage/uploads/logos/profile.png');
+  });
+
+  it('falls back to branding_logo_path when profile is empty', async () => {
+    existsSpy.mockImplementation((p) => p === '/app/storage/uploads/logos/branding.png');
+    getAppSetting.mockImplementation(async (key) => {
+      if (key === 'branding_logo_path') return '/app/storage/uploads/logos/branding.png';
+      return null;
+    });
+    const out = await resolveLogoFile({ logo_path: '' });
+    expect(out).toBe('/app/storage/uploads/logos/branding.png');
+  });
+
+  it('falls back to branding_logo_url when branding_logo_path is absent', async () => {
+    existsSpy.mockImplementation((p) => p === '/app/storage/uploads/logos/branding.png');
+    getAppSetting.mockImplementation(async (key) => {
+      if (key === 'branding_logo_url') return '/uploads/logos/branding.png';
+      return null;
+    });
+    const out = await resolveLogoFile({});
+    expect(out).toBe('/app/storage/uploads/logos/branding.png');
+  });
+
+  it('skips SVG (PDFKit cannot embed)', async () => {
+    existsSpy.mockImplementation((p) => p === '/app/storage/uploads/logos/logo.svg');
+    getAppSetting.mockResolvedValue(null);
+    const out = await resolveLogoFile({ logo_path: 'uploads/logos/logo.svg' });
+    expect(out).toBeNull();
+  });
+
+  it('also rejects WebP / GIF / TIFF', async () => {
+    for (const ext of ['webp', 'gif', 'tif', 'tiff']) {
+      existsSpy.mockReturnValue(true);
+      statSpy.mockImplementation(() => ({ isFile: () => true }));
+      existsSpy.mockImplementation((p) => p === `/app/storage/uploads/logos/logo.${ext}`);
+      getAppSetting.mockResolvedValue(null);
+      const out = await resolveLogoFile({ logo_path: `uploads/logos/logo.${ext}` });
+      expect(out).toBeNull();
+    }
+  });
+
+  it('accepts PNG and JPEG', async () => {
+    for (const ext of ['png', 'jpg', 'jpeg', 'PNG', 'JPG']) {
+      existsSpy.mockImplementation((p) => p === `/app/storage/uploads/logos/logo.${ext}`);
+      getAppSetting.mockResolvedValue(null);
+      const out = await resolveLogoFile({ logo_path: `uploads/logos/logo.${ext}` });
+      expect(out).toBe(`/app/storage/uploads/logos/logo.${ext}`);
+    }
+  });
+
+  it('treats absolute paths as-is when they exist', async () => {
+    existsSpy.mockImplementation((p) => p === '/abs/path/logo.png');
+    getAppSetting.mockResolvedValue(null);
+    const out = await resolveLogoFile({ logo_path: '/abs/path/logo.png' });
+    expect(out).toBe('/abs/path/logo.png');
+  });
+});

backend/assets/fonts/Comic-Neue/meta.json

@@ -0,0 +1,3 @@
+{
+  "generic": "cursive"
+}