Merge branch 'main' into dev/ChangeBrowserLabelToMatchWorktree

Portal policies: SUI setup forms fixes and improvements (#6927 )
## What this does Reworks the portal's policy setup screens so a policy reads as **its own settings** rather than a list of tools you wire together, and rebuilds the forms on the shared design system so they match the rest of the portal. ## Why Setup showed one card per underlying tool (tool name + a toggle), which exposed the "a policy is a pipeline of tools" plumbing. A policy should read in terms of what it does to a document, not which tools run under the hood. ## Changes - **Setup reads as policy settings.** The per-tool cards are now a plain-language list of what the policy does — "Redact sensitive information", "Strip active content", "Apply a watermark", and so on — each with a short description and a toggle, with its options appearing inline when turned on. - **Consistent design system.** The setup and edit forms use the shared components instead of one-off styling. - **Simpler setup.** Removed two sections that aren't part of what ships here: Document Types (scope-by-type) and Retries. - **Watermarks are text-only.** A policy watermark is a text stamp, so the image option and the type picker are hidden. - **The editor always shows as a source** (it used to disappear when no other sources were connected), and the source tiles now lay out correctly. - **Clearer upsell copy.** Locked policies read **"Upgrade to Enterprise"** instead of "Coming soon". ## Scope UI only — no backend changes. Keeping a policy's settings in sync between the portal and the editor is a known, separate issue and is **not** part of this PR. ## Testing Prettier, ESLint, typecheck (proprietary + saas), and the unused-translation guard all pass. Setup screens verified in Storybook.
2026-07-09 21:03:23 +01:00 · 2026-07-09 19:13:10 +00:00 · 2026-07-09 16:35:30 +00:00 · 2026-07-09 15:43:38 +00:00 · 2026-07-09 14:50:50 +00:00 · 2026-07-09 14:47:37 +00:00
3008 changed files with 196970 additions and 74195 deletions
@@ -0,0 +1,97 @@
+---
+name: feature-walkthrough
+description: >-
+  Explain the full logic and process of the current branch end-to-end so someone
+  with no prior knowledge of the task can understand, review, and reproduce it.
+  Scopes the change from the branch diff, traces the flow across every layer it
+  touches (frontend tool/hook/component, Java controller/service/endpoint, Python
+  engine, config, i18n, tests), and produces a self-contained walkthrough document
+  with Mermaid diagrams (sequence/flow/architecture), annotated file map with
+  clickable references, before/after behavior, screenshots where a UI is involved,
+  a "try it locally" section, and edge cases/risks. Use when asked for a feature or
+  branch walkthrough, "explain what this branch does", a design/logic writeup, PR
+  reviewer onboarding, or a hand-off doc. Pass --html to also emit a rendered HTML
+  version; --no-screens to skip screenshots.
+argument-hint: "[branch-or-area] [--html] [--no-screens]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Feature / Branch Walkthrough
+
+Turn the current branch into a walkthrough a newcomer can follow. Audience:
+**someone who has never seen this task**. Explain the *why*, the *flow*, and *how to
+try it* - not just a diff summary.
+
+`$ARGUMENTS` may name a branch or area to focus on; default is the current branch
+vs `main`. Flags: `--html` (also emit a rendered HTML twin), `--no-screens`.
+
+## Process
+
+### 1. Scope the change
+- `git log --oneline main..HEAD` and `git diff --stat main...HEAD` for the shape.
+- Read the PR description / commit messages for stated intent. Do **not** invent
+  history or motivation that isn't evidenced (state current behavior in present tense).
+- Classify touched files by layer:
+  - **Frontend**: tools (`frontend/editor/src/core/components/tools/*` or `.../core/tools/*`),
+    hooks (`core/hooks/tools/*`, `useToolOperation`), contexts, routes, i18n
+    (`public/locales/en-US`).
+  - **Java backend**: controllers (`.../controller/api/...`), services, models, config.
+  - **Engine**: `engine/src/stirling/{agents,contracts,api,services}`.
+  - **Config / build / docker / tests.**
+
+### 2. Trace the flow end-to-end
+Follow one real path from user action to result. For a typical PDF tool that's:
+UI control → `useToolOperation` hook → `POST /api/v1/...` → Spring controller →
+service (PDFBox / LibreOffice / engine call) → response → review panel → download.
+Read the actual files so the narrative is true to the code, and collect the exact
+file:line anchors you'll cite.
+
+### 3. Draw the diagrams (Mermaid)
+Pick what fits; usually 2-3 of:
+- **Sequence diagram** - request/response across frontend → backend → engine.
+- **Flowchart** - the core decision/branching logic of the feature.
+- **Architecture/component** - new pieces and how they wire to existing ones.
+- **State** - if the feature has modes/steps.
+Keep nodes labeled in plain language. Validate the Mermaid parses before shipping.
+
+### 4. Screenshots (unless --no-screens)
+If a UI is involved, capture key states with the stubbed Playwright harness
+(see the **ui-walkthrough** skill and `files-page-screenshots.spec.ts` for the
+pattern) or, for before/after, capture `main` then the branch. Drop PNGs in
+`walkthrough/<feature>/` and reference them from the doc. For backend-only
+changes, show request/response examples (curl + JSON) instead.
+
+### 5. Write the walkthrough
+Create `walkthrough/<feature>/FEATURE-WALKTHROUGH.md` with:
+1. **TL;DR** - what the branch does and who it's for, in 3-4 sentences.
+2. **Problem & approach** - what wasn't possible before; the chosen solution.
+3. **Architecture diagram** + 1-paragraph orientation.
+4. **End-to-end flow** - the sequence diagram + a numbered walk of each step,
+   each citing the real file (clickable `path:line`).
+5. **Key files** - annotated map (path → one line on its role).
+6. **Logic deep-dive** - the flowchart + prose for the non-obvious decisions.
+7. **Behavior** - before vs after; screenshots or request/response examples.
+8. **Try it locally** - exact steps (`task dev` / `task dev:all`, the route to
+   open or the curl to run, any env like `DOCKER_ENABLE_SECURITY` or a test
+   license key). Make it copy-pasteable.
+9. **Edge cases, risks, follow-ups** - what's untested, known limits, gotchas.
+
+Markdown is the primary deliverable - it renders with diagrams in GitHub PRs and
+IDEs, no build step, ideal for review.
+
+### 6. If `--html`
+Also emit `walkthrough/<feature>/walkthrough.html`: the same content with Mermaid
+rendered via `mermaid.initialize({startOnLoad:true})` (script from CDN; note in
+the file that rendering diagrams needs network, the `.md` is the offline copy) and
+screenshots inline. Keep it self-contained otherwise.
+
+### 7. Deliver
+Give the doc path and a short chat summary. Offer to `SendUserFile` it.
+
+## Principles
+- **True to the code.** Every claim traces to a file you read; cite `path:line`.
+  No fabricated migration/version history.
+- **Newcomer-first.** Define repo-specific terms (FileContext, `useToolOperation`,
+  the `@app/*` layer cascade, stubbed vs live tests) on first use.
+- **Show, don't assert.** Prefer a diagram + a real example over adjectives.
+- Don't commit the `walkthrough/` output unless asked.
@@ -0,0 +1,122 @@
+---
+name: ui-before-after
+description: >-
+  Analyse a branch or PR and automatically capture before/after screenshots of
+  every UI surface its changes touch, then pixel-diff the pairs to surface what
+  actually changed and assemble PR-ready before/after montage images. Generic and
+  diff-driven: it derives the capture targets from the diff (changed tools/routes →
+  URLs) instead of hand-listing screens, captures "before" from the base branch and
+  "after" from the head, then keeps only the views that visually differ. Each
+  comparison is auto-cropped to the region that actually changed (the bounding box of
+  differing pixels), falling back to the full page only when the change spans most of
+  it. Use for before/after shots, a visual diff of a branch/PR, "screenshots for the
+  PR description", "show what changed in the UI", or a side-by-side of UI changes.
+  Takes a PR number/URL (resolved via gh) or a branch; defaults to the current branch
+  vs its base. Flags: --scope <selector>, --base <ref|merge-base>, --theme
+  light|dark|both, --all (capture every route, not just changed), --no-autocrop,
+  --pagewide <n>, --threshold <n>.
+argument-hint: "[PR# | PR-url | branch] [--scope <sel>] [--base <ref>] [--theme both] [--all] [--no-autocrop]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# UI Before / After (generic visual diff)
+
+Point it at a branch or PR; it figures out which UI changed, screenshots every
+affected surface **before** (base) and **after** (head), pixel-diffs the pairs, and
+montages the ones that actually changed into images for the PR description.
+
+`$ARGUMENTS`: a PR number/URL, a branch, or nothing (current branch vs base).
+By default it captures the full viewport and auto-crops each comparison to the region
+that changed. Flags: `--scope <css>` (narrow the *capture* to a container, e.g.
+`[data-sidebar="tool-panel"]`, when you already know where the change is),
+`--no-autocrop` (keep full frames), `--pagewide <fraction>` (above this share of the
+page, skip cropping; default 0.6), `--base <ref|merge-base>`,
+`--theme light|dark|both`, `--all` (walk every route, not just changed),
+`--threshold <fraction>` (diff sensitivity, default 0.001).
+
+Shares the capture harness with **ui-walkthrough** - read its SKILL.md for the
+stubbed-Playwright setup, worktree node_modules + `generate-icons`, the
+stale-`:5173` gotcha, and the dark-mode init-script. Bundled helpers:
+[capture-spec.template.ts](capture-spec.template.ts), [diff-shots.mjs](diff-shots.mjs),
+[montage-template.html](montage-template.html), [shoot-sections.mjs](shoot-sections.mjs).
+
+## Process
+
+### 1. Resolve target + base
+```
+gh pr view <pr> --json number,title,headRefName,baseRefName,url,files   # PR
+# or branch: base = merge-base(main, HEAD); head = HEAD
+gh pr diff <pr> --name-only        # or: git diff --name-only <base>...HEAD
+```
+
+### 2. Derive capture targets from the diff (the "analyse" step - no hand-listing)
+Map changed frontend files to URLs generically:
+- **Tools**: a changed `components/tools/<toolDir>/…` or `hooks/tools/<tool>/…` →
+  toolId → URL via the repo's own rule `getToolUrlPath` in
+  [toolsTaxonomy.ts:200](frontend/editor/src/core/data/toolsTaxonomy.ts): `/` + the
+  id kebab-cased (`addPageNumbers` → `/add-page-numbers`).
+- **Pages/routes**: changed `filesPage/*` → `/files`, etc.
+- `--all`: enumerate every tool in the registry instead of just changed ones.
+Write `frontend/editor/screenshots/ui-diff/targets.json` =
+`[{ "id":"compress", "url":"/compress", "name":"Compress" }]`. This is what makes
+it generic - the spec never names a tool.
+
+### 3. Capture AFTER (head) then BEFORE (base)
+Copy [capture-spec.template.ts](capture-spec.template.ts) →
+`src/core/tests/stubbed/ui-before-after.spec.ts` (it loops `targets.json`, seeds a
+sample PDF so file-dependent panels render, navigates to each URL, and screenshots
+the full viewport - or the `--scope` container if given). Ensure the harness is ready
+(node_modules + icons).
+```
+# after = current head
+cd frontend/editor && PR_SHOT_SIDE=after PR_SHOT_THEME=light \
+  npx playwright test --project=stubbed ui-before-after.spec.ts
+# before = base, in an isolated worktree (copy the spec + targets.json in)
+git worktree add ../ba-base origin/<baseRefName>        # or the merge-base
+#   set up its frontend, copy spec + screenshots/ui-diff/targets.json across, then:
+cd ../ba-base/frontend/editor && PR_SHOT_SIDE=before PR_SHOT_THEME=light \
+  npx playwright test --project=stubbed ui-before-after.spec.ts
+#   copy its screenshots/ui-diff/before/ back next to after/. Repeat with
+#   PR_SHOT_THEME=dark if --theme includes dark. Remove worktree when done.
+```
+
+### 4. Auto-diff (surface what changed)
+```
+cd frontend/editor && node <skill>/diff-shots.mjs \
+  screenshots/ui-diff/before screenshots/ui-diff/after screenshots/ui-diff
+```
+Produces `diff-report.json` classifying each view `unchanged | changed | added |
+removed`. For each changed view it computes the bounding box of differing pixels and
+writes cropped `__before_crop.png` / `__after_crop.png` / `__diff.png` to that region
+(+ padding) - **unless** the change covers more than `--pagewide` of the frame, where
+it keeps the full frame (`pageWide:true`). Drop `unchanged` - that's the noise the
+user doesn't want.
+
+### 5. Montage the changes
+Build the manifest from the non-unchanged entries (group by tab/tool; each becomes a
+state row with before/after). For changed views use the cropped `cropBefore` /
+`cropAfter` from `diff-report.json` (tight on the affected region; full frame when
+`pageWide`); `added`/`removed` render the "not present" placeholder. Fill
+[montage-template.html](montage-template.html) (replace the `window.__BA__` data
+block; base64-inline the PNGs for portability), then render one PNG per section with
+[shoot-sections.mjs](shoot-sections.mjs). Optionally include the `__diff.png` overlay
+as a third column.
+
+### 6. Deliver
+Output the `montage_<tab>.png` files + a short summary (N changed / added / removed,
+M unchanged skipped) and a paste-ready Markdown block. GitHub has no PR-body image
+API, so tell the user to drag the PNGs into the description. Do **not** post to the
+PR.
+
+## Gotchas
+- Two installs (base worktree + head); junction main's node_modules only if its deps
+  match that ref, else `npm ci` (see ui-walkthrough's stale-dep note).
+- A view that errors on one side (refactored/removed) → that side is missing; the
+  diff marks it added/removed rather than failing the run.
+- Pixel diff needs equal dimensions, so capture at a fixed viewport (the template
+  does); a view whose size changed is reported as "changed (dimensions differ)",
+  uncropped.
+- Auto-crop uses a single bounding box, so two far-apart changes give one large crop
+  (or trip `--pagewide`); narrow with `--scope` if that happens.
+- `getToolUrlPath` is the source of truth for tool URLs - use it, don't guess slugs.
+- Don't commit `screenshots/`, the throwaway spec, or the base worktree.
@@ -0,0 +1,67 @@
+// Generic before/after capturer. NOT app-specific: it walks a targets.json that
+// the ui-before-after skill generates from the branch/PR diff, so nothing here is
+// hand-listed. Copy to src/core/tests/stubbed/ui-before-after.spec.ts, then run
+// once per (side, theme):
+//   PR_SHOT_SIDE=after  PR_SHOT_THEME=light \
+//     npx playwright test --project=stubbed ui-before-after.spec.ts
+//
+// targets.json shape: [{ "id":"compress", "url":"/compress", "name":"Compress",
+//                        "needsFile": true }]
+import { test } from "@app/tests/helpers/stub-test-base";
+import type { Page } from "@playwright/test";
+import fs from "node:fs";
+import path from "node:path";
+
+const SIDE = process.env.PR_SHOT_SIDE ?? "after";
+const THEME = process.env.PR_SHOT_THEME ?? "light";
+// Capture the full viewport by default so the affected region is in frame
+// wherever it is; diff-shots.mjs crops each comparison to what actually changed.
+// Set PR_SHOT_SCOPE to a selector to narrow the capture to one container.
+const SCOPE = process.env.PR_SHOT_SCOPE ?? "";
+const ROOT = path.resolve(process.cwd(), "screenshots", "ui-diff");
+const OUT = path.join(ROOT, SIDE);
+// A tiny sample PDF so file-dependent tool panels render. Point at a real fixture.
+const SAMPLE_PDF = process.env.PR_SHOT_SAMPLE ?? "src/core/tests/test-fixtures/sample.pdf";
+
+type Target = { id: string; url: string; name?: string; needsFile?: boolean };
+const targets: Target[] = JSON.parse(fs.readFileSync(path.join(ROOT, "targets.json"), "utf-8"));
+
+test.use({ autoGoto: false, viewport: { width: 1600, height: 900 }, seedJwt: true });
+
+async function applyTheme(page: Page): Promise<void> {
+  if (THEME !== "dark") return;
+  await page.addInitScript(() => {
+    localStorage.setItem("mantine-color-scheme", "dark");
+    localStorage.setItem("mantine-color-scheme-value", "dark");
+  });
+  await page.emulateMedia({ colorScheme: "dark" });
+}
+
+async function seedFile(page: Page): Promise<void> {
+  if (!fs.existsSync(SAMPLE_PDF)) return;
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.getByTestId("files-button").click().catch(() => {});
+  await page.locator('[data-testid="file-input"]').setInputFiles(SAMPLE_PDF).catch(() => {});
+  await page.locator(".file-sidebar-file-item").first().isVisible({ timeout: 8_000 }).catch(() => {});
+}
+
+for (const t of targets) {
+  // One test per target so a single failure doesn't drop the rest.
+  test(`${SIDE}/${THEME} ${t.id}`, async ({ page }) => {
+    fs.mkdirSync(OUT, { recursive: true });
+    await applyTheme(page);
+    if (t.needsFile !== false) await seedFile(page);
+    await page.goto(t.url, { waitUntil: "domcontentloaded" });
+    await page.waitForTimeout(400); // settle Mantine portals/transitions
+    const shot = path.join(OUT, `${t.id}__${THEME}.png`);
+    if (SCOPE) {
+      const scope = page.locator(SCOPE).first();
+      if (await scope.isVisible({ timeout: 8_000 }).catch(() => false)) {
+        await scope.screenshot({ path: shot });
+        return;
+      }
+    }
+    // Full viewport (fixed size → stable dimensions for pixel diffing).
+    await page.screenshot({ path: shot });
+  });
+}
@@ -0,0 +1,106 @@
+// Auto-diff before/ vs after/ screenshots, classify each as
+// unchanged | changed | added | removed, and CROP each changed pair to the
+// affected region (bounding box of differing pixels + padding) - unless the
+// change spans most of the page, in which case the full frame is kept.
+// Run from frontend/editor (so deps resolve):
+//   node <skill>/diff-shots.mjs <beforeDir> <afterDir> [outDir]
+// Env:
+//   DIFF_THRESHOLD  min fraction of differing pixels to count as changed (default 0.001)
+//   DIFF_PAD        padding px around the affected region (default 24)
+//   DIFF_PAGEWIDE   if affected bbox area / image area exceeds this, keep full frame (default 0.6)
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(path.join(process.cwd(), "noop.js"));
+const pm = require("pixelmatch");
+const pixelmatch = pm.default || pm;
+const { PNG } = require("pngjs");
+
+const beforeDir = path.resolve(process.argv[2]);
+const afterDir = path.resolve(process.argv[3]);
+const outDir = path.resolve(process.argv[4] || afterDir);
+const THRESHOLD = Number(process.env.DIFF_THRESHOLD ?? "0.001");
+const PAD = Number(process.env.DIFF_PAD ?? "24");
+const PAGEWIDE = Number(process.env.DIFF_PAGEWIDE ?? "0.6");
+
+const read = (p) => PNG.sync.read(fs.readFileSync(p));
+const isShot = (f) => f.endsWith(".png") && !/__(diff|before_crop|after_crop)\.png$/.test(f);
+const list = (d) => (fs.existsSync(d) ? fs.readdirSync(d).filter(isShot) : []);
+const names = [...new Set([...list(beforeDir), ...list(afterDir)])].sort();
+fs.mkdirSync(outDir, { recursive: true });
+
+function cropPNG(src, x, y, w, h) {
+  const out = new PNG({ width: w, height: h });
+  PNG.bitblt(src, out, x, y, w, h, 0, 0);
+  return out;
+}
+const writePNG = (p, png) => fs.writeFileSync(p, PNG.sync.write(png));
+
+// Bounding box of differing pixels using a diff mask (alpha>0 where changed).
+function changedBBox(before, after, w, h) {
+  const mask = new PNG({ width: w, height: h });
+  pixelmatch(before.data, after.data, mask.data, w, h, { threshold: 0.1, diffMask: true });
+  let minX = w, minY = h, maxX = -1, maxY = -1, count = 0;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (mask.data[(y * w + x) * 4 + 3] > 0) {
+        count++;
+        if (x < minX) minX = x; if (x > maxX) maxX = x;
+        if (y < minY) minY = y; if (y > maxY) maxY = y;
+      }
+    }
+  }
+  return maxX < 0 ? null : { minX, minY, maxX, maxY, count };
+}
+
+const report = [];
+for (const name of names) {
+  const id = name.replace(/\.png$/, "");
+  const bp = path.join(beforeDir, name), ap = path.join(afterDir, name);
+  const hasB = fs.existsSync(bp), hasA = fs.existsSync(ap);
+  if (hasB && !hasA) { report.push({ id, status: "removed", before: bp }); continue; }
+  if (!hasB && hasA) { report.push({ id, status: "added", after: ap }); continue; }
+
+  const before = read(bp), after = read(ap);
+  if (before.width !== after.width || before.height !== after.height) {
+    report.push({ id, status: "changed", note: "dimensions differ", before: bp, after: ap });
+    continue;
+  }
+  const w = after.width, h = after.height;
+  const overlay = new PNG({ width: w, height: h });
+  const px = pixelmatch(before.data, after.data, overlay.data, w, h, { threshold: 0.1 });
+  const ratio = px / (w * h);
+  if (ratio <= THRESHOLD) { report.push({ id, status: "unchanged", ratio: Number(ratio.toFixed(5)), before: bp, after: ap }); continue; }
+
+  const box = changedBBox(before, after, w, h);
+  // Pad + clamp the affected region.
+  const x = Math.max(0, box.minX - PAD), y = Math.max(0, box.minY - PAD);
+  const x2 = Math.min(w, box.maxX + 1 + PAD), y2 = Math.min(h, box.maxY + 1 + PAD);
+  const bw = x2 - x, bh = y2 - y;
+  const pageWide = (bw * bh) / (w * h) > PAGEWIDE;
+
+  const entry = { id, status: "changed", ratio: Number(ratio.toFixed(5)), before: bp, after: ap, pageWide };
+  if (pageWide) {
+    // Change spans most of the page - keep the full frame, full overlay.
+    const dp = path.join(outDir, `${id}__diff.png`); writePNG(dp, overlay);
+    entry.diff = dp;
+  } else {
+    entry.bbox = { x, y, w: bw, h: bh };
+    const cb = path.join(outDir, `${id}__before_crop.png`); writePNG(cb, cropPNG(before, x, y, bw, bh));
+    const ca = path.join(outDir, `${id}__after_crop.png`); writePNG(ca, cropPNG(after, x, y, bw, bh));
+    const dp = path.join(outDir, `${id}__diff.png`); writePNG(dp, cropPNG(overlay, x, y, bw, bh));
+    entry.cropBefore = cb; entry.cropAfter = ca; entry.diff = dp;
+  }
+  report.push(entry);
+}
+
+fs.writeFileSync(path.join(outDir, "diff-report.json"), JSON.stringify(report, null, 2));
+const changed = report.filter((r) => r.status !== "unchanged");
+console.log(`diffed ${report.length} view(s): ${changed.length} changed/added/removed, ${report.length - changed.length} unchanged`);
+for (const r of changed) {
+  const tail = r.status !== "changed" ? ""
+    : r.pageWide ? " (page-wide → full frame)"
+    : ` (${(r.ratio * 100).toFixed(2)}%, cropped to ${r.bbox.w}×${r.bbox.h})`;
+  console.log(`  ${r.status.padEnd(9)} ${r.id}${tail}${r.note ? " - " + r.note : ""}`);
+}
@@ -0,0 +1,48 @@
+"""Build EXAMPLE.html from montage-template.html using REAL files-page shots as
+stand-in before/after pairs (layout demo, not an actual PR diff). Inlines PNGs as
+data URIs so the HTML is portable. Run: python make_example.py"""
+import base64
+import json
+import pathlib
+import re
+
+HERE = pathlib.Path(__file__).parent
+SHOTS = pathlib.Path(
+    r"C:\Users\systo\git\Stirling-PDFNew\.claude\worktrees\kind-faraday-522a30"
+    r"\frontend\editor\screenshots\files-page"
+)
+
+
+def uri(fname):
+    p = SHOTS / fname
+    return "data:image/png;base64," + base64.b64encode(p.read_bytes()).decode() if p.exists() else None
+
+
+data = {
+    "pr": "DEMO",
+    "title": "EXAMPLE — before/after montage (layout demo, real Files-page shots; not a real PR diff)",
+    "base": "main", "head": "demo-branch",
+    "cropSelector": "[data-sidebar=\"tool-panel\"]  (real runs crop to the side; these demo shots are full-page)",
+    "tabs": [
+        {"id": "files", "title": "Files page", "ctx": "Each row = one flow state; left = base branch, right = this PR.",
+         "states": [
+             {"name": "Empty folder", "before": uri("01_empty_state_ctas.png"), "after": uri("02_empty_state_storage_off.png")},
+             {"name": "Files + details panel", "before": uri("03_subtoolbar_with_files.png"), "after": uri("06_details_panel_save_to_server.png")},
+             {"name": "Delete folder confirm", "before": None, "after": uri("19_delete_folder_dialog.png"), "note": "New in this PR"},
+         ]},
+        {"id": "move", "title": "Move-to-folder dialog",
+         "states": [
+             {"name": "Dialog opened", "before": uri("07_move_dialog_collapsed.png"), "after": uri("08_move_dialog_create_folder_expanded.png")},
+             {"name": "After folder created", "before": None, "after": uri("08b_move_dialog_after_create_folder.png"), "note": "New flow"},
+         ]},
+    ],
+}
+
+tpl = (HERE / "montage-template.html").read_text(encoding="utf-8")
+out = re.sub(
+    r"/\*__DATA__\*/.*?/\*__END__\*/",
+    lambda _m: "/*__DATA__*/" + json.dumps(data) + "/*__END__*/",
+    tpl, count=1, flags=re.S,
+)
+(HERE / "EXAMPLE.html").write_text(out, encoding="utf-8")
+print("wrote", HERE / "EXAMPLE.html", "(", (HERE / "EXAMPLE.html").stat().st_size // 1024, "KB )")
@@ -0,0 +1,106 @@
+<!doctype html>
+<!--
+  Before/After montage for a PR description. The ui-before-after skill replaces
+  the JSON in the window.__BA__ data block below with the captured manifest, then
+  screenshots each .tab-section (id="section-<tabId>") into a PNG to drag into the
+  PR description. Self-contained; images may be relative paths or data URIs.
+
+  Data shape:
+  {
+    "pr":"6552","title":"...","base":"main","head":"feat/x",
+    "cropSelector":"[data-sidebar=\"tool-panel\"]",
+    "tabs":[
+      { "id":"sign","title":"Sign tool","states":[
+        {"name":"Initial","before":"before/sign__initial.png","after":"after/sign__initial.png"},
+        {"name":"Cert selected","before":null,"after":"after/sign__cert.png","note":"New in this PR"}
+      ]}
+    ]
+  }
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Before / After</title>
+<style>
+  :root { --bg:#ffffff; --ink:#0b0c0e; --muted:#6b7280; --line:#e5e7eb;
+          --before:#6b7280; --after:#1f883d; --frame:#f3f4f6; --note:#b45309; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--ink);
+         font:14px/1.5 -apple-system,"Segoe UI",Roboto,system-ui,sans-serif; }
+  .wrap { max-width:1100px; margin:0 auto; padding:24px; }
+  .doc-head { margin-bottom:8px; }
+  .doc-head h1 { font-size:18px; margin:0 0 2px; }
+  .doc-head .sub { color:var(--muted); font-size:12.5px; }
+  .legend { display:flex; gap:14px; align-items:center; margin:10px 0 4px; font-size:12px; color:var(--muted); }
+  .chip { font-size:10px; font-weight:700; letter-spacing:.04em; text-transform:uppercase;
+          padding:2px 8px; border-radius:999px; color:#fff; }
+  .chip.before { background:var(--before); } .chip.after { background:var(--after); }
+
+  .tab-section { border:1px solid var(--line); border-radius:14px; padding:18px 18px 8px;
+                 margin:18px 0; background:var(--bg); }
+  .tab-section > h2 { font-size:16px; margin:0 0 2px; }
+  .tab-section > .ctx { color:var(--muted); font-size:12px; margin-bottom:14px; }
+  .state { margin-bottom:18px; }
+  .state .name { font-weight:600; font-size:13.5px; margin-bottom:8px; display:flex; gap:8px; align-items:center; }
+  .state .name .note { font-weight:500; color:var(--note); font-size:12px; }
+  .pair { display:grid; grid-template-columns:1fr 1fr; gap:14px; align-items:start; }
+  .cell { border:1px solid var(--line); border-radius:10px; overflow:hidden; background:var(--frame); }
+  .cell .cap { display:flex; align-items:center; gap:8px; padding:7px 10px; border-bottom:1px solid var(--line);
+               background:var(--bg); }
+  .cell .cap .meta { color:var(--muted); font-size:11px; }
+  .cell img { display:block; width:100%; height:auto; background:#fff; }
+  .cell.empty .ph { display:flex; align-items:center; justify-content:center; height:160px; color:var(--muted);
+                    font-size:12.5px; text-align:center; padding:0 16px; }
+  .single .pair { grid-template-columns:1fr; }
+  .empty-doc { color:var(--muted); padding:40px; text-align:center; }
+  @media (max-width:760px){ .pair{ grid-template-columns:1fr; } }
+</style>
+</head>
+<body>
+<div class="wrap" id="root"></div>
+
+<script id="data">
+window.__BA__ = /*__DATA__*/{"pr":"","title":"No data","base":"","head":"","cropSelector":"","tabs":[]}/*__END__*/;
+</script>
+<script>
+(function(){
+  var D = window.__BA__ || { tabs: [] };
+  var root = document.getElementById("root");
+  function el(html){ var t=document.createElement("template"); t.innerHTML=html.trim(); return t.content.firstChild; }
+  function esc(s){ return (s==null?"":String(s)).replace(/[&<>]/g, function(c){return {"&":"&amp;","<":"&lt;",">":"&gt;"}[c];}); }
+
+  function cell(kind, src){
+    if (src) {
+      return '<div class="cell"><div class="cap"><span class="chip '+kind+'">'+kind+'</span></div>'+
+             '<img src="'+esc(src)+'" alt="'+kind+'"/></div>';
+    }
+    return '<div class="cell empty"><div class="cap"><span class="chip '+kind+'">'+kind+'</span>'+
+           '<span class="meta">not present</span></div><div class="ph">No '+kind+' screenshot for this state</div></div>';
+  }
+
+  var head = '<div class="doc-head"><h1>'+esc(D.title || ("PR #"+D.pr))+'</h1>'+
+    '<div class="sub">Before / after &nbsp;·&nbsp; base <code>'+esc(D.base)+'</code> → head <code>'+esc(D.head)+'</code>'+
+    (D.cropSelector ? ' &nbsp;·&nbsp; cropped to <code>'+esc(D.cropSelector)+'</code>' : '')+'</div></div>'+
+    '<div class="legend"><span class="chip before">Before</span> base branch'+
+    '<span class="chip after">After</span> this PR</div>';
+  root.appendChild(el('<div>'+head+'</div>'));
+
+  if (!D.tabs || !D.tabs.length){ root.appendChild(el('<div class="empty-doc">No tabs captured yet.</div>')); return; }
+
+  D.tabs.forEach(function(tab){
+    var states = (tab.states||[]).map(function(s){
+      var onlyOne = (!s.before || !s.after);
+      return '<div class="state'+(onlyOne?' ':'')+'">'+
+        '<div class="name">'+esc(s.name)+(s.note?'<span class="note">'+esc(s.note)+'</span>':'')+'</div>'+
+        '<div class="pair">'+cell("before", s.before)+cell("after", s.after)+'</div></div>';
+    }).join("");
+    var sec = '<section class="tab-section" id="section-'+esc(tab.id)+'">'+
+      '<h2>'+esc(tab.title)+'</h2>'+
+      (tab.ctx?'<div class="ctx">'+esc(tab.ctx)+'</div>':'')+
+      states+'</section>';
+    root.appendChild(el(sec));
+  });
+})();
+</script>
+</body>
+</html>
@@ -0,0 +1,25 @@
+// Render each .tab-section of a montage HTML into its own PNG (the PR-ready image).
+// Run from frontend/editor (so @playwright/test resolves):
+//   node <skill>/shoot-sections.mjs <montage.html> <outDir>
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const require = createRequire(path.join(process.cwd(), "noop.js"));
+const { chromium } = require("@playwright/test");
+
+const htmlPath = path.resolve(process.argv[2]);
+const outDir = path.resolve(process.argv[3] || path.dirname(htmlPath));
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1200, height: 1200 }, deviceScaleFactor: 2 });
+await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+await page.waitForTimeout(250); // let images/fonts paint
+const ids = await page.$$eval(".tab-section", (els) => els.map((e) => e.id));
+if (!ids.length) { console.error("no .tab-section found"); process.exit(1); }
+for (const id of ids) {
+  const name = id.replace(/^section-/, "");
+  await page.locator("#" + id).screenshot({ path: path.join(outDir, `montage_${name}.png`) });
+  console.log("wrote montage_" + name + ".png");
+}
+await browser.close();
@@ -0,0 +1,120 @@
+---
+name: ui-walkthrough
+description: >-
+  Full UI investigation of the current branch's feature. Enumerates every view
+  and state (empty, populated, loading, error, each dialog/menu/panel, responsive
+  breakpoints, light + dark + RTL), captures them with the stubbed Playwright
+  harness, assembles a single-image HTML walkthrough with a global light/dark
+  toggle slider, then runs two review passes: visual/consistency (alignment,
+  spacing, professionalism, dark/light parity, contrast, truncation) and
+  UX/ease-of-use (flow, discoverability, affordances, empty/error states,
+  expectations). Use when asked for a UI walkthrough, screenshot review, design
+  or QA pass, "find anywhere to make it easier/better for users", or before
+  merging frontend work. Pass --fix to auto-apply safe frontend fixes and
+  re-capture; --theme to limit themes; --no-rtl to skip RTL.
+argument-hint: "[feature/area] [--fix] [--theme light|dark|both] [--no-rtl] [--breakpoints]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# UI Walkthrough
+
+Produce a reviewable HTML walkthrough of a feature's UI in every state and theme,
+then critique it. Optionally auto-fix and re-capture.
+
+`$ARGUMENTS` may name the feature/area to focus on. If empty, scope from the
+current branch diff. Flags: `--fix`, `--theme light|dark|both` (default both),
+`--no-rtl`, `--breakpoints` (also capture phone/narrow widths).
+
+## What this repo gives you (use it, don't reinvent)
+
+- **Stubbed Playwright project** = backend-free screenshots via `page.route()` mocks.
+  Reference implementation: `frontend/editor/src/core/tests/stubbed/files-page-screenshots.spec.ts`.
+  It already shows the light / **dark** / **RTL** passes, JWT seeding, IndexedDB
+  seeding, and dumping PNGs to a `screenshots/<area>/` folder. Copy its shape.
+- Helpers: `frontend/editor/src/core/tests/helpers/ui-helpers.ts`
+  (`uploadFiles`, `openSettings`, `waitForModalOpen`, `dismissTourTooltip`, …)
+  and the `stub-test-base` fixtures (`autoGoto`, `seedJwt`, `viewport`).
+- Config: `frontend/editor/playwright.config.ts` (run from `frontend/editor/`).
+- Report template: [report-template.html](report-template.html) - self-contained,
+  one big image at a time, a global light/dark slider that flips every shot,
+  thumbnail rail, prev/next + arrow keys, and a Findings tab.
+
+## Process
+
+### 1. Scope the feature
+- If `$ARGUMENTS` is empty: `git diff --name-only main...HEAD` and read the PR/commits.
+  Identify changed pages, tools (`core/components/tools/<tool>` or `core/tools/<tool>`),
+  dialogs, panels, and routes.
+- Enumerate **every view and state** to capture, e.g.:
+  empty / populated / loading / error / disabled; each dialog, menu, popover, tooltip;
+  each tab or step; selection + multi-select; success/result panel; and (if relevant)
+  permission/role variants. Write the list down before capturing - it's the report's spine.
+
+### 2. Prepare the harness (worktree-safe)
+Worktrees have no `node_modules` and no generated icons. From repo root:
+```
+cd frontend && npm ci                       # or junction main's node_modules (see memory)
+cd frontend/editor && node scripts/generate-icons.js
+```
+Kill any stale dev server first (it serves old modules):
+`Get-NetTCPConnection -LocalPort 5173 -State Listen | %{ Stop-Process -Id $_.OwningProcess -Force }`
+
+### 3. Write the capture spec
+Create `frontend/editor/src/core/tests/stubbed/<feature>-walkthrough.spec.ts`,
+modeled on `files-page-screenshots.spec.ts`. For each enumerated view:
+- stub the APIs it needs, drive the UI to that state, wait on a real locator
+  (not a fixed sleep), `await settle(page)` for Mantine portals, then
+  `page.screenshot({ path: shotPath("NN_name_<theme>") })`.
+- Capture each view in **light and dark** (and RTL unless `--no-rtl`). Reuse the
+  `enableDarkMode` / `enableRtl` init-script pattern from the reference spec
+  (`localStorage["mantine-color-scheme"]="dark"` + `emulateMedia({colorScheme:"dark"})`).
+- Name shots `NN_<view>_<theme>.png` so light/dark pair up by suffix.
+- Prefer **stable test-ids** over translated accessible names (RTL/i18n breaks text locators).
+
+Run it: `cd frontend/editor && npx playwright test --project=stubbed <feature>-walkthrough.spec.ts`.
+Add `--project=stubbed-firefox`/`-webkit` only if cross-browser layout matters.
+
+### 4. Build the report
+- Copy `report-template.html` to `screenshots/<feature>/walkthrough.html` (so the
+  relative `screenshots/...` image paths resolve, or rewrite paths to sit beside it).
+- Build the manifest and inject it: replace the JSON between the
+  `/*__DATA__*/` … `/*__END__*/` markers with one `views[]` entry per view
+  (`{id,title,light,dark,viewport,notes}`) and an empty `findings` object you'll
+  fill in step 5. Keep `light`/`dark` as relative paths.
+- The toggle slider answers the "one big image + flip light/dark for all" request:
+  it shows a single large screenshot, and switching the slider re-themes every view.
+
+### 5. Review pass 1 - visual & consistency
+Open each screenshot (Read the PNG) and judge against the others:
+alignment & spacing rhythm, control placement, button hierarchy, typography,
+**light/dark parity** (contrast, invisible borders, washed-out text, wrong tokens),
+truncation/overflow, RTL mirroring, focus states, icon consistency, professional polish.
+Record each issue as a finding `{severity:high|med|low, view, title, detail, fix}`.
+
+### 6. Review pass 2 - UX & ease of use
+Walk the flow as a first-time user: discoverability, number of steps, affordance
+clarity, empty-state guidance, error recovery, destructive-action confirmation,
+defaults, loading feedback, mobile reachability, accessible names, and whether the
+UI matches user expectations for this kind of tool. Record findings the same way.
+
+Write both finding lists into the report's `findings.visual` / `findings.ux`,
+and add short per-view `notes`. Re-inject the manifest.
+
+### 7. If `--fix`
+Only safe, self-contained frontend fixes (spacing, alignment, tokens, missing
+dark-mode colors, labels, aria, obvious copy). For each: edit the component/CSS,
+mark the finding `fixed:true` with what changed, then **re-run the spec** to
+re-capture the affected shots and regenerate the report. Run `task frontend:check`.
+Leave anything risky or ambiguous as a finding, not a change.
+
+### 8. Deliver
+Tell the user the report path and give a tight chat summary: N views ×
+themes captured, top findings by severity, and (if `--fix`) what changed.
+Optionally `SendUserFile` the `walkthrough.html`.
+
+## Gotchas
+- Stale `:5173` server serves old bundles - kill it before capturing (see step 2).
+- Missing `material-symbols-icons.json` → blank app → every shot times out. Run
+  `generate-icons.js` first.
+- `await settle(page)` before shots or portals/transitions tear mid-capture.
+- Don't commit the generated `screenshots/` or the throwaway spec unless asked.
@@ -0,0 +1,116 @@
+"""Build a self-contained EXAMPLE.html from report-template.html with mock
+light/dark screenshots, so the viewer + global theme slider can be demoed
+without a real capture run. Run: python make_example.py"""
+import base64
+import json
+import pathlib
+import re
+
+HERE = pathlib.Path(__file__).parent
+
+
+def svg(bg, fg, panel, accent, muted, label, kind):
+    """A simple fake 'screen' SVG: title bar, sidebar, content varies by kind."""
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900">',
+        f'<rect width="1600" height="900" fill="{bg}"/>',
+        # top bar
+        f'<rect width="1600" height="64" fill="{panel}"/>',
+        f'<circle cx="40" cy="32" r="12" fill="{accent}"/>',
+        f'<rect x="64" y="24" width="160" height="16" rx="6" fill="{muted}"/>',
+        f'<rect x="1430" y="20" width="130" height="24" rx="12" fill="{accent}"/>',
+        # left sidebar
+        f'<rect x="0" y="64" width="220" height="836" fill="{panel}"/>',
+    ]
+    for i in range(6):
+        y = 100 + i * 56
+        parts.append(f'<rect x="24" y="{y}" width="172" height="32" rx="8" fill="{bg}"/>')
+    if kind == "empty":
+        parts += [
+            f'<rect x="700" y="360" width="200" height="120" rx="16" fill="none" stroke="{muted}" stroke-width="3" stroke-dasharray="10 8"/>',
+            f'<rect x="690" y="510" width="220" height="44" rx="10" fill="{accent}"/>',
+            f'<text x="800" y="600" fill="{muted}" font-family="sans-serif" font-size="26" text-anchor="middle">{label}</text>',
+        ]
+    elif kind == "form":
+        for i in range(4):
+            y = 140 + i * 90
+            parts.append(f'<rect x="280" y="{y}" width="160" height="16" rx="6" fill="{muted}"/>')
+            parts.append(f'<rect x="280" y="{y+26}" width="900" height="44" rx="8" fill="{panel}" stroke="{muted}" stroke-width="1"/>')
+        parts.append(f'<rect x="280" y="560" width="200" height="50" rx="10" fill="{accent}"/>')
+        parts.append(f'<text x="800" y="850" fill="{muted}" font-family="sans-serif" font-size="24" text-anchor="middle">{label}</text>')
+    else:  # dialog
+        parts += [
+            f'<rect width="1600" height="900" fill="{fg}" opacity="0.45"/>',
+            f'<rect x="520" y="280" width="560" height="360" rx="18" fill="{panel}"/>',
+            f'<rect x="556" y="320" width="280" height="22" rx="8" fill="{fg}"/>',
+            f'<rect x="556" y="372" width="488" height="14" rx="6" fill="{muted}"/>',
+            f'<rect x="556" y="398" width="420" height="14" rx="6" fill="{muted}"/>',
+            f'<rect x="820" y="560" width="110" height="44" rx="9" fill="{bg}" stroke="{muted}"/>',
+            f'<rect x="946" y="560" width="98" height="44" rx="9" fill="{accent}"/>',
+            f'<text x="800" y="700" fill="#fff" font-family="sans-serif" font-size="24" text-anchor="middle">{label}</text>',
+        ]
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+def data_uri(s):
+    return "data:image/svg+xml;base64," + base64.b64encode(s.encode()).decode()
+
+
+LIGHT = dict(bg="#ffffff", fg="#111418", panel="#f1f3f6", accent="#2f6fed", muted="#c2c8d0")
+DARK = dict(bg="#16181c", fg="#000000", panel="#1f232a", accent="#5b8cff", muted="#3a414b")
+
+
+def pair(kind, label):
+    return (
+        data_uri(svg(LIGHT["bg"], LIGHT["fg"], LIGHT["panel"], LIGHT["accent"], LIGHT["muted"], label, kind)),
+        data_uri(svg(DARK["bg"], DARK["fg"], DARK["panel"], DARK["accent"], DARK["muted"], label, kind)),
+    )
+
+
+views = []
+for idx, (kind, title, label) in enumerate([
+    ("empty", "Empty state", "Drop a PDF to start"),
+    ("form", "Tool options panel", "Compress options"),
+    ("dialog", "Confirm dialog", "Replace original file?"),
+], start=1):
+    light, dark = pair(kind, label)
+    views.append({
+        "id": f"{idx:02d}_{kind}",
+        "title": title,
+        "light": light,
+        "dark": dark,
+        "viewport": "1600x900",
+        "notes": ["This is mock data to demo the viewer."],
+    })
+
+data = {
+    "feature": "EXAMPLE - Compress PDF (mock data)",
+    "branch": "demo",
+    "generated": "example",
+    "views": views,
+    "findings": {
+        "visual": [
+            {"severity": "high", "view": "03_dialog", "title": "Dialog buttons too close",
+             "detail": "Cancel/Confirm have only 8px gap; easy to misclick.",
+             "fix": "Increase gap to var(--mantine-spacing-md)."},
+            {"severity": "low", "view": "02_form", "title": "Field labels low contrast in dark mode",
+             "detail": "Muted token fails WCAG AA on the dark panel.",
+             "fix": "Use --mantine-color-dimmed instead of a hard-coded grey."},
+        ],
+        "ux": [
+            {"severity": "med", "view": "01_empty", "title": "Primary CTA below the dropzone",
+             "detail": "Users expect the action button adjacent to the dropzone.",
+             "fix": "Move the button directly under the dashed zone."},
+        ],
+    },
+}
+
+tpl = (HERE / "report-template.html").read_text(encoding="utf-8")
+out = re.sub(
+    r"/\*__DATA__\*/.*?/\*__END__\*/",
+    lambda _m: "/*__DATA__*/" + json.dumps(data) + "/*__END__*/",
+    tpl, count=1, flags=re.S,
+)
+(HERE / "EXAMPLE.html").write_text(out, encoding="utf-8")
+print("wrote", (HERE / "EXAMPLE.html"))
@@ -0,0 +1,298 @@
+<!doctype html>
+<!--
+  UI Walkthrough report template (self-contained, works from file://).
+  The ui-walkthrough skill replaces the JSON in the window.__WALKTHROUGH__ data
+  block below with the captured manifest. Do not add external CDN deps - it must open offline.
+
+  Data shape:
+  {
+    "feature": "Compress PDF tool",
+    "branch": "claude/...",
+    "generated": "2026-06-21",
+    "views": [
+      { "id": "01_empty", "title": "Empty state",
+        "light": "screenshots/compress/01_empty_light.png",
+        "dark":  "screenshots/compress/01_empty_dark.png",
+        "viewport": "1600x900",
+        "notes": ["Heading is centered", "Primary CTA below the fold on mobile"] }
+    ],
+    "findings": {
+      "visual": [ { "severity":"high", "view":"01_empty", "title":"...", "detail":"...", "fix":"..." } ],
+      "ux":     [ { "severity":"med",  "view":"03_dialog", "title":"...", "detail":"...", "fix":"..." } ]
+    }
+  }
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>UI Walkthrough</title>
+<style>
+  :root {
+    --bg: #f6f7f9; --panel: #ffffff; --panel-2: #f0f2f5; --text: #1a1b1e;
+    --muted: #6b7280; --border: #e2e5ea; --accent: #2f6fed; --accent-weak: #e8f0fe;
+    --shadow: 0 1px 3px rgba(0,0,0,.08), 0 8px 24px rgba(0,0,0,.06);
+    --hi: #d92d20; --med: #d98e00; --low: #2f6fed; --stage: #0b0c0e;
+  }
+  html[data-theme="dark"] {
+    --bg: #0d0e10; --panel: #16181c; --panel-2: #1d2024; --text: #e6e8eb;
+    --muted: #9aa3ad; --border: #2a2e35; --accent: #5b8cff; --accent-weak: #1a2336;
+    --shadow: 0 1px 3px rgba(0,0,0,.5), 0 8px 24px rgba(0,0,0,.4); --stage: #000;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, "Segoe UI", Roboto, system-ui, sans-serif;
+         background: var(--bg); color: var(--text); }
+  header { display: flex; align-items: center; gap: 16px; padding: 12px 20px;
+           background: var(--panel); border-bottom: 1px solid var(--border); position: sticky; top: 0; z-index: 5; }
+  header h1 { font-size: 15px; margin: 0; font-weight: 650; }
+  header .sub { color: var(--muted); font-size: 12px; }
+  .spacer { flex: 1; }
+  .counter { color: var(--muted); font-variant-numeric: tabular-nums; font-size: 13px; }
+  .tabs { display: flex; gap: 4px; }
+  .tab { border: 1px solid var(--border); background: var(--panel-2); color: var(--text);
+         padding: 6px 12px; border-radius: 8px; cursor: pointer; font-size: 13px; }
+  .tab.active { background: var(--accent); color: #fff; border-color: var(--accent); }
+
+  /* Light/Dark slider */
+  .theme-toggle { display: flex; align-items: center; gap: 9px; user-select: none; }
+  .theme-toggle .lbl { font-size: 12px; color: var(--muted); }
+  .theme-toggle .lbl.on { color: var(--text); font-weight: 600; }
+  .switch { position: relative; width: 52px; height: 28px; }
+  .switch input { opacity: 0; width: 0; height: 0; }
+  .slider { position: absolute; inset: 0; cursor: pointer; background: var(--panel-2);
+            border: 1px solid var(--border); border-radius: 999px; transition: .2s; }
+  .slider:before { content: ""; position: absolute; height: 20px; width: 20px; left: 3px; top: 3px;
+                   background: #fbbf24; border-radius: 50%; transition: .2s; box-shadow: 0 1px 2px rgba(0,0,0,.3); }
+  .switch input:checked + .slider { background: var(--accent); }
+  .switch input:checked + .slider:before { transform: translateX(24px); background: #c7d2fe; }
+
+  main { display: grid; grid-template-columns: 240px 1fr; height: calc(100vh - 53px); }
+  .rail { border-right: 1px solid var(--border); overflow-y: auto; background: var(--panel); padding: 8px; }
+  .rail .group-label { font-size: 11px; text-transform: uppercase; letter-spacing: .05em;
+                       color: var(--muted); padding: 10px 8px 4px; }
+  .thumb { display: flex; gap: 9px; align-items: center; padding: 7px; border-radius: 8px;
+           cursor: pointer; border: 1px solid transparent; }
+  .thumb:hover { background: var(--panel-2); }
+  .thumb.active { background: var(--accent-weak); border-color: var(--accent); }
+  .thumb img { width: 64px; height: 40px; object-fit: cover; border-radius: 4px; border: 1px solid var(--border); background: var(--stage); }
+  .thumb .t { font-size: 12.5px; line-height: 1.3; }
+  .thumb .badge { font-size: 10px; color: var(--muted); }
+  .thumb .dot { width: 7px; height: 7px; border-radius: 50%; margin-left: auto; flex: none; }
+
+  .stagewrap { display: flex; flex-direction: column; min-width: 0; }
+  .stage { flex: 1; display: flex; align-items: center; justify-content: center; padding: 22px;
+           background: var(--stage); position: relative; min-height: 0; }
+  .stage img { max-width: 100%; max-height: 100%; object-fit: contain; border-radius: 8px;
+               box-shadow: 0 4px 30px rgba(0,0,0,.4); background: #fff; }
+  html[data-theme="dark"] .stage img { background: #16181c; }
+  .nav-btn { position: absolute; top: 50%; transform: translateY(-50%); width: 42px; height: 42px;
+             border-radius: 50%; border: 1px solid var(--border); background: var(--panel);
+             color: var(--text); cursor: pointer; font-size: 18px; opacity: .85; }
+  .nav-btn:hover { opacity: 1; } .nav-btn.prev { left: 16px; } .nav-btn.next { right: 16px; }
+  .nav-btn:disabled { opacity: .25; cursor: default; }
+  .missing { color: var(--muted); font-size: 13px; text-align: center; }
+
+  .detail { border-top: 1px solid var(--border); background: var(--panel); padding: 14px 20px;
+            max-height: 38vh; overflow-y: auto; }
+  .detail h2 { margin: 0 0 4px; font-size: 15px; }
+  .detail .meta { color: var(--muted); font-size: 12px; margin-bottom: 10px; }
+  .notes { list-style: none; padding: 0; margin: 0; display: grid; gap: 6px; }
+  .notes li { display: flex; gap: 8px; align-items: flex-start; }
+  .sev { font-size: 10px; font-weight: 700; text-transform: uppercase; padding: 2px 7px; border-radius: 999px;
+         color: #fff; flex: none; margin-top: 1px; }
+  .sev.high { background: var(--hi); } .sev.med { background: var(--med); } .sev.low { background: var(--low); }
+  .finding .fix { color: var(--muted); font-size: 12.5px; }
+  .finding .fix b { color: var(--text); font-weight: 600; }
+
+  /* Summary tab */
+  .summary { padding: 20px 28px; overflow-y: auto; }
+  .summary h2 { font-size: 16px; margin: 22px 0 8px; }
+  .summary .empty { color: var(--muted); }
+  .card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px;
+          padding: 12px 14px; margin-bottom: 8px; box-shadow: var(--shadow); }
+  .card .head { display: flex; gap: 8px; align-items: center; }
+  .card a { color: var(--accent); text-decoration: none; cursor: pointer; }
+  .hide { display: none !important; }
+  kbd { font: 11px ui-monospace, monospace; background: var(--panel-2); border: 1px solid var(--border);
+        border-radius: 4px; padding: 1px 5px; }
+</style>
+</head>
+<body>
+<header>
+  <div>
+    <h1 id="feature-title">UI Walkthrough</h1>
+    <div class="sub" id="feature-sub"></div>
+  </div>
+  <div class="spacer"></div>
+  <div class="tabs">
+    <button class="tab active" data-tab="viewer">Walkthrough</button>
+    <button class="tab" data-tab="summary">Findings</button>
+  </div>
+  <div class="counter" id="counter"></div>
+  <label class="theme-toggle" title="Toggle light / dark for every screenshot">
+    <span class="lbl" id="lbl-light">Light</span>
+    <span class="switch"><input type="checkbox" id="theme-switch" /><span class="slider"></span></span>
+    <span class="lbl" id="lbl-dark">Dark</span>
+  </label>
+</header>
+
+<main id="viewer-pane">
+  <aside class="rail" id="rail"></aside>
+  <section class="stagewrap">
+    <div class="stage">
+      <button class="nav-btn prev" id="prev" aria-label="Previous">&#8249;</button>
+      <img id="stage-img" alt="" />
+      <div class="missing hide" id="missing"></div>
+      <button class="nav-btn next" id="next" aria-label="Next">&#8250;</button>
+    </div>
+    <div class="detail">
+      <h2 id="view-title"></h2>
+      <div class="meta" id="view-meta"></div>
+      <ul class="notes" id="view-notes"></ul>
+    </div>
+  </section>
+</main>
+
+<section class="summary hide" id="summary-pane"></section>
+
+<script id="data">
+window.__WALKTHROUGH__ = /*__DATA__*/{"feature":"No data","branch":"","generated":"","views":[],"findings":{"visual":[],"ux":[]}}/*__END__*/;
+</script>
+<script>
+(function () {
+  var D = window.__WALKTHROUGH__ || { views: [], findings: { visual: [], ux: [] } };
+  var views = D.views || [];
+  var state = { i: 0, theme: localStorage.getItem("ui-wt-theme") || "light", tab: "viewer" };
+
+  var $ = function (id) { return document.getElementById(id); };
+  function sevClass(s) { return s === "high" ? "high" : s === "med" || s === "medium" ? "med" : "low"; }
+
+  function applyChrome() {
+    document.documentElement.setAttribute("data-theme", state.theme);
+    $("theme-switch").checked = state.theme === "dark";
+    $("lbl-light").classList.toggle("on", state.theme === "light");
+    $("lbl-dark").classList.toggle("on", state.theme === "dark");
+  }
+
+  function srcFor(v) { return state.theme === "dark" ? (v.dark || v.light) : (v.light || v.dark); }
+
+  function findingsForView(id) {
+    var all = (D.findings && D.findings.visual || []).concat(D.findings && D.findings.ux || []);
+    return all.filter(function (f) { return f.view === id; });
+  }
+
+  function renderRail() {
+    var rail = $("rail");
+    rail.innerHTML = "";
+    if (!views.length) { rail.innerHTML = '<div class="group-label">No views captured</div>'; return; }
+    views.forEach(function (v, idx) {
+      var fs = findingsForView(v.id);
+      var worst = fs.some(function (f){return sevClass(f.severity)==="high";}) ? "var(--hi)"
+                : fs.some(function (f){return sevClass(f.severity)==="med";}) ? "var(--med)"
+                : fs.length ? "var(--low)" : "transparent";
+      var el = document.createElement("div");
+      el.className = "thumb" + (idx === state.i ? " active" : "");
+      el.innerHTML = '<img src="' + srcFor(v) + '" alt="" />' +
+        '<div><div class="t">' + (v.title || v.id) + '</div>' +
+        '<div class="badge">' + (v.viewport || "") + '</div></div>' +
+        '<span class="dot" style="background:' + worst + '"></span>';
+      el.onclick = function () { state.i = idx; render(); };
+      rail.appendChild(el);
+    });
+  }
+
+  function render() {
+    applyChrome();
+    if (!views.length) {
+      $("missing").classList.remove("hide"); $("stage-img").classList.add("hide");
+      $("missing").textContent = "No screenshots in this report yet.";
+      $("counter").textContent = ""; return;
+    }
+    var v = views[state.i];
+    var src = srcFor(v);
+    var img = $("stage-img");
+    if (src) {
+      img.classList.remove("hide"); $("missing").classList.add("hide");
+      img.src = src; img.alt = v.title || v.id;
+    } else {
+      img.classList.add("hide"); $("missing").classList.remove("hide");
+      $("missing").textContent = "No " + state.theme + " screenshot for this view.";
+    }
+    $("counter").textContent = (state.i + 1) + " / " + views.length;
+    $("view-title").textContent = v.title || v.id;
+    $("view-meta").textContent = [v.viewport, state.theme + " mode"].filter(Boolean).join("  ·  ");
+    var notes = $("view-notes"); notes.innerHTML = "";
+    var fs = findingsForView(v.id);
+    (v.notes || []).forEach(function (n) {
+      var li = document.createElement("li"); li.textContent = "· " + n; notes.appendChild(li);
+    });
+    fs.forEach(function (f) {
+      var li = document.createElement("li"); li.className = "finding";
+      li.innerHTML = '<span class="sev ' + sevClass(f.severity) + '">' + (f.severity || "note") + '</span>' +
+        '<span><b>' + (f.title || "") + '</b> — ' + (f.detail || "") +
+        (f.fix ? ' <span class="fix"><b>Fix:</b> ' + f.fix + '</span>' : '') + '</span>';
+      notes.appendChild(li);
+    });
+    $("prev").disabled = state.i === 0;
+    $("next").disabled = state.i === views.length - 1;
+    renderRail();
+  }
+
+  function renderSummary() {
+    var pane = $("summary-pane");
+    function block(title, arr) {
+      var h = '<h2>' + title + ' (' + arr.length + ')</h2>';
+      if (!arr.length) return h + '<div class="empty">None found.</div>';
+      return h + arr.map(function (f) {
+        return '<div class="card"><div class="head">' +
+          '<span class="sev ' + sevClass(f.severity) + '">' + (f.severity || "note") + '</span>' +
+          '<b>' + (f.title || "") + '</b>' +
+          (f.view ? ' <a data-jump="' + f.view + '">' + f.view + '</a>' : '') + '</div>' +
+          '<div style="margin-top:6px">' + (f.detail || "") + '</div>' +
+          (f.fix ? '<div class="finding" style="margin-top:6px"><span class="fix"><b>Fix:</b> ' + f.fix + '</span></div>' : '') +
+          '</div>';
+      }).join("");
+    }
+    pane.innerHTML = block("Visual & consistency", (D.findings && D.findings.visual) || []) +
+                     block("UX & ease of use", (D.findings && D.findings.ux) || []);
+    pane.querySelectorAll("[data-jump]").forEach(function (a) {
+      a.onclick = function () {
+        var id = a.getAttribute("data-jump");
+        var idx = views.findIndex(function (v) { return v.id === id; });
+        if (idx >= 0) { state.i = idx; setTab("viewer"); }
+      };
+    });
+  }
+
+  function setTab(t) {
+    state.tab = t;
+    document.querySelectorAll(".tab").forEach(function (b) { b.classList.toggle("active", b.dataset.tab === t); });
+    $("viewer-pane").classList.toggle("hide", t !== "viewer");
+    $("summary-pane").classList.toggle("hide", t !== "summary");
+    if (t === "viewer") $("viewer-pane").style.display = "grid";
+    if (t === "summary") renderSummary();
+  }
+
+  // wiring
+  $("feature-title").textContent = D.feature || "UI Walkthrough";
+  $("feature-sub").textContent = [D.branch, D.generated].filter(Boolean).join("  ·  ");
+  $("theme-switch").onchange = function () {
+    state.theme = this.checked ? "dark" : "light";
+    localStorage.setItem("ui-wt-theme", state.theme);
+    render();
+  };
+  $("prev").onclick = function () { if (state.i > 0) { state.i--; render(); } };
+  $("next").onclick = function () { if (state.i < views.length - 1) { state.i++; render(); } };
+  document.addEventListener("keydown", function (e) {
+    if (state.tab !== "viewer") return;
+    if (e.key === "ArrowLeft") $("prev").click();
+    if (e.key === "ArrowRight") $("next").click();
+    if (e.key.toLowerCase() === "t") $("theme-switch").click();
+  });
+  document.querySelectorAll(".tab").forEach(function (b) { b.onclick = function () { setTab(b.dataset.tab); }; });
+
+  render();
+})();
+</script>
+</body>
+</html>
@@ -8,8 +8,6 @@
 build/
 */build/
 **/build/
-# ...but re-include the Quarkus runner-jar so docker/quarkus/Dockerfile can layer it on the base image
-!app/core/build/*-runner.jar
 out/
 target/
 **/target/
@@ -29,7 +27,6 @@ node_modules/
 **/node_modules/
 frontend/node_modules/
 frontend/editor/dist/
-frontend/dist-portal/
 frontend/editor/playwright-report/
 .npm/
 .yarn/
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-desktop
-pkgver=2.13.0
+pkgver=2.14.1
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (Tauri desktop app, official Stirling PDF Inc build)"
 arch=('x86_64')
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-server-bin
-pkgver=2.13.0
+pkgver=2.14.1
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
 arch=('any')
@@ -87,6 +87,21 @@ engine: &engine
  - Taskfile.yml
  - .taskfiles/engine.yml

+# Files that can make the committed generated API models (frontend tool API
+# types + engine tool models) go stale: the Java tool surfaces they derive from,
+# the generators, the generated files themselves (to catch a hand-edit), and the
+# tasks that drive generation. Deliberately excludes the broad frontend/docker/
+# testing globs, so a CSS-only PR does not boot the backend to rebuild the spec.
+generated-models: &generated-models
+  - *openapi
+  - frontend/editor/scripts/generate-tool-api-types.mts
+  - frontend/editor/src/core/types/toolApiTypes.ts
+  - engine/scripts/generate_tool_models.py
+  - engine/src/stirling/models/tool_models.py
+  - .taskfiles/frontend.yml
+  - .taskfiles/engine.yml
+  - .github/workflows/check-generated-models.yml
+
 licenses-frontend: &licenses-frontend
  - ".github/workflows/frontend-backend-licenses-update.yml"
  - "frontend/package.json"
@@ -116,6 +116,9 @@ jobs:
    env:
      USE_DEPOT: ${{ needs.pick.outputs.is_fork != 'true' }}
      DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
+      # Single source of truth for whether this preview embeds the admin portal:
+      # drives the image build-arg and the deployment comment.
+      BUILD_PORTAL: "true"

    steps:
      - name: Harden Runner
@@ -246,7 +249,9 @@ jobs:
          file: ./docker/embedded/Dockerfile
          push: true
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-${{ steps.commit-hash.outputs.app_short }}
-          build-args: VERSION_TAG=v2-alpha
+          build-args: |
+            VERSION_TAG=v2-alpha
+            BUILD_PORTAL=${{ env.BUILD_PORTAL }}
          platforms: linux/amd64

      - name: Build and push V2 image (Docker fork fallback)
@@ -259,7 +264,9 @@ jobs:
          cache-from: type=gha,scope=stirling-pdf-latest
          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-${{ steps.commit-hash.outputs.app_short }}
-          build-args: VERSION_TAG=v2-alpha
+          build-args: |
+            VERSION_TAG=v2-alpha
+            BUILD_PORTAL=${{ env.BUILD_PORTAL }}
          platforms: linux/amd64

      - name: Set up SSH
@@ -290,6 +297,8 @@ jobs:
                - /stirling/V2-PR-${{ needs.check-pr.outputs.pr_number }}/storage:/storage:rw
              environment:
                DISABLE_ADDITIONAL_FEATURES: "false"
+                POLICIES_ENABLED: "true"
+                STIRLING_BILLING_ACCOUNT_LINK_ENABLED: "true"
                SECURITY_ENABLELOGIN: "true"
                SECURITY_INITIALLOGIN_USERNAME: "${{ secrets.TEST_LOGIN_USERNAME }}"
                SECURITY_INITIALLOGIN_PASSWORD: "${{ secrets.TEST_LOGIN_PASSWORD }}"
@@ -333,9 +342,70 @@ jobs:
          # Set port for output
          echo "v2_port=${V2_PORT}" >> $GITHUB_OUTPUT

+      # ---- Storybook preview (only when this PR touches stories/.storybook) ----
+      # Runs inside the same approved-contributor-gated deploy job, so it deploys
+      # under the exact same access rules as the app preview.
+      - name: Detect Storybook changes
+        id: sb-changes
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          list-files: json
+          filters: |
+            storybook:
+              - 'frontend/**/*.stories.@(ts|tsx|mdx)'
+              - 'frontend/**/*.mdx'
+              - 'frontend/.storybook/**'
+
+      - name: Set up Node.js for Storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install Task for Storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+
+      - name: Build and deploy Storybook
+        id: storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        env:
+          VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+          VPS_USER: ${{ secrets.NEW_VPS_USERNAME }}
+        run: |
+          set -euo pipefail
+          # `prepare` generates the icon set stories import (not committed).
+          task frontend:prepare
+          task frontend:storybook:build
+          PR=${{ needs.check-pr.outputs.pr_number }}
+          # Served at the ROOT of its own port so Storybook's global MSW worker
+          # (/mockServiceWorker.js) resolves. Port = PR + 20000 (bijective, offset
+          # from the app preview's bare-PR-number port).
+          SB_PORT=$((PR + 20000))
+          DIR=/stirling/SB-PR-$PR
+          tar czf storybook.tgz -C frontend/storybook-static .
+          scp -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            storybook.tgz "$VPS_USER@$VPS_HOST:/tmp/storybook-$PR.tgz"
+          ssh -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -T \
+            "$VPS_USER@$VPS_HOST" << ENDSSH
+            set -e
+            rm -rf "$DIR" && mkdir -p "$DIR"
+            tar xzf /tmp/storybook-$PR.tgz -C "$DIR"
+            rm -f /tmp/storybook-$PR.tgz
+            docker rm -f storybook-pr-$PR 2>/dev/null || true
+            docker run -d --name storybook-pr-$PR --restart unless-stopped \
+              -p $SB_PORT:80 -v "$DIR":/usr/share/nginx/html:ro nginx:alpine
+          ENDSSH
+          echo "url=http://$VPS_HOST:$SB_PORT/" >> "$GITHUB_OUTPUT"
+
      - name: Post V2 deployment URL to PR
        if: success()
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          SB_URL: ${{ steps.storybook.outputs.url }}
+          SB_FILES: ${{ steps.sb-changes.outputs.storybook_files }}
        with:
          github-token: ${{ steps.setup-bot.outputs.token }}
          script: |
@@ -359,12 +429,40 @@ jobs:
            }

            const deploymentUrl = `http://${{ secrets.NEW_VPS_HOST }}:${v2Port}`;
-            const httpsUrl = `https://${v2Port}.ssl.stirlingpdf.cloud`;
+
+            // Only mention the portal when this image actually embeds it.
+            // Use the direct IP URL - the SSL hostname isn't supported yet.
+            const withPortal = "${{ env.BUILD_PORTAL }}" === "true";
+            const portalNote = withPortal
+              ? `🧩 **Admin portal** included - try it at [${deploymentUrl}/portal](${deploymentUrl}/portal).\n\n`
+              : ``;
+
+            // Storybook preview: only present when this PR changed stories/config.
+            const sbUrl = process.env.SB_URL;
+            let storybookNote = "";
+            if (sbUrl) {
+              const files = JSON.parse(process.env.SB_FILES || "[]");
+              const stories = files.filter((f) => /\.stories\.(ts|tsx|mdx)$/.test(f));
+              const config = files.filter((f) => f.startsWith("frontend/.storybook/"));
+              const shorten = (f) =>
+                f.replace(/^frontend\/editor\/src\//, "").replace(/^frontend\//, "");
+              const storyList = stories.map((f) => `- \`${shorten(f)}\``).join("\n");
+              const configList = config.map((f) => `- \`${shorten(f)}\``).join("\n");
+              const summary =
+                `${stories.length} stor${stories.length === 1 ? "y" : "ies"} changed` +
+                (config.length ? ` (+${config.length} config file${config.length === 1 ? "" : "s"})` : "");
+              storybookNote =
+                `📚 **Storybook:** [${sbUrl}](${sbUrl})\n\n` +
+                `<details>\n<summary>${summary}</summary>\n\n` +
+                (storyList ? `**Stories**\n${storyList}\n\n` : "") +
+                (configList ? `**Config**\n${configList}\n` : "") +
+                `</details>\n\n`;
+            }

            const commentBody = `## 🚀 V2 Auto-Deployment Complete!\n\n` +
-                              `Your V2 PR with embedded architecture has been deployed!\n\n` +
                              `🔗 **Direct Test URL (non-SSL)** [${deploymentUrl}](${deploymentUrl})\n\n` +
-                              `🔐 **Secure HTTPS URL**: [${httpsUrl}](${httpsUrl})\n\n` +
+                              portalNote +
+                              storybookNote +
                              `_This deployment will be automatically cleaned up when the PR is closed._\n\n` +
                              `🔄 **Auto-deployed** for approved V2 contributors.`;

@@ -460,7 +558,11 @@ jobs:
            else
              echo "V2 PR directory not found, nothing to clean up"
            fi
-            
+
+            # Remove this PR's Storybook preview (container + files), if any.
+            docker rm -f storybook-pr-${{ github.event.pull_request.number }} 2>/dev/null || true
+            rm -rf /stirling/SB-PR-${{ github.event.pull_request.number }}
+
            # Clean up old unused images (older than 2 weeks) but keep recent ones for reuse
            docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true

@@ -222,7 +222,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -1,9 +1,9 @@
 name: AI Engine CI

-# Validates the Python AI engine: regenerates tool models and runs the
-# engine quality gate (lint, type-check, format-check, tests). Called from
-# build.yml on PRs and merge_group; also runs directly on push to main as
-# a post-merge safety net.
+# Runs the engine quality gate (lint, type-check, format-check, tests). Called
+# from build.yml on PRs and merge_group; also runs directly on push to main as
+# a post-merge safety net. Freshness of the generated tool_models.py is checked
+# by the shared check-generated-models workflow.
 on:
  workflow_call:
  push:
@@ -30,108 +30,13 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

-      - name: Set up JDK 25
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
-        with:
-          java-version: "25"
-          distribution: "temurin"
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
-        with:
-          gradle-version: 9.5.1
-
      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0

-      - name: Regenerate tool models
-        run: task engine:tool-models
-
-      - name: Verify tool models are up to date
-        id: tool-models-check
-        continue-on-error: true
-        run: git diff --exit-code engine/src/stirling/models/tool_models.py
-
-      - name: Comment on tool models check failure
-        # Only post a comment on PRs. github-script's PR helpers need an
-        # issue/PR number, which doesn't exist on merge_group runs.
-        if: steps.tool-models-check.outcome == 'failure' && github.event_name == 'pull_request'
-        continue-on-error: true
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        with:
-          script: |
-            const marker = '<!-- tool-models-check -->';
-            const body = [
-              marker,
-              '### Tool Models Check Failed',
-              '',
-              'The generated `engine/src/stirling/models/tool_models.py` is out of date with the Java OpenAPI spec and will need to be regenerated before it can be merged in.',
-              '',
-              'Run `task engine:tool-models` to regenerate, then commit the updated file.',
-            ].join('\n');
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            });
-            const existing = comments.find(c => c.body.includes(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body,
-              });
-            }
-
-      - name: Fail if tool models check failed
-        if: steps.tool-models-check.outcome == 'failure'
-        run: |
-          echo "============================================"
-          echo "  Tool Models Check Failed"
-          echo "============================================"
-          echo ""
-          echo "The generated engine/src/stirling/models/tool_models.py"
-          echo "is out of date with the Java OpenAPI spec and will"
-          echo "need to be regenerated before it can be merged in."
-          echo ""
-          echo "Run 'task engine:tool-models' to regenerate, then"
-          echo "commit the updated file."
-          echo "============================================"
-          exit 1
-
-      - name: Remove tool models check comment on success
-        if: steps.tool-models-check.outcome == 'success' && github.event_name == 'pull_request'
-        continue-on-error: true
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        with:
-          script: |
-            const marker = '<!-- tool-models-check -->';
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            });
-            const existing = comments.find(c => c.body.includes(marker));
-            if (existing) {
-              await github.rest.issues.deleteComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-              });
-            }
-
      - name: Quality-check engine
        id: engine-check
        run: task engine:check
@@ -58,7 +58,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -2,7 +2,7 @@ name: Enterprise E2E (Playwright)

 # Enterprise Playwright suite — exercises premium-key gated features (audit,
 # teams, analytics) plus full OAuth + SAML logins via the Keycloak compose
-# stacks under testing/compose. Slow and secret-gated, so it runs in three
+# stacks under testing/compose. Slow and secret-gated, so it runs in four
 # situations:
 #
 #   - PRs that touch proprietary / premium / SSO compose / enterprise tests
@@ -12,8 +12,6 @@ name: Enterprise E2E (Playwright)
 #   - on a nightly cron schedule (catches Keycloak image drift, license
 #     expiry, upstream proprietary changes),
 #   - manual workflow_dispatch.
-#
-# Auto-skipped when secrets.PREMIUM_KEY_ENTERPRISE is missing (forks, dependabot).

 on:
  workflow_call:
@@ -52,6 +50,10 @@ jobs:

  playwright-e2e-enterprise:
    needs: pick
+    # Skip on fork PRs / untrusted authors: they have no PREMIUM_KEY_ENTERPRISE
+    # (nor DEPOT_TOKEN), so the suite can't boot premium and would fail. See the
+    # header comment. GitHub reports the skipped reusable workflow as success.
+    if: needs.pick.outputs.is_fork != 'true'
    runs-on: ${{ needs.pick.outputs.is_fork == 'true' && 'ubuntu-latest' || format('depot-ubuntu-24.04-{0}', inputs.depot_cores || '8') }}
    timeout-minutes: 45
    env:
@@ -165,6 +167,8 @@ jobs:
          wait_for_backend
      - name: Run enterprise OAuth Playwright tests
        id: oauth-tests
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results-oauth.json
        run: task e2e:enterprise -- --grep "OAuth"
      - name: Stop backend + tear down OAuth Keycloak
        if: always()
@@ -238,6 +242,8 @@ jobs:
          wait_for_backend
      - name: Run enterprise SAML Playwright tests
        id: saml-tests
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results-saml.json
        run: task e2e:enterprise -- --grep "SAML"
      - name: Stop backend + tear down SAML Keycloak
        if: always()
@@ -268,6 +274,8 @@ jobs:
          wait_for_backend
      - name: Run enterprise feature Playwright tests
        id: feature-tests
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results-feature.json
        run: task e2e:enterprise -- --grep "Enterprise license"
      - name: Print backend log on failure
        if: failure()
@@ -280,10 +288,23 @@ jobs:
        run: |
          source /tmp/helpers.sh
          stop_backend
+      - name: Flag flaky tests
+        # Runs regardless of the test outcomes: a flaky test (passed on retry)
+        # leaves its step green, so this is the only place it surfaces. Merges
+        # all three phase reports (some may be absent if an earlier phase hard-
+        # failed and skipped the rest). Emits ::warning:: annotations + a job
+        # summary; never fails the job.
+        if: always()
+        working-directory: frontend
+        run: >
+          npx tsx editor/scripts/report-flaky-tests.mts
+          "${{ github.workspace }}/frontend/playwright-report/results-oauth.json"
+          "${{ github.workspace }}/frontend/playwright-report/results-saml.json"
+          "${{ github.workspace }}/frontend/playwright-report/results-feature.json"
      - name: Upload Playwright report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: playwright-report-enterprise-${{ github.run_id }}
-          path: frontend/editor/playwright-report/
+          path: frontend/playwright-report/
          retention-days: 7
@@ -43,6 +43,7 @@ jobs:
      docker-base: ${{ steps.changes.outputs.docker-base }}
      tauri: ${{ steps.changes.outputs.tauri }}
      engine: ${{ steps.changes.outputs.engine }}
+      generated-models: ${{ steps.changes.outputs.generated-models }}
      proprietary: ${{ steps.changes.outputs.proprietary }}
    steps:
      - name: Harden the runner (Audit all outbound calls)
@@ -171,6 +172,20 @@ jobs:
    uses: ./.github/workflows/ai-engine.yml
    secrets: inherit

+  # The generated frontend types and engine tool models are both derived from
+  # the Java OpenAPI spec. This job regenerates and diffs them; it boots the
+  # backend, so it is gated on the narrow generated-models filter (spec source,
+  # generators, generated files, generation tasks) rather than the broad
+  # frontend filter, so a CSS-only PR does not pay for a backend build.
+  generated-models:
+    if: needs.files-changed.outputs.generated-models == 'true'
+    needs: [files-changed]
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/check-generated-models.yml
+    secrets: inherit
+
  pre-commit:
    needs: [files-changed]
    permissions:
@@ -202,6 +217,9 @@ jobs:
      contents: read
    uses: ./.github/workflows/coverage-aggregate.yml
    secrets: inherit
+    with:
+      frontend-validation-result: ${{ needs.frontend-validation.result }}
+      playwright-e2e-live-result: ${{ needs.playwright-e2e-live.result }}

  # Single status check that branch protection should mark as required.
  # Succeeds when every upstream job is either `success` or `skipped` (path-
@@ -225,6 +243,7 @@ jobs:
      - test-build-docker-images
      - tauri-build
      - ai-engine
+      - generated-models
      - pre-commit
      - dependency-review
    runs-on: ubuntu-latest
@@ -250,6 +269,7 @@ jobs:
            test-build-docker-images=${{ needs.test-build-docker-images.result }}
            tauri-build=${{ needs.tauri-build.result }}
            ai-engine=${{ needs.ai-engine.result }}
+            generated-models=${{ needs.generated-models.result }}
            pre-commit=${{ needs.pre-commit.result }}
            dependency-review=${{ needs.dependency-review.result }}
        run: |
@@ -0,0 +1,148 @@
+name: Check generated models
+
+# Verifies the committed generated API models are still in sync with the Java
+# OpenAPI spec: the frontend tool API types
+# (frontend/editor/src/core/types/toolApiTypes.ts) and the engine tool
+# models (engine/src/stirling/models/tool_models.py). Regenerates both with the
+# single top-level `task tool-models` and fails if either committed file is
+# out of date. Called from build.yml when the backend Java, frontend, or engine
+# changes; also runs on push to main as a post-merge safety net.
+on:
+  workflow_call:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  generated-models:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2.19.3
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: "25"
+          distribution: "temurin"
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+        with:
+          gradle-version: 9.6.0
+
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install Task
+        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+
+      # Rebuilds the OpenAPI spec from the current Java and regenerates both the
+      # frontend types and the engine tool models from it.
+      - name: Regenerate generated models
+        run: task tool-models
+
+      - name: Verify generated models are up to date
+        id: models-check
+        continue-on-error: true
+        run: |
+          git diff --exit-code \
+            frontend/editor/src/core/types/toolApiTypes.ts \
+            engine/src/stirling/models/tool_models.py
+
+      - name: Comment on generated models check failure
+        # Only post a comment on PRs. github-script's PR helpers need an
+        # issue/PR number, which doesn't exist on merge_group runs.
+        if: steps.models-check.outcome == 'failure' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- generated-models-check -->';
+            const body = [
+              marker,
+              '### Generated Models Check Failed',
+              '',
+              'The generated `frontend/editor/src/core/types/toolApiTypes.ts` and/or `engine/src/stirling/models/tool_models.py` are out of date with the Java OpenAPI spec and will need to be regenerated before they can be merged in.',
+              '',
+              'Run `task tool-models` to regenerate both, then commit the updated files.',
+            ].join('\n');
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+      - name: Fail if generated models check failed
+        if: steps.models-check.outcome == 'failure'
+        run: |
+          echo "============================================"
+          echo "  Generated Models Check Failed"
+          echo "============================================"
+          echo ""
+          echo "The generated frontend API types and/or engine tool"
+          echo "models are out of date with the Java OpenAPI spec and"
+          echo "will need to be regenerated before they can be merged in."
+          echo ""
+          echo "Run 'task tool-models' to regenerate both, then"
+          echo "commit the updated files."
+          echo "============================================"
+          exit 1
+
+      - name: Remove generated models check comment on success
+        if: steps.models-check.outcome == 'success' && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const marker = '<!-- generated-models-check -->';
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+              });
+            }
@@ -40,7 +40,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -45,7 +45,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -13,6 +13,17 @@ name: Aggregate backend coverage
 #     producers themselves
 on:
  workflow_call:
+    inputs:
+      frontend-validation-result:
+        description: Result of the frontend-validation producer job
+        required: false
+        type: string
+        default: skipped
+      playwright-e2e-live-result:
+        description: Result of the playwright-e2e-live producer job
+        required: false
+        type: string
+        default: skipped

 permissions:
  contents: read
@@ -51,7 +62,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.3.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Set up Python
@@ -196,9 +207,9 @@ jobs:
      # --------------------------------------------------------------
      - name: Download vitest coverage artifact
        # frontend-validation uploads as `frontend-coverage`. Tolerate
-        # absence so a backend-only PR still produces the matrix with
-        # just backend rows populated.
-        if: always()
+        # absence on backend-only runs by skipping the download entirely
+        # when the producer job was not part of this workflow run.
+        if: inputs.frontend-validation-result == 'success'
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v6.0.0
        with:
          name: frontend-coverage
@@ -206,12 +217,12 @@ jobs:
        continue-on-error: true

      - name: Download Playwright frontend coverage artifact
-        # e2e-live uploads as `playwright-frontend-coverage-<run_id>`.
-        # Same tolerance as vitest - matrix script handles missing inputs.
-        if: always()
+        # e2e-live uploads the artifact with a stable name. Skip the
+        # download entirely when the producer job did not run.
+        if: inputs.playwright-e2e-live-result == 'success'
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v6.0.0
        with:
-          name: playwright-frontend-coverage-${{ github.run_id }}
+          name: playwright-frontend-coverage
          path: matrix-inputs/playwright/
        continue-on-error: true

@@ -48,7 +48,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      # No `-PnoSpotless` here yet because the upstream cache layer matches the
@@ -58,18 +58,16 @@ jobs:
          MAVEN_USER: ${{ secrets.MAVEN_USER }}
          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}
-        run: ./gradlew :stirling-pdf:quarkusBuild -PnoSpotless --no-daemon
+        run: ./gradlew :stirling-pdf:bootJar -PnoSpotless --no-daemon

      - name: Locate built JAR
        id: jar
        run: |
-          # Quarkus (quarkus.package.jar.type=uber-jar) emits a standalone runnable
-          # jar at app/core/build/<name>-runner.jar, replacing the Spring Boot bootJar
-          # that used to land in app/core/build/libs.
-          jar=$(find app/core/build -maxdepth 1 -name '*-runner.jar' 2>/dev/null | head -n 1)
+          jar=$(find app/core/build/libs -maxdepth 1 -name 'Stirling-PDF*.jar' -o -name 'stirling-pdf*.jar' 2>/dev/null \
+              | grep -vE '(-plain|-sources)\.jar$' | head -n 1)
          if [[ -z "$jar" ]]; then
-            echo "::error::No *-runner.jar under app/core/build"
-            ls -lah app/core/build || true
+            echo "::error::No JAR under app/core/build/libs"
+            ls -lah app/core/build/libs || true
            exit 1
          fi
          # Absolute path - the migration script pushd's into a temp workdir
@@ -61,14 +61,22 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

+      # When the PR changes the base image, test.sh builds it locally
+      # (stirling-pdf-base:local) into the daemon image store. A buildx
+      # container builder can't see that store, so skip it here and let
+      # `docker buildx build` fall back to the default docker driver, which
+      # resolves the local base. The gha cache backend is also skipped (its
+      # runtime token isn't exposed) since the docker driver can't use it.
      - name: Set up Docker Buildx
+        if: inputs.docker-base-changed != 'true'
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      # Expose ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL for docker buildx type=gha cache backend.
      - name: Expose GitHub runtime for Buildx cache
+        if: inputs.docker-base-changed != 'true'
        uses: crazy-max/ghaction-github-runtime@04d248b84655b509d8c44dc1d6f990c879747487 # v4.0.0

      - name: Install Docker Compose
@@ -62,7 +62,17 @@ jobs:
          # .test-state/playwright/coverage-pw/ for the post-process step
          # to aggregate. Chromium-only - other engines silently skip.
          PW_COVERAGE: "1"
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
        run: task e2e:live
+      - name: Flag flaky tests
+        # Runs regardless of the test outcome: a flaky test (passed on retry)
+        # leaves the step green, so this is the only place it surfaces. Emits
+        # ::warning:: annotations + a job summary; never fails the job.
+        if: always()
+        working-directory: frontend
+        run: npx tsx editor/scripts/report-flaky-tests.mts "$PLAYWRIGHT_JSON_OUTPUT_FILE"
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
      - name: Generate JaCoCo report from e2e:live .exec
        if: always()
        id: live-coverage
@@ -169,7 +179,7 @@ jobs:
        if: always() && steps.pw-frontend-coverage.outputs.summary == 'true'
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
-          name: playwright-frontend-coverage-${{ github.run_id }}
+          name: playwright-frontend-coverage
          path: |
            .test-state/playwright/coverage-pw-summary/
            .test-state/playwright/coverage-pw/
@@ -44,11 +44,22 @@ jobs:
          VITE_BUILD_FOR_PREVIEW: "1"
        run: task frontend:build
      - name: Run stubbed E2E tests (chromium)
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
        run: task e2e:stubbed -- --workers=3
+      - name: Flag flaky tests
+        # Runs regardless of the test outcome: a flaky test (passed on retry)
+        # leaves the step green, so this is the only place it surfaces. Emits
+        # ::warning:: annotations + a job summary; never fails the job.
+        if: always()
+        working-directory: frontend
+        run: npx tsx editor/scripts/report-flaky-tests.mts "$PLAYWRIGHT_JSON_OUTPUT_FILE"
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
      - name: Upload Playwright report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: playwright-report-stubbed-${{ github.run_id }}
-          path: frontend/editor/playwright-report/
+          path: frontend/playwright-report/
          retention-days: 7
@@ -98,6 +98,13 @@ jobs:

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+
+      - name: Generate frontend license report (Push only)
+        if: github.event_name == 'push'
+        env:
+          PR_IS_FORK: "false"
+        run: task frontend:licenses:generate
+
      - name: Generate frontend license report (internal PR)
        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
        env:
@@ -349,10 +356,11 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+
      - name: Check licenses and generate report
        id: license-check
        run: task backend:licenses:generate || echo "LICENSE_CHECK_FAILED=true" >> $GITHUB_ENV
@@ -73,7 +73,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -148,7 +148,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Setup Node.js
        if: matrix.variant.build_frontend == true
@@ -252,7 +252,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -41,6 +41,11 @@ jobs:
      - name: Install all Playwright browsers
        run: task e2e:install

+      - name: Build frontend (production bundle for vite preview)
+        env:
+          VITE_BUILD_FOR_PREVIEW: "1"
+        run: task frontend:build
+
      - name: Run E2E tests (all browsers)
        run: task e2e:cross-browser

@@ -48,6 +53,19 @@ jobs:
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
-          name: playwright-nightly-${{ github.run_id }}
-          path: frontend/editor/playwright-report/
+          name: playwright-report-nightly-${{ github.run_id }}
+          path: frontend/playwright-report/
          retention-days: 14
+
+  # Builds all desktop platforms on a schedule so the Rust dependency cache is
+  # written on main, where PR and merge-queue tauri builds can restore it.
+  warm-tauri-cache:
+    name: Warm Tauri Rust cache
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/tauri-build.yml
+    with:
+      platform: all
+      sign: false
+    secrets: inherit
@@ -25,7 +25,7 @@ jobs:
          persist-credentials: false

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

@@ -78,7 +78,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Set up Docker Buildx
        id: buildx
@@ -155,9 +155,9 @@ jobs:
          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
+          # No BASE_VERSION pin: inherit the Dockerfile ARG default (single source of truth).
          build-args: |
            VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
-            BASE_VERSION=1.0.0
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true
@@ -48,7 +48,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Generate Swagger documentation
        run: ./gradlew :stirling-pdf:generateOpenApiDocs
@@ -61,7 +61,7 @@ jobs:
          pip install --require-hashes --only-binary=:all: -r ./.github/scripts/requirements_sync_readme.txt

      - name: Install uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: true

@@ -16,6 +16,11 @@ on:
        required: false
        type: string
        default: "all"
+      sign:
+        description: "Sign and notarize the bundles."
+        required: false
+        type: boolean
+        default: true
  workflow_dispatch:
    inputs:
      platform:
@@ -28,6 +33,11 @@ on:
          - windows
          - macos
          - linux
+      sign:
+        description: "Sign and notarize the bundles."
+        required: false
+        default: true
+        type: boolean

 permissions:
  contents: read
@@ -115,6 +125,20 @@ jobs:
          toolchain: stable
          targets: ${{ matrix.platform == 'macos-15' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

+      # Cache the Cargo registry and compiled dependency crates so the build
+      # only recompiles the app crate. Written on main; PRs and the merge queue
+      # restore from it.
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          workspaces: frontend/editor/src-tauri
+          # Stable key shared across workflows so the nightly warmer.
+          # rust-cache still appends OS + rustc + Cargo.lock.
+          shared-key: tauri-${{ matrix.name }}
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+          # Save the dependency cache even if a later step fails
+          cache-on-failure: true
+
      - name: Set up x86_64 JDK 25 (macOS universal JRE)
        if: matrix.platform == 'macos-15'
        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
@@ -136,7 +160,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Setup Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
@@ -163,7 +187,7 @@ jobs:
      # DigiCert KeyLocker Setup (Cloud HSM)
      - name: Setup DigiCert KeyLocker
        id: digicert-setup
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        uses: digicert/ssm-code-signing@1d820463733701cf1484c7eb5d7d24a15ca2c454 # v1.2.1
        env:
          SM_API_KEY: ${{ secrets.SM_API_KEY }}
@@ -173,7 +197,7 @@ jobs:
          SM_HOST: ${{ secrets.SM_HOST }}

      - name: Setup DigiCert KeyLocker Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: pwsh
        run: |
          Write-Host "Setting up DigiCert KeyLocker environment..."
@@ -208,7 +232,7 @@ jobs:

      # Traditional PFX Certificate Import (fallback if KeyLocker not configured)
      - name: Import Windows Code Signing Certificate
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY == '' && github.ref == 'refs/heads/main' }}
        env:
          WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
          WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
@@ -239,7 +263,7 @@ jobs:
          }

      - name: Import Apple Developer Certificate
-        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
+        if: inputs.sign && matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
        env:
          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
@@ -260,7 +284,7 @@ jobs:
          rm certificate.p12

      - name: Verify Certificate
-        if: matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
+        if: inputs.sign && matrix.platform == 'macos-15' && env.APPLE_CERTIFICATE != ''
        run: |
          echo "Verifying Apple Developer Certificate..."
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
@@ -283,7 +307,7 @@ jobs:
          ls -la /usr/bin/hd* || echo "No hd* tools found"

      - name: Preflight smctl
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: pwsh
        env:
          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
@@ -296,7 +320,7 @@ jobs:
          if ($LASTEXITCODE -ne 0) { Write-Host "[WARN] smctl windows certsync returned non-zero - continuing" }

      - name: Configure Windows code signing
-        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
+        if: ${{ inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main' }}
        shell: bash
        env:
          KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
@@ -315,7 +339,7 @@ jobs:
          EOF

      - name: Import release GPG signing key (Linux)
-        if: matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        if: inputs.sign && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
        run: |
          echo "$RELEASE_GPG_PRIVATE_KEY" | gpg --batch --import
          gpg --list-secret-keys --keyid-format=long
@@ -332,7 +356,8 @@ jobs:
            exit 1
          fi

-      - name: Build Tauri app
+      - name: Build Tauri app (signed)
+        if: inputs.sign
        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -366,6 +391,26 @@ jobs:
          # failure (#6127 onwards) does not tank deb/rpm uploads.
          args: ${{ matrix.platform == 'ubuntu-22.04' && '--bundles deb,rpm' || matrix.args }}

+      - name: Build Tauri app (unsigned)
+        if: ${{ !inputs.sign }}
+        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SIGN: "0"
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: ${{ secrets.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY || 'sb_publishable_UHz2SVRF5mvdrPHWkRteyA_yNlZTkYb' }}
+          VITE_SAAS_SERVER_URL: ${{ secrets.VITE_SAAS_SERVER_URL || 'https://app.stirlingpdf.com' }}
+          VITE_SAAS_BACKEND_API_URL: ${{ secrets.VITE_SAAS_BACKEND_API_URL || 'https://api.stirlingpdf.com' }}
+          CI: true
+        with:
+          projectPath: ./frontend/editor
+          tauriScript: npx tauri
+          # Linux: build deb+rpm only here. AppImage runs in its own
+          # continue-on-error step below so its persistent linuxdeploy
+          # failure (#6127 onwards) does not tank deb/rpm uploads.
+          args: ${{ matrix.platform == 'ubuntu-22.04' && '--bundles deb,rpm' || matrix.args }}
+
      # AppImage is decoupled so its linuxdeploy run gets a fresh process
      # (rpm scratch state torn down) and its failure can't tank deb/rpm.
      - name: Build Tauri app (Linux AppImage)
@@ -374,7 +419,7 @@ jobs:
        uses: tauri-apps/tauri-action@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0.6.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SIGN: ${{ (env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
+          SIGN: ${{ (inputs.sign && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main') && '1' || '0' }}
          APPIMAGETOOL_SIGN_PASSPHRASE: ${{ secrets.RELEASE_GPG_PASSPHRASE }}
          SIGN_KEY: ${{ vars.RELEASE_GPG_FINGERPRINT }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
@@ -389,7 +434,7 @@ jobs:
          args: --bundles appimage

      - name: Clear release GPG key from runner keyring (Linux)
-        if: always() && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
+        if: always() && inputs.sign && matrix.platform == 'ubuntu-22.04' && env.RELEASE_GPG_PRIVATE_KEY != '' && github.ref == 'refs/heads/main'
        env:
          RELEASE_GPG_FINGERPRINT: ${{ vars.RELEASE_GPG_FINGERPRINT }}
        run: |
@@ -399,7 +444,7 @@ jobs:
          fi

      - name: Verify notarization (macOS only)
-        if: matrix.platform == 'macos-15'
+        if: inputs.sign && matrix.platform == 'macos-15'
        run: |
          echo "🔍 Verifying notarization status..."
          cd ./frontend/editor/src-tauri/target
@@ -437,7 +482,7 @@ jobs:
      # Verify the MSI AND the inner exe extracted from it are signed.
      # The inner exe is what gets installed on users' machines and what AV scans.
      - name: Verify Windows Code Signature
-        if: matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main'
+        if: inputs.sign && matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && github.ref == 'refs/heads/main'
        shell: pwsh
        run: |
          $allSigned = $true
@@ -106,7 +106,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0
          cache-disabled: true

      - name: Install Task
@@ -155,6 +155,19 @@ jobs:
            echo "platforms=linux/amd64,linux/arm64/v8" >> "$GITHUB_OUTPUT"
          fi

+      # Base-changed PRs build the embedded image with the local docker driver
+      # so the locally-built stirling-pdf-base:pr-test (in the daemon image
+      # store) resolves. A buildx container builder cannot see it and would try
+      # to pull it from a registry, which fails. Single-platform, no gha cache.
+      - name: Build ${{ matrix.docker-rev }} against local base (PR base change)
+        if: github.event_name == 'pull_request' && inputs.docker-base-changed == 'true'
+        run: |
+          DOCKER_BUILDKIT=1 docker build \
+            --build-arg BASE_IMAGE=${{ steps.build-params.outputs.base_image }} \
+            --file ./${{ matrix.docker-rev }} \
+            --tag stirling-pdf-embedded:pr-test \
+            .
+
      - name: Build ${{ matrix.docker-rev }} (Depot)
        if: env.USE_DEPOT == 'true'
        uses: depot/build-push-action@98e78adca7817480b8185f474a400b451d74e287 # v1.16.0
@@ -169,8 +182,10 @@ jobs:
          provenance: true
          sbom: true

+      # Fork PRs that did NOT change the base use the buildx container builder
+      # (multi-platform + gha cache) against the published base image.
      - name: Build ${{ matrix.docker-rev }} (Docker fork fallback)
-        if: env.USE_DEPOT != 'true'
+        if: env.USE_DEPOT != 'true' && inputs.docker-base-changed != 'true'
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
@@ -51,7 +51,7 @@ jobs:
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
        with:
-          gradle-version: 9.5.1
+          gradle-version: 9.6.0

      - name: Build with Gradle
        run: ./gradlew build
@@ -42,18 +42,14 @@ SwaggerDoc.json
 # Runtime storage for uploaded files and user data (not Java source code)
 app/core/storage/

-# Frontend build artifacts copied to Quarkus static resources
-# Generated by `npm build` + the copyFrontendAssets/copyFrontendIndexHtml tasks; never committed.
-# The React bundle goes to META-INF/resources/ (Quarkus serves these over HTTP); index.html is the
-# only generated file in static/ (ReactRoutingController serves it). See app/core/build.gradle.
-app/core/src/main/resources/META-INF/resources/
-app/core/src/main/resources/static/index.html
-# Migration cleanup: earlier builds emitted the whole bundle into static/. Keep these ignored so
-# any stale generated assets left in static/ are not accidentally committed.
+# Frontend build artifacts copied to backend static resources
+# These are generated by npm build and should not be committed
 app/core/src/main/resources/static/assets/
+app/core/src/main/resources/static/index.html
 # Prerendered per-route SPA pages (OG/social-preview), e.g. compress.html. api-landing.html is source.
 app/core/src/main/resources/static/*.html
 !app/core/src/main/resources/static/api-landing.html
+!app/core/src/main/resources/static/mobile-upload.html
 # Prerendered nested-route pages (e.g. settings/people.html)
 app/core/src/main/resources/static/settings/
 app/core/src/main/resources/static/locales/
@@ -71,7 +67,7 @@ app/core/src/main/resources/static/pdfjs/
 app/core/src/main/resources/static/vendor/
 app/core/src/main/resources/static/**/*.gz
 app/core/src/main/resources/static/**/*.br
-# Note: Keep backend-managed files like fonts/, css/, js/, etc.
+# Note: Keep backend-managed files like fonts/, css/, js/, pdfjs/, etc.

 # Gradle
 .gradle
@@ -285,23 +281,8 @@ docs/type3/signatures/

 **/application-dev-local.properties

-# AI agent session/local files - may contain tokens and secrets
+# Claude
 .claude/
-.agents/
-.cursor/
-.codex/
-.opencode/
-.copilot/
-.cline/
-.continue/
-.windsurf/
-.junie/
-.pi/
-.roo/
-.augment/
-.aider*
-CLAUDE.local.md
-skills-lock.json

 # Playwright MCP screenshots / traces
 .playwright-mcp/
@@ -15,7 +15,15 @@ testing/compose/validate-mcp-test.sh:curl-auth-header:92
 testing/compose/validate-mcp-test.sh:curl-auth-header:116

 # Storybook example showing curl with a fake Bearer token placeholder (sk_live_a3f8...).
-frontend/shared/components/CodeBlock.stories.tsx:curl-auth-header:4
+frontend/editor/src/proprietary/ui/CodeBlock.stories.tsx:curl-auth-header:5

 # Truncated placeholder API key in portal docs example (sk_live_8f2c...e10) - not a real secret.
-frontend/portal/src/components/docs/GettingStartedSection.tsx:generic-api-key:31
+frontend/editor/src/portal/components/docs/GettingStartedSection.tsx:generic-api-key:30
+
+# False positive: generic-api-key matches the Java type name "X509Certificate"
+# in a method signature (CreateSignatureBase.resolveSignatureAlgorithm) - not a secret.
+app/core/src/main/java/org/apache/pdfbox/examples/signature/CreateSignatureBase.java:generic-api-key:224
+
+# Supabase publishable key (public by design, RLS-protected) used as a CI fallback
+# default in the tauri-build workflow when the GitHub secret is unset - not a real secret.
+.github/workflows/tauri-build.yml:generic-api-key:402
@@ -25,21 +25,29 @@ tasks:
          AIENGINE_URL: '{{.AIENGINE_URL}}'
          AIENGINE_ENABLED: '{{.AIENGINE_ENABLED}}'
          AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS}}'
+          SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN}}'
+          POLICIES_ENABLED: '{{.POLICIES_ENABLED}}'

  dev:proprietary:
    desc: "Start backend dev server in proprietary mode"
+    # `dotenv:` reads from the root Taskfile's directory (".") because this
+    # subtaskfile is included with `dir: .`. Local overrides in
+    # .env.proprietary.local win over the committed .env.proprietary defaults.
+    dotenv: ['app/.env.proprietary.local', 'app/.env.proprietary']
    ignore_error: true
    vars:
      PORT: '{{.PORT | default "8080"}}'
      AIENGINE_URL: '{{.AIENGINE_URL | default ""}}'
      AIENGINE_ENABLED: '{{.AIENGINE_ENABLED | default "false"}}'
      AIENGINE_TIMEOUTSECONDS: '{{.AIENGINE_TIMEOUTSECONDS | default "120"}}'
+      SECURITY_ENABLELOGIN: '{{.SECURITY_ENABLELOGIN | default ""}}'
+      POLICIES_ENABLED: '{{.POLICIES_ENABLED | default ""}}'
    env:
      SERVER_PORT: '{{.PORT}}'
    cmds:
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .POLICIES_ENABLED}}POLICIES_ENABLED={{.POLICIES_ENABLED}} {{end}}cmd /c ".\gradlew.bat :stirling-pdf:bootRun"'
        platforms: [windows]
-      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}./gradlew :stirling-pdf:bootRun'
+      - cmd: '{{if .AIENGINE_URL}}AIENGINE_URL={{.AIENGINE_URL}} AIENGINE_ENABLED={{.AIENGINE_ENABLED}} AIENGINE_TIMEOUTSECONDS={{.AIENGINE_TIMEOUTSECONDS}} {{end}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{end}}{{if .POLICIES_ENABLED}}POLICIES_ENABLED={{.POLICIES_ENABLED}} {{end}}./gradlew :stirling-pdf:bootRun'
        platforms: [linux, darwin]

  dev:bundled:
@@ -5,6 +5,11 @@ vars:
  # NoClassDefFoundError: jdk/dynalink/Namespace at runtime in get-info-on-pdf and verify-pdf
  JLINK_MODULES: "java.base,java.compiler,java.desktop,java.instrument,java.logging,java.management,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.security.jgss,java.security.sasl,java.sql,java.transaction.xa,java.xml,java.xml.crypto,jdk.crypto.ec,jdk.crypto.cryptoki,jdk.unsupported,jdk.dynalink"

+  # Minimum Java major the bundled JRE must be. Keep in sync with build.gradle
+  # `modernJavaVersion` - the app JAR is compiled for this, so an older runtime
+  # fails at launch with UnsupportedClassVersionError. Enforced by jlink:verify.
+  REQUIRED_JAVA: "25"
+
  # Override via JPDFIUM_PLATFORMS env (csv of platform keys, or 'all').
  JPDFIUM_PLATFORMS:
    sh: |
@@ -102,6 +107,20 @@ tasks:
  jlink:
    desc: "Build backend JAR and create JLink runtime for Tauri"
    deps: [jlink:jar, jlink:runtime]
+    # Runs after the runtime is in place. Lives here (not in jlink:runtime's
+    # cmds) so it still fires when jlink:runtime short-circuits on its `status:`
+    # check and reuses an existing runtime/jre - that reuse path is exactly how
+    # a stale, too-old JRE slips through.
+    cmds:
+      - task: jlink:verify
+
+  jlink:verify:
+    desc: "Fail the build if the bundled JRE is older than the app JAR requires"
+    dir: editor
+    env:
+      REQUIRED_JAVA: "{{.REQUIRED_JAVA}}"
+    cmds:
+      - node scripts/verify-bundled-jre.mjs src-tauri/runtime/jre/release

  jlink:jar:
    desc: "Build backend JAR for Tauri bundling (host-OS natives only by default)"
@@ -127,15 +146,35 @@ tasks:
    cmds:
      - rm -rf runtime/jre
      - mkdir -p runtime
-      - |
-        JLINK_COMPRESS="$(jlink --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
-        jlink \
-          --add-modules {{.JLINK_MODULES}} \
-          --strip-debug \
-          --compress="$JLINK_COMPRESS" \
-          --no-header-files \
-          --no-man-pages \
-          --output runtime/jre
+      # Pin jlink to JAVA_HOME so the bundled JRE matches the JDK the build
+      # uses. Bare `jlink` on PATH can resolve to an older system Java (the
+      # ubuntu runner ships Java 11), producing a runtime jlink:verify rejects.
+      #
+      # jdk.crypto.mscapi (the Windows certificate store / SunMSCAPI provider, used by
+      # hardware-backed cert signing) is a Windows-only module - it only exists in a Windows
+      # JDK's jmods, so it is added on Windows only or jlink fails to resolve it elsewhere.
+      - cmd: |
+          JLINK="${JAVA_HOME:+$JAVA_HOME/bin/}jlink"
+          JLINK_COMPRESS="$("$JLINK" --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
+          "$JLINK" \
+            --add-modules {{.JLINK_MODULES}},jdk.crypto.mscapi \
+            --strip-debug \
+            --compress="$JLINK_COMPRESS" \
+            --no-header-files \
+            --no-man-pages \
+            --output runtime/jre
+        platforms: [windows]
+      - cmd: |
+          JLINK="${JAVA_HOME:+$JAVA_HOME/bin/}jlink"
+          JLINK_COMPRESS="$("$JLINK" --help 2>&1 | grep -q 'zip-\[0-9\]' && echo zip-6 || echo 2)"
+          "$JLINK" \
+            --add-modules {{.JLINK_MODULES}} \
+            --strip-debug \
+            --compress="$JLINK_COMPRESS" \
+            --no-header-files \
+            --no-man-pages \
+            --output runtime/jre
+        platforms: [linux, darwin]
      # jlink emits its files mode 444 (read-only). Tauri's build-script
      # resource copier preserves source permissions when staging
      # `runtime/jre/**/*` into `target/<profile>/runtime/jre/...`, so the
@@ -80,6 +80,12 @@ tasks:
      OPEN: '{{.OPEN | default ""}}'
    env:
      BACKEND_URL: '{{.BACKEND_URL}}'
+      # Dev-only browser-tab label so concurrent worktrees are distinguishable.
+      # Only the worktree folder basename (e.g. "wt1") is exposed — never the
+      # full path, hostname, or user. Consumed at dev-serve time by vite.config
+      # and dropped from production builds.
+      STIRLING_DEV_LABEL:
+        sh: basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
    cmds:
      - npx vite editor --mode {{.MODE}} --port {{.PORT}}{{if .OPEN}} --open{{end}}

@@ -128,12 +134,6 @@ tasks:
      - task: dev:_run
        vars: { MODE: prototypes, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }

-  dev:portal:
-    desc: "Start developer portal dev server"
-    deps: [install]
-    cmds:
-      - npx vite portal --port {{.PORT | default "5173"}}{{if .OPEN}} --open{{end}}
-
  # ============================================================
  # Build
  # ============================================================
@@ -153,8 +153,10 @@ tasks:
  build:proprietary:
    desc: "Build for proprietary mode"
    deps: [prepare]
+    vars:
+      PREVIEW: '{{.PREVIEW | default ""}}'
    cmds:
-      - npx vite build editor --mode proprietary
+      - '{{if .PREVIEW}}VITE_BUILD_FOR_PREVIEW=1 {{end}}npx vite build editor --mode proprietary'

  build:saas:
    desc: "Build for SaaS mode"
@@ -178,11 +180,6 @@ tasks:
    cmds:
      - npx vite build editor --mode prototypes

-  build:portal:
-    desc: "Build developer portal"
-    deps: [install]
-    cmds:
-      - npx vite build portal

  storybook:
    desc: "Start Storybook dev server"
@@ -218,8 +215,8 @@ tasks:
    deps: [install]
    cmds:
      # Globs so dpdm walks the whole tree. dpdm expands the braces itself, so this is
-      # shell-agnostic. Covers editor, portal, and the shared design system.
-      - npx dpdm "editor/src/**/*.{ts,tsx}" "portal/src/**/*.{ts,tsx}" "shared/**/*.{ts,tsx}" --circular --no-warning --no-tree --exit-code circular:1
+      # shell-agnostic. Covers the whole editor tree, including the portal layer.
+      - npx dpdm "editor/src/**/*.{ts,tsx}" --circular --no-warning --no-tree --exit-code circular:1

  lint:fix:
    desc: "Auto-fix lint issues"
@@ -250,17 +247,26 @@ tasks:
    cmds:
      - task: typecheck:proprietary

+  typecheck:_run:
+    internal: true
+    env:
+      CI: '{{ .CI | default "false" }}'
+    cmds:
+      - '{{ if eq .CI "true" }}npx tsc{{ else }}npx tsgo{{ end }} --noEmit --project {{.PROJECT}}'
+
  typecheck:core:
    desc: "Typecheck core build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/core/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/core/tsconfig.json }

  typecheck:proprietary:
    desc: "Typecheck proprietary build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/proprietary/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/proprietary/tsconfig.json }

  typecheck:saas:
    desc: "Typecheck SaaS build variant"
@@ -268,7 +274,8 @@ tasks:
      - task: prepare
        vars: { MODE: saas }
    cmds:
-      - npx tsc --noEmit --project editor/src/saas/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/saas/tsconfig.json }

  typecheck:desktop:
    desc: "Typecheck desktop build variant"
@@ -276,37 +283,36 @@ tasks:
      - task: prepare
        vars: { MODE: desktop }
    cmds:
-      - npx tsc --noEmit --project editor/src/desktop/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/desktop/tsconfig.json }

  typecheck:cloud:
    desc: "Typecheck cloud shared layer (standalone)"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/cloud/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/cloud/tsconfig.json }

  typecheck:scripts:
    desc: "Typecheck scripts"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/scripts/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/scripts/tsconfig.json }

  typecheck:prototypes:
    desc: "Typecheck prototypes build variant"
    deps: [prepare]
    cmds:
-      - npx tsc --noEmit --project editor/src/prototypes/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/prototypes/tsconfig.json }

  typecheck:portal:
    desc: "Typecheck developer portal build variant"
    deps: [install]
    cmds:
-      - npx tsc --noEmit --project portal/tsconfig.json
-
-  typecheck:shared:
-    desc: "Typecheck the shared design system"
-    deps: [install]
-    cmds:
-      - npx tsc --noEmit --project shared/tsconfig.json
+      - task: typecheck:_run
+        vars: { PROJECT: editor/src/portal/tsconfig.json }

  typecheck:all:
    desc: "Typecheck all build variants"
@@ -319,7 +325,6 @@ tasks:
      - task: typecheck:scripts
      - task: typecheck:prototypes
      - task: typecheck:portal
-      - task: typecheck:shared

  # ============================================================
  # Quality Gate
@@ -348,7 +353,6 @@ tasks:
      - task: lint
      - task: format:check
      - task: build
-      - task: build:portal
      - task: test
      - task: storybook:build

@@ -358,6 +362,11 @@ tasks:

  test:
    desc: "Run tests"
+    cmds:
+      - task: test:editor
+
+  test:editor:
+    desc: "Run editor tests"
    deps: [prepare]
    cmds:
      - npx vitest run --root editor
@@ -393,6 +402,23 @@ tasks:
  # Code Generation
  # ============================================================

+  tool-models:
+    desc: "Generate tool API types from the Java OpenAPI spec"
+    deps: [install, ":backend:swagger"]
+    cmds:
+      - npx tsx editor/scripts/generate-tool-api-types.mts --spec ../SwaggerDoc.json --output editor/src/core/types/toolApiTypes.ts
+    sources:
+      - editor/scripts/generate-tool-api-types.mts
+      - ../SwaggerDoc.json
+    generates:
+      - editor/src/core/types/toolApiTypes.ts
+
+  tool-models:check:
+    desc: "Fail if committed tool API types are out of date"
+    deps: [install, ":backend:swagger"]
+    cmds:
+      - npx tsx editor/scripts/generate-tool-api-types.mts --spec ../SwaggerDoc.json --output editor/src/core/types/toolApiTypes.ts --check
+
  licenses:generate:
    desc: "Generate frontend license report"
    deps: [install]
@@ -406,7 +432,7 @@ tasks:
  clean:
    desc: "Clean build artifacts and caches"
    cmds:
-      - cmd: powershell rm -Recurse -Force -ErrorAction SilentlyContinue node_modules/.vite, editor/dist, dist, dist-portal
+      - cmd: powershell rm -Recurse -Force -ErrorAction SilentlyContinue node_modules/.vite, editor/dist, dist
        platforms: [windows]
-      - cmd: rm -rf node_modules/.vite editor/dist dist dist-portal
+      - cmd: rm -rf node_modules/.vite editor/dist dist
        platforms: [linux, darwin]
@@ -4,8 +4,6 @@ version: '3'
 # pre-commit hook (.pre-commit-config.yaml) and CI (pre_commit.yml) both call.

 vars:
-  GITLEAKS: '8.30.0'
-
  # File selections as git pathspecs: git does the include/exclude matching, so
  # there is no grep/xargs and it behaves identically on every platform.
  PY_FILES: >-
@@ -43,7 +41,9 @@ vars:
    ':(exclude).github/workflows/*'
  LOCALE_TOML: 'frontend/editor/public/locales/*/translation.toml'

-  GITLEAKS_BIN: '.task/bin/gitleaks-{{.GITLEAKS}}{{if eq OS "windows"}}.exe{{end}}'
+  # gitleaks is pinned + checksum-verified by scripts/pre-commit/install_gitleaks.py,
+  # which owns the version and caches the binary here.
+  GITLEAKS_BIN: '.task/bin/gitleaks{{if eq OS "windows"}}.exe{{end}}'

 tasks:
  default:
@@ -84,22 +84,13 @@ tasks:
      - test -d scripts/pre-commit/.venv

  clean:
-    desc: "Remove the cache/build artifacts"
+    desc: "Remove the cached gitleaks binary and the tool virtualenv"
    cmds:
-      - task: '{{if eq OS "windows"}}clean-windows{{else}}clean-unix{{end}}'
-
-  clean-unix:
-    internal: true
-    cmds:
-      - rm -rf scripts/pre-commit/.venv .task/bin/gitleaks-*
-
-  # On Windows, use PowerShell so it matches the same paths and tolerates absent
-  # files without erroring.
-  clean-windows:
-    internal: true
-    ignore_error: true
-    cmds:
-      - powershell -NoProfile -Command "Remove-Item -Recurse -Force -ErrorAction SilentlyContinue scripts/pre-commit/.venv, .task/bin/gitleaks-*"
+      - cmd: rm -rf scripts/pre-commit/.venv .task/bin/gitleaks
+        platforms: [linux, darwin]
+      - cmd: cmd /c "rmdir /s /q scripts\pre-commit\.venv & del /q .task\bin\gitleaks.exe"
+        platforms: [windows]
+        ignore_error: true

  # Individual checks (hidden from `task --list`, but callable, e.g.
  # `task pre-commit:toml-sort FIX=1`). Pass FIX=1 to auto-fix where supported.
@@ -116,7 +107,7 @@ tasks:
  codespell:
    deps: [install]
    cmds:
-      - uv run --project scripts/pre-commit --no-sync codespell --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment,vertx --quiet-level=2 $(git ls-files {{.SPELL_FILES}})
+      - uv run --project scripts/pre-commit --no-sync codespell --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment --quiet-level=2 $(git ls-files {{.SPELL_FILES}})

  toml-sort:
    deps: [install]
@@ -125,7 +116,7 @@ tasks:

  whitespace:
    cmds:
-      - uv run --no-project python scripts/pre-commit/whitespace.py {{if .FIX}}--fix {{end}}$(git ls-files {{.WS_FILES}})
+      - uv run --no-project python scripts/pre-commit/whitespace.py {{if .FIX}}--fix {{end}}{{.WS_FILES}}

  gitleaks:
    deps: [gitleaks-bin]
@@ -137,23 +128,6 @@ tasks:

  gitleaks-bin:
    internal: true
-    desc: "Ensure the pinned gitleaks binary is cached in .task/bin"
-    status:
-      - test -f {{.GITLEAKS_BIN}}
-    vars:
-      GL_ARCH: '{{if eq ARCH "amd64"}}x64{{else if eq ARCH "arm64"}}arm64{{else if eq ARCH "386"}}x32{{else}}{{ARCH}}{{end}}'
-      GL_PLATFORM: '{{OS}}_{{.GL_ARCH}}'
-      GL_URL: 'https://github.com/gitleaks/gitleaks/releases/download/v{{.GITLEAKS}}/gitleaks_{{.GITLEAKS}}_{{.GL_PLATFORM}}'
-      # SHA-256 of each release asset, from gitleaks_{{.GITLEAKS}}_checksums.txt.
-      GL_SHA: >-
-        {{if eq .GL_PLATFORM "linux_x64"}}79a3ab579b53f71efd634f3aaf7e04a0fa0cf206b7ed434638d1547a2470a66e
-        {{- else if eq .GL_PLATFORM "linux_arm64"}}b4cbbb6ddf7d1b2a603088cd03a4e3f7ce48ee7fd449b51f7de6ee2906f5fa2f
-        {{- else if eq .GL_PLATFORM "darwin_x64"}}ca221d012d247080c2f6f61f4b7a83bffa2453806b0c195c795bbe9a8c775ed5
-        {{- else if eq .GL_PLATFORM "darwin_arm64"}}b251ab2bcd4cd8ba9e56ff37698c033ebf38582b477d21ebd86586d927cf87e7
-        {{- else if eq .GL_PLATFORM "windows_x64"}}54fe94f644b832dd08e8c3a5915efb3bfa862386d59fb27ca0792cb687a83573
-        {{- end}}
+    desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
    cmds:
-      - cmd: bash scripts/pre-commit/install-gitleaks.sh "{{.GL_URL}}.tar.gz" "{{.GL_SHA}}" "{{.GITLEAKS_BIN}}"
-        platforms: [linux, darwin]
-      - cmd: powershell -NoProfile -File scripts/pre-commit/install-gitleaks.ps1 -Url "{{.GL_URL}}.zip" -Sha "{{.GL_SHA}}" -Dest "{{.GITLEAKS_BIN}}"
-        platforms: [windows]
+      - uv run --no-project python scripts/pre-commit/install_gitleaks.py
@@ -139,7 +139,8 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie

 #### Environment Variables
 - All `VITE_*` variables must be declared in the appropriate committed env file:
-  - `frontend/editor/.env` — core, proprietary, and shared vars
+  - `frontend/editor/.env` — core and shared vars (base, loaded in every mode)
+  - `frontend/editor/.env.proprietary` — proprietary-only vars, e.g. the admin portal's SaaS/account-link keys (layered on top of `.env` in proprietary mode)
  - `frontend/editor/.env.saas` — SaaS-only vars (layered on top of `.env` in SaaS mode)
  - `frontend/editor/.env.desktop` — desktop (Tauri)-only vars (layered on top of `.env` in desktop mode)
 - These files are committed to Git and must not contain private keys
@@ -152,7 +153,7 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie
 #### Import Paths - CRITICAL
 **ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.

-For a broader explanation of the frontend layering and override architecture, see [frontend/editor/DeveloperGuide.md](frontend/editor/DeveloperGuide.md).
+For a broader explanation of the frontend layering and override architecture, read @frontend/editor/DeveloperGuide.md

 ```typescript
 // ✅ CORRECT - Use @app/* for all imports
@@ -452,6 +453,7 @@ The frontend is organized with a clear separation of concerns:

 - **CRITICAL**: Always update translations in `en-US` only - all other languages (including `en-GB`) are handled separately
 - Translation files are located in `frontend/editor/public/locales/`
+- After changing any translation file, run `task pre-commit:fix`

 ## Important Notes

@@ -92,7 +92,7 @@ Visit the [Lombok website](https://projectlombok.org/setup/) for installation in

 5. Add environment variable
 For local testing, you should generally be testing the full 'Security' version of Stirling PDF. To do this, you must add the environment flag DISABLE_ADDITIONAL_FEATURES=false to your system and/or IDE build/run step.
-5. **Frontend Setup (Required for Stirling 2.0)**
+6. **Frontend Setup (Required for Stirling 2.0)**
   Navigate to the frontend directory and install dependencies using npm.

 ### Verify Setup
@@ -275,7 +275,7 @@ Stirling-PDF uses different Docker images for various configurations. The build
 1. Set the security environment variable:

   ```bash
-   export DISABLE_ADDITIONAL_FEATURES=true  # or false for to enable login and security features for builds
+   export DISABLE_ADDITIONAL_FEATURES=true  # or false to enable login and security features for builds
   ```

 2. Build the project:
@@ -305,7 +305,7 @@ Stirling-PDF uses different Docker images for various configurations. The build
   docker build --no-cache --pull --build-arg VERSION_TAG=alpha -t stirlingtools/stirling-pdf:latest-fat -f ./Dockerfile.fat .
   ```

-Note: The `--no-cache` and `--pull` flags ensure that the build process uses the latest base images and doesn't use cached layers, which is useful for testing and ensuring reproducible builds. however to improve build times these can often be removed depending on your usecase
+Note: The `--no-cache` and `--pull` flags ensure that the build process uses the latest base images and doesn't use cached layers, which is useful for testing and ensuring reproducible builds. However, to improve build times these can often be removed depending on your use case

 ## 7. Testing

@@ -20,8 +20,8 @@ if that directory exists, is licensed under the license defined in "frontend/edi
 if that directory exists, is licensed under the license defined in "frontend/editor/src/cloud/LICENSE".
 * All content that resides under the "frontend/editor/src/prototypes/" directory of this repository,
 if that directory exists, is licensed under the license defined in "frontend/editor/src/prototypes/LICENSE".
-* All content that resides under the "frontend/portal/" directory of this repository,
-if that directory exists, is licensed under the license defined in "frontend/portal/LICENSE".
+* All content that resides under the "frontend/editor/src/portal/" directory of this repository,
+if that directory exists, is licensed under the license defined in "frontend/editor/src/portal/LICENSE".
 * Content outside of the above mentioned directories or restrictions above is
 available under the MIT License as defined below.

@@ -1,563 +0,0 @@
-# Stirling-PDF: Spring Boot → Quarkus Migration — Continuation Handoff
-
-> **Purpose:** everything needed to resume this migration in a fresh session. Read this top-to-bottom
-> before touching anything. Companion doc `migration-report.md` has the higher-level summary; this
-> file is the working/continuation guide with the concrete state, commands, fixed bugs, remaining
-> bugs, and the recurring patterns you need to apply.
-
---
-
-## 0. TL;DR status
-
- **2026-06-19 — merged `main` (136 commits) into `migration/run-02`.** Resolved 69 conflicts and
-  did **full Spring removal + Quarkus migration of every newly pulled-in file** (36 Spring-bearing
-  files: 21 proprietary + 15 saas). Net effect on main: legacy credits engine deleted (#6687,
-  replaced by PAYG #6589); the proprietary **policy** subsystem and the new **PAYG** subsystem
-  migrated to CDI/JAX-RS/Panache. Verified: 0 conflict markers, 0 `org.springframework` imports in
-  any main source. **`core` + `proprietary` compile; `proprietary` Quarkus-augments + boots + serves
-  real traffic; `saas` now compiles AND augments too** (previously ~28 CDI issues). Cross-file fix:
-  `PolicyExecutor`/`DownstreamEntitlementError` now carry HTTP status+body via
-  `jakarta.ws.rs.WebApplicationException` (was Spring `RestClientResponseException`);
-  `AiWorkflowService.paygLimitResponseOrNull` rewired to it. Repo `save()` shim added to the Panache
-  repos whose callers/tests expect Spring-Data `save()`.
- **Branch:** `migration/run-01` (all work committed locally, **nothing pushed** — `origin` is the
-  public `Stirling-Tools/Stirling-PDF` repo; do not push without the owner's say-so).
- **Default flavor (`proprietary`):** compiles, Quarkus-augments, boots, and serves real traffic in
-  Docker. ✅
- **Cucumber API e2e (full-tool Docker image):** baselines, newest first:
-  - **Run 2 (login off, this session's fixes, no JWT mechanism): 223 / 258 pass**, 35 failed, 80
-    skipped. Up from the prior **183 / 258** baseline (+40). Eliminated buckets: split
-    `PDF corrupted` 8→0, `FileAlreadyExists` 8→0, `Admin login failed (500)` 17→0.
-  - **Run 3 (login off + `V2=true` + the new JWT Bearer mechanism): the 80 JWT/admin scenarios now
-    RUN (0 skipped)** because the `login → /me` probe passes. See §6.E / "Session 2". Final tally
-    recorded in §9.
- **Stack:** Quarkus 3.33.2 LTS, **Java 25** (mandatory — see §2), Hibernate ORM Panache,
-  quarkus-rest (RESTEasy Reactive), quarkus-oidc, quarkus-undertow (servlet, for filters), OpenSAML 5.
- **`saas` flavor:** compiles but full augmentation has ~28 CDI issues (design-level follow-up).
- **JWT Bearer login:** ✅ works end-to-end (token issue + validate → `SecurityIdentity`, role
-  mapping, `@RolesAllowed`). **OAuth2/OIDC + SAML2 SSO:** ✅ both work end-to-end against the
-  `testing/compose` Keycloak stacks; `validate-oauth-test.sh` and `validate-saml-test.sh` both pass
-  (see §6.F). The default e2e Docker image + build helper are committed at `docker/quarkus/` (§3.3).
-
---
-
-## 1. Repo / flavor layout
-
-Multi-module Gradle build, three selectable flavors via `STIRLING_FLAVOR` (or `ENABLE_SAAS` /
-`DISABLE_ADDITIONAL_FEATURES`):
-
-| Flavor | Modules included | Notes |
-|--------|------------------|-------|
-| `core` | `:common`, `:stirling-pdf` (core) | OSS only |
-| `proprietary` (**default**) | + `:proprietary` | what all the e2e work targets |
-| `saas` | + `:saas` | opt-in: `STIRLING_FLAVOR=saas`; not yet augmentable |
-
-Module → directory:
- `:stirling-pdf` → `app/core` (the runnable Quarkus app; applies the `io.quarkus` gradle plugin)
- `:common` → `app/common` (library; CDI beans / JAX-RS / entities)
- `:proprietary` → `app/proprietary` (library)
- `:saas` → `app/saas` (library, only on saas flavor)
-
-Quarkus only discovers beans/entities in dependency jars that carry a **Jandex index**; the library
-modules are indexed via `quarkus.index-dependency.*` in
-`app/core/src/main/resources/application.properties`.
-
---
-
-## 2. Java 25 is mandatory (don't regress this)
-
- The build uses a **JDK 25 toolchain** (`build.gradle` `subprojects { java { toolchain = 25 } }`).
- The app is compiled to **class-file version 69 (Java 25)** — it will NOT run on JDK 21.
- **The host's default `java` on the PATH is JDK 21.** Use the toolchain JDK 25 explicitly:
-  - `JAVA_HOME` points to a Temurin 25 JDK (`C:\Users\systo\scoop\apps\temurin25-jdk\current`).
-  - In Git Bash run the jar with `"$JAVA_HOME/bin/java" -jar ...` (host `java` = 21 → `UnsupportedClassVersionError`).
- The Docker base image `stirlingtools/stirling-pdf-base:1.0.2` ships **Temurin 25.0.2** — so the
-  container runtime is JDK 25 already. Keep it that way; do not switch the base image to a JRE < 25.
- Gradle build images / CI also pin `gradle:9.3.1-jdk25` and `eclipse-temurin:25-jre-noble`.
-
---
-
-## 3. Build → package → run → test (the exact loop)
-
-### 3.1 Build the runnable jar
-```bash
-./gradlew :stirling-pdf:quarkusBuild -x test --console=plain
-```
- Produces the **runnable uber-jar** at: `app/core/build/stirling-pdf-2.12.0-runner.jar`
-  - `Main-Class: stirling.software.SPDF.SPDFApplication`.
- ⚠️ **GOTCHA:** `app/core/build/libs/stirling-pdf-2.12.0.jar` is the *plain* (non-runnable) jar with
-  an empty manifest. The upstream `docker/embedded/Dockerfile` copies `libs/*.jar` — that's now the
-  WRONG jar. Always use the `-runner.jar`. (`quarkus.package.jar.type=uber-jar` is set in
-  application.properties.)
- ⚠️ If the build fails with `Unable to delete .../-runner.jar`, a previous `java -jar` is still
-  holding it. Kill it: PowerShell `Get-CimInstance Win32_Process -Filter "Name='java.exe'" | ?{ $_.CommandLine -like '*stirling-pdf-2.12.0-runner*' } | %{ Stop-Process -Id $_.ProcessId -Force }`.
-
-### 3.2 Run standalone for a quick boot check (host JDK 25, fastest)
-```bash
-SECURITY_ENABLELOGIN=false QUARKUS_HTTP_PORT=8095 \
-QUARKUS_DATASOURCE_JDBC_URL="jdbc:h2:mem:t;DB_CLOSE_DELAY=-1;MODE=PostgreSQL" \
-nohup "$JAVA_HOME/bin/java" -jar app/core/build/stirling-pdf-2.12.0-runner.jar > /tmp/boot.log 2>&1 &
-# success line in log: "Stirling-PDF running on port: 8095"  (this app does NOT print Quarkus' "Listening on")
-```
-Health: `curl localhost:8095/api/v1/info/status` → `{"version":"2.12.0","status":"UP"}`.
-
-### 3.3 The "normal" Docker image (full tools) — what the cucumber e2e uses
-The upstream `docker/embedded/Dockerfile` is **Spring-Boot-specific** (uses
-`java -Djarmode=tools -jar app.jar extract --layers` + `spring-boot-loader` layers) and does NOT
-work with the Quarkus jar. For e2e I built an ad-hoc image layering the runner-jar on the prebuilt
-**base image** (which already has Java 25 + LibreOffice + Tesseract + qpdf + Ghostscript + Calibre +
-Python). **This Dockerfile lives in a temp dir and needs to be committed into the repo** (see §6 TODO).
-
-Build context (currently ephemeral at the bash path `/tmp/sp-full` =
-`C:\Users\systo\AppData\Local\Temp\sp-full`): `app.jar` (the runner jar), `fonts/*.ttf`, and this
-Dockerfile:
-```dockerfile
-FROM stirlingtools/stirling-pdf-base:1.0.2          # Java 25 + all tools
-WORKDIR /app
-COPY --chown=1000:1000 app.jar /app/app.jar
-COPY fonts/*.ttf /usr/share/fonts/truetype/
-RUN fc-cache -f \
-    && mkdir -p /storage \
-    && chown stirlingpdfuser:stirlingpdfgroup /storage /app \
-    && ln -sf /configs /app/configs && ln -sf /logs /app/logs \
-    && ln -sf /customFiles /app/customFiles && ln -sf /pipeline /app/pipeline \
-    && ln -sf /storage /app/storage \
-    && chown -h stirlingpdfuser:stirlingpdfgroup /app/configs /app/logs /app/customFiles /app/pipeline /app/storage
-ENV HOME=/home/stirlingpdfuser STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
-    TMPDIR=/tmp/stirling-pdf TEMP=/tmp/stirling-pdf TMP=/tmp/stirling-pdf \
-    SAL_TMP=/tmp/stirling-pdf/libre DBUS_SESSION_BUS_ADDRESS=/dev/null \
-    JAVA_OPTS="-XX:+UseG1GC -Djava.awt.headless=true" \
-    QUARKUS_HTTP_HOST=0.0.0.0 QUARKUS_HTTP_PORT=8080
-EXPOSE 8080/tcp
-STOPSIGNAL SIGTERM
-USER stirlingpdfuser
-ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]
-```
-Stage + build + run:
-```bash
-# stage (bash /tmp resolves to %LOCALAPPDATA%\Temp)
-mkdir -p /tmp/sp-full/fonts
-cp app/core/build/stirling-pdf-2.12.0-runner.jar /tmp/sp-full/app.jar
-cp app/core/src/main/resources/static/fonts/*.ttf /tmp/sp-full/fonts/
-# (write the Dockerfile above to C:\Users\systo\AppData\Local\Temp\sp-full\Dockerfile)
-cd /tmp/sp-full && docker build -t stirling-pdf-quarkus:full .
-docker rm -f sp-e2e
-docker run -d --name sp-e2e -p 8080:8080 \
-  -e SECURITY_ENABLELOGIN=false -e METRICS_ENABLED=true \
-  -e SYSTEM_DEFAULTLOCALE=en-US -e SYSTEM_MAXFILESIZE=100 \
-  stirling-pdf-quarkus:full
-# wait for: curl localhost:8080/api/v1/info/status == 200
-```
-Base image was pulled with `docker pull stirlingtools/stirling-pdf-base:1.0.2`.
-
-### 3.4 Run the cucumber (behave) suite
- Tests live in `testing/cucumber/` — Python **behave** (BDD), pure HTTP via `requests` (no browser).
- **Target URL is hardcoded `http://localhost:8080`** in `features/steps/step_definitions.py`
-  (lines ~584/592/601) and `features/environment.py`. Easiest is to run the app on 8080.
- `behave.ini` excludes `features/(enterprise|payg)` and tag `~@manual` by default.
- `environment.py` probes `/api/v1/auth/login` (admin/stirling) at startup; if JWT/login is not
-  functional (login disabled / V2) it **skips** all `@jwt @login @me @refresh @token @mfa @apikey
-  @admin_settings @audit @signature @team @user_mgmt` scenarios → ~80 skips. That's expected.
-
-Install deps + run:
-```bash
-cd testing/cucumber
-pip install -r requirements.txt        # behave, requests, pypdf, reportlab, psycopg, pillow, ...
-TEST_CONTAINER_NAME=sp-e2e TEST_REPORT_DIR=/tmp python -m behave --no-capture --format progress2
-# single feature:  python -m behave features/general.feature
-# one scenario:    python -m behave features/general.feature:22 --format plain
-```
-The official CI driver is `testing/test.sh` (builds images via `docker/embedded/Dockerfile.*` and
-runs behave) — it will need the Dockerfile fixes from §6 before it works on Quarkus.
-
---
-
-## 4. Bugs FIXED this session (with the *why*, so you can spot siblings)
-
-### Session 2 (branch `claude/happy-chaplygin-906fe7`, fast-forwarded from `migration/run-01`)
-
-Newest first. These took the login-off suite **183 → 223** and then wired JWT so the **80 skipped
-JWT/admin scenarios run** (run 3, §9):
-
-1. **JWT Bearer → `SecurityIdentity` was never populated** → every user-scoped endpoint that reads
-   `SecurityIdentity.getPrincipal()` (folders, files, `/me`, user/team settings…) failed, and the
-   `environment.py` probe (`login → /me`) failed so ~80 scenarios auto-skipped. Added a custom
-   `HttpAuthenticationMechanism` + `IdentityProvider` in
-   `app/proprietary/.../security/identity/` (`JwtBearerAuthenticationMechanism`,
-   `JwtTokenIdentityProvider`): extract `Authorization: Bearer`, validate via the existing
-   `JwtService` (jjwt + keystore), build a `QuarkusSecurityIdentity` and map the `role` claim
-   (`ROLE_ADMIN` → also add `ADMIN` so `@RolesAllowed("ADMIN")` matches). Returns no identity when
-   no Bearer is present, so the X-API-KEY / login-off open-endpoint path is unaffected. **This is the
-   IdentityProvider that ~10 `// TODO: Migration required` comments across the security/storage code
-   asked for.** Run with `V2=true`.
-2. **No admin user was ever created** → all logins failed "No user found: admin". `InitialSecuritySetup`
-   was a Spring `@Component` (eagerly constructed, `@PostConstruct` ran every boot); the migration
-   made it a lazy `@ApplicationScoped` whose `@PostConstruct` never ran. Restored eager init via
-   `@Observes StartupEvent`. **Pattern: any migrated `@PostConstruct`-on-`@ApplicationScoped` startup
-   bean with no injector is dead code — grep for them.**
-3. **Eager init then exposed two latent bugs** (both real, both now fixed):
-   - `@Produces @ApplicationScoped DataSource` → Arc generated the client proxy in the JDK-sealed
-     `javax.sql` package → `NoClassDefFoundError` on first use. Fix: `@Singleton` (pseudo-scope, no
-     proxy). **Audit other `@Produces @ApplicationScoped` whose return type is a `java.*`/`javax.*`
-     type.**
-   - Panache `persist()` in the `StartupEvent` observer ran with no transaction (Spring Data wrapped
-     `save()` implicitly). Fix: `@Transactional` on the observer.
-4. **Login returned 500 instead of 401** for unknown user / bad password. `CustomUserDetailsService`
-   threw `IllegalArgumentException`, but `AuthController` catches the migration shim
-   `stirling.software.common.security.UsernameNotFoundException`. Made the service throw the shim
-   type. **Sibling: the locked-account path still throws `IllegalStateException` — wire it similarly
-   when needed.**
-5. **`@Transactional` missing on policy-store reads** (`JpaPolicyStore.all()`,
-   `findByTriggerType()`) → the scheduled folder-watch/schedule triggers threw
-   `ContextNotActiveException` off-request (§6.C). The reads are reached via the CDI proxy so a
-   method-level `@Transactional` applies even from the background virtual-thread executor.
-6. **Split scenarios sent a duplicate `fileInput` text part** (`| fileInput | fileInput |` in
-   `general.feature`) alongside the file part; Quarkus `@RestForm FileUpload` bound the *text* part
-   ("fileInput", 9 bytes) → "PDF corrupted". Spring ignored the stray part. Removed the redundant
-   rows (the file is already attached via the generate step). **Real clients send one part, so this
-   is a test artifact, not a server tolerance gap worth chasing.**
-7. **e2e Docker build is now first-class:** `docker/quarkus/Dockerfile` (+ `README.md`,
-   `build-and-run.sh`) layers the runner-jar on the base image, and `.dockerignore` re-includes
-   `app/core/build/*-runner.jar` (it was excluded by `**/build/`, so a clean `docker build` had been
-   silently relying on BuildKit cache).
-
-### Session 1
-
-1. **`MultipartFile.transferTo` didn't overwrite** (`a30d524ec`).
-   `app/common/.../model/MultipartFile.java` + `.../model/multipart/FileUploadMultipartFile.java`
-   used `Files.copy(in, dest)` without `REPLACE_EXISTING`. Callers do
-   `Files.createTempFile(...)` (creates the file) then `transferTo(thatPath)` → `FileAlreadyExistsException`.
-   Spring's `transferTo` overwrites. **Fixed** by adding `StandardCopyOption.REPLACE_EXISTING`.
-   Fixes the whole class of `/api/v1/misc/*` failures (scanner-effect, replace-invert, ocr,
-   update-metadata, unlock-pdf-forms, repair, extract-image-scans, add-page-numbers, …).
-
-2. **`maxDPI` defaulted to 0** (`a30d524ec`).
-   `ApplicationProperties.System.maxDPI` is a primitive `int` (→ 0 when not bound from settings).
-   Every DPI guard (`dpi > maxDPI`) then failed with *"maximum safe limit of 0"*. The
-   `settings.yml.template` default is 500. **Fixed** by `private int maxDPI = 500;`.
-   ⚠️ Root cause hint: this strongly suggests **settings.yml → ApplicationProperties config binding
-   is incomplete in the Quarkus migration**. Other primitive/unset fields may also be silently
-   wrong. Worth a dedicated audit (see §5).
-
-3. **Request-path `HttpServletRequest` → `UT000048` "No request is currently active"** (`860bd6e63`,
-   `4b572852c`). This was the dominant blocker. `quarkus-rest` (RESTEasy Reactive) runs handlers on
-   reactive/worker threads where the undertow servlet request context is NOT active, so ANY
-   `HttpServletRequest.getX()` throws. Fixed in:
-   - `GlobalExceptionHandler` (an `ExceptionMapper` that threw while handling *every* error, masking
-     the real cause) → `@Context UriInfo` + exception-safe `requestUri()`.
-   - `ControllerAuditAspect`, `AuditAspect` → route through the already-guarded
-     `AuditService.getCurrentRequest()` (returns null off-request) + a guarded `safeResponse()`.
-   - `AutoJobAspect`, `JobExecutorService` → inject `io.quarkus.vertx.http.runtime.CurrentVertxRequest`,
-     read query-param/method/path/attributes from the Vert.x request, degrade to null/no-op.
-   - `AuthController`, `UserController`, `ConfigController` → `@Context UriInfo` / `HttpHeaders` /
-     `io.vertx.core.http.HttpServerRequest`.
-   This unblocked the entire `@AutoJobPostMapping` chain (most PDF endpoints).
-
-4. **License singleton PK race** (`860bd6e63`). `UserLicenseSettings` has a manually-assigned
-   `@Id = 1L`. Spring Data `save()` on a non-new (pre-set-id) entity does a **MERGE (upsert)**; the
-   migration converted it to `persist()` (INSERT-only). The startup license sync raced the first
-   request, both inserted id=1 → `JdbcSQLIntegrityConstraintViolationException` → app crash. **Fixed**
-   in `UserLicenseSettingsService.getOrCreateSettings()` with a JVM lock +
-   `io.quarkus.narayana.jta.QuarkusTransaction.requiringNew()` create-once, then reload into the
-   caller's tx. **⚠️ This `save()`→`persist()`-should-be-`merge()` bug almost certainly exists for
-   OTHER manually-`@Id`'d entities — audit them (see §5).**
-
-5. **App couldn't boot without Redis** (`4665cceeb`).
-   - `quarkus.oidc.enabled=false` default (quarkus-oidc aborts startup without `auth-server-url`;
-     re-enable for an OAuth2 deployment).
-   - Valkey backplane beans eagerly injected the inactive `RedisDataSource`. Gated all 7 with
-     **build-time** `@io.quarkus.arc.properties.IfBuildProperty(name="cluster.backplane", stringValue="valkey")`
-     (NOT `@LookupIfProperty` — that leaves the bean in the build, so `RedisDataSource` still has a
-     consumer and Quarkus emits an eager startup observer that fails). Plus
-     `quarkus.redis.health.enabled=false`.
-
-6. **Runtime boot fixes** (`20b25ad76`): `quarkus.hibernate-orm.mapping.format.global=ignore` (JSON
-   columns), Quartz cron `0 0 0 * * MON` → `0 0 0 ? * MON` (Quartz rejects `*` in both day fields),
-   `@Scheduled(every="7d")` → `"P7D"`, `quarkus.arc.fail-on-intercepted-private-method=false`.
-
-7. **CDI augmentation** (`185ac88b3`): interceptor bindings made `@InterceptorBinding`
-   (`@EnterpriseEndpoint`, `@PremiumEndpoint`), a `tools.jackson.databind.ObjectMapper` producer
-   added in `AppConfig` (92 injection points), ambiguous beans resolved (`@DefaultBean`),
-   `Optional<X>`→`Instance<X>`, collection `List<X>`→`@All List<X>`, nested `SAML2` config producer.
-
-8. **Test layer** (`d51228af6`): a content-based exclude in root `build.gradle subprojects` skips any
-   test still importing `org.springframework`/`com.nimbusds` (self-maintaining), plus an explicit
-   list for tests asserting changed production signatures.
-
---
-
-## 5. Recurring patterns / gotchas (apply these everywhere)
-
- **HttpServletRequest is poison on reactive threads.** ~35 main-source files still reference
-  `HttpServletRequest` (see §6 list). For each in the request path, replace with:
-  - path/URI → `@Context jakarta.ws.rs.core.UriInfo` (`uriInfo.getRequestUri().getPath()`), or in a
-    non-JAX-RS bean inject `io.quarkus.vertx.http.runtime.CurrentVertxRequest`
-    (`currentVertxRequest.getCurrent().request().path()`), guarded in try/catch returning null/"".
-  - headers → `@Context jakarta.ws.rs.core.HttpHeaders` (`getHeaderString(name)`).
-  - remote addr / method → `@Context io.vertx.core.http.HttpServerRequest`.
-  - request attributes (`get/setAttribute`) → Vert.x `RoutingContext.get/put` via `CurrentVertxRequest`.
-  - In services that already have a guarded accessor, reuse `AuditService.getCurrentRequest()`.
- **Spring `save()` → Panache:** if the entity uses `@GeneratedValue` (new on insert) → `persist()`.
-  If the entity has a **manually-assigned `@Id`** (caller sets the id, "upsert" semantics) →
-  `getEntityManager().merge()` (NOT `persist()`), and consider concurrency.
- **Config gating:** runtime selection that must REMOVE a bean (so its deps don't get wired) →
-  build-time `@IfBuildProperty`/`@UnlessBuildProperty`. `@LookupIfProperty` only disables *lookup*,
-  the bean and its injection points stay in the build.
- **`quarkus.*` build-time props** (e.g. `quarkus.oidc.enabled`, `quarkus.hibernate-orm.*`,
-  `quarkus.arc.*`) can't be overridden by env at runtime — they require a rebuild.
- **settings.yml binding is suspect** (see maxDPI). Audit `ApplicationProperties` for primitive
-  fields that need non-zero/template defaults, and verify the settings.yml → ApplicationProperties
-  binding path actually works in Quarkus (it was Spring `@ConfigurationProperties` + a custom YAML
-  property source — see the `YamlPropertySourceFactory` / `ConfigInitializer` TODOs).
- **Augment gate:** `compileJava` passing ≠ working. `./gradlew :stirling-pdf:quarkusBuild` surfaces
-  CDI wiring errors; only *running* surfaces the `UT000048` / config / race bugs. Always run.
- **Jackson 2 vs 3 coexist:** ~100 files use `tools.jackson` (Jackson 3, from Spring Boot 4); REST
-  (de)serialization uses Quarkus' Jackson 2. Don't "fix" `tools.jackson` imports — there's a producer.
-
---
-
-## 6. REMAINING WORK (prioritized)
-
-### A. Make the e2e Docker build first-class
- [x] **DONE (Session 2):** `docker/quarkus/Dockerfile` (+ `README.md`, `build-and-run.sh`) committed,
-      uses the runner-jar, copies fonts; `.dockerignore` re-includes `app/core/build/*-runner.jar`.
- [ ] Rewrite/replace `docker/embedded/Dockerfile`, `Dockerfile.fat`, `Dockerfile.ultra-lite` for
-      Quarkus: drop the Spring-Boot `-Djarmode=tools extract --layers` + `spring-boot-loader` layer
-      copies; either copy the uber `-runner.jar` to `/app/app.jar` or use the Quarkus fast-jar
-      (`quarkus-app/`) layout. The stage-1 `gradle clean build -PbuildWithFrontend=true` still builds
-      the frontend (fine).
- [ ] Update `scripts/init.sh` / `init-without-ocr.sh` — they have Spring-loader fallbacks and AOT
-      machinery; the primary `java -jar /app.jar` path works for the uber-jar, but verify the AOT
-      cache + `restart-helper.jar` paths.
- [ ] Then `testing/test.sh` (the official cucumber driver) should work end-to-end.
-
-### B. Real per-endpoint bugs surfaced by cucumber (login-off suite)
-Last measured failure buckets (before the transferTo/maxDPI fixes — re-run to refresh):
- [ ] **`PdfCorruptedException` (~48)** on `convert/pdf/{word,vector,presentation,text,pdfa,...}`,
-      `convert/{html,cbz}/pdf`. Investigate `CustomPDFDocumentFactory` (PDF loading) — is it
-      misreporting valid PDFs as corrupted, or do these convert paths need LibreOffice/handling that
-      errors first and gets wrapped? Check one: `python -m behave features/convert_new.feature:NN --format plain`
-      then read `docker logs sp-e2e` for the real cause.
- [ ] **`ClassCastException: String cannot be cast to ...` (~6)** — form/param binding type mismatch.
-      Likely a `@RestForm`/`@QueryParam` bound to the wrong type, or a Map/JSON form field. Check
-      `form/fill`, `form_advanced.feature`.
- [ ] **Remaining `500`s** after A/B fixes — `misc/compress-pdf`, `general/split-pdf-by-chapters`,
-      `misc/add-image`, etc. Triage each via container logs.
- [ ] **`400`s (~5)** — multipart `@RestForm` binding gaps. The migration left several request DTOs
-      with `MultipartFile`/POJO-list fields not bound to RESTEasy `FileUpload` (AI/workflow/sign DTOs
-      explicitly flagged). See `migration-report.md` "Representative deferred code".
- [ ] **temp-file collisions other than transferTo** — also check `GeneralUtils.createTempFile`
-      (`app/common/.../util/GeneralUtils.java:79/85`) and any `Files.createFile`/`Files.copy`/
-      `Files.move` without `REPLACE_EXISTING`. `temp<rand>genericNonCustomisableName.pdf` and
-      `/tmp/stirling-pdf/stirling-pdf-<rand>.pdf` were two such names.
-
-### C. Background scheduled-task errors (log noise, not request-breaking)
- [ ] `FolderWatchTrigger` (reconcile) and `ScheduleTrigger` (sweep) throw
-      `jakarta.enterprise.context.ContextNotActiveException` ("neither a transaction nor a CDI
-      request context is active") because they hit Panache/`PolicyRepository` off-request. Add
-      `@Transactional` (and/or `@ActivateRequestContext`) to those scheduled methods, or wrap the EM
-      access in `QuarkusTransaction.requiringNew()`. Files:
-      `app/proprietary/.../policy/trigger/FolderWatchTrigger.java`,
-      `.../policy/trigger/ScheduleTrigger.java`, `.../policy/store/JpaPolicyStore.java`.
-
-### D. The remaining ~35 `HttpServletRequest` files (apply §5 pattern as they surface)
-Not all are in the hot path; fix the ones that throw `UT000048` when their endpoints are exercised.
-Get the list any time with:
-```bash
-grep -rln "HttpServletRequest" app/core/src/main app/proprietary/src/main app/common/src/main --include=*.java
-```
-Known-fixed already: GlobalExceptionHandler, ControllerAuditAspect, AuditAspect, AutoJobAspect,
-JobExecutorService, AuthController, UserController, ConfigController. Everything else is unverified.
-High-risk: security filters (`UserAuthenticationFilter`, rate-limit filters, `JwtAuthenticationFilter`),
-anything reading headers/cookies/remote-addr per request.
-
-### E. Auth / JWT / login — DONE (Session 2)
-The whole Quarkus auth-identity layer is now in place (`app/proprietary/.../security/identity/`):
- [x] **JWT Bearer** → `JwtBearerAuthenticationMechanism` + `JwtTokenIdentityProvider` (validate via
-      `JwtService`, map `role` claim). Run with `V2=true`.
- [x] **X-API-KEY** → `ApiKeyAuthenticationMechanism` + `ApiKeyAuthenticationRequest` +
-      `ApiKeyIdentityProvider` (resolve via `userService.getUserByApiKey`). Lets `X-API-KEY` requests
-      authenticate (e.g. `/me`), and lets the suite run `SECURITY_ENABLELOGIN=true`.
- [x] **User-as-principal** → `UserSecurityIdentityAugmentor` re-loads the `User` and sets it as the
-      `SecurityIdentity` principal; `User implements Principal`. This satisfies the ~7
-      `principal instanceof User` sites (folders, file storage, sessions, audit, UserController) — the
-      augmentor every `// TODO: Migration required` in security/storage asked for.
- [x] **Config binding** → `ApplicationPropertiesConfigOverlay` overlays env/config onto
-      `ApplicationProperties` at startup (the Spring `@ConfigurationProperties` bind was never
-      migrated, so `SECURITY_ENABLELOGIN` / `SECURITY_CUSTOMGLOBALAPIKEY` / `STORAGE_ENABLED` were
-      ignored — root cause of the maxDPI/loginAttemptCount class too). **Currently a focused subset
-      (auth/storage/SSO toggles); a complete generic bind (all ~445 fields + settings.yml) is still
-      TODO.**
- Validated on a login-ON probe (`SECURITY_ENABLELOGIN=true V2=true STORAGE_ENABLED=true
-  SECURITY_CUSTOMGLOBALAPIKEY=123456789`): open PDF endpoints (anon), JWT login+/me, X-API-KEY /me,
-  folder list/create all work. The 183 open endpoints stay open (no global `quarkus.http.auth.*`
-  policy), so login-ON does not regress them.
-
-### F. SAML / SSO — DONE (Session 2), both flows work end-to-end
-
-**Both `validate-oauth-test.sh` and `validate-saml-test.sh` pass, and both full login flows were
-verified end-to-end against the Keycloak compose** (login -> IdP -> callback/ACS -> auto-created
-user -> app JWT cookie -> `/me` 200). Run with `PREMIUM_KEY=<your enterprise license key>`. Tag the Quarkus image as
-`docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest` so the compose uses it (or repoint the
-`image:`); `start-saml-test.sh` generates the SP certs + fetches Keycloak's cert.
-
- **OAuth2 / OIDC** (`security/oauth2/`): `OAuth2LoginController` (JAX-RS) serves
-  `/oauth2/authorization/{id}` -> IdP authorize redirect; `OAuth2CallbackServlet` (`@WebServlet
-  /login/oauth2/code/*`) does the code exchange + userinfo + auto-create + JWT cookie. **Why a
-  servlet for the callback:** quarkus-undertow's default servlet owns the `/login/*` prefix and
-  query-strips/intercepts the extension-less callback before RESTEasy sees it; a registered
-  `@WebServlet` takes precedence. (Same reason the SAML SP endpoints are servlets.)
- **SAML2** (`security/saml2/`): `Saml2Service` (OpenSAML 5) initialises the library, loads SP
-  key/cert + IdP cert, builds SP metadata, builds+signs the redirect-binding AuthnRequest, and
-  validates the SAMLResponse signature (`SAMLSignatureProfileValidator` + `SignatureValidator`
-  against the IdP cert). `SamlMetadataServlet` -> `/saml2/service-provider-metadata/{id}`;
-  `SamlSpServlet` -> `/saml2/authenticate/{id}` (login init) + `/login/saml2/sso/{id}` (ACS).
-  **Gotcha:** the SP entityId must equal the SP-metadata URL (`{backendUrl}/saml2/service-provider-
-  metadata/{id}`), which is what Keycloak's SAML client is keyed on - NOT the bare
-  `SECURITY_SAML2_SP_ENTITYID` host (`SamlConfig` derives it). Keycloak's realm has
-  `saml.client.signature=false` (AuthnRequest signature optional) + `saml.server.signature=true`
-  (so the ACS validates the response against Keycloak's cert).
- Both flows finish by issuing the app JWT as the `stirling_jwt` cookie, which
-  `JwtBearerAuthenticationMechanism` now also reads (not just the `Authorization` header) -> feeds
-  the `UserSecurityIdentityAugmentor` (principal = User).
- Follow-ups: logout/SLO endpoints; encrypted-assertion handling; the `mcp` Keycloak compose;
-  desktop/Tauri RelayState (`TauriSamlUtils` preserved). Multi-provider (google/github) OAuth uses
-  the same pattern keyed by registrationId.
-
-### F-old. (superseded) original SAML/SSO scoping
-The `validate-*-test.sh` scripts are **endpoint-existence
-checks** (Keycloak up + Stirling serves the SSO endpoint), not full browser logins.
-
-Prereqs for any run: the compose files use `image: docker.stirlingpdf.com/.../stirling-pdf:latest`
-(the published Spring image) — **repoint to `stirling-pdf-quarkus:jwt`** (or wire
-`docker/quarkus/Dockerfile`). The SAML compose mounts `saml-private-key.key`/`saml-public-cert.crt`/
-`keycloak-saml-cert.pem` which **do not exist in the repo** — generate them (the SP signing
-key/cert; `start-saml-test.sh` may do this). SAML/OAuth need the **Enterprise license** env.
-
-**OAuth2 / OIDC** (more tractable — Quarkus has `quarkus-oidc`):
- [ ] Extend `ApplicationPropertiesConfigOverlay` for `security.oauth2.*` (client issuer/clientId/
-      clientSecret/scopes/useAsUsername) — currently only the `enabled` toggle is bound.
- [ ] Serve `GET /oauth2/authorization/{registrationId}` → 302 to the IdP authorize URL (login
-      initiation; the OAuth `validate` script checks this responds). Build from issuer + clientId +
-      redirect-uri `/login/oauth2/code/{registrationId}`.
- [ ] Serve the callback `GET /login/oauth2/code/{registrationId}` → exchange code (REST Client to
-      the token endpoint), fetch userinfo, auto-create/login the user (reuse `CustomOAuth2UserService`
-      logic), issue the app JWT via `JwtService`. `quarkus.oidc.enabled` is **build-time** and aborts
-      startup with no `auth-server-url`, so either hand-roll the flow (simplest, no build-time gate)
-      or enable oidc with a runtime-disabled default tenant.
-
-**SAML2** (larger — no Quarkus SAML extension; OpenSAML 5 from scratch):
- [ ] `Saml2Configuration` already loads the SP/IdP certs and computes entityId/ACS/SLO URLs and
-      customizes the AuthnRequest (all preserved). Build on it:
-  - [ ] `GET /saml2/service-provider-metadata/{registrationId}` → SP `EntityDescriptor` XML
-        (ACS=`/login/saml2/sso/{id}`, SP signing cert) marshalled via OpenSAML 5. (The SAML `validate`
-        script checks this.)
-  - [ ] login initiation → build+sign an `AuthnRequest` (use `customizeAuthnRequest`) and
-        redirect/POST to `samlConf.getIdpSingleLoginUrl()`.
-  - [ ] `POST /login/saml2/sso/{registrationId}` (ACS) → validate the SAML response/assertion against
-        the IdP cert, extract the NameID/attributes, auto-create/login the user, issue the app JWT.
-  - Host these as Jakarta `@WebServlet` (quarkus-undertow) or JAX-RS resources; gate on
-        `security.saml2.enabled`.
- [ ] Both flows then feed the existing `UserSecurityIdentityAugmentor` (principal=User) once they
-      establish the session/JWT.
-
-### G. `saas` flavor full augmentation (optional, non-default)
- [ ] `STIRLING_FLAVOR=saas ./gradlew :stirling-pdf:quarkusBuild` → ~28 Arc deployment problems
-      (Supabase second datasource via `quarkus.datasource."supabase".*`, `SecurityFilterChain`/
-      `JwtDecoder` → `quarkus.http.auth.*`+OIDC, credit `HandlerInterceptor`/`@RestControllerAdvice`
-      → JAX-RS `@Provider`/`ExceptionMapper`, `@ConfigurationProperties` → `@ConfigMapping`,
-      RestTemplate → REST Client). ~90 `// TODO: Migration required` across 34 saas files.
-
-### H. Test suite (unit/integration) re-enablement
- [ ] ~180 test files are excluded from compilation (content filter on `org.springframework`/
-      `com.nimbusds` imports + an explicit list in `build.gradle`). Port them to `@QuarkusTest`
-      incrementally; as a file's Spring imports go away it auto-re-enters the build.
-
-### I. Loose ends
- [ ] `/q/openapi` returns 500 (`UT000048`) — known quarkus-undertow + smallrye-openapi interaction;
-      swagger-ui works, live API works. Affects API-doc tooling only.
- [ ] Jackson 2/3 convergence (drop `tools.jackson`).
- [ ] ~437 `// TODO: Migration required` markers across the codebase document every deferred decision;
-      `grep -rn "TODO: Migration required" app/*/src/main` to enumerate.
-
---
-
-## 7. Quick reference — env vars used in e2e
-
-| Var | Value | Why |
-|-----|-------|-----|
-| `SECURITY_ENABLELOGIN` | `false` | run without auth (most API tests); set `true` for the JWT suite |
-| `METRICS_ENABLED` | `true` | enables `/api/v1/info/*` (info.feature) |
-| `SYSTEM_DEFAULTLOCALE` | `en-US` | matches default-language change |
-| `SYSTEM_MAXFILESIZE` | `100` | upload limit for tests |
-| `QUARKUS_HTTP_PORT` | `8080` | cucumber steps hardcode 8080 |
-| `QUARKUS_DATASOURCE_JDBC_URL` | `jdbc:h2:mem:...` | use a fresh in-mem DB for clean runs (avoids stale H2 file lock) |
-
-Default datasource (in `application.properties`) is **H2 file** at
-`./configs/stirling-pdf-DB-2.3.232` — fine in a container; for repeated host runs override to
-`jdbc:h2:mem:...` to dodge the file lock (`Database may be already in use`).
-
---
-
-## 8. Useful diagnostic one-liners
-
-```bash
-# container alive + real error (strip ANSI, drop known background noise)
-docker logs sp-e2e 2>&1 | sed 's/\x1b\[[0-9;]*m//g' \
-  | grep -iE "ERROR|Caused by|Exception" \
-  | grep -viE "Log4j|LogManager|ForkJoinPool|FolderWatch|ScheduleTrigger|policy-" | tail -30
-
-# categorize cucumber failures
-cd testing/cucumber && TEST_CONTAINER_NAME=sp-e2e python -m behave --no-capture --format plain --no-skipped > /tmp/behave.txt 2>&1
-grep -oE "Expected status code [0-9]+ but got [0-9]+" /tmp/behave.txt | sort | uniq -c | sort -rn
-grep -oE "features/[a-z_]+\.feature" /tmp/behave.txt | sort | uniq -c | sort -rn   # rough; use a junit reporter for precise
-
-# what still touches the servlet request
-grep -rln "HttpServletRequest" app/*/src/main --include=*.java
-
-# enumerate deferred work
-grep -rn "TODO: Migration required" app/*/src/main --include=*.java | wc -l
-```
-
---
-
-## 9. Measured cucumber results — newest first
-
-**Run 5 — LOGIN ON (`SECURITY_ENABLELOGIN=true V2=true STORAGE_ENABLED=true
-SECURITY_CUSTOMGLOBALAPIKEY=123456789`):**
-```
-18 features passed, 7 failed, 0 skipped
-304 scenarios passed, 34 failed, 0 skipped     <-- folders + user-scoped features now pass
-```
-X-API-KEY mechanism + User-principal augmentor + config overlay made login-ON work without
-regressing the open endpoints (0 folder failures). Trajectory: **183 → 223 → 272 → 291 → 304**.
-
-**Run 4 — login off + lockout fix:** `291 passed, 47 failed, 0 skipped`.
-
-**Run 3 — login off + `V2=true` + JWT Bearer mechanism (Session 2):**
-```
-17 features passed, 8 failed, 0 skipped
-272 scenarios passed, 66 failed, 0 skipped     <-- 0 skipped: all JWT/admin scenarios now run
-```
-The JWT mechanism unskipped all 80 and added +49 passing over run 2 with no regressions. Remaining
-66 failures, biggest buckets:
- **~38 = login-lockout cascade (FIXED, pending re-measure).** `loginAttemptCount` defaulted to 0
-  (template = 5) → admin locked after one failed-login test → every later admin scenario blocked
-  ("Admin login failed" 21×, "Folder list returned" 17×). Fixed the primitive default (same as
-  maxDPI). **Re-run to confirm; expect ~300+.**
- 10×(200→403) feature-gated/disabled (mostly not bugs).
- 5×(200→401) + 2×(401→403) — auth scenarios asserting specific codes; triage individually.
- 3×(200→500) — real per-endpoint bugs (e.g. `user/get-api-key`). Triage via container logs.
-
-**Run 2 — login off, Session 2 fixes, no JWT mechanism:**
-```
-16 features passed, 5 failed, 4 skipped
-223 scenarios passed, 35 failed, 80 skipped
-```
-
-**Run 1 — original baseline (login off):**
-```
-183 scenarios passed, 75 failed, 80 skipped
-```
-
-Trajectory this session: **183 → 223 (boot/login/test fixes) → 272 (JWT mechanism), 0 skipped.**
@@ -53,8 +53,8 @@ For full installation options (including desktop and Kubernetes), see our [Docum

 ## Support

- **Community** [Discord](https://discord.gg/HYmhKj45pU)
- **Bug Reports**: [Github issues](https://github.com/Stirling-Tools/Stirling-PDF/issues)
+- **Community**: [Discord](https://discord.gg/HYmhKj45pU)
+- **Bug Reports**: [GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues)

 ## Contributing

@@ -78,6 +78,25 @@ tasks:
          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
          OPEN: "true"

+  dev:portal:
+    desc: "Start backend + editor; the portal is an admin route at /portal"
+    vars:
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173{{end}}'
+      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      EDITOR_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+    deps:
+      - task: backend:dev
+        vars:
+          PORT: '{{.BACKEND_PORT}}'
+          SECURITY_ENABLELOGIN: "true"
+          POLICIES_ENABLED: "true"
+      - task: frontend:dev:proprietary
+        vars:
+          PORT: '{{.EDITOR_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          OPEN: "true"
+
  dev:saas:
    desc: "Start SaaS backend + frontend concurrently on free ports"
    cmds:
@@ -166,6 +185,16 @@ tasks:
      - task: frontend:format:check
      - task: engine:format:check

+  # ============================================================
+  # Code generation
+  # ============================================================
+
+  tool-models:
+    desc: "Generate all API models from the Java OpenAPI spec"
+    cmds:
+      - task: frontend:tool-models
+      - task: engine:tool-models
+
  # ============================================================
  # Quality Gate
  # ============================================================
@@ -0,0 +1,8 @@
+# Committed defaults for `task backend:dev:proprietary` (self-hosted / proprietary
+# flavor). Local overrides + secrets live in app/.env.proprietary.local (ignored).
+
+# Combined-billing account link (Mode A). Feature-flagged: OFF until release.
+# Flip to true in app/.env.proprietary.local to test linking locally.
+STIRLING_BILLING_ACCOUNT_LINK_ENABLED=false
+# SaaS base URL the linked instance calls (register + entitlement).
+STIRLING_BILLING_ACCOUNT_LINK_SAAS_BASE_URL=https://stirling.com/app
@@ -1,3 +1,4 @@
 # Whitelist committed env defaults. `.env.saas.local` (and any other .env*)
 # stays ignored via the root .gitignore.
 !.env.saas
+!.env.proprietary
@@ -1,9 +1,5 @@
 {
  "allowedLicenses": [
-    {
-      "moduleName": "org.jboss:jboss-transaction-spi",
-      "moduleLicense": "Public Domain"
-    },
    {
      "moduleName": ".*",
      "moduleLicense": "BSD License"
@@ -84,10 +80,18 @@
      "moduleName": ".*",
      "moduleLicense": "Apache License Version 2.0"
    },
+    {
+      "moduleName": ".*",
+      "moduleLicense": "Apache License version 2.0"
+    },
    {
      "moduleName": ".*",
      "moduleLicense": "Apache License, Version 2.0"
    },
+    {
+      "moduleName": ".*",
+      "moduleLicense": "Apache License, version 2.0"
+    },
    {
      "moduleName": ".*",
      "moduleLicense": "The Apache License, Version 2.0"
@@ -112,6 +116,10 @@
      "moduleName": ".*",
      "moduleLicense": "Mozilla Public License 2.0 (MPL-2.0)"
    },
+    {
+      "moduleName": ".*",
+      "moduleLicense": "Mozilla Public License Version 2.0"
+    },
    {
      "moduleName": ".*",
      "moduleLicense": 	"CDDL+GPL License"
@@ -176,6 +184,14 @@
      "moduleName": ".*",
      "moduleLicense": "Eclipse Public License, Version 2.0"
    },
+    {
+      "moduleName": ".*",
+      "moduleLicense": "EPL-2.0"
+    },
+    {
+      "moduleName": ".*",
+      "moduleLicense": "LGPL-2.1-only"
+    },
    {
      "moduleName": ".*",
      "moduleLicense": "Ubuntu Font Licence 1.0"
@@ -1,4 +1,7 @@
-// REMOVED: bootRun{enabled=false} - Spring Boot plugin task. :common is a Quarkus library module.
+// Configure bootRun to disable it or point to a main class
+bootRun {
+    enabled = false
+}
 spotless {
    java {
        target 'src/**/java/**/*.java'
@@ -26,34 +29,13 @@ spotless {
    }
 }
 dependencies {
-    api 'com.google.guava:guava:33.6.0-jre'
-
-    // spring-boot-starter-webmvc -> Quarkus REST stack (api-scoped so downstream modules inherit it).
-    api 'io.quarkus:quarkus-rest'
-    api 'io.quarkus:quarkus-rest-jackson'
-    // Servlet bridge: large amounts of controller/filter code use jakarta.servlet (HttpServletRequest,
-    // Filter, etc.). quarkus-undertow provides a servlet container on Quarkus so that API resolves and
-    // runs. TODO: Migration required - longer term, port servlet usage to JAX-RS (ContainerRequestContext)
-    //       and drop quarkus-undertow.
-    api 'io.quarkus:quarkus-undertow'
-    // Bean Validation (was transitively in spring-boot-starter-webmvc).
-    api 'io.quarkus:quarkus-hibernate-validator'
-    // @Scheduled support (was spring-context scheduling). quarkus-scheduler manages its own
-    // executor; the former SchedulingConfig TaskScheduler bean is no longer needed.
-    api 'io.quarkus:quarkus-scheduler'
-    // BCrypt implementation backing the Spring Security PasswordEncoder compatibility shim
-    // (replaces spring-security-crypto's BCryptPasswordEncoder). Standalone, no framework.
-    api 'at.favre.lib:bcrypt:0.10.2'
-    // Swagger/OpenAPI annotations (io.swagger.v3.oas.annotations.*) used by common's API marker
-    // interfaces; was transitive via springdoc. Quarkus' SmallRye OpenAPI also understands these.
-    api 'io.swagger.core.v3:swagger-core-jakarta:2.2.46'
-    // REMOVED: spring-boot-starter-aspectj. Quarkus has no AspectJ weaving; quarkus-arc provides
-    // CDI interceptors (@AroundInvoke / interceptor bindings) instead.
-    // TODO: Migration required - any @Aspect/@Around advice must be rewritten as CDI interceptors.
+    api "com.google.guava:guava:${guavaVersion}"
+    api 'org.springframework.boot:spring-boot-starter-webmvc'
+    api 'org.springframework.boot:spring-boot-starter-aspectj'
    api 'com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizer:20260313.1'
    api 'com.fathzer:javaluator:3.0.6'
    api 'com.posthog.java:posthog:1.2.0'
-    api 'org.apache.commons:commons-lang3:3.20.0'
+    api "org.apache.commons:commons-lang3:${commonsLang3}"
    api 'com.drewnoakes:metadata-extractor:2.20.0' // Image metadata extractor
    api 'com.vladsch.flexmark:flexmark-html2md-converter:0.64.8'
    api "org.apache.pdfbox:pdfbox:$pdfboxVersion"
@@ -63,8 +45,7 @@ dependencies {
    api 'com.github.junrar:junrar:7.5.10' // RAR archive support for CBR files
    api 'jakarta.servlet:jakarta.servlet-api:6.1.0'
    api 'org.snakeyaml:snakeyaml-engine:3.0.1'
-    // springdoc-openapi-starter-webmvc-ui -> SmallRye OpenAPI (schema at /q/openapi, UI at /q/swagger-ui)
-    api 'io.quarkus:quarkus-smallrye-openapi'
+    api "org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.3"
    // Simple Java Mail for EML/MSG parsing (replaces direct Angus Mail usage)
    api 'org.simplejavamail:simple-java-mail:8.12.6'
    api 'org.simplejavamail:outlook-module:8.12.6' // MSG file support
@@ -79,7 +60,7 @@ dependencies {
        exclude group: 'com.google.code.gson', module: 'gson'
    }

-    api 'com.stirling:jpdfium:1.0.2'
+    api "com.stirling:jpdfium:${jpdfiumVersion}"

    // -PjpdfiumPlatforms=all|<csv of linux-x64,linux-arm64,darwin-x64,darwin-arm64,windows-x64>
    def jpdfiumPlatformsProp = (project.findProperty('jpdfiumPlatforms') ?: 'all').toString().trim()
@@ -94,20 +75,12 @@ dependencies {
    }
    logger.lifecycle("JPDFium native platforms: ${jpdfiumPlatforms.join(', ')}")
    jpdfiumPlatforms.each { platform ->
-        runtimeOnly "com.stirling:jpdfium-natives-${platform}:1.0.2"
+        runtimeOnly "com.stirling:jpdfium-natives-${platform}:${jpdfiumVersion}"
    }

-    // Jackson 3 (tools.jackson) - retained because ~100 files migrated to the Jackson 3 namespace
-    // under Spring Boot 4. Quarkus integrates Jackson 2 for REST bodies; Jackson 3 coexists here as a
-    // plain library so those files compile and can still build/parse JSON directly.
-    // api-scoped so downstream modules (core, proprietary, saas) that import tools.jackson inherit it.
-    // TODO: Migration required - converge the codebase on a single Jackson major version.
-    api 'tools.jackson.core:jackson-databind:3.0.0'
-    api 'tools.jackson.core:jackson-core:3.0.0'
-
    // Bucket4j (local in-process token bucket for RateLimitStore default impl)
-    implementation 'com.bucket4j:bucket4j_jdk17-core:8.19.0'
+    implementation "com.bucket4j:bucket4j_jdk17-core:${bucket4jVersion}"

    // ArchUnit: enforces module dependency direction (see ArchitectureTest)
-    testImplementation 'com.tngtech.archunit:archunit-junit5:1.4.2'
+    testImplementation "com.tngtech.archunit:archunit-junit5:${archunitVersion}"
 }
@@ -6,16 +6,15 @@ import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;

-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.inject.Inject;
-import jakarta.inject.Named;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.stereotype.Service;

 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;

-@ApplicationScoped
+@Service
@Slf4j
 public class EndpointConfiguration {

@@ -53,10 +52,9 @@ public class EndpointConfiguration {
    private Map<String, Set<String>> endpointAlternatives = new ConcurrentHashMap<>();
    private final boolean runningProOrHigher;

-    @Inject
    public EndpointConfiguration(
            ApplicationProperties applicationProperties,
-            @Named("runningProOrHigher") boolean runningProOrHigher) {
+            @Qualifier("runningProOrHigher") boolean runningProOrHigher) {
        this.applicationProperties = applicationProperties;
        this.runningProOrHigher = runningProOrHigher;
        init();
@@ -9,8 +9,7 @@ import java.util.Collections;
 import java.util.List;

 import org.apache.pdfbox.pdmodel.PDDocument;
-
-import jakarta.enterprise.context.ApplicationScoped;
+import org.springframework.stereotype.Service;

 import lombok.extern.slf4j.Slf4j;

@@ -48,7 +47,7 @@ import technology.tabula.extractors.SpreadsheetExtractionAlgorithm;
 *   <li>Rotated tables (90°/270° pages) may produce incorrect bounds.
 * </ul>
 */
-@ApplicationScoped
+@Service
@Slf4j
 public class TabulaTableParser implements TableParser {

@@ -2,27 +2,21 @@ package stirling.software.common.annotations;

 import java.lang.annotation.*;

-import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import org.springframework.core.annotation.AliasFor;
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestMethod;

-import jakarta.enterprise.util.Nonbinding;
-import jakarta.interceptor.InterceptorBinding;
-import jakarta.ws.rs.core.MediaType;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;

 /**
 * Shortcut for a POST endpoint that is executed through the Stirling "auto‑job" framework.
 *
- * <p>MIGRATION (Spring -> Quarkus): this was a Spring composed meta-annotation that stamped
- * {@code @RequestMapping(method=POST)} onto the target via {@code @AliasFor}. JAX-RS does not
- * honour {@code @Path}/{@code @POST}/{@code @Consumes} through meta-annotations, so this annotation
- * no longer provides routing. It is now a CDI {@link InterceptorBinding} handled by {@code
- * AutoJobInterceptor}. <b>Controllers using {@code @AutoJobPostMapping} must additionally declare
- * their own JAX-RS {@code @POST} + {@code @Path(value)} + {@code @Consumes(consumes)}.</b> The
- * {@link #value()}/{@link #consumes()} members are retained so a scanner/controller can read the
- * intended routing.
- *
 * <p>Behaviour notes:
 *
 * <ul>
+ *   <li>The endpoint is registered with {@code POST} and, by default, consumes {@code
+ *       multipart/form-data} unless you override {@link #consumes()}.
 *   <li>When the client supplies {@code ?async=true} the call is handed to {@link
 *       stirling.software.common.service.JobExecutorService JobExecutorService} where it may be
 *       queued, retried, tracked and subject to time‑outs. For synchronous (default) invocations
@@ -32,26 +26,22 @@ import jakarta.ws.rs.core.MediaType;
 *       GET /api/v1/general/job/{id}</code>.
 * </ul>
 *
- * <p>Unless stated otherwise an attribute only affects <em>async</em> execution. All members are
- * {@code @Nonbinding} so the single {@code AutoJobInterceptor} matches every annotated method; the
- * interceptor reads the actual values reflectively from the target method.
+ * <p>Unless stated otherwise an attribute only affects <em>async</em> execution.
 */
-@Target({ElementType.METHOD, ElementType.TYPE})
+@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
-@InterceptorBinding
+@RequestMapping(method = RequestMethod.POST)
@RequestBody(required = true)
 public @interface AutoJobPostMapping {

-    /**
-     * The path mapping of the endpoint (controllers must mirror this on a JAX-RS {@code @Path}).
-     */
-    @Nonbinding
+    /** Alias for {@link RequestMapping#value} – the path mapping of the endpoint. */
+    @AliasFor(annotation = RequestMapping.class, attribute = "value")
    String[] value() default {};

    /** MIME types this endpoint accepts. Defaults to {@code multipart/form-data}. */
-    @Nonbinding
-    String[] consumes() default {MediaType.MULTIPART_FORM_DATA};
+    @AliasFor(annotation = RequestMapping.class, attribute = "consumes")
+    String[] consumes() default {MediaType.MULTIPART_FORM_DATA_VALUE};

    /**
     * Maximum execution time in milliseconds before the job is aborted. A negative value means "use
@@ -59,7 +49,6 @@ public @interface AutoJobPostMapping {
     *
     * <p>Only honoured when {@code async=true}.
     */
-    @Nonbinding
    long timeout() default -1;

    /**
@@ -68,7 +57,6 @@ public @interface AutoJobPostMapping {
     *
     * <p>Only honoured when {@code async=true}.
     */
-    @Nonbinding
    int retryCount() default 1;

    /**
@@ -76,7 +64,6 @@ public @interface AutoJobPostMapping {
     *
     * <p>Only honoured when {@code async=true}.
     */
-    @Nonbinding
    boolean trackProgress() default true;

    /**
@@ -85,7 +72,6 @@ public @interface AutoJobPostMapping {
     *
     * <p>Only honoured when {@code async=true}.
     */
-    @Nonbinding
    boolean queueable() default false;

    /**
@@ -96,6 +82,5 @@ public @interface AutoJobPostMapping {
     * AutoJobPostMappingWeightTest} fails the build if any endpoint leaves it unset. Runtime
     * readers clamp the value into {@code [1, 100]}.
     */
-    @Nonbinding
    int resourceWeight() default Integer.MIN_VALUE;
 }
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/account").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/account")
@Tag(
        name = "Account Security",
        description =
@@ -5,20 +5,19 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
 * Combined annotation for Admin Settings API controllers.
- *
- * <p>MIGRATION (Spring -> JAX-RS): JAX-RS/RESTEasy does NOT process {@code @Path} via custom
- * meta-annotations (Spring honoured composed {@code @RestController}/{@code @RequestMapping}
- * through {@code @AliasFor}; JAX-RS has no equivalent). This annotation therefore now carries only
- * the OpenAPI {@code @Tag}. Each controller annotated with {@code @AdminApi} MUST additionally
- * declare its own {@code @jakarta.ws.rs.Path("/api/v1/admin/settings")} (the path the removed
- * {@code @RequestMapping} used to supply).
+ * Includes @RestController, @RequestMapping("/api/v1/admin/settings"), and OpenAPI @Tag.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/admin/settings")
@Tag(
        name = "Admin Settings",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/admin/server-certificate").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/admin/server-certificate")
@Tag(
        name = "Admin - Server Certificate",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/analysis").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/analysis")
@Tag(
        name = "Analysis",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/config").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/config")
@Tag(
        name = "Config",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/convert").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/convert")
@Tag(
        name = "Convert",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/database").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/database")
@Tag(
        name = "Database",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/admin/database").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/admin/database")
@Tag(
        name = "Database Management",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/filter").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/filter")
@Tag(
        name = "Filter",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/general").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/general")
@Tag(
        name = "General",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/info").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/info")
@Tag(
        name = "Info",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/invite").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/invite")
@Tag(
        name = "Invite",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/misc").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/misc")
@Tag(
        name = "Misc",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/pipeline").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/pipeline")
@Tag(
        name = "Pipeline",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -14,9 +17,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/proprietary/ui-data").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/proprietary/ui-data")
@Tag(
        name = "Proprietary UI Data",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/security").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/security")
@Tag(
        name = "Security",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/settings").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/settings")
@Tag(
        name = "Settings",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/team").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/team")
@Tag(
        name = "Team",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/ui-data").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/ui-data")
@Tag(
        name = "UI Data",
        description =
@@ -5,6 +5,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
 import io.swagger.v3.oas.annotations.tags.Tag;

 /**
@@ -13,9 +16,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
-// MIGRATION (Spring->JAX-RS): controllers using this annotation must declare
-// @jakarta.ws.rs.Path("/api/v1/user").
-// JAX-RS does not honour @Path via meta-annotations, so the path is not inherited from here.
+@RestController
+@RequestMapping("/api/v1/user")
@Tag(
        name = "User",
        description =
@@ -7,101 +7,46 @@ import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Supplier;

+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.*;
 import org.slf4j.MDC;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.multipart.MultipartFile;

-import io.quarkus.vertx.http.runtime.CurrentVertxRequest;
-
-import jakarta.annotation.Priority;
-import jakarta.inject.Inject;
-import jakarta.interceptor.AroundInvoke;
-import jakarta.interceptor.Interceptor;
-import jakarta.interceptor.InvocationContext;
+import jakarta.servlet.http.HttpServletRequest;

+import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.annotations.AutoJobPostMapping;
-import stirling.software.common.model.MultipartFile;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.FileStorage;
 import stirling.software.common.service.JobExecutorService;

-/**
- * MIGRATION (Spring AOP -> CDI interceptor): was an {@code @Aspect} with {@code @Around} advice on
- * {@code @AutoJobPostMapping}. Reworked into a CDI {@link Interceptor} bound by the
- * {@code @AutoJobPostMapping} {@code @InterceptorBinding}; {@code @Around}/{@code
- * ProceedingJoinPoint} became {@code @AroundInvoke}/{@link InvocationContext}.
- * {@code @Priority(20)} now meaningfully orders this interceptor (runs after lower-priority audit
- * interceptors populate MDC).
- */
-@Interceptor
-@AutoJobPostMapping
-@Priority(20)
+@Aspect
+@Component
+@RequiredArgsConstructor
@Slf4j
+@Order(20) // Lower precedence - executes AFTER audit aspects populate MDC
 public class AutoJobAspect {

    private static final Duration RETRY_BASE_DELAY = Duration.ofMillis(100);

    private final JobExecutorService jobExecutorService;
-    // Reactive-safe access to the current request. The undertow HttpServletRequest proxy throws
-    // UT000048 ("No request is currently active") on RESTEasy Reactive worker threads, so query
-    // params / method / path / attributes are read from the Vert.x request instead, degrading to
-    // null/empty when no request is active.
-    private final CurrentVertxRequest currentVertxRequest;
+    private final HttpServletRequest request;
    private final FileStorage fileStorage;

-    @Inject
-    public AutoJobAspect(
-            JobExecutorService jobExecutorService,
-            CurrentVertxRequest currentVertxRequest,
-            FileStorage fileStorage) {
-        this.jobExecutorService = jobExecutorService;
-        this.currentVertxRequest = currentVertxRequest;
-        this.fileStorage = fileStorage;
-    }
-
-    private io.vertx.core.http.HttpServerRequest vertxRequest() {
-        try {
-            var current = currentVertxRequest.getCurrent();
-            return current != null ? current.request() : null;
-        } catch (RuntimeException e) {
-            return null;
-        }
-    }
-
-    private String requestParam(String name) {
-        io.vertx.core.http.HttpServerRequest req = vertxRequest();
-        return req != null ? req.getParam(name) : null;
-    }
-
-    private String requestMethod() {
-        io.vertx.core.http.HttpServerRequest req = vertxRequest();
-        return req != null ? req.method().name() : "";
-    }
-
-    private String requestUri() {
-        io.vertx.core.http.HttpServerRequest req = vertxRequest();
-        return req != null ? req.path() : "";
-    }
-
-    private Object requestAttribute(String name) {
-        try {
-            var current = currentVertxRequest.getCurrent();
-            return current != null ? current.get(name) : null;
-        } catch (RuntimeException e) {
-            return null;
-        }
-    }
-
-    @AroundInvoke
-    public Object wrapWithJobExecution(InvocationContext ctx) throws Exception {
-        AutoJobPostMapping autoJobPostMapping =
-                ctx.getMethod().getAnnotation(AutoJobPostMapping.class);
+    @Around("@annotation(autoJobPostMapping)")
+    public Object wrapWithJobExecution(
+            ProceedingJoinPoint joinPoint, AutoJobPostMapping autoJobPostMapping) throws Exception {
+        // This aspect will run before any audit aspects due to @Order(0)
        // Extract parameters from the request and annotation
-        boolean async = Boolean.parseBoolean(requestParam("async"));
+        boolean async = Boolean.parseBoolean(request.getParameter("async"));
        log.debug(
                "AutoJobAspect: Processing {} {} with async={}",
-                requestMethod(),
-                requestUri(),
+                request.getMethod(),
+                request.getRequestURI(),
                async);
        long timeout = autoJobPostMapping.timeout();
        int retryCount = autoJobPostMapping.retryCount();
@@ -116,8 +61,7 @@ public class AutoJobAspect {
                trackProgress);

        // Process arguments in-place to avoid type mismatch issues
-        Object[] args = processArgsInPlace(ctx.getParameters(), async);
-        ctx.setParameters(args);
+        Object[] args = processArgsInPlace(joinPoint.getArgs(), async);

        // Extract queueable and resourceWeight parameters and validate
        boolean queueable = autoJobPostMapping.queueable();
@@ -136,7 +80,7 @@ public class AutoJobAspect {
                                    // The trackProgress flag controls whether detailed progress is
                                    // stored
                                    // for REST API queries, not WebSocket notifications
-                                    return ctx.proceed();
+                                    return joinPoint.proceed(args);
                                } catch (Throwable ex) {
                                    log.error(
                                            "AutoJobAspect caught exception during job execution: {}",
@@ -157,7 +101,7 @@ public class AutoJobAspect {
        } else {
            // Use retry logic
            return executeWithRetries(
-                    ctx,
+                    joinPoint,
                    args,
                    async,
                    timeout,
@@ -169,7 +113,7 @@ public class AutoJobAspect {
    }

    private Object executeWithRetries(
-            InvocationContext ctx,
+            ProceedingJoinPoint joinPoint,
            Object[] args,
            boolean async,
            long timeout,
@@ -214,7 +158,7 @@ public class AutoJobAspect {
                                    }

                                    // Attempt to execute the operation
-                                    return ctx.proceed();
+                                    return joinPoint.proceed(args);

                                } catch (Throwable ex) {
                                    lastException = ex;
@@ -348,7 +292,7 @@ public class AutoJobAspect {

    private String getJobIdFromContext() {
        try {
-            return (String) requestAttribute("jobId");
+            return (String) request.getAttribute("jobId");
        } catch (Exception e) {
            log.debug("Could not retrieve job ID from context: {}", e.getMessage());
            return null;
@@ -1,7 +1,8 @@
 package stirling.software.common.cluster;

+import org.springframework.context.annotation.Configuration;
+
 import jakarta.annotation.PostConstruct;
-import jakarta.enterprise.context.ApplicationScoped;

 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -18,7 +19,7 @@ import stirling.software.common.model.ApplicationProperties.Cluster;
 * single-instance install needs no new config.
 */
@Slf4j
-@ApplicationScoped
+@Configuration
@RequiredArgsConstructor
 public class ClusterConfig {

@@ -46,7 +47,7 @@ public class ClusterConfig {
                            + " JVM is coordinated. Cross-node lookups and the file proxy will fail."
                            + " Use backplane=valkey for real multi-node deployments.");
        } else {
-            // Fail fast on typos like "valky" so CDI doesn't later report a cryptic
+            // Fail fast on typos like "valky" so Spring doesn't later report a cryptic
            // "no ClusterBackplane bean" - the operator-facing error names the bad value.
            throw new IllegalStateException(
                    "cluster.enabled=true with unknown backplane '"
@@ -1,9 +1,9 @@
 package stirling.software.common.cluster.inprocess;

-import io.quarkus.arc.DefaultBean;
-
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.inject.Produces;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;

 import lombok.extern.slf4j.Slf4j;

@@ -19,58 +19,46 @@ import stirling.software.common.model.ApplicationProperties;
 * Default cluster backplane wiring: every interface gets an {@code InProcess*} bean. Active when
 * cluster mode is off or {@code cluster.backplane=inprocess}.
 */
-// TODO: Migration required - the original @ConditionalOnExpression
-// ("!${cluster.enabled:false} || '${cluster.backplane:inprocess}'.equalsIgnoreCase('inprocess')")
-// gated activation of this whole configuration on a SpEL expression over two config properties.
-// Quarkus/CDI has no direct equivalent for conditionally registering a producer set based on a
-// SpEL boolean. The @DefaultBean producers below now always provide the in-process implementations
-// unless another bean of the same type is present. If a non-inprocess backplane is added, ensure
-// it is NOT a @DefaultBean so it wins, and consider gating with
-// @io.quarkus.arc.lookup.LookupIfProperty
-// / @io.quarkus.arc.lookup.LookupUnlessProperty or a build-time @IfBuildProperty per producer.
@Slf4j
-@ApplicationScoped
+@Configuration
+@ConditionalOnExpression(
+        "!${cluster.enabled:false} ||"
+                + " '${cluster.backplane:inprocess}'.equalsIgnoreCase('inprocess')")
 public class InProcessClusterConfiguration {

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public ClusterBackplane clusterBackplane(ApplicationProperties applicationProperties) {
        log.info("Cluster backplane: in-process (single node)");
        return new InProcessClusterBackplane(applicationProperties);
    }

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public JobStore jobStore() {
        return new InProcessJobStore();
    }

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public RateLimitStore rateLimitStore() {
        return new InProcessRateLimitStore();
    }

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public DistributedLock distributedLock() {
        return new InProcessDistributedLock();
    }

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public KeyValueCache keyValueCache() {
        return new InProcessKeyValueCache();
    }

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
+    @Bean
+    @ConditionalOnMissingBean
    public InstanceRegistry instanceRegistry() {
        return new InProcessInstanceRegistry();
    }
@@ -1,11 +1,10 @@
 package stirling.software.common.cluster.inprocess;

-import org.eclipse.microprofile.config.inject.ConfigProperty;
-
-import io.quarkus.arc.DefaultBean;
-
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.inject.Produces;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;

 import stirling.software.common.cluster.FileStore;

@@ -14,23 +13,17 @@ import stirling.software.common.cluster.FileStore;
 * cluster.artifactStore=local} (the default; {@code matchIfMissing=true}). The S3 artifact-store
 * supplies its own bean when {@code cluster.artifactStore=s3}.
 */
-// TODO: Migration required - the original class was guarded by Spring's
-// @ConditionalOnProperty(prefix="cluster", name="artifactStore", havingValue="local",
-// matchIfMissing=true). Quarkus has no runtime equivalent: @io.quarkus.arc.profile.IfBuildProperty
-// is build-time only and does not support matchIfMissing semantics. The producer below is now
-// unconditional. The "local is the default; S3 supplies its own bean" behavior is preserved via
-// @DefaultBean (the S3 artifact-store bean, if present, wins over this default). If a true
-// runtime toggle on cluster.artifactStore is needed, gate the producer body on the config value
-// and return/short-circuit accordingly.
-@ApplicationScoped
+@Configuration
+@ConditionalOnProperty(
+        prefix = "cluster",
+        name = "artifactStore",
+        havingValue = "local",
+        matchIfMissing = true)
 public class LocalDiskFileStoreConfiguration {

-    @Produces
-    @DefaultBean
-    @ApplicationScoped
-    public FileStore fileStore(
-            @ConfigProperty(name = "stirling.tempDir", defaultValue = "/tmp/stirling-files")
-                    String tempDir) {
+    @Bean
+    @ConditionalOnMissingBean
+    public FileStore fileStore(@Value("${stirling.tempDir:/tmp/stirling-files}") String tempDir) {
        return new LocalDiskFileStore(tempDir);
    }
 }
@@ -3,29 +3,37 @@ package stirling.software.common.config;
 import java.nio.file.Files;
 import java.nio.file.Path;

+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
 import jakarta.annotation.PostConstruct;
-import jakarta.enterprise.context.ApplicationScoped;

 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.util.TempFileRegistry;

 /**
 * Configuration for the temporary file management system. Sets up the necessary beans and
 * configures system properties.
 */
@Slf4j
-@ApplicationScoped
+@Configuration
@RequiredArgsConstructor
 public class TempFileConfiguration {

    private final ApplicationProperties applicationProperties;

-    // MIGRATION: the @Produces TempFileRegistry producer was removed. TempFileRegistry is already
-    // an
-    // @ApplicationScoped CDI bean with a no-arg constructor, so the producer was a redundant second
-    // @Default bean of the same type and made every injection point ambiguous.
+    /**
+     * Create the TempFileRegistry bean.
+     *
+     * @return A new TempFileRegistry instance
+     */
+    @Bean
+    public TempFileRegistry tempFileRegistry() {
+        return new TempFileRegistry();
+    }

    @PostConstruct
    public void initTempFileConfig() {
@@ -5,8 +5,8 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Set;

-import jakarta.annotation.PreDestroy;
-import jakarta.enterprise.context.ApplicationScoped;
+import org.springframework.beans.factory.DisposableBean;
+import org.springframework.stereotype.Component;

 import lombok.extern.slf4j.Slf4j;

@@ -14,12 +14,12 @@ import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.TempFileRegistry;

 /**
- * Handles cleanup of temporary files on application shutdown. Uses a CDI {@code @PreDestroy} method
- * (migrated from Spring's {@code DisposableBean}) to ensure cleanup happens during normal shutdown.
+ * Handles cleanup of temporary files on application shutdown. Implements Spring's DisposableBean
+ * interface to ensure cleanup happens during normal application shutdown.
 */
@Slf4j
-@ApplicationScoped
-public class TempFileShutdownHook {
+@Component
+public class TempFileShutdownHook implements DisposableBean {

    private final TempFileRegistry registry;

@@ -31,8 +31,8 @@ public class TempFileShutdownHook {
        Runtime.getRuntime().addShutdownHook(new Thread(this::cleanupTempFiles));
    }

-    /** CDI pre-destroy callback (was DisposableBean#destroy). Called during normal shutdown. */
-    @PreDestroy
+    /** Spring's DisposableBean interface method. Called during normal application shutdown. */
+    @Override
    public void destroy() {
        log.info("Application shutting down, cleaning up temporary files");
        cleanupTempFiles();
@@ -9,69 +9,40 @@ import java.util.Properties;
 import java.util.function.Predicate;
 import java.util.stream.Stream;

-import org.eclipse.microprofile.config.Config;
-import org.eclipse.microprofile.config.inject.ConfigProperty;
-
-import io.quarkus.arc.profile.IfBuildProfile;
-
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.context.Dependent;
-import jakarta.enterprise.inject.Produces;
-import jakarta.inject.Inject;
-import jakarta.inject.Named;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.context.annotation.Profile;
+import org.springframework.context.annotation.Scope;
+import org.springframework.core.env.Environment;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.Resource;
+import org.springframework.util.ClassUtils;

 import lombok.Getter;
+import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;

-/**
- * Central CDI producer hub (migrated from a Spring {@code @Configuration} class).
- *
- * <p>MIGRATION NOTES (Spring -> Quarkus CDI):
- *
- * <ul>
- *   <li>{@code @Bean} -> {@code @Produces}; {@code @Bean(name="x")} ->
- *       {@code @Produces @Named("x")}.
- *   <li>{@code @Value} -> {@code @ConfigProperty}; Spring {@code Environment} -> MicroProfile
- *       {@code Config}.
- *   <li>{@code @Profile("default")} flavor-default beans -> {@code @DefaultBean}: the :proprietary
- *       / :saas modules provide the "real" producer and automatically win when present, exactly
- *       like the old profile override (this is the Quarkus idiom for "default unless overridden").
- *   <li>{@code @Scope("request")} on {@code boolean} producers -> {@code @Dependent}. CDI normal
- *       scopes (e.g. {@code @RequestScoped}) require a client proxy, which is impossible for
- *       primitives/finals, so Spring's request-scoped primitive beans cannot be reproduced
- *       directly. {@code @Dependent} recomputes the value at each injection point, which is the
- *       closest behaviour. TODO: Migration required - if true per-HTTP-request semantics are
- *       needed, wrap the value in a {@code @RequestScoped} holder object instead of producing a
- *       bare boolean.
- *   <li>{@code @Lazy} dropped - CDI beans are initialised lazily by default.
- * </ul>
- */
+@Lazy
@Slf4j
-@ApplicationScoped
+@Configuration
+@RequiredArgsConstructor
 public class AppConfig {

-    private final Config config;
+    private final Environment env;

    private final ApplicationProperties applicationProperties;

    @Getter
-    @ConfigProperty(name = "server.servlet.context-path", defaultValue = "/")
-    String contextPath;
+    @Value("${server.servlet.context-path:/}")
+    private String contextPath;

    @Getter
-    @ConfigProperty(name = "quarkus.http.port", defaultValue = "8080")
-    String serverPort;
-
-    @ConfigProperty(name = "v2")
-    boolean v2Enabled;
-
-    @Inject
-    public AppConfig(Config config, ApplicationProperties applicationProperties) {
-        this.config = config;
-        this.applicationProperties = applicationProperties;
-    }
+    @Value("${server.port:8080}")
+    private String serverPort;

    /**
     * Get the backend URL from system configuration. Falls back to http://localhost if not
@@ -84,111 +55,76 @@ public class AppConfig {
        return (backendUrl != null && !backendUrl.isBlank()) ? backendUrl : "http://localhost";
    }

-    @Produces
-    @Named("v2Enabled")
+    @Value("${v2}")
+    public boolean v2Enabled;
+
+    @Bean
    public boolean v2Enabled() {
        return v2Enabled;
    }

-    // MIGRATION: many beans inject tools.jackson.databind.ObjectMapper (Jackson 3, inherited from
-    // Spring Boot 4). Quarkus' container only produces a com.fasterxml.jackson (Jackson 2)
-    // ObjectMapper for REST (de)serialization, so the Jackson 3 type is an unsatisfied CDI
-    // dependency. This producer supplies a single application-scoped Jackson 3 mapper built the
-    // same
-    // way the codebase builds them ad hoc (JsonMapper.builder().build()). REST bodies still go
-    // through Quarkus' Jackson 2 mapper; this is only for code that uses the Jackson 3 API
-    // directly.
-    // TODO: Migration required - converge the codebase on one Jackson line (drop Jackson 3) later.
-    @Produces
-    @ApplicationScoped
-    public tools.jackson.databind.ObjectMapper jackson3ObjectMapper() {
-        return tools.jackson.databind.json.JsonMapper.builder().build();
-    }
-
-    @Produces
-    @Named("contextPath")
-    public String contextPathBean() {
-        return contextPath;
-    }
-
-    @Produces
-    @Named("loginEnabled")
+    @Bean(name = "loginEnabled")
    public boolean loginEnabled() {
        return applicationProperties.getSecurity().isEnableLogin();
    }

-    // MIGRATION: CDI has no producer for the nested ApplicationProperties.Security.SAML2 config
-    // object, so beans that inject it directly (e.g. CustomSaml2AuthenticationSuccessHandler) were
-    // unsatisfied. Expose it from the already-injected ApplicationProperties. May be null/disabled;
-    // that is fine for injection.
-    @Produces
-    public ApplicationProperties.Security.SAML2 saml2Config() {
-        return applicationProperties.getSecurity().getSaml2();
-    }
-
-    @Produces
-    @Named("appName")
+    @Bean(name = "appName")
    public String appName() {
        return "Stirling PDF";
    }

-    @Produces
-    @Named("appVersion")
+    @Bean(name = "appVersion")
    public String appVersion() {
-        // MIGRATION: Spring ClassPathResource -> plain classloader resource lookup.
+        Resource resource = new ClassPathResource("version.properties");
        Properties props = new Properties();
-        try (var in = getClass().getClassLoader().getResourceAsStream("version.properties")) {
-            if (in != null) {
-                props.load(in);
-                return props.getProperty("version");
-            }
+        try {
+            props.load(resource.getInputStream());
+            return props.getProperty("version");
        } catch (IOException e) {
            log.error("exception", e);
        }
        return "0.0.0";
    }

-    @Produces
-    @Named("homeText")
+    @Bean(name = "homeText")
    public String homeText() {
        return "null";
    }

-    @Produces
-    @Named("languages")
+    @Bean(name = "languages")
    public List<String> languages() {
        return applicationProperties.getUi().getLanguages();
    }

-    @Produces
-    @Named("navBarText")
+    @Bean
+    public String contextPath(@Value("${server.servlet.context-path}") String contextPath) {
+        return contextPath;
+    }
+
+    @Bean(name = "navBarText")
    public String navBarText() {
        String navBar = applicationProperties.getUi().getAppNameNavbar();
        return (navBar != null) ? navBar : "Stirling PDF";
    }

-    @Produces
-    @Named("enableAlphaFunctionality")
+    @Bean(name = "enableAlphaFunctionality")
    public boolean enableAlphaFunctionality() {
        return applicationProperties.getSystem().isEnableAlphaFunctionality();
    }

-    @Produces
-    @Named("rateLimit")
+    @Bean(name = "rateLimit")
    public boolean rateLimit() {
        String rateLimit = System.getProperty("rateLimit");
        if (rateLimit == null) rateLimit = System.getenv("rateLimit");
        return Boolean.parseBoolean(rateLimit);
    }

-    @Produces
-    @Named("RunningInDocker")
+    @Bean(name = "RunningInDocker")
    public boolean runningInDocker() {
        return Files.exists(Path.of("/.dockerenv"));
    }

-    @Produces
-    @Named("configDirMounted")
+    @Bean(name = "configDirMounted")
    public boolean isRunningInDockerWithConfig() {
        Path dockerEnv = Path.of("/.dockerenv");
        // default to true if not docker
@@ -196,7 +132,7 @@ public class AppConfig {
            return true;
        }
        Path mountInfo = Path.of("/proc/1/mountinfo");
-        // this should always exist, if not some unknown usecase
+        // this should always exist, if not some unknown use case
        if (!Files.exists(mountInfo)) {
            return true;
        }
@@ -207,23 +143,14 @@ public class AppConfig {
        }
    }

-    @Produces
-    @Named("activeSecurity")
+    @Bean(name = "activeSecurity")
    public boolean missingActiveSecurity() {
-        // MIGRATION: Spring ClassUtils.isPresent -> manual Class.forName presence check.
-        try {
-            Class.forName(
-                    "stirling.software.proprietary.security.configuration.SecurityConfiguration",
-                    false,
-                    this.getClass().getClassLoader());
-            return true;
-        } catch (ClassNotFoundException e) {
-            return false;
-        }
+        return ClassUtils.isPresent(
+                "stirling.software.proprietary.security.configuration.SecurityConfiguration",
+                this.getClass().getClassLoader());
    }

-    @Produces
-    @Named("directoryFilter")
+    @Bean(name = "directoryFilter")
    public Predicate<Path> processOnlyFiles() {
        return path -> {
            if (Files.isDirectory(path)) {
@@ -234,138 +161,113 @@ public class AppConfig {
        };
    }

-    @Produces
-    @Named("termsAndConditions")
+    @Bean(name = "termsAndConditions")
    public String termsAndConditions() {
        return applicationProperties.getLegal().getTermsAndConditions();
    }

-    @Produces
-    @Named("privacyPolicy")
+    @Bean(name = "privacyPolicy")
    public String privacyPolicy() {
        return applicationProperties.getLegal().getPrivacyPolicy();
    }

-    @Produces
-    @Named("cookiePolicy")
+    @Bean(name = "cookiePolicy")
    public String cookiePolicy() {
        return applicationProperties.getLegal().getCookiePolicy();
    }

-    @Produces
-    @Named("impressum")
+    @Bean(name = "impressum")
    public String impressum() {
        return applicationProperties.getLegal().getImpressum();
    }

-    @Produces
-    @Named("accessibilityStatement")
+    @Bean(name = "accessibilityStatement")
    public String accessibilityStatement() {
        return applicationProperties.getLegal().getAccessibilityStatement();
    }

-    @Produces
-    @Dependent
-    @Named("analyticsPrompt")
+    @Bean(name = "analyticsPrompt")
+    @Scope("request")
    public boolean analyticsPrompt() {
        return applicationProperties.getSystem().getEnableAnalytics() == null;
    }

-    @Produces
-    @Dependent
-    @Named("analyticsEnabled")
+    @Bean(name = "analyticsEnabled")
+    @Scope("request")
    public boolean analyticsEnabled() {
        if (applicationProperties.getPremium().isEnabled()) return true;
        return applicationProperties.getSystem().isAnalyticsEnabled();
    }

-    @Produces
-    @Named("StirlingPDFLabel")
+    @Bean(name = "StirlingPDFLabel")
    public String stirlingPDFLabel() {
        return "Stirling-PDF" + " v" + appVersion();
    }

-    @Produces
-    @Named("UUID")
+    @Bean(name = "UUID")
    public String uuid() {
        return applicationProperties.getAutomaticallyGenerated().getUUID();
    }

-    @Produces
+    @Bean
    public ApplicationProperties.Security security() {
        return applicationProperties.getSecurity();
    }

-    @Produces
+    @Bean
    public ApplicationProperties.Security.OAUTH2 oAuth2() {
        return applicationProperties.getSecurity().getOauth2();
    }

-    @Produces
+    @Bean
    public ApplicationProperties.Premium premium() {
        return applicationProperties.getPremium();
    }

-    @Produces
+    @Bean
    public ApplicationProperties.System system() {
        return applicationProperties.getSystem();
    }

-    @Produces
+    @Bean
    public ApplicationProperties.Datasource datasource() {
        return applicationProperties.getSystem().getDatasource();
    }

-    // @IfBuildProfile("core"): these NORMAL/default license @Named beans apply only to the core
-    // flavor. In proprietary EEAppConfig provides them (security profile) and in saas
-    // SaasLicenseOverride does (saas profile); registering this producer alongside those trips
-    // Qute's named-bean validation ("Duplicate key runningEE"), which does not honour @DefaultBean
-    // suppression - so gate to core outright. (In core, EEAppConfig/SaasLicenseOverride are not
-    // even on the classpath.)
-    @Produces
-    @IfBuildProfile("core")
-    @Named("runningProOrHigher")
+    @Bean(name = "runningProOrHigher")
+    @Profile("default")
    public boolean runningProOrHigher() {
        return false;
    }

-    @Produces
-    @IfBuildProfile("core")
-    @Named("runningEE")
+    @Bean(name = "runningEE")
+    @Profile("default")
    public boolean runningEnterprise() {
        return false;
    }

-    @Produces
-    @IfBuildProfile("core")
-    @Named("license")
+    @Bean(name = "license")
+    @Profile("default")
    public String licenseType() {
        return "NORMAL";
    }

-    @Produces
-    @Named("scarfEnabled")
+    @Bean(name = "scarfEnabled")
    public boolean scarfEnabled() {
        return applicationProperties.getSystem().isScarfEnabled();
    }

-    @Produces
-    @Named("posthogEnabled")
+    @Bean(name = "posthogEnabled")
    public boolean posthogEnabled() {
        return applicationProperties.getSystem().isPosthogEnabled();
    }

-    @Produces
-    @Named("machineType")
+    @Bean(name = "machineType")
    public String determineMachineType() {
        try {
            boolean isDocker = runningInDocker();
            boolean isKubernetes = System.getenv("KUBERNETES_SERVICE_HOST") != null;
-            boolean isBrowserOpen =
-                    "true"
-                            .equalsIgnoreCase(
-                                    config.getOptionalValue("BROWSER_OPEN", String.class)
-                                            .orElse(null));
+            boolean isBrowserOpen = "true".equalsIgnoreCase(env.getProperty("BROWSER_OPEN"));

            if (isKubernetes) {
                return "Kubernetes";
@@ -1,193 +0,0 @@
-package stirling.software.common.configuration;
-
-import java.lang.reflect.Field;
-import java.lang.reflect.Modifier;
-import java.lang.reflect.ParameterizedType;
-import java.lang.reflect.Type;
-import java.util.List;
-
-import org.eclipse.microprofile.config.Config;
-import org.eclipse.microprofile.config.ConfigProvider;
-
-import io.quarkus.arc.ClientProxy;
-import io.quarkus.runtime.StartupEvent;
-
-import jakarta.annotation.Priority;
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.event.Observes;
-import jakarta.inject.Inject;
-import jakarta.interceptor.Interceptor;
-
-import lombok.extern.slf4j.Slf4j;
-
-import stirling.software.common.model.ApplicationProperties;
-
-/**
- * Binds MicroProfile/Quarkus config (env vars, {@code settings.yml} via {@link
- * SettingsYamlConfigSource}, {@code application.properties}, system properties) onto the mutable
- * {@link ApplicationProperties} bean at startup - the Quarkus replacement for the Spring
- * {@code @ConfigurationProperties(prefix = "")} relaxed binding that was lost in the migration.
- *
- * <p>Rather than hand-listing each property, this walks the whole {@code ApplicationProperties}
- * object graph by reflection and, for every scalar / enum / scalar-list field, applies the value
- * from config when one is present (so unset fields keep their Java default). The dotted key for a
- * field mirrors its path in the tree ({@code security.oauth2.client.keycloak.clientId}, {@code
- * endpoints.toRemove}, ...); SmallRye then resolves it from any source - e.g. env var {@code
- * SECURITY_OAUTH2_CLIENT_KEYCLOAK_CLIENTID} or the same key in {@code settings.yml} - with the
- * usual precedence (sys props &gt; env &gt; settings.yml &gt; application.properties).
- *
- * <p>This is the behaviour Spring had: every settings.yml / {@code SECURITY_*}/{@code STORAGE_*}
- * /{@code PREMIUM_*} value is honoured, fixing the whole {@code maxDPI=0} / {@code enableLogin}
- * /{@code endpoints.toRemove} / premium-license class of "ignored config" bugs at once.
- *
- * <p>Runs with {@code @Priority(APPLICATION)} so it completes before startup consumers read the
- * bean: {@code InitialSecuritySetup} (enableLogin / customGlobalAPIKey), {@code
- * EndpointConfiguration} (endpoints.toRemove), and {@code LicenseKeyChecker.onApplicationReady}
- * (premium.enabled / premium.key, which has the lower default observer priority 2500).
- *
- * <p>Values are never logged - only key names at DEBUG and a total at INFO - because the tree
- * carries secrets (premium key, client secrets, initial-login password, SMTP/Telegram tokens).
- */
-@Slf4j
-@ApplicationScoped
-public class ApplicationPropertiesConfigOverlay {
-
-    private static final int MAX_DEPTH = 20;
-
-    @Inject ApplicationProperties applicationProperties;
-
-    void onStart(@Observes @Priority(Interceptor.Priority.APPLICATION) StartupEvent event) {
-        Config config = ConfigProvider.getConfig();
-        // ApplicationProperties is @ApplicationScoped, so the injected reference is a client proxy;
-        // reflect over the real contextual instance (its getters delegate, but getDeclaredFields()
-        // on the proxy would not see the model fields).
-        Object root = applicationProperties;
-        if (root instanceof ClientProxy proxy) {
-            root = proxy.arc_contextualInstance();
-        }
-        int[] applied = {0};
-        bind(root, "", config, 0, applied);
-        log.info(
-                "Applied {} configuration override(s) onto ApplicationProperties"
-                        + " (settings.yml + environment)",
-                applied[0]);
-    }
-
-    private void bind(Object node, String prefix, Config config, int depth, int[] applied) {
-        if (node == null || depth > MAX_DEPTH) {
-            return;
-        }
-        for (Field field : node.getClass().getDeclaredFields()) {
-            int mods = field.getModifiers();
-            if (Modifier.isStatic(mods) || field.isSynthetic()) {
-                continue;
-            }
-            String key = prefix.isEmpty() ? field.getName() : prefix + "." + field.getName();
-            Class<?> type = field.getType();
-            try {
-                field.setAccessible(true);
-                if (isModelType(type)) {
-                    Object child = field.get(node);
-                    if (child == null) {
-                        child = instantiate(type);
-                        if (child != null) {
-                            field.set(node, child);
-                        }
-                    }
-                    bind(child, key, config, depth + 1, applied);
-                } else if (List.class.isAssignableFrom(type)) {
-                    Class<?> element = listElementType(field);
-                    if (element != null && isLeaf(element)) {
-                        config.getOptionalValues(key, element)
-                                .ifPresent(value -> apply(field, node, value, key, applied));
-                    }
-                    // List<model-type> has no flat scalar representation here - skip.
-                } else if (isLeaf(type)) {
-                    config.getOptionalValue(key, box(type))
-                            .ifPresent(value -> apply(field, node, value, key, applied));
-                }
-                // Maps and other container/unsupported types are left to their Java defaults.
-            } catch (Exception ex) {
-                // Per-field best effort: an unconvertible value or inaccessible field must not
-                // abort
-                // the whole overlay. Never include the value (may be a secret).
-                log.debug("Skipped config binding for {} ({})", key, ex.toString());
-            }
-        }
-    }
-
-    private void apply(Field field, Object node, Object value, String key, int[] applied) {
-        try {
-            field.set(node, value);
-            applied[0]++;
-            // Key name only - the value may be a secret (license key, password, client secret).
-            log.debug("Applied config override: {}", key);
-        } catch (Exception ex) {
-            log.debug("Failed to set {} ({})", key, ex.toString());
-        }
-    }
-
-    private static boolean isModelType(Class<?> type) {
-        return type.getName().startsWith("stirling.software") && !type.isEnum();
-    }
-
-    private static boolean isLeaf(Class<?> type) {
-        return type == String.class
-                || type.isEnum()
-                || type.isPrimitive()
-                || type == Boolean.class
-                || type == Integer.class
-                || type == Long.class
-                || type == Double.class
-                || type == Float.class
-                || type == Short.class
-                || type == Byte.class;
-    }
-
-    private static Class<?> box(Class<?> type) {
-        if (!type.isPrimitive()) {
-            return type;
-        }
-        if (type == boolean.class) {
-            return Boolean.class;
-        }
-        if (type == int.class) {
-            return Integer.class;
-        }
-        if (type == long.class) {
-            return Long.class;
-        }
-        if (type == double.class) {
-            return Double.class;
-        }
-        if (type == float.class) {
-            return Float.class;
-        }
-        if (type == short.class) {
-            return Short.class;
-        }
-        if (type == byte.class) {
-            return Byte.class;
-        }
-        return type;
-    }
-
-    private static Class<?> listElementType(Field field) {
-        Type generic = field.getGenericType();
-        if (generic instanceof ParameterizedType parameterized) {
-            Type[] args = parameterized.getActualTypeArguments();
-            if (args.length == 1 && args[0] instanceof Class<?> element) {
-                return element;
-            }
-        }
-        return null;
-    }
-
-    private static Object instantiate(Class<?> type) {
-        try {
-            return type.getDeclaredConstructor().newInstance();
-        } catch (Exception ex) {
-            return null;
-        }
-    }
-}
@@ -1,29 +1,28 @@
 package stirling.software.common.configuration;

-import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;

 import com.posthog.java.PostHog;

 import jakarta.annotation.PreDestroy;
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.inject.Produces;

 import lombok.extern.slf4j.Slf4j;

-@ApplicationScoped
+@Configuration
@Slf4j
 public class PostHogConfig {

-    @ConfigProperty(name = "posthog.api.key")
-    String posthogApiKey;
+    @Value("${posthog.api.key}")
+    private String posthogApiKey;

-    @ConfigProperty(name = "posthog.host")
-    String posthogHost;
+    @Value("${posthog.host}")
+    private String posthogHost;

    private PostHog postHogClient;

-    @Produces
-    @ApplicationScoped
+    @Bean
    public PostHog postHogClient() {
        postHogClient =
                new PostHog.Builder(posthogApiKey)
@@ -1,13 +1,13 @@
 package stirling.software.common.configuration;

-import com.posthog.java.PostHogLogger;
+import org.springframework.stereotype.Component;

-import jakarta.enterprise.context.ApplicationScoped;
+import com.posthog.java.PostHogLogger;

 import lombok.extern.slf4j.Slf4j;

@Slf4j
-@ApplicationScoped
+@Component
 public class PostHogLoggerImpl implements PostHogLogger {

    @Override
@@ -10,8 +10,7 @@ import java.util.List;
 import java.util.Set;

 import org.apache.commons.lang3.StringUtils;
-
-import jakarta.enterprise.context.ApplicationScoped;
+import org.springframework.context.annotation.Configuration;

 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
@@ -25,7 +24,7 @@ import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.UnoServerPool;

@Slf4j
-@ApplicationScoped
+@Configuration
@Getter
 public class RuntimePathConfig {
    private final ApplicationProperties properties;
@@ -1,19 +1,23 @@
 package stirling.software.common.configuration;

+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.TaskScheduler;
+import org.springframework.scheduling.concurrent.SimpleAsyncTaskScheduler;
+
 /**
 * Configures the scheduler used by all {@code @Scheduled} methods. Uses virtual threads so that
 * long-running scheduled tasks (e.g. cleanup, license checks, file monitoring) never block each
 * other — each runs on its own lightweight virtual thread.
- *
- * <p>MIGRATION (Spring -> Quarkus): the custom Spring {@code TaskScheduler} bean has been removed.
- * Quarkus' {@code quarkus-scheduler} extension owns the scheduling thread pool, so no application
- * bean is required. To keep the "each scheduled task on its own virtual thread" behaviour, annotate
- * the individual {@code @io.quarkus.scheduler.Scheduled} methods with
- * {@code @io.smallrye.common.annotation.RunOnVirtualThread} (or configure {@code
- * quarkus.scheduler.use-virtual-threads=true} where supported).
- *
- * <p>TODO: Migration required - any injection point that received the former Spring {@code
- * TaskScheduler} bean must be rewritten to use the Quarkus scheduler API or a CDI-managed {@code
- * java.util.concurrent.ScheduledExecutorService}.
 */
-public class SchedulingConfig {}
+@Configuration
+public class SchedulingConfig {
+
+    @Bean
+    public TaskScheduler taskScheduler() {
+        SimpleAsyncTaskScheduler scheduler = new SimpleAsyncTaskScheduler();
+        scheduler.setVirtualThreads(true);
+        scheduler.setThreadNamePrefix("scheduled-vt-");
+        return scheduler;
+    }
+}
@@ -1,141 +0,0 @@
-package stirling.software.common.configuration;
-
-import java.io.InputStream;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-import org.eclipse.microprofile.config.spi.ConfigSource;
-import org.snakeyaml.engine.v2.api.Load;
-import org.snakeyaml.engine.v2.api.LoadSettings;
-
-/**
- * Exposes {@code settings.yml} (and {@code custom_settings.yml}, with the bundled {@code
- * settings.yml.template} as the default fallback) as a MicroProfile/SmallRye {@link ConfigSource}.
- *
- * <p>Restores the Spring {@code @ConfigurationProperties} behaviour that bound {@code settings.yml}
- * into {@code ApplicationProperties}: without this the YAML was never read under Quarkus, so flags
- * like {@code security.enableLogin} fell back to their Java defaults regardless of the file (the
- * {@code enableLogin=false}/{@code maxDPI=0}/{@code loginAttemptCount=0} class of bugs). The nested
- * YAML is flattened to dotted keys ({@code security.enableLogin -> "true"}); {@link
- * ApplicationPropertiesConfigOverlay} and {@code @ConfigProperty} injections then read them.
- *
- * <p>Ordinal {@value #ORDINAL} sits above {@code application.properties} (250) but below
- * environment variables (300) and system properties (400), matching Spring's precedence - e.g.
- * {@code SECURITY_ENABLELOGIN} still overrides the file.
- *
- * <p>Registered via {@code META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource}.
- */
-public class SettingsYamlConfigSource implements ConfigSource {
-
-    private static final int ORDINAL = 275;
-
-    private final Map<String, String> properties;
-
-    public SettingsYamlConfigSource() {
-        this.properties = load();
-    }
-
-    private static Map<String, String> load() {
-        Map<String, String> flat = new HashMap<>();
-        // 1. Bundled template provides the defaults (e.g. security.enableLogin: true).
-        try (InputStream in =
-                SettingsYamlConfigSource.class
-                        .getClassLoader()
-                        .getResourceAsStream("settings.yml.template")) {
-            if (in != null) {
-                flatten("", loadYaml(in), flat);
-            }
-        } catch (Exception ignored) {
-            // best effort - fall through to file overrides / Java defaults
-        }
-        // 2. The user's settings.yml overrides the template.
-        mergeFile(InstallationPathConfig.getSettingsPath(), flat);
-        // 3. custom_settings.yml overrides settings.yml.
-        mergeFile(InstallationPathConfig.getCustomSettingsPath(), flat);
-        return flat;
-    }
-
-    private static void mergeFile(String path, Map<String, String> flat) {
-        try {
-            Path p = Path.of(path);
-            if (Files.isRegularFile(p)) {
-                try (InputStream in = Files.newInputStream(p)) {
-                    flatten("", loadYaml(in), flat);
-                }
-            }
-        } catch (Exception ignored) {
-            // unreadable/invalid file - keep whatever defaults were already loaded
-        }
-    }
-
-    private static Object loadYaml(InputStream in) {
-        return new Load(LoadSettings.builder().build()).loadFromInputStream(in);
-    }
-
-    private static void flatten(String prefix, Object node, Map<String, String> out) {
-        if (node instanceof Map<?, ?> map) {
-            for (Map.Entry<?, ?> e : map.entrySet()) {
-                String key =
-                        prefix.isEmpty() ? String.valueOf(e.getKey()) : prefix + "." + e.getKey();
-                flatten(key, e.getValue(), out);
-            }
-        } else if (node instanceof List<?> list) {
-            // Emit scalar lists as a comma-separated value so SmallRye binds them via
-            // config.getValues()/getOptionalValues() (e.g. endpoints.toRemove, consumed by
-            // EndpointConfiguration to disable endpoints). Lists containing maps/nested lists have
-            // no
-            // flat scalar form, so skip those - their consumers read them structurally, not through
-            // this overlay. The scalar lists here (endpoint names, group names) contain no commas,
-            // so
-            // a plain join round-trips cleanly.
-            boolean scalarList =
-                    !list.isEmpty()
-                            && list.stream()
-                                    .allMatch(
-                                            e ->
-                                                    e != null
-                                                            && !(e instanceof Map)
-                                                            && !(e instanceof List));
-            if (scalarList) {
-                out.put(
-                        prefix,
-                        list.stream()
-                                .map(String::valueOf)
-                                .collect(java.util.stream.Collectors.joining(",")));
-            }
-            return;
-        } else if (node != null) {
-            out.put(prefix, String.valueOf(node));
-        }
-        // null leaves are left unset so the Java default applies.
-    }
-
-    @Override
-    public Map<String, String> getProperties() {
-        return properties;
-    }
-
-    @Override
-    public Set<String> getPropertyNames() {
-        return properties.keySet();
-    }
-
-    @Override
-    public String getValue(String propertyName) {
-        return properties.get(propertyName);
-    }
-
-    @Override
-    public String getName() {
-        return "settings.yml";
-    }
-
-    @Override
-    public int getOrdinal() {
-        return ORDINAL;
-    }
-}
@@ -0,0 +1,22 @@
+package stirling.software.common.configuration;
+
+import java.util.Properties;
+
+import org.springframework.beans.factory.config.YamlPropertiesFactoryBean;
+import org.springframework.core.env.PropertiesPropertySource;
+import org.springframework.core.env.PropertySource;
+import org.springframework.core.io.support.EncodedResource;
+import org.springframework.core.io.support.PropertySourceFactory;
+
+public class YamlPropertySourceFactory implements PropertySourceFactory {
+
+    @Override
+    public PropertySource<?> createPropertySource(String name, EncodedResource encodedResource) {
+        YamlPropertiesFactoryBean factory = new YamlPropertiesFactoryBean();
+        factory.setResources(encodedResource.getResource());
+        Properties properties = factory.getObject();
+
+        return new PropertiesPropertySource(
+                encodedResource.getResource().getFilename(), properties);
+    }
+}
@@ -1,6 +1,7 @@
 package stirling.software.common.model;

 import java.io.File;
+import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.HttpURLConnection;
@@ -14,11 +15,22 @@ import java.util.List;
 import java.util.Locale;
 import java.util.UUID;

+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.core.env.ConfigurableEnvironment;
+import org.springframework.core.env.PropertySource;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.core.io.Resource;
+import org.springframework.core.io.support.EncodedResource;
+import org.springframework.stereotype.Component;
+
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;

 import jakarta.annotation.PostConstruct;
-import jakarta.enterprise.context.ApplicationScoped;

 import lombok.Data;
 import lombok.Getter;
@@ -27,11 +39,9 @@ import lombok.ToString;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.configuration.InstallationPathConfig;
+import stirling.software.common.configuration.YamlPropertySourceFactory;
 import stirling.software.common.constants.JwtConstants;
 import stirling.software.common.model.exception.UnsupportedProviderException;
-import stirling.software.common.model.io.ClassPathResource;
-import stirling.software.common.model.io.FileSystemResource;
-import stirling.software.common.model.io.Resource;
 import stirling.software.common.model.oauth2.GitHubProvider;
 import stirling.software.common.model.oauth2.GoogleProvider;
 import stirling.software.common.model.oauth2.KeycloakProvider;
@@ -41,12 +51,9 @@ import stirling.software.common.util.ValidationUtils;

@Data
@Slf4j
-@ApplicationScoped
-// TODO: Migration required - rebind via @io.smallrye.config.ConfigMapping or
-// @io.quarkus.arc.config.ConfigProperties. Was Spring @ConfigurationProperties(prefix = ""),
-// kept here as a plain CDI bean POJO; the property binding is not yet wired in Quarkus.
-// TODO: Migration required - Spring @Order(Ordered.HIGHEST_PRECEDENCE) controlled
-// configuration-bean ordering; there is no equivalent CDI ordering annotation for this bean.
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+@ConfigurationProperties(prefix = "")
 public class ApplicationProperties {

    private Legal legal = new Legal();
@@ -75,17 +82,38 @@ public class ApplicationProperties {
    private Cluster cluster = new Cluster();
    private Policies policies = new Policies();

-    // REMOVED (Spring -> Quarkus): dynamicYamlPropertySource(ConfigurableEnvironment).
-    // This was a Spring @Bean that registered settings.yml as an extra runtime PropertySource on
-    // the
-    // ConfigurableEnvironment (added first, or last under the "saas" profile). Quarkus has no
-    // ConfigurableEnvironment/PropertySource model and the @Bean had already been removed, so the
-    // method was dead code referencing Spring-only types.
-    // TODO: Migration required - reimplement external settings.yml loading as a custom
-    // org.eclipse.microprofile.config.spi.ConfigSource (registered via a ConfigSourceProvider /
-    // META-INF/services), giving it an ordinal that reproduces the old precedence: higher than the
-    // application defaults normally, but lower than application-saas.properties under the saas
-    // profile. Wire it in ConfigInitializer.
+    @Bean
+    public PropertySource<?> dynamicYamlPropertySource(ConfigurableEnvironment environment)
+            throws IOException {
+        String configPath = InstallationPathConfig.getSettingsPath();
+        log.debug("Attempting to load settings from: {}", configPath);
+
+        File file = new File(configPath);
+        if (!file.exists()) {
+            log.error("Warning: Settings file does not exist at: {}", configPath);
+        }
+
+        Resource resource = new FileSystemResource(configPath);
+        if (!resource.exists()) {
+            throw new FileNotFoundException("Settings file not found at: " + configPath);
+        }
+
+        EncodedResource encodedResource = new EncodedResource(resource);
+        PropertySource<?> propertySource =
+                new YamlPropertySourceFactory().createPropertySource(null, encodedResource);
+
+        boolean saasActive = Arrays.asList(environment.getActiveProfiles()).contains("saas");
+        if (saasActive) {
+            // Saas-pinned values in application-saas.properties must beat settings.yml.
+            environment.getPropertySources().addLast(propertySource);
+        } else {
+            environment.getPropertySources().addFirst(propertySource);
+        }
+
+        log.debug("Loaded properties: {}", propertySource.getSource());
+
+        return propertySource;
+    }

    /**
     * Initialize fileUploadLimit from environment variables if not set in settings.yml. Supports
@@ -178,6 +206,11 @@ public class ApplicationProperties {

    @Data
    public static class Policies {
+        /**
+         * Master switch for the policy + sources subsystem (the PAYG-metered automation surface).
+         */
+        private boolean enabled = false;
+
        /**
         * Absolute directories that policy folder input sources and output sinks may read from or
         * write to. Empty (the default) disables folder access entirely, so a policy can never be
@@ -486,6 +519,14 @@ public class ApplicationProperties {
        private String accessibilityStatement;
        private String cookiePolicy;
        private String impressum;
+        private LoginAgreement loginAgreement = new LoginAgreement();
+
+        @Data
+        public static class LoginAgreement {
+            private boolean enabled = false;
+            private boolean showInAnonymousMode = true;
+            private String fallbackText = "";
+        }
    }

    @Data
@@ -494,12 +535,8 @@ public class ApplicationProperties {
        private InitialLogin initialLogin = new InitialLogin();
        private OAUTH2 oauth2 = new OAUTH2();
        private SAML2 saml2 = new SAML2();
-        // Defaults mirror settings.yml.template. These primitives are not bound from the template
-        // by the current Quarkus config path, so an unset 0 means "lock after 0 attempts" (every
-        // login blocked, and the lockout never accumulates a window) - same class of bug as
-        // maxDPI=0. See the settings.yml binding TODO.
-        private int loginAttemptCount = 5;
-        private long loginResetTimeMinutes = 120;
+        private int loginAttemptCount;
+        private long loginResetTimeMinutes;
        private String loginMethod = "all";
        private String customGlobalAPIKey;
        private Jwt jwt = new Jwt();
@@ -558,7 +595,7 @@ public class ApplicationProperties {
        public static class SAML2 {
            private String provider;
            private Boolean enabled = false;
-            private Boolean autoCreateUser = false;
+            private Boolean autoCreateUser = true;
            private Boolean blockRegistration = false;
            private String registrationId = "stirling";

@@ -584,9 +621,8 @@ public class ApplicationProperties {
            @JsonIgnore
            public InputStream getIdpMetadataUri() throws IOException {
                if (idpMetadataUri.startsWith("classpath:")) {
-                    return getClass()
-                            .getClassLoader()
-                            .getResourceAsStream(idpMetadataUri.substring("classpath:".length()));
+                    return new ClassPathResource(idpMetadataUri.substring("classpath:".length()))
+                            .getInputStream();
                }
                try {
                    URI uri = new URI(idpMetadataUri);
@@ -599,9 +635,6 @@ public class ApplicationProperties {
                }
            }

-            // TODO: Migration required - returns org.springframework.core.io.Resource, a public
-            // signature relied on by callers. Converting to InputStream/byte[]/java.nio would
-            // ripple to those call sites, so the Spring Resource type is retained for now.
            @JsonIgnore
            public Resource getSpCert() {
                if (spCert == null) return null;
@@ -612,9 +645,6 @@ public class ApplicationProperties {
                }
            }

-            // TODO: Migration required - returns org.springframework.core.io.Resource, a public
-            // signature relied on by callers. Converting to InputStream/byte[]/java.nio would
-            // ripple to those call sites, so the Spring Resource type is retained for now.
            @JsonIgnore
            public Resource getIdpCert() {
                if (idpCert == null) return null;
@@ -625,9 +655,6 @@ public class ApplicationProperties {
                }
            }

-            // TODO: Migration required - returns org.springframework.core.io.Resource, a public
-            // signature relied on by callers. Converting to InputStream/byte[]/java.nio would
-            // ripple to those call sites, so the Spring Resource type is retained for now.
            @JsonIgnore
            public Resource getPrivateKey() {
                if (privateKey == null) return null;
@@ -645,7 +672,7 @@ public class ApplicationProperties {
            private String issuer;
            private String clientId;
            @ToString.Exclude private String clientSecret;
-            private Boolean autoCreateUser = false;
+            private Boolean autoCreateUser = true;
            private Boolean blockRegistration = false;
            private String useAsUsername;
            private Collection<String> scopes = new ArrayList<>();
@@ -716,7 +743,6 @@ public class ApplicationProperties {
        @Data
        public static class Jwt {
            private boolean enableKeystore = true;
-            private boolean enableKeyRotation = false;
            private boolean enableKeyCleanup = true;

            /**
@@ -820,8 +846,8 @@ public class ApplicationProperties {
            @Data
            public static class Trust {
                private boolean serverAsAnchor = true;
-                private boolean useSystemTrust = false;
-                private boolean useMozillaBundle = false;
+                private boolean useSystemTrust = true;
+                private boolean useMozillaBundle = true;
                private boolean useAATL = false;
                private boolean useEUTL = false;
            }
@@ -855,8 +881,8 @@ public class ApplicationProperties {
    public static class System {
        private String defaultLocale;
        private boolean googlevisibility;
-        private boolean showUpdate;
-        private boolean showUpdateOnlyAdmin;
+        private boolean showUpdate = true;
+        private boolean showUpdateOnlyAdmin = true;
        private boolean showSettingsWhenNoLogin = true;
        private boolean customHTMLFiles;
        private String tessdataDir;
@@ -864,12 +890,9 @@ public class ApplicationProperties {
        private Boolean enableAnalytics;
        private Boolean enablePosthog;
        private Boolean enableScarf;
-        private Boolean enableDesktopInstallSlide;
+        private Boolean enableDesktopInstallSlide = true;
        private Datasource datasource;
        private boolean disableSanitize;
-        // Default mirrors settings.yml.template (maxDPI: 500). Without an explicit default this
-        // primitive is 0, which makes every DPI check (dpi > maxDPI) fail with "maximum safe limit
-        // of 0" when the value is not populated from settings.
        private int maxDPI = 500;
        private boolean enableUrlToPDF;
        private Html html = new Html();
@@ -884,8 +907,9 @@ public class ApplicationProperties {
        private String frontendUrl; // Frontend URL for invite email links (e.g.

        // 'https://app.example.com'). If not set, falls back to backendUrl.
-        private boolean enableMobileScanner = false; // Enable mobile phone QR code upload feature
+        private boolean enableMobileScanner = true; // Enable mobile phone QR code upload feature
        private MobileScannerSettings mobileScannerSettings = new MobileScannerSettings();
+        private ServerCertificate serverCertificate = new ServerCertificate();

        @Data
        public static class MobileScannerSettings {
@@ -895,6 +919,16 @@ public class ApplicationProperties {
            private boolean stretchToFit = false; // Whether to stretch image to fill page
        }

+        @Data
+        public static class ServerCertificate {
+            private boolean enabled =
+                    true; // Enable server-side "Sign with Stirling-PDF" certificate
+            private String organizationName = "Stirling PDF Inc";
+            private int validity = 365; // Certificate validity in days
+            private boolean regenerateOnStartup =
+                    false; // Generate a new certificate on each startup
+        }
+
        public boolean isAnalyticsEnabled() {
            return this.enableAnalytics != null && this.enableAnalytics;
        }
@@ -979,7 +1013,7 @@ public class ApplicationProperties {
        @Data
        public static class Sharing {
            private boolean enabled = false;
-            private boolean linkEnabled = false;
+            private boolean linkEnabled = true;
            private boolean emailEnabled = false;
            private int linkExpirationDays = 3;
        }
@@ -1153,7 +1187,7 @@ public class ApplicationProperties {

    @Data
    public static class Metrics {
-        private boolean enabled;
+        private boolean enabled = true;
    }

    @Data
@@ -1205,7 +1239,7 @@ public class ApplicationProperties {
        private boolean enableInvites = false;
        private int inviteLinkExpiryHours = 72; // Default: 72 hours (3 days)
        private String host;
-        private int port;
+        private int port = 587;
        private String username;
        @ToString.Exclude private String password;
        private String from;
@@ -1232,10 +1266,10 @@ public class ApplicationProperties {
        @ToString.Exclude private String botToken;
        private String botUsername;
        private String pipelineInboxFolder = "telegram";
-        private Boolean customFolderSuffix = false;
-        private Boolean enableAllowUserIDs = false;
+        private Boolean customFolderSuffix = true;
+        private Boolean enableAllowUserIDs = true;
        private List<Long> allowUserIDs = new ArrayList<>();
-        private Boolean enableAllowChannelIDs = false;
+        private Boolean enableAllowChannelIDs = true;
        private List<Long> allowChannelIDs = new ArrayList<>();
        private long processingTimeoutSeconds = 180;
        private long pollingIntervalMillis = 2000;
@@ -1,70 +0,0 @@
-package stirling.software.common.model;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.nio.file.Files;
-import java.nio.file.Path;
-
-import stirling.software.common.model.io.Resource;
-
-/**
- * Migration compatibility shim for Spring's {@code
- * org.springframework.web.multipart.MultipartFile}.
- *
- * <p>Quarkus/JAX-RS has no drop-in equivalent for the {@code MultipartFile} abstraction that the
- * service layer relies on (it exposes {@code org.jboss.resteasy.reactive.multipart.FileUpload} at
- * the REST boundary instead). To avoid rewriting the public signatures of dozens of service and
- * util methods across every module, this interface mirrors the subset of Spring's API that the
- * codebase actually uses. Controllers adapt the inbound {@code FileUpload}/{@code byte[]} to one of
- * the implementations ({@link stirling.software.common.model.multipart.ByteArrayMultipartFile},
- * {@link stirling.software.common.model.multipart.FileUploadMultipartFile}) and pass it down
- * unchanged.
- *
- * <p>TODO: Migration required - longer term, the REST boundary should standardise on {@code
- * FileUpload}/{@code @RestForm} and this shim can be retired.
- */
-public interface MultipartFile {
-
-    String getName();
-
-    String getOriginalFilename();
-
-    String getContentType();
-
-    boolean isEmpty();
-
-    long getSize();
-
-    byte[] getBytes() throws IOException;
-
-    InputStream getInputStream() throws IOException;
-
-    /**
-     * The content as a {@link Resource}. The default is a stream-backed resource; file-backed
-     * implementations (e.g. {@code FileUploadMultipartFile}) override this to enable zero-copy fast
-     * paths.
-     */
-    default Resource getResource() {
-        try {
-            return new stirling.software.common.model.io.InputStreamResource(
-                    getInputStream(), getOriginalFilename());
-        } catch (IOException e) {
-            throw new java.io.UncheckedIOException(e);
-        }
-    }
-
-    default void transferTo(File dest) throws IOException {
-        transferTo(dest.toPath());
-    }
-
-    default void transferTo(Path dest) throws IOException {
-        try (InputStream in = getInputStream()) {
-            // Spring's MultipartFile#transferTo overwrites an existing destination. Callers
-            // commonly
-            // pass a path from Files.createTempFile(...) (which has already created an empty file),
-            // so REPLACE_EXISTING is required - a plain Files.copy would throw FileAlreadyExists.
-            Files.copy(in, dest, java.nio.file.StandardCopyOption.REPLACE_EXISTING);
-        }
-    }
-}
@@ -1,12 +1,12 @@
 package stirling.software.common.model.api;

+import org.springframework.web.multipart.MultipartFile;
+
 import io.swagger.v3.oas.annotations.media.Schema;

 import lombok.Data;
 import lombok.EqualsAndHashCode;

-import stirling.software.common.model.MultipartFile;
-
@Data
@EqualsAndHashCode
 public class GeneralFile {
@@ -1,5 +1,8 @@
 package stirling.software.common.model.api;

+import org.springframework.http.MediaType;
+import org.springframework.web.multipart.MultipartFile;
+
 import io.swagger.v3.oas.annotations.media.Schema;

 import jakarta.validation.constraints.AssertTrue;
@@ -8,8 +11,6 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;

-import stirling.software.common.model.MultipartFile;
-
@Data
@NoArgsConstructor
@EqualsAndHashCode
@@ -17,7 +18,7 @@ public class PDFFile {

    @Schema(
            description = "The input PDF file",
-            contentMediaType = "application/pdf",
+            contentMediaType = MediaType.APPLICATION_PDF_VALUE,
            format = "binary")
    private MultipartFile fileInput;

@@ -1,64 +0,0 @@
-package stirling.software.common.model.io;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.net.URL;
-
-/** Classpath-backed {@link Resource} (migration shim for Spring's {@code ClassPathResource}). */
-public class ClassPathResource implements Resource {
-
-    private final String path;
-    private final ClassLoader classLoader;
-
-    public ClassPathResource(String path) {
-        this(path, ClassPathResource.class.getClassLoader());
-    }
-
-    public ClassPathResource(String path, ClassLoader classLoader) {
-        this.path = path.startsWith("/") ? path.substring(1) : path;
-        this.classLoader = classLoader != null ? classLoader : ClassLoader.getSystemClassLoader();
-    }
-
-    @Override
-    public InputStream getInputStream() throws IOException {
-        InputStream is = classLoader.getResourceAsStream(path);
-        if (is == null) {
-            throw new IOException("class path resource [" + path + "] cannot be opened");
-        }
-        return is;
-    }
-
-    @Override
-    public boolean exists() {
-        return classLoader.getResource(path) != null;
-    }
-
-    @Override
-    public String getFilename() {
-        int sep = path.lastIndexOf('/');
-        return sep != -1 ? path.substring(sep + 1) : path;
-    }
-
-    @Override
-    public long contentLength() throws IOException {
-        try (InputStream is = getInputStream()) {
-            long count = 0;
-            byte[] buf = new byte[8192];
-            int read;
-            while ((read = is.read(buf)) != -1) {
-                count += read;
-            }
-            return count;
-        }
-    }
-
-    @Override
-    public File getFile() throws IOException {
-        URL url = classLoader.getResource(path);
-        if (url == null || !"file".equals(url.getProtocol())) {
-            throw new IOException("class path resource [" + path + "] is not a filesystem file");
-        }
-        return new File(url.getFile());
-    }
-}
@@ -1,56 +0,0 @@
-package stirling.software.common.model.io;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.nio.file.Files;
-import java.nio.file.Path;
-
-/** File-backed {@link Resource} (migration shim for Spring's {@code FileSystemResource}). */
-public class FileSystemResource implements Resource {
-
-    private final Path path;
-
-    public FileSystemResource(Path path) {
-        this.path = path;
-    }
-
-    public FileSystemResource(File file) {
-        this.path = file.toPath();
-    }
-
-    public FileSystemResource(String path) {
-        this.path = Path.of(path);
-    }
-
-    @Override
-    public InputStream getInputStream() throws IOException {
-        return Files.newInputStream(path);
-    }
-
-    @Override
-    public boolean exists() {
-        return Files.exists(path);
-    }
-
-    @Override
-    public String getFilename() {
-        Path name = path.getFileName();
-        return name == null ? null : name.toString();
-    }
-
-    @Override
-    public long contentLength() throws IOException {
-        return Files.size(path);
-    }
-
-    @Override
-    public boolean isFile() {
-        return true;
-    }
-
-    @Override
-    public File getFile() {
-        return path.toFile();
-    }
-}
@@ -1,50 +0,0 @@
-package stirling.software.common.model.io;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-
-/**
- * Stream-backed {@link Resource} (migration shim for Spring's {@code InputStreamResource}). As with
- * Spring, the stream can only be read once.
- */
-public class InputStreamResource implements Resource {
-
-    private final InputStream inputStream;
-    private final String filename;
-
-    public InputStreamResource(InputStream inputStream) {
-        this(inputStream, null);
-    }
-
-    public InputStreamResource(InputStream inputStream, String filename) {
-        this.inputStream = inputStream;
-        this.filename = filename;
-    }
-
-    @Override
-    public InputStream getInputStream() {
-        return inputStream;
-    }
-
-    @Override
-    public boolean exists() {
-        return true;
-    }
-
-    @Override
-    public String getFilename() {
-        return filename;
-    }
-
-    @Override
-    public long contentLength() throws IOException {
-        // Spring's InputStreamResource also cannot report length without consuming the stream.
-        return -1;
-    }
-
-    @Override
-    public File getFile() throws IOException {
-        throw new IOException("InputStreamResource is not backed by a file");
-    }
-}
@@ -1,40 +0,0 @@
-package stirling.software.common.model.io;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-
-/**
- * Migration compatibility shim for Spring's {@code org.springframework.core.io.Resource}.
- *
- * <p>Quarkus/Jakarta has no single {@code Resource} abstraction. Rather than rewrite the many
- * public method signatures across the codebase that accept or return {@code Resource}, this
- * interface mirrors the subset of Spring's API the codebase actually uses ({@code
- * getInputStream/exists/getFile/getFilename/contentLength/isFile}) together with the {@link
- * FileSystemResource}, {@link InputStreamResource} and {@link ClassPathResource} implementations.
- * Converting a file is then just an import swap.
- *
- * <p>TODO: Migration required - longer term, prefer {@code java.nio.file.Path} / {@code
- * InputStream} directly at the boundaries and retire this shim.
- */
-public interface Resource {
-
-    InputStream getInputStream() throws IOException;
-
-    boolean exists();
-
-    String getFilename();
-
-    long contentLength() throws IOException;
-
-    /** Whether this resource is backed by a real file in the filesystem. */
-    default boolean isFile() {
-        return false;
-    }
-
-    /**
-     * @return the underlying file.
-     * @throws IOException if the resource is not file-backed.
-     */
-    File getFile() throws IOException;
-}
@@ -1,68 +0,0 @@
-package stirling.software.common.model.multipart;
-
-import java.io.ByteArrayInputStream;
-import java.io.InputStream;
-
-import stirling.software.common.model.MultipartFile;
-import stirling.software.common.model.io.InputStreamResource;
-import stirling.software.common.model.io.Resource;
-
-/**
- * In-memory {@link MultipartFile} backed by a byte array. Useful for tests and for code paths that
- * synthesize file content (migration shim - see {@link MultipartFile}).
- */
-public class ByteArrayMultipartFile implements MultipartFile {
-
-    private final String name;
-    private final String originalFilename;
-    private final String contentType;
-    private final byte[] content;
-
-    public ByteArrayMultipartFile(
-            String name, String originalFilename, String contentType, byte[] content) {
-        this.name = name;
-        this.originalFilename = originalFilename;
-        this.contentType = contentType;
-        this.content = content != null ? content : new byte[0];
-    }
-
-    @Override
-    public String getName() {
-        return name;
-    }
-
-    @Override
-    public String getOriginalFilename() {
-        return originalFilename;
-    }
-
-    @Override
-    public String getContentType() {
-        return contentType;
-    }
-
-    @Override
-    public boolean isEmpty() {
-        return content.length == 0;
-    }
-
-    @Override
-    public long getSize() {
-        return content.length;
-    }
-
-    @Override
-    public byte[] getBytes() {
-        return content;
-    }
-
-    @Override
-    public InputStream getInputStream() {
-        return new ByteArrayInputStream(content);
-    }
-
-    @Override
-    public Resource getResource() {
-        return new InputStreamResource(new ByteArrayInputStream(content), originalFilename);
-    }
-}
--- a/Show More
+++ b/Show More