Update PolicyExecutor.java

Update PortalInfraAuditService.java
Merge branch 'main' into switch_expression
2026-07-09 22:52:21 +02:00 · 2026-07-09 22:51:55 +02:00 · 2026-07-09 22:41:35 +02: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
2057 changed files with 102235 additions and 42431 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>
@@ -27,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.1
+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.1
+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
@@ -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,8 +53,8 @@ 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
@@ -62,4 +67,5 @@ jobs:
    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
@@ -122,7 +132,7 @@ jobs:
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          workspaces: frontend/editor/src-tauri
-          # Stable key shared across workflows so the nightly warmer. 
+          # 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' }}
@@ -150,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
@@ -177,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 }}
@@ -187,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..."
@@ -222,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 }}
@@ -253,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 }}
@@ -274,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
@@ -297,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 }}
@@ -310,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 }}
@@ -329,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
@@ -346,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 }}
@@ -380,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)
@@ -388,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 }}
@@ -403,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: |
@@ -413,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
@@ -451,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
@@ -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
@@ -26,9 +26,14 @@ tasks:
          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"}}'
@@ -36,12 +41,13 @@ tasks:
      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}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{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}}{{if .SECURITY_ENABLELOGIN}}SECURITY_ENABLELOGIN={{.SECURITY_ENABLELOGIN}} {{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
@@ -128,37 +128,6 @@ tasks:
      - task: dev:_run
        vars: { MODE: prototypes, PORT: '{{.PORT}}', BACKEND_URL: '{{.BACKEND_URL}}', OPEN: '{{.OPEN}}' }

-  dev:portal:
-    desc: "Start developer portal dev server"
-    ignore_error: true
-    deps: [install]
-    vars:
-      PORT: '{{.PORT | default "5173"}}'
-      BACKEND_URL: '{{.BACKEND_URL | default "http://localhost:8080"}}'
-      EDITOR_URL: '{{.EDITOR_URL | default ""}}'
-      OPEN: '{{.OPEN | default ""}}'
-      SUBPATH: '{{.SUBPATH | default ""}}'
-      MOCKS: '{{.MOCKS | default ""}}'
-    env:
-      BACKEND_URL: '{{.BACKEND_URL}}'
-    cmds:
-      - '{{if .SUBPATH}}RUN_SUBPATH={{.SUBPATH}} {{end}}{{if .MOCKS}}VITE_PORTAL_MOCKS={{.MOCKS}} {{end}}{{if .EDITOR_URL}}VITE_EDITOR_URL={{.EDITOR_URL}} {{end}}npx vite portal --port {{.PORT}}{{if .OPEN}} --open{{end}}'
-
-  dev:portal:proxy:serve:
-    internal: true
-    vars:
-      PORT: '{{.PORT | default "3000"}}'
-      BACKEND_URL: '{{.BACKEND_URL | default "http://localhost:8080"}}'
-      EDITOR_DEV_URL: '{{.EDITOR_DEV_URL | default ""}}'
-      PORTAL_DEV_URL: '{{.PORTAL_DEV_URL | default ""}}'
-    env:
-      PORT: '{{.PORT}}'
-      BACKEND_URL: '{{.BACKEND_URL}}'
-      EDITOR_DEV_URL: '{{.EDITOR_DEV_URL}}'
-      PORTAL_DEV_URL: '{{.PORTAL_DEV_URL}}'
-    cmds:
-      - npx tsx scripts/dev-origin-proxy.ts
-
  # ============================================================
  # Build
  # ============================================================
@@ -205,29 +174,6 @@ tasks:
    cmds:
      - npx vite build editor --mode prototypes

-  build:portal:
-    desc: "Build developer portal"
-    deps: [install]
-    vars:
-      SUBPATH: '{{.SUBPATH | default ""}}'
-    cmds:
-      - '{{if .SUBPATH}}RUN_SUBPATH={{.SUBPATH}} {{end}}npx vite build portal'
-
-  preview:portal:proxy:
-    desc: "Build + serve editor + portal behind one origin (prod-like auth testing)"
-    deps: [prepare]
-    vars:
-      PORT: '{{.PORT | default "3000"}}'
-      BACKEND_URL: '{{.BACKEND_URL | default "http://localhost:8080"}}'
-    env:
-      PORT: '{{.PORT}}'
-      BACKEND_URL: '{{.BACKEND_URL}}'
-    cmds:
-      - task: build:proprietary
-        vars: { PREVIEW: '1' }
-      - task: build:portal
-        vars: { SUBPATH: portal }
-      - npx tsx scripts/dev-origin-proxy.ts

  storybook:
    desc: "Start Storybook dev server"
@@ -263,8 +209,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"
@@ -295,17 +241,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"
@@ -313,7 +268,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"
@@ -321,38 +277,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 scripts/tsconfig.json
-      - 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"
@@ -365,7 +319,6 @@ tasks:
      - task: typecheck:scripts
      - task: typecheck:prototypes
      - task: typecheck:portal
-      - task: typecheck:shared

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

@@ -404,6 +356,11 @@ tasks:

  test:
    desc: "Run tests"
+    cmds:
+      - task: test:editor
+
+  test:editor:
+    desc: "Run editor tests"
    deps: [prepare]
    cmds:
      - npx vitest run --root editor
@@ -439,6 +396,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]
@@ -452,7 +426,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]
@@ -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
@@ -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.

@@ -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

@@ -79,78 +79,23 @@ tasks:
          OPEN: "true"

  dev:portal:
-    desc: "Start backend + developer portal concurrently on free ports"
+    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}}'
-      PORTAL_PORT: '{{index (splitList "\n" .PORTS) 1}}'
-    deps:
-      - task: backend:dev
-        vars:
-          PORT: '{{.BACKEND_PORT}}'
-          SECURITY_ENABLELOGIN: "true"
-      - task: frontend:dev:portal
-        vars:
-          PORT: '{{.PORTAL_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-          OPEN: "true"
-
-  dev:portal:all:
-    desc: "Start backend + developer portal + editor concurrently on free ports"
-    vars:
-      PORTS:
-        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173 5174{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173 5174{{end}}'
-      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
-      PORTAL_PORT: '{{index (splitList "\n" .PORTS) 1}}'
-      EDITOR_PORT: '{{index (splitList "\n" .PORTS) 2}}'
-    deps:
-      - task: backend:dev
-        vars:
-          PORT: '{{.BACKEND_PORT}}'
-          SECURITY_ENABLELOGIN: "true"
-      - task: frontend:dev:portal
-        vars:
-          PORT: '{{.PORTAL_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-          # Point the portal's "Editor" app switcher at the editor we spawn here.
-          EDITOR_URL: 'http://localhost:{{.EDITOR_PORT}}/'
-          OPEN: "true"
-      - task: frontend:dev
-        vars:
-          PORT: '{{.EDITOR_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-
-  dev:portal:proxy:
-    desc: "Editor + portal on ONE origin + backend via live dev servers (shared-token login)"
-    vars:
-      PORTS:
-        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 3000 5173 5174{{else}}{{.FIND_FREE_PORT_SH}} 8080 3000 5173 5174{{end}}'
-      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
-      PROXY_PORT: '{{index (splitList "\n" .PORTS) 1}}'
-      EDITOR_PORT: '{{index (splitList "\n" .PORTS) 2}}'
-      PORTAL_PORT: '{{index (splitList "\n" .PORTS) 3}}'
+      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}}'
-      - task: frontend:dev:portal
-        vars:
-          PORT: '{{.PORTAL_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-          SUBPATH: portal
-          MOCKS: 'false'
-      - task: frontend:dev:portal:proxy:serve
-        vars:
-          PORT: '{{.PROXY_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-          EDITOR_DEV_URL: 'http://localhost:{{.EDITOR_PORT}}'
-          PORTAL_DEV_URL: 'http://localhost:{{.PORTAL_PORT}}'
+          OPEN: "true"

  dev:saas:
    desc: "Start SaaS backend + frontend concurrently on free ports"
@@ -198,23 +143,6 @@ tasks:
      - task: backend:build
      - task: frontend:build

-  preview:portal:proxy:
-    desc: "Build + serve editor + portal on ONE origin + backend (prod-like auth test)"
-    vars:
-      PORTS:
-        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 3000{{else}}{{.FIND_FREE_PORT_SH}} 8080 3000{{end}}'
-      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
-      PROXY_PORT: '{{index (splitList "\n" .PORTS) 1}}'
-    deps:
-      - task: backend:dev
-        vars:
-          PORT: '{{.BACKEND_PORT}}'
-          SECURITY_ENABLELOGIN: "true"
-      - task: frontend:preview:portal:proxy
-        vars:
-          PORT: '{{.PROXY_PORT}}'
-          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
-
  # ============================================================
  # Test
  # ============================================================
@@ -257,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
@@ -80,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"
@@ -108,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"
@@ -172,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"
@@ -29,13 +29,13 @@ spotless {
    }
 }
 dependencies {
-    api 'com.google.guava:guava:33.6.0-jre'
+    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"
@@ -60,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()
@@ -75,12 +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}"
    }

    // 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}"
 }
@@ -132,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;
        }
@@ -73,7 +73,7 @@ public class RuntimePathConfig {
                        defaultWatchedFolders,
                        watchedFoldersDirs,
                        pipeline != null ? pipeline.getWatchedFoldersDir() : null);
-        this.pipelineWatchedFoldersPath = this.pipelineWatchedFoldersPaths.get(0);
+        this.pipelineWatchedFoldersPath = this.pipelineWatchedFoldersPaths.getFirst();
        this.pipelineFinishedFoldersPath =
                resolvePath(
                        defaultFinishedFolders,
@@ -206,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
@@ -514,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
@@ -582,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";

@@ -659,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<>();
@@ -730,7 +743,6 @@ public class ApplicationProperties {
        @Data
        public static class Jwt {
            private boolean enableKeystore = true;
-            private boolean enableKeyRotation = false;
            private boolean enableKeyCleanup = true;

            /**
@@ -834,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;
            }
@@ -869,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;
@@ -878,10 +890,10 @@ 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;
-        private int maxDPI;
+        private int maxDPI = 500;
        private boolean enableUrlToPDF;
        private Html html = new Html();
        private CustomPaths customPaths = new CustomPaths();
@@ -895,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 {
@@ -906,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;
        }
@@ -990,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;
        }
@@ -1164,7 +1187,7 @@ public class ApplicationProperties {

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

    @Data
@@ -1216,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;
@@ -1243,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;
@@ -60,54 +60,40 @@ public class Provider {
    }

    private UsernameAttribute validateUsernameAttribute(UsernameAttribute usernameAttribute) {
-        switch (name) {
-            case "google" -> {
-                return validateGoogleUsernameAttribute(usernameAttribute);
-            }
-            case "github" -> {
-                return validateGitHubUsernameAttribute(usernameAttribute);
-            }
-            case "keycloak" -> {
-                return validateKeycloakUsernameAttribute(usernameAttribute);
-            }
-            default -> {
-                return usernameAttribute;
-            }
-        }
+        return switch (name) {
+            case "google" -> validateGoogleUsernameAttribute(usernameAttribute);
+            case "github" -> validateGitHubUsernameAttribute(usernameAttribute);
+            case "keycloak" -> validateKeycloakUsernameAttribute(usernameAttribute);
+            default -> usernameAttribute;
+        };
    }

    private UsernameAttribute validateKeycloakUsernameAttribute(
            UsernameAttribute usernameAttribute) {
-        switch (usernameAttribute) {
-            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME, PREFERRED_USERNAME -> {
-                return usernameAttribute;
-            }
+        return switch (usernameAttribute) {
+            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME, PREFERRED_USERNAME -> usernameAttribute;
            default ->
                    throw new UnsupportedClaimException(
                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
-        }
+        };
    }

    private UsernameAttribute validateGoogleUsernameAttribute(UsernameAttribute usernameAttribute) {
-        switch (usernameAttribute) {
-            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME -> {
-                return usernameAttribute;
-            }
+        return switch (usernameAttribute) {
+            case EMAIL, NAME, GIVEN_NAME, FAMILY_NAME -> usernameAttribute;
            default ->
                    throw new UnsupportedClaimException(
                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
-        }
+        };
    }

    private UsernameAttribute validateGitHubUsernameAttribute(UsernameAttribute usernameAttribute) {
-        switch (usernameAttribute) {
-            case LOGIN, EMAIL, NAME -> {
-                return usernameAttribute;
-            }
+        return switch (usernameAttribute) {
+            case LOGIN, EMAIL, NAME -> usernameAttribute;
            default ->
                    throw new UnsupportedClaimException(
                            String.format(EXCEPTION_MESSAGE, usernameAttribute, clientName));
-        }
+        };
    }

    @Override
@@ -361,8 +361,8 @@ public class PdfMarkdownConverter {
        if (xs.isEmpty()) {
            return List.of(lines);
        }
-        float minX = xs.get(0);
-        float maxX = xs.get(xs.size() - 1);
+        float minX = xs.getFirst();
+        float maxX = xs.getLast();
        float splitAt = (minX + maxX) / 2f;
        float biggestGap = 0;
        for (int i = 1; i < xs.size(); i++) {
@@ -492,7 +492,7 @@ public class PdfMarkdownConverter {

        List<List<Line>> anchorGroups = new ArrayList<>();
        List<Line> current = new ArrayList<>();
-        current.add(cands.get(0));
+        current.add(cands.getFirst());
        for (int i = 1; i < cands.size(); i++) {
            float gap = cands.get(i - 1).y - cands.get(i).y;
            if (gap > splitThreshold) {
@@ -513,8 +513,8 @@ public class PdfMarkdownConverter {
            if (anchors.size() < 2) {
                continue;
            }
-            float top = anchors.get(0).y;
-            float bottom = anchors.get(anchors.size() - 1).y;
+            float top = anchors.getFirst().y;
+            float bottom = anchors.getLast().y;

            // Each anchor seeds a row; absorb wrapped continuation lines (non-anchors within the
            // run's vertical span, with a little slack below the last row) into the anchor above.
@@ -674,8 +674,8 @@ public class PdfMarkdownConverter {
        float minGutter = Math.max(10f, charWidth * 2.5f);
        List<float[]> merged = new ArrayList<>();
        for (float[] band : columns) {
-            if (!merged.isEmpty() && band[0] - merged.get(merged.size() - 1)[1] < minGutter) {
-                merged.get(merged.size() - 1)[1] = band[1];
+            if (!merged.isEmpty() && band[0] - merged.getLast()[1] < minGutter) {
+                merged.getLast()[1] = band[1];
            } else {
                merged.add(new float[] {band[0], band[1]});
            }
@@ -734,7 +734,7 @@ public class PdfMarkdownConverter {
            }
        }
        StringBuilder sb = new StringBuilder();
-        sb.append(buildGfmRow(rows.get(0), widths, cols)).append('\n');
+        sb.append(buildGfmRow(rows.getFirst(), widths, cols)).append('\n');
        sb.append('|');
        for (int c = 0; c < cols; c++) {
            sb.append('-').append("-".repeat(widths[c])).append('-').append('|');
@@ -910,8 +910,8 @@ public class PdfMarkdownConverter {
        }
        // Only merge a sentence continuation between two text paragraphs, never into/out of a
        // table.
-        if (!(output.get(output.size() - 1) instanceof String last)
-                || !(pageItems.get(0) instanceof String first)) {
+        if (!(output.getLast() instanceof String last)
+                || !(pageItems.getFirst() instanceof String first)) {
            return;
        }
        if (!first.isEmpty()
@@ -932,13 +932,13 @@ public class PdfMarkdownConverter {
        for (Object e : elements) {
            if (e instanceof TableBlock tb
                    && !out.isEmpty()
-                    && out.get(out.size() - 1) instanceof TableBlock prev
+                    && out.getLast() instanceof TableBlock prev
                    && columnsMatch(flatten(prev.rows()), flatten(tb.rows()))) {
                List<List<Line>> merged = new ArrayList<>(prev.rows());
                List<List<Line>> tail = tb.rows();
                if (!tail.isEmpty()
                        && !prev.rows().isEmpty()
-                        && rowText(tail.get(0)).equals(rowText(prev.rows().get(0)))) {
+                        && rowText(tail.getFirst()).equals(rowText(prev.rows().getFirst()))) {
                    tail = tail.subList(1, tail.size());
                }
                merged.addAll(tail);
@@ -971,7 +971,7 @@ public class PdfMarkdownConverter {
                continue;
            }
            if (e instanceof TableBlock tb && !tb.rows().isEmpty()) {
-                return rowText(tb.rows().get(0));
+                return rowText(tb.rows().getFirst());
            }
            return null;
        }
@@ -119,7 +119,7 @@ public class InternalApiClient {
        boolean hasFilePart =
                body.values().stream()
                        .flatMap(java.util.List::stream)
-                        .anyMatch(v -> v instanceof Resource);
+                        .anyMatch(Resource.class::isInstance);
        if (isAiTool && !hasFilePart) {
            headers.setContentType(MediaType.MULTIPART_FORM_DATA);
        }
@@ -0,0 +1,204 @@
+package stirling.software.common.service;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.AtomicMoveNotSupportedException;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.configuration.InstallationPathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+// Resolves login agreement text from customFiles/disclaimer/<locale>.md (read live);
+// enable/visibility come from the legal.loginAgreement settings.
+@Service
+@Slf4j
+public class LoginAgreementService {
+
+    // Locale codes only: rejects path separators and dots so the value can never escape the
+    // disclaimer directory. Matches e.g. en, en-GB, fr-FR, zh-Hant, pt-BR.
+    private static final Pattern LOCALE_PATTERN =
+            Pattern.compile("^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*$");
+
+    // BCP-47 tags are well under this; the cap also prevents the regex's repetition group
+    // from recursing far enough to overflow the stack on a hostile over-length input.
+    private static final int MAX_LOCALE_LENGTH = 35;
+
+    // Disclaimers are short markdown; cap the read so an oversized file can't be loaded
+    // wholesale into heap on every public request.
+    private static final long MAX_FILE_BYTES = 256 * 1024;
+
+    private final ApplicationProperties applicationProperties;
+
+    public LoginAgreementService(ApplicationProperties applicationProperties) {
+        this.applicationProperties = applicationProperties;
+    }
+
+    public boolean isEnabled() {
+        return config().isEnabled();
+    }
+
+    public boolean isShowInAnonymousMode() {
+        return config().isShowInAnonymousMode();
+    }
+
+    /**
+     * Resolve the markdown to show for the requested language, falling back through the base
+     * language, the configured default locale (and its base), then the configured fallbackText.
+     * Returns an empty string when nothing is configured.
+     */
+    public String resolveContent(String requestedLang) {
+        List<String> candidates = new ArrayList<>();
+        addLocaleCandidates(candidates, requestedLang);
+        addLocaleCandidates(candidates, applicationProperties.getSystem().getDefaultLocale());
+
+        for (String candidate : candidates) {
+            String content = readFileIfExists(candidate);
+            if (content != null && !content.isBlank()) {
+                return content;
+            }
+        }
+
+        String fallback = config().getFallbackText();
+        return fallback == null ? "" : fallback;
+    }
+
+    /**
+     * Admin read of a single locale's raw file. Returns null for an invalid locale, "" if absent.
+     */
+    public String readRawForLocale(String locale) {
+        if (!isValidLocale(locale)) {
+            return null;
+        }
+        String content = readFileIfExists(locale);
+        return content == null ? "" : content;
+    }
+
+    /** Admin write. Blank content deletes the file so it falls back cleanly. */
+    public void writeForLocale(String locale, String content) throws IOException {
+        Path file = resolveLocaleFile(locale);
+        if (file == null) {
+            throw new IllegalArgumentException("Invalid locale: " + locale);
+        }
+        if (content == null || content.isBlank()) {
+            Files.deleteIfExists(file);
+            return;
+        }
+        Files.createDirectories(file.getParent());
+        // Write to a sibling temp file then atomically swap, so a concurrent reader (the public
+        // /login-disclaimer fetch is lockless) never observes a truncated/partial file.
+        Path tmp = Files.createTempFile(file.getParent(), "disclaimer", ".md.tmp");
+        try {
+            Files.writeString(tmp, content, StandardCharsets.UTF_8);
+            try {
+                Files.move(
+                        tmp,
+                        file,
+                        StandardCopyOption.ATOMIC_MOVE,
+                        StandardCopyOption.REPLACE_EXISTING);
+            } catch (AtomicMoveNotSupportedException e) {
+                Files.move(tmp, file, StandardCopyOption.REPLACE_EXISTING);
+            }
+        } finally {
+            Files.deleteIfExists(tmp);
+        }
+    }
+
+    /** Locales that currently have a markdown file, for the admin editor. */
+    public Set<String> listLocalesWithContent() {
+        Set<String> result = new TreeSet<>();
+        Path dir = disclaimerDir();
+        if (!Files.isDirectory(dir)) {
+            return result;
+        }
+        try (Stream<Path> files = Files.list(dir)) {
+            files.filter(Files::isRegularFile)
+                    .map(path -> path.getFileName().toString())
+                    .filter(name -> name.endsWith(".md"))
+                    .map(name -> name.substring(0, name.length() - ".md".length()))
+                    .filter(this::isValidLocale)
+                    .forEach(result::add);
+        } catch (IOException e) {
+            log.warn("Failed listing login agreement files", e);
+        }
+        return result;
+    }
+
+    private ApplicationProperties.Legal.LoginAgreement config() {
+        return applicationProperties.getLegal().getLoginAgreement();
+    }
+
+    private Path disclaimerDir() {
+        return Path.of(InstallationPathConfig.getCustomFilesPath(), "disclaimer").normalize();
+    }
+
+    private void addLocaleCandidates(List<String> out, String locale) {
+        if (!isValidLocale(locale)) {
+            return;
+        }
+        if (!out.contains(locale)) {
+            out.add(locale);
+        }
+        String base = locale.split("[_-]", 2)[0];
+        if (!base.equals(locale) && !out.contains(base)) {
+            out.add(base);
+        }
+    }
+
+    private String readFileIfExists(String locale) {
+        Path file = resolveLocaleFile(locale);
+        if (file == null) {
+            return null;
+        }
+        try {
+            // NOFOLLOW_LINKS: a symlinked entry is treated as non-regular and skipped, so a
+            // planted symlink can't expose files outside the disclaimer dir via the public read.
+            if (Files.isRegularFile(file, LinkOption.NOFOLLOW_LINKS)) {
+                if (Files.size(file) > MAX_FILE_BYTES) {
+                    log.warn(
+                            "Login agreement file for locale {} exceeds {} bytes; ignoring",
+                            locale,
+                            MAX_FILE_BYTES);
+                    return null;
+                }
+                return Files.readString(file, StandardCharsets.UTF_8);
+            }
+        } catch (IOException e) {
+            log.warn("Failed reading login agreement file for locale {}", locale, e);
+        }
+        return null;
+    }
+
+    private Path resolveLocaleFile(String locale) {
+        if (!isValidLocale(locale)) {
+            return null;
+        }
+        Path dir = disclaimerDir();
+        Path file = dir.resolve(locale + ".md").normalize();
+        // Defence in depth: the regex already blocks separators, but confirm containment.
+        if (!file.startsWith(dir)) {
+            return null;
+        }
+        return file;
+    }
+
+    private boolean isValidLocale(String locale) {
+        // Length check BEFORE the regex: LOCALE_PATTERN's repetition group recurses one stack
+        // frame per repeat in java.util.regex, so an unbounded input could overflow the stack.
+        return locale != null
+                && locale.length() <= MAX_LOCALE_LENGTH
+                && LOCALE_PATTERN.matcher(locale).matches();
+    }
+}
@@ -7,6 +7,7 @@ import java.time.format.DateTimeFormatter;
 import java.util.Calendar;

 import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentInformation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;
@@ -17,6 +18,9 @@ import stirling.software.common.model.PdfMetadata;
@Service
 public class PdfMetadataService {

+    /** ({@code {labels}}). Written by the classify-and-label tool. */
+    public static final String CLASSIFICATION_KEY = "StirlingPDFClassification";
+
    private final ApplicationProperties applicationProperties;
    private final String stirlingPDFLabel;
    private final UserServiceInterface userService;
@@ -177,4 +181,14 @@ public class PdfMetadataService {
        }
        pdf.getDocumentInformation().setAuthor(author);
    }
+
+    /**
+     * Write the document classifier's JSON result into the custom Info-dictionary field {@link
+     * #CLASSIFICATION_KEY}, leaving all other metadata untouched.
+     */
+    public void setClassificationMetadata(PDDocument pdf, String classificationJson) {
+        PDDocumentInformation info = pdf.getDocumentInformation();
+        info.setCustomMetadataValue(CLASSIFICATION_KEY, classificationJson);
+        pdf.setDocumentInformation(info);
+    }
 }
@@ -140,20 +140,25 @@ public class ChecksumUtils {

        for (String algorithm : algorithms) {
            String key = algorithm; // keep original key for output
-            switch (algorithm.toUpperCase(Locale.ROOT)) {
-                case "CRC32":
-                    checksums.put(key, new CRC32());
-                    break;
-                case "ADLER32":
-                    checksums.put(key, new Adler32());
-                    break;
-                default:
-                    try {
-                        // For MessageDigest, pass the original name (case-insensitive per JCA)
-                        digests.put(key, MessageDigest.getInstance(algorithm));
-                    } catch (NoSuchAlgorithmException e) {
-                        throw new IllegalStateException("Unsupported algorithm: " + algorithm, e);
-                    }
+            Object digestOrChecksum =
+                    switch (algorithm.toUpperCase(Locale.ROOT)) {
+                        case "CRC32" -> new CRC32();
+                        case "ADLER32" -> new Adler32();
+                        default -> {
+                            try {
+                                // For MessageDigest, pass the original name (case-insensitive
+                                // per JCA)
+                                yield MessageDigest.getInstance(algorithm);
+                            } catch (NoSuchAlgorithmException e) {
+                                throw new IllegalStateException(
+                                        "Unsupported algorithm: " + algorithm, e);
+                            }
+                        }
+                    };
+            if (digestOrChecksum instanceof Checksum checksum) {
+                checksums.put(key, checksum);
+            } else {
+                digests.put(key, (MessageDigest) digestOrChecksum);
            }
        }

@@ -751,7 +751,7 @@ public class ExceptionUtils {
        String targetDescription;
        if (errorInfo.affectedPages() != null && !errorInfo.affectedPages().isEmpty()) {
            if (errorInfo.affectedPages().size() == 1) {
-                targetDescription = "page " + errorInfo.affectedPages().get(0);
+                targetDescription = "page " + errorInfo.affectedPages().getFirst();
            } else {
                targetDescription =
                        "pages "
@@ -848,7 +848,7 @@ public class ExceptionUtils {
            }

            // Use the first page number, or null if none found
-            Integer pageNumber = affectedPages.isEmpty() ? null : affectedPages.get(0);
+            Integer pageNumber = affectedPages.isEmpty() ? null : affectedPages.getFirst();

            return new GhostscriptErrorInfo(
                    ErrorCode.GHOSTSCRIPT_PAGE_DRAWING,
@@ -114,7 +114,7 @@ public enum FormFieldTypeSupport {
                    return;
                }

-                PDAnnotationWidget widget = checkBox.getWidgets().get(0);
+                PDAnnotationWidget widget = checkBox.getWidgets().getFirst();

                PDAppearanceCharacteristicsDictionary appearanceChars =
                        widget.getAppearanceCharacteristics();
@@ -88,28 +88,16 @@ public class FormUtils {
     *     text)
     */
    public String detectFieldType(PDField field) {
-        if (field instanceof PDSignatureField) {
-            return FIELD_TYPE_SIGNATURE;
-        }
-        if (field instanceof PDPushButton) {
-            return FIELD_TYPE_BUTTON;
-        }
-        if (field instanceof PDTextField) {
-            return FIELD_TYPE_TEXT;
-        }
-        if (field instanceof PDCheckBox) {
-            return FIELD_TYPE_CHECKBOX;
-        }
-        if (field instanceof PDComboBox) {
-            return FIELD_TYPE_COMBOBOX;
-        }
-        if (field instanceof PDListBox) {
-            return FIELD_TYPE_LISTBOX;
-        }
-        if (field instanceof PDRadioButton) {
-            return FIELD_TYPE_RADIO;
-        }
-        return FIELD_TYPE_TEXT;
+        return switch (field) {
+            case PDSignatureField ignored -> FIELD_TYPE_SIGNATURE;
+            case PDPushButton ignored -> FIELD_TYPE_BUTTON;
+            case PDTextField ignored -> FIELD_TYPE_TEXT;
+            case PDCheckBox ignored -> FIELD_TYPE_CHECKBOX;
+            case PDComboBox ignored -> FIELD_TYPE_COMBOBOX;
+            case PDListBox ignored -> FIELD_TYPE_LISTBOX;
+            case PDRadioButton ignored -> FIELD_TYPE_RADIO;
+            case null, default -> FIELD_TYPE_TEXT;
+        };
    }

    public List<FormFieldInfo> extractFormFields(PDDocument document) {
@@ -583,22 +571,17 @@ public class FormUtils {
                continue;
            }
            String type = info.type();
-            Object value;
-            switch (type) {
-                case FIELD_TYPE_CHECKBOX:
-                    value = isChecked(info.value()) ? Boolean.TRUE : Boolean.FALSE;
-                    break;
-                case FIELD_TYPE_LISTBOX:
-                    if (info.multiSelect()) {
-                        value = new ArrayList<>();
-                    } else {
-                        value = safeDefault(info.value());
-                    }
-                    break;
-                case FIELD_TYPE_BUTTON, FIELD_TYPE_SIGNATURE:
-                    continue; // skip non-fillable
-                default:
-                    value = safeDefault(info.value());
+            Object value =
+                    switch (type) {
+                        case FIELD_TYPE_CHECKBOX ->
+                                isChecked(info.value()) ? Boolean.TRUE : Boolean.FALSE;
+                        case FIELD_TYPE_LISTBOX ->
+                                info.multiSelect() ? new ArrayList<>() : safeDefault(info.value());
+                        case FIELD_TYPE_BUTTON, FIELD_TYPE_SIGNATURE -> null;
+                        default -> safeDefault(info.value());
+                    };
+            if (value == null) {
+                continue; // skip non-fillable
            }
            record.put(info.name(), value);
        }
@@ -949,44 +932,44 @@ public class FormUtils {
        if (selection == null || selection.trim().isEmpty()) return null;
        List<String> filtered =
                filterChoiceSelections(List.of(selection), allowedOptions, fieldName);
-        return filtered.isEmpty() ? null : filtered.get(0);
+        return filtered.isEmpty() ? null : filtered.getFirst();
    }

    private void applyValueToField(PDField field, String value, boolean strict) throws IOException {
        try {
-            if (field instanceof PDTextField textField) {
-                setTextValue(textField, value);
-            } else if (field instanceof PDCheckBox checkBox) {
-                LinkedHashSet<String> candidateStates = collectCheckBoxStates(checkBox);
-                boolean shouldCheck = shouldCheckBoxBeChecked(value, candidateStates);
-                try {
-                    if (shouldCheck) {
-                        checkBox.check();
-                    } else {
-                        checkBox.unCheck();
-                    }
-                } catch (IOException checkProblem) {
-                    log.warn(
-                            "Failed to set checkbox state for '{}': {}",
-                            field.getFullyQualifiedName(),
-                            checkProblem.getMessage(),
-                            checkProblem);
-                    if (strict) {
-                        throw checkProblem;
+            switch (field) {
+                case PDTextField textField -> setTextValue(textField, value);
+                case PDCheckBox checkBox -> {
+                    LinkedHashSet<String> candidateStates = collectCheckBoxStates(checkBox);
+                    boolean shouldCheck = shouldCheckBoxBeChecked(value, candidateStates);
+                    try {
+                        if (shouldCheck) {
+                            checkBox.check();
+                        } else {
+                            checkBox.unCheck();
+                        }
+                    } catch (IOException checkProblem) {
+                        log.warn(
+                                "Failed to set checkbox state for '{}': {}",
+                                field.getFullyQualifiedName(),
+                                checkProblem.getMessage(),
+                                checkProblem);
+                        if (strict) {
+                            throw checkProblem;
+                        }
                    }
                }
-            } else if (field instanceof PDRadioButton radioButton) {
-                if (value != null && !value.isBlank()) {
-                    radioButton.setValue(value);
+                case PDRadioButton radioButton -> {
+                    if (value != null && !value.isBlank()) {
+                        radioButton.setValue(value);
+                    }
                }
-            } else if (field instanceof PDChoice choiceField) {
-                applyChoiceValue(choiceField, value);
-            } else if (field instanceof PDPushButton) {
-                log.debug("Ignore Push button");
-            } else if (field instanceof PDSignatureField) {
-                log.debug("Skipping signature field '{}'", field.getFullyQualifiedName());
-            } else {
-                field.setValue(value != null ? value : "");
+                case PDChoice choiceField -> applyChoiceValue(choiceField, value);
+                case PDPushButton ignored -> log.debug("Ignore Push button");
+                case PDSignatureField ignored ->
+                        log.debug("Skipping signature field '{}'", field.getFullyQualifiedName());
+                case null -> log.warn("Attempted to set value on null field");
+                default -> field.setValue(value != null ? value : "");
            }
        } catch (Exception e) {
            log.warn(
@@ -1306,37 +1289,42 @@ public class FormUtils {

    List<String> resolveOptions(PDTerminalField field) {
        try {
-            if (field instanceof PDChoice choice) {
-                LinkedHashSet<String> allowed = new LinkedHashSet<>();
-                List<String> exportValues = choice.getOptionsExportValues();
-                List<String> displayValues = choice.getOptionsDisplayValues();
+            return switch (field) {
+                case PDChoice choice -> {
+                    LinkedHashSet<String> allowed = new LinkedHashSet<>();
+                    List<String> exportValues = choice.getOptionsExportValues();
+                    List<String> displayValues = choice.getOptionsDisplayValues();

-                if (exportValues != null) {
-                    exportValues.stream()
-                            .filter(Objects::nonNull)
-                            .map(String::trim)
-                            .filter(s -> !s.isEmpty())
-                            .forEach(allowed::add);
+                    if (exportValues != null) {
+                        exportValues.stream()
+                                .filter(Objects::nonNull)
+                                .map(String::trim)
+                                .filter(s -> !s.isEmpty())
+                                .forEach(allowed::add);
+                    }
+                    if (displayValues != null) {
+                        displayValues.stream()
+                                .filter(Objects::nonNull)
+                                .map(String::trim)
+                                .filter(s -> !s.isEmpty())
+                                .forEach(allowed::add);
+                    }
+                    yield new ArrayList<>(allowed);
                }
-                if (displayValues != null) {
-                    displayValues.stream()
-                            .filter(Objects::nonNull)
-                            .map(String::trim)
-                            .filter(s -> !s.isEmpty())
-                            .forEach(allowed::add);
+                case PDRadioButton radio -> {
+                    List<String> exports = radio.getExportValues();
+                    yield exports != null && !exports.isEmpty()
+                            ? new ArrayList<>(exports)
+                            : Collections.emptyList();
                }
-                return new ArrayList<>(allowed);
-            } else if (field instanceof PDRadioButton radio) {
-                List<String> exports = radio.getExportValues();
-                if (exports != null && !exports.isEmpty()) {
-                    return new ArrayList<>(exports);
+                case PDCheckBox checkBox -> {
+                    List<String> exports = checkBox.getExportValues();
+                    yield exports != null && !exports.isEmpty()
+                            ? new ArrayList<>(exports)
+                            : Collections.emptyList();
                }
-            } else if (field instanceof PDCheckBox checkBox) {
-                List<String> exports = checkBox.getExportValues();
-                if (exports != null && !exports.isEmpty()) {
-                    return new ArrayList<>(exports);
-                }
-            }
+                case null, default -> Collections.emptyList();
+            };
        } catch (Exception e) {
            log.debug(
                    "Failed to resolve options for field '{}': {}",
@@ -1465,7 +1453,7 @@ public class FormUtils {

        // Only check options for choice-type fields (combobox, listbox, radio)
        if (CHOICE_FIELD_TYPES.contains(type) && options != null && !options.isEmpty()) {
-            String optionCandidate = cleanLabel(options.get(0));
+            String optionCandidate = cleanLabel(options.getFirst());
            if (optionCandidate != null && !looksGeneric(optionCandidate)) {
                return optionCandidate;
            }
@@ -1557,7 +1545,7 @@ public class FormUtils {
                continue;
            }

-            PDAnnotationWidget widget = widgets.get(0);
+            PDAnnotationWidget widget = widgets.getFirst();
            PDRectangle originalRectangle = cloneRectangle(widget.getRectangle());
            PDPage page = resolveWidgetPage(document, widget, null);
            if (page == null || originalRectangle == null) {
@@ -2446,19 +2434,19 @@ public class FormUtils {

        private static int firstWidgetPageIndex(FormFieldWithCoordinates f) {
            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
-                    ? f.getWidgets().get(0).getPageIndex()
+                    ? f.getWidgets().getFirst().getPageIndex()
                    : -1;
        }

        private static float firstWidgetY(FormFieldWithCoordinates f) {
            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
-                    ? f.getWidgets().get(0).getY()
+                    ? f.getWidgets().getFirst().getY()
                    : 0;
        }

        private static float firstWidgetX(FormFieldWithCoordinates f) {
            return (f.getWidgets() != null && !f.getWidgets().isEmpty())
-                    ? f.getWidgets().get(0).getX()
+                    ? f.getWidgets().getFirst().getX()
                    : 0;
        }

@@ -26,29 +26,27 @@ import lombok.extern.slf4j.Slf4j;
 public class ImageProcessingUtils {

    static BufferedImage convertColorType(BufferedImage sourceImage, String colorType) {
-        BufferedImage convertedImage;
-        switch (colorType) {
-            case "greyscale":
-                convertedImage =
+        return switch (colorType) {
+            case "greyscale" -> {
+                BufferedImage convertedImage =
                        new BufferedImage(
                                sourceImage.getWidth(),
                                sourceImage.getHeight(),
                                BufferedImage.TYPE_BYTE_GRAY);
                convertedImage.getGraphics().drawImage(sourceImage, 0, 0, null);
-                break;
-            case "blackwhite":
-                convertedImage =
+                yield convertedImage;
+            }
+            case "blackwhite" -> {
+                BufferedImage convertedImage =
                        new BufferedImage(
                                sourceImage.getWidth(),
                                sourceImage.getHeight(),
                                BufferedImage.TYPE_BYTE_BINARY);
                convertedImage.getGraphics().drawImage(sourceImage, 0, 0, null);
-                break;
-            default: // full color
-                convertedImage = sourceImage;
-                break;
-        }
-        return convertedImage;
+                yield convertedImage;
+            }
+            default -> sourceImage;
+        };
    }

    public static byte[] getImageData(BufferedImage image) {
@@ -330,7 +330,7 @@ public class PDFToFile {

                if (outputFiles.size() == 1) {
                    // Return single output file
-                    File outputFile = outputFiles.get(0);
+                    File outputFile = outputFiles.getFirst();
                    if ("txt:Text".equals(outputFormat)) {
                        outputFormat = "txt";
                    }
@@ -307,7 +307,7 @@ public class ProcessExecutor {
            boolean isQpdf =
                    commandToRun != null
                            && !commandToRun.isEmpty()
-                            && commandToRun.get(0).contains("qpdf");
+                            && commandToRun.getFirst().contains("qpdf");

            if (!outputLines.isEmpty()) {
                String outputMessage = String.join("\n", outputLines);
@@ -370,7 +370,7 @@ public class ProcessExecutor {
        }

        // Check if this is a UNO conversion by looking for unoconvert executable
-        String executable = command.get(0);
+        String executable = command.getFirst();
        if (executable != null) {
            // Extract basename from path for matching
            String basename = executable;
@@ -504,7 +504,7 @@ public class ProcessExecutor {
        }

        // Validate executable (first argument)
-        String executable = command.get(0);
+        String executable = command.getFirst();
        if (executable == null || executable.isBlank()) {
            throw new IllegalArgumentException("Command executable must not be empty");
        }
@@ -57,6 +57,16 @@ public class RequestUriUtils {
            return true;
        }

+        // Admin portal SPA shell (mounted at /processor — must match the frontend
+        // PORTAL_BASENAME). Served publicly like the editor root so a direct nav /
+        // refresh to /processor loads the app (the JWT lives in localStorage, not a
+        // cookie, so the server can't authenticate the navigation itself). The
+        // portal gates access via its own auth gate + RequirePortalAccess, and its
+        // data APIs stay protected, so serving the shell pre-auth is safe.
+        if (normalizedUri.equals("/processor") || normalizedUri.startsWith("/processor/")) {
+            return true;
+        }
+
        // Treat common static file extensions as static resources
        return normalizedUri.endsWith(".svg")
                || normalizedUri.endsWith(".png")
@@ -244,10 +244,7 @@ public class SvgSanitizer {
            return false;
        }

-        return normalized.startsWith("http://")
-                || normalized.startsWith("https://")
-                || normalized.startsWith("//")
-                || normalized.startsWith("file:");
+        return true;
    }

    private boolean isUrlAllowed(String url) {
@@ -114,7 +114,7 @@ public class YamlHelper {

        for (NodeTuple tuple : mappingNode.getValue()) {
            ScalarNode keyNode = (tuple.getKeyNode() instanceof ScalarNode sk) ? sk : null;
-            if (keyNode == null || !keyNode.getValue().equals(keys.get(0))) {
+            if (keyNode == null || !keyNode.getValue().equals(keys.getFirst())) {
                updatedTuples.add(tuple);
                continue;
            }
@@ -0,0 +1,201 @@
+package stirling.software.common.service;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mockStatic;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.MockedStatic;
+
+import stirling.software.common.configuration.InstallationPathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+/**
+ * Unit tests for {@link LoginAgreementService}. The service resolves per-language markdown from
+ * {@code <customFiles>/disclaimer/<locale>.md}; here {@link
+ * InstallationPathConfig#getCustomFilesPath()} is mocked to a {@link TempDir} so file IO is
+ * isolated.
+ */
+class LoginAgreementServiceTest {
+
+    @TempDir Path customFilesDir;
+
+    private ApplicationProperties properties;
+    private ApplicationProperties.Legal.LoginAgreement config;
+    private LoginAgreementService service;
+    private Path disclaimerDir;
+
+    @BeforeEach
+    void setUp() {
+        properties = new ApplicationProperties();
+        config = properties.getLegal().getLoginAgreement();
+        service = new LoginAgreementService(properties);
+        disclaimerDir = customFilesDir.resolve("disclaimer");
+    }
+
+    /**
+     * Run {@code action} with InstallationPathConfig.getCustomFilesPath() pointing at the temp dir.
+     */
+    private void withMockedPath(Runnable action) {
+        try (MockedStatic<InstallationPathConfig> mocked =
+                mockStatic(InstallationPathConfig.class)) {
+            mocked.when(InstallationPathConfig::getCustomFilesPath)
+                    .thenReturn(customFilesDir.toString());
+            action.run();
+        }
+    }
+
+    private void writeFile(String locale, String content) throws IOException {
+        Files.createDirectories(disclaimerDir);
+        Files.writeString(disclaimerDir.resolve(locale + ".md"), content, StandardCharsets.UTF_8);
+    }
+
+    @Test
+    void flagsReflectConfig() {
+        config.setEnabled(true);
+        config.setShowInAnonymousMode(false);
+        assertTrue(service.isEnabled());
+        assertFalse(service.isShowInAnonymousMode());
+    }
+
+    @Test
+    void resolveContentReturnsExactLocaleFile() throws IOException {
+        writeFile("fr-FR", "# Avis");
+        withMockedPath(() -> assertEquals("# Avis", service.resolveContent("fr-FR")));
+    }
+
+    @Test
+    void resolveContentFallsBackToBaseLanguage() throws IOException {
+        // Only a language-only file exists; a region-specific request should fall back to it.
+        writeFile("de", "# Hinweis");
+        withMockedPath(() -> assertEquals("# Hinweis", service.resolveContent("de-DE")));
+    }
+
+    @Test
+    void resolveContentFallsBackToDefaultLocale() throws IOException {
+        properties.getSystem().setDefaultLocale("en-GB");
+        writeFile("en-GB", "# Notice");
+        // No file for the requested locale -> falls through to the configured default locale.
+        withMockedPath(() -> assertEquals("# Notice", service.resolveContent("es-ES")));
+    }
+
+    @Test
+    void resolveContentFallsBackToFallbackTextWhenNoFile() {
+        config.setFallbackText("# Fallback");
+        withMockedPath(() -> assertEquals("# Fallback", service.resolveContent("ja-JP")));
+    }
+
+    @Test
+    void resolveContentReturnsEmptyWhenNothingConfigured() {
+        withMockedPath(() -> assertEquals("", service.resolveContent("ja-JP")));
+    }
+
+    @Test
+    void resolveContentDoesNotEscapeDisclaimerDirectory() throws IOException {
+        // Plant a file outside the disclaimer dir; a traversal-style locale must not read it.
+        Files.writeString(
+                customFilesDir.resolve("secret.md"), "TOP SECRET", StandardCharsets.UTF_8);
+        config.setFallbackText("safe");
+        withMockedPath(
+                () -> {
+                    assertEquals("safe", service.resolveContent("../secret"));
+                    assertEquals("safe", service.resolveContent("..%2Fsecret"));
+                    assertEquals("safe", service.resolveContent("/etc/passwd"));
+                });
+    }
+
+    @Test
+    void readRawRejectsInvalidLocale() {
+        withMockedPath(
+                () -> {
+                    assertNull(service.readRawForLocale("../secret"));
+                    assertNull(service.readRawForLocale("en/GB"));
+                    assertNull(service.readRawForLocale("C:\\x"));
+                    assertNull(service.readRawForLocale(null));
+                });
+    }
+
+    @Test
+    void readRawReturnsEmptyForValidButAbsentLocale() {
+        withMockedPath(() -> assertEquals("", service.readRawForLocale("pt-BR")));
+    }
+
+    @Test
+    void overlongLocaleIsRejectedWithoutStackOverflow() {
+        // Guards against the regex-recursion stack overflow on unbounded input.
+        String hostile = "en" + "-ab".repeat(4000);
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.readRawForLocale(hostile));
+                    assertNull(service.readRawForLocale(hostile));
+                    assertDoesNotThrow(() -> service.resolveContent(hostile));
+                });
+    }
+
+    @Test
+    void writeThenReadRoundTrips() throws IOException {
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.writeForLocale("fr-FR", "# Bonjour"));
+                    assertEquals("# Bonjour", service.readRawForLocale("fr-FR"));
+                });
+        assertTrue(Files.isRegularFile(disclaimerDir.resolve("fr-FR.md")));
+    }
+
+    @Test
+    void writeBlankDeletesFile() throws IOException {
+        writeFile("fr-FR", "# Bonjour");
+        withMockedPath(
+                () -> {
+                    assertDoesNotThrow(() -> service.writeForLocale("fr-FR", "   "));
+                    assertEquals("", service.readRawForLocale("fr-FR"));
+                });
+        assertFalse(Files.exists(disclaimerDir.resolve("fr-FR.md")));
+    }
+
+    @Test
+    void writeRejectsInvalidLocale() {
+        withMockedPath(
+                () ->
+                        assertThrows(
+                                IllegalArgumentException.class,
+                                () -> service.writeForLocale("../escape", "x")));
+    }
+
+    @Test
+    void listLocalesWithContentReturnsOnlyValidMarkdownFiles() throws IOException {
+        writeFile("en-GB", "a");
+        writeFile("fr-FR", "b");
+        Files.writeString(disclaimerDir.resolve("notes.txt"), "x", StandardCharsets.UTF_8);
+        withMockedPath(
+                () -> {
+                    var locales = service.listLocalesWithContent();
+                    assertTrue(locales.contains("en-GB"));
+                    assertTrue(locales.contains("fr-FR"));
+                    assertEquals(2, locales.size());
+                });
+    }
+
+    @Test
+    void oversizedFileIsIgnored() throws IOException {
+        // Files beyond the read cap are skipped rather than loaded into heap.
+        byte[] big = new byte[300 * 1024];
+        java.util.Arrays.fill(big, (byte) 'x');
+        Files.createDirectories(disclaimerDir);
+        Files.write(disclaimerDir.resolve("en-GB.md"), big);
+        config.setFallbackText("small-fallback");
+        properties.getSystem().setDefaultLocale("en-GB");
+        withMockedPath(() -> assertEquals("small-fallback", service.resolveContent("en-GB")));
+    }
+}
@@ -721,7 +721,7 @@ class PDFToFileTest {
                    .thenAnswer(
                            invocation -> {
                                List<String> args = invocation.getArgument(0);
-                                String outputPath = args.get(args.size() - 1);
+                                String outputPath = args.getLast();
                                Files.write(Path.of(outputPath), "Fake DOCX content".getBytes());
                                return mockExecutorResult;
                            });
@@ -73,6 +73,14 @@ class RequestUriUtilsTest {
        assertTrue(RequestUriUtils.isStaticResource("/mobile-scanner"));
    }

+    @Test
+    void testIsStaticResource_portalShell() {
+        // The admin portal SPA shell (/processor) is served pre-auth so it's directly navigable.
+        assertTrue(RequestUriUtils.isStaticResource("/processor"));
+        assertTrue(RequestUriUtils.isStaticResource("/processor/users"));
+        assertTrue(RequestUriUtils.isStaticResource("/app", "/app/processor"));
+    }
+
    // --- isFrontendRoute tests ---

    @Test
@@ -97,4 +97,51 @@ class SvgSanitizerTest {
        byte[] invalid = "not xml at all".getBytes(StandardCharsets.UTF_8);
        assertThrows(IOException.class, () -> sanitizer.sanitize(invalid));
    }
+
+    @Test
+    void testSanitize_removesRootRelativeLocalPath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<image href=\"/tmp/image.png\" width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(output.contains("/tmp/image.png"), "Root-relative local path must be stripped");
+    }
+
+    @Test
+    void testSanitize_removesRelativeLocalPath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<image href=\"../../assets/image.png\" width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(output.contains("assets/image.png"), "Relative local path must be stripped");
+    }
+
+    @Test
+    void testSanitize_removesRootRelativeWindowsDrivePath() throws IOException {
+        when(ssrfProtectionService.isUrlAllowed(anyString())).thenReturn(false);
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\" "
+                        + "xmlns:xlink=\"http://www.w3.org/1999/xlink\">"
+                        + "<image xlink:href=\"/C:/Users/x/external-image.svg\""
+                        + " width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertFalse(
+                output.contains("external-image"), "Root-relative Windows path must be stripped");
+    }
+
+    @Test
+    void testSanitize_keepsInDocumentFragmentReference() throws IOException {
+        String svg =
+                "<svg xmlns=\"http://www.w3.org/2000/svg\">"
+                        + "<use href=\"#gradient\"/><rect width=\"10\" height=\"10\"/></svg>";
+        byte[] result = sanitizer.sanitize(svg.getBytes(StandardCharsets.UTF_8));
+        String output = new String(result, StandardCharsets.UTF_8);
+        assertTrue(
+                output.contains("#gradient"), "In-document fragment references must be preserved");
+    }
 }
@@ -67,7 +67,7 @@ dependencies {
        exclude group: 'com.fasterxml.jackson.jaxrs'
        exclude group: 'com.fasterxml.jackson.module', module: 'jackson-module-jaxb-annotations'
    }
-    implementation 'commons-io:commons-io:2.22.0'
+    implementation "commons-io:commons-io:$commonsIoVersion"
    implementation "org.bouncycastle:bcprov-jdk18on:$bouncycastleVersion"
    implementation "org.bouncycastle:bcpkix-jdk18on:$bouncycastleVersion"
    implementation 'io.micrometer:micrometer-core'
@@ -81,25 +81,24 @@ dependencies {

    implementation 'org.verapdf:validation-model:1.28.2'
    // CVE-2025-66453: Explicit rhino 1.7.15 to override verapdf's 1.7.13
-    implementation 'org.mozilla:rhino:1.9.1'
+    implementation "org.mozilla:rhino:${rhinoVersion}"

    // veraPDF still uses javax.xml.bind, not the new jakarta namespace
    implementation 'javax.xml.bind:jaxb-api:2.3.1'
    implementation 'com.sun.xml.bind:jaxb-impl:2.3.9'
    implementation 'com.sun.xml.bind:jaxb-core:4.0.7'
-    implementation 'org.apache.poi:poi-ooxml:5.5.1'

-    // CVE-2022-25647: Explicit gson 2.13.2 to prevent unsafe deserialization (tabula would pull 2.8.7)
-    implementation 'com.google.code.gson:gson:2.13.2'
+    // CVE-2022-25647: Explicit gson to prevent unsafe deserialization (tabula would pull 2.8.7)
+    implementation "com.google.code.gson:gson:${gsonVersion}"
    implementation 'org.apache.pdfbox:jbig2-imageio:3.0.4'
    implementation 'com.opencsv:opencsv:5.12.0' // https://mvnrepository.com/artifact/com.opencsv/opencsv
    implementation 'org.apache.poi:poi-ooxml:5.5.1'

    // Batik only bridge module needed (transitively pulls anim, gvt, util, css, dom, svg-dom)
    // Replaces batik-all which included unused codec, svggen, transcoder, script modules
-    implementation 'org.apache.xmlgraphics:batik-bridge:1.19'
+    implementation "org.apache.xmlgraphics:batik-bridge:${batikVersion}"
    // Required by TwelveMonkeys imageio-batik SPI (SVGImageReaderSpi) during ImageIO init
-    runtimeOnly 'org.apache.xmlgraphics:batik-transcoder:1.19'
+    runtimeOnly "org.apache.xmlgraphics:batik-transcoder:${batikVersion}"

    // PDFBox Graphics2D bridge for Batik SVG to PDF conversion
    implementation 'de.rototor.pdfbox:graphics2d:3.0.5'
@@ -176,6 +175,14 @@ springBoot {
 // Frontend build tasks - only enabled with -PbuildWithFrontend=true
 def buildWithFrontend = project.hasProperty('buildWithFrontend') && project.property('buildWithFrontend') == 'true'
 def buildPrototypes = project.hasProperty('prototypesMode') && project.property('prototypesMode') == 'true'
+// The admin portal ships as a lazy route inside the editor bundle (see
+// proprietary/routes/adminRouteExtensions). -PbuildWithPortal=true includes that
+// chunk via VITE_INCLUDE_PORTAL on the editor build; the deploy GHA sets it when
+// the portal or AI layers change. Building the portal implies building the editor.
+def buildWithPortal = project.hasProperty('buildWithPortal') && project.property('buildWithPortal') == 'true'
+if (buildWithPortal) {
+    buildWithFrontend = true
+}
 // Workspace root holds package.json and node_modules (shared across editor /
 // future portal). Editor-specific paths (src, public, dist, tauri) live one
 // level deeper under frontend/editor/.
@@ -298,9 +305,11 @@ tasks.register('npmBuild', Exec) {
    // Override VITE_API_BASE_URL to use relative paths for production builds
    // This ensures JARs work regardless of how they're deployed (direct, proxied, etc.)
    environment 'VITE_API_BASE_URL', '/'
+    // Include the admin portal's lazy route/chunk in the editor build when requested.
+    environment 'VITE_INCLUDE_PORTAL', (buildWithPortal ? 'true' : 'false')

    doFirst {
-        println "Building editor frontend application for production (mode=${frontendMode}, VITE_API_BASE_URL=/)"
+        println "Building editor frontend application for production (mode=${frontendMode}, VITE_API_BASE_URL=/, portal=${buildWithPortal})"
    }
 }

@@ -24,12 +24,14 @@ import java.security.KeyStore;
 import java.security.KeyStoreException;
 import java.security.NoSuchAlgorithmException;
 import java.security.PrivateKey;
+import java.security.Provider;
 import java.security.UnrecoverableKeyException;
 import java.security.cert.Certificate;
 import java.security.cert.CertificateException;
 import java.security.cert.X509Certificate;
 import java.util.Arrays;
 import java.util.Enumeration;
+import java.util.Locale;

 import org.apache.pdfbox.pdmodel.interactive.digitalsignature.SignatureInterface;
 import org.bouncycastle.cert.jcajce.JcaCertStore;
@@ -50,6 +52,13 @@ public abstract class CreateSignatureBase implements SignatureInterface {
    @Getter private Certificate[] certificateChain;
    @Setter private String tsaUrl;

+    /**
+     * Provider that must service the signing operation. Set for hardware-held keys (SunPKCS11 for
+     * USB tokens, SunMSCAPI for the Windows store) so the {@link java.security.Signature} runs on
+     * the token. Left {@code null} for software keystores, which use the default provider.
+     */
+    @Setter private Provider signingProvider;
+
    /**
     * Specifies whether the external signing scenario should be used. If set to {@code true},
     * external signing will be performed and {@link SignatureInterface} will be used for signing.
@@ -80,25 +89,48 @@ public abstract class CreateSignatureBase implements SignatureInterface {
                    NoSuchAlgorithmException,
                    IOException,
                    CertificateException {
-        // grabs the first alias from the keystore and get the private key. An
-        // alternative method or constructor could be used for setting a specific
-        // alias that should be used.
+        this(keystore, pin, null);
+    }
+
+    /**
+     * Initialize the signature creator, optionally selecting a specific certificate by alias. A
+     * hardware token / the Windows store can hold several certificates, so the caller picks one;
+     * when {@code requestedAlias} is null the first usable entry is used (software keystore
+     * behaviour).
+     *
+     * @param keystore the keystore (software, PKCS#11 or Windows-MY)
+     * @param pin the keystore / token PIN, may be null for the Windows store
+     * @param requestedAlias the alias to sign with, or null to pick the first usable entry
+     */
+    public CreateSignatureBase(KeyStore keystore, char[] pin, String requestedAlias)
+            throws KeyStoreException,
+                    UnrecoverableKeyException,
+                    NoSuchAlgorithmException,
+                    IOException,
+                    CertificateException {
+        if (requestedAlias != null
+                && !requestedAlias.isBlank()
+                && keystore.containsAlias(requestedAlias)) {
+            privateKey = (PrivateKey) keystore.getKey(requestedAlias, pin);
+            certificateChain = resolveChain(keystore, requestedAlias);
+            if (certificateChain == null) {
+                throw new IOException("Could not find certificate for alias " + requestedAlias);
+            }
+            checkValidity(certificateChain[0]);
+            return;
+        }
+
+        // grabs the first alias from the keystore and gets the private key.
        Enumeration<String> aliases = keystore.aliases();
-        String alias;
        Certificate cert = null;
        while (cert == null && aliases.hasMoreElements()) {
-            alias = aliases.nextElement();
+            String alias = aliases.nextElement();
            privateKey = (PrivateKey) keystore.getKey(alias, pin);
-            Certificate[] certChain = keystore.getCertificateChain(alias);
+            Certificate[] certChain = resolveChain(keystore, alias);
            if (certChain != null) {
                certificateChain = certChain;
                cert = certChain[0];
-                if (cert instanceof X509Certificate) {
-                    // avoid expired certificate
-                    ((X509Certificate) cert).checkValidity();
-
-                    //// SigUtils.checkCertificateUsage((X509Certificate) cert);
-                }
+                checkValidity(cert);
            }
        }

@@ -107,6 +139,27 @@ public abstract class CreateSignatureBase implements SignatureInterface {
        }
    }

+    /**
+     * Resolve the certificate chain for an alias. PKCS#11 tokens and the Windows store frequently
+     * expose only the leaf certificate (a null chain), so fall back to the single certificate.
+     */
+    private static Certificate[] resolveChain(KeyStore keystore, String alias)
+            throws KeyStoreException {
+        Certificate[] chain = keystore.getCertificateChain(alias);
+        if (chain != null && chain.length > 0) {
+            return chain;
+        }
+        Certificate single = keystore.getCertificate(alias);
+        return single != null ? new Certificate[] {single} : null;
+    }
+
+    private static void checkValidity(Certificate cert) throws CertificateException {
+        if (cert instanceof X509Certificate x509Cert) {
+            // avoid expired certificate
+            x509Cert.checkValidity();
+        }
+    }
+
    public final void setPrivateKey(PrivateKey privateKey) {
        this.privateKey = privateKey;
    }
@@ -136,12 +189,18 @@ public abstract class CreateSignatureBase implements SignatureInterface {
        try {
            CMSSignedDataGenerator gen = new CMSSignedDataGenerator();
            X509Certificate cert = (X509Certificate) certificateChain[0];
-            ContentSigner sha1Signer =
-                    new JcaContentSignerBuilder("SHA256WithRSA").build(privateKey);
+            JcaContentSignerBuilder signerBuilder =
+                    new JcaContentSignerBuilder(resolveSignatureAlgorithm(privateKey, cert));
+            // Hardware keys (PKCS#11 / Windows store) must sign on their own provider so the
+            // operation runs on the token; software keys use the default provider.
+            if (signingProvider != null) {
+                signerBuilder.setProvider(signingProvider);
+            }
+            ContentSigner signer = signerBuilder.build(privateKey);
            gen.addSignerInfoGenerator(
                    new JcaSignerInfoGeneratorBuilder(
                                    new JcaDigestCalculatorProviderBuilder().build())
-                            .build(sha1Signer, cert));
+                            .build(signer, cert));
            gen.addCertificates(new JcaCertStore(Arrays.asList(certificateChain)));
            CMSProcessableInputStream msg = new CMSProcessableInputStream(content);
            CMSSignedData signedData = gen.generate(msg, false);
@@ -157,4 +216,26 @@ public abstract class CreateSignatureBase implements SignatureInterface {
            throw new IOException(e);
        }
    }
+
+    /**
+     * Pick a SHA-256 signature algorithm that matches the key type. RSA keeps the historical
+     * default; EC / EdDSA tokens are common, so they are handled too.
+     */
+    private static String resolveSignatureAlgorithm(PrivateKey key, X509Certificate cert) {
+        String alg = key.getAlgorithm();
+        if (alg == null || alg.isBlank()) {
+            alg = cert.getPublicKey().getAlgorithm();
+        }
+        alg = alg == null ? "" : alg.toUpperCase(Locale.ROOT);
+        if (alg.contains("ED25519") || alg.contains("EDDSA")) {
+            return "Ed25519";
+        }
+        if (alg.contains("EC")) { // EC, ECDSA
+            return "SHA256withECDSA";
+        }
+        if (alg.contains("DSA")) {
+            return "SHA256withDSA";
+        }
+        return "SHA256withRSA";
+    }
 }
@@ -1,6 +1,5 @@
 package stirling.software.SPDF.config;

-import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.servlet.MultipartConfigFactory;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -22,7 +21,11 @@ import stirling.software.SPDF.controller.web.UploadLimitService;
@Slf4j
 public class MultipartConfiguration {

-    @Autowired private UploadLimitService uploadLimitService;
+    private final UploadLimitService uploadLimitService;
+
+    public MultipartConfiguration(UploadLimitService uploadLimitService) {
+        this.uploadLimitService = uploadLimitService;
+    }

    /**
     * Creates MultipartConfigElement that respects fileUploadLimit from settings.yml or environment
@@ -85,7 +85,6 @@ public class WebMvcConfig implements WebMvcConfigurer {
                        "/icons/**",
                        "/modern-logo/**",
                        "/classic-logo/**",
-                        "/robots.txt",
                        "/3rdPartyLicenses.json",
                        "/pdfjs/**",
                        "/pdfjs-legacy/**",
@@ -294,24 +294,25 @@ public class BookletImpositionController {

        // Apply rotation if needed (rotate about origin), then translate to keep in cell
        switch (rot) {
-            case 90:
+            case 90 -> {
                cs.transform(Matrix.getRotateInstance(Math.PI / 2, 0, 0));
                // After 90° CCW, the content spans x in [-r.getHeight(), 0] and y in [0,
                // r.getWidth()]
                cs.transform(Matrix.getTranslateInstance(0, -r.getWidth()));
-                break;
-            case 180:
+            }
+            case 180 -> {
                cs.transform(Matrix.getRotateInstance(Math.PI, 0, 0));
                cs.transform(Matrix.getTranslateInstance(-r.getWidth(), -r.getHeight()));
-                break;
-            case 270:
+            }
+            case 270 -> {
                cs.transform(Matrix.getRotateInstance(3 * Math.PI / 2, 0, 0));
                // After 270° CCW, the content spans x in [0, r.getHeight()] and y in
                // [-r.getWidth(), 0]
                cs.transform(Matrix.getTranslateInstance(-r.getHeight(), 0));
-                break;
-            default:
+            }
+            default -> {
                // 0°: no-op
+            }
        }

        // Reuse LayerUtility passed from caller
@@ -9,7 +9,6 @@ import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Comparator;
 import java.util.List;
-import java.util.regex.Pattern;

 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDDocumentCatalog;
@@ -58,8 +57,6 @@ import stirling.software.jpdfium.doc.PdfBookmarkEditor.BookmarkTree;
@Slf4j
@RequiredArgsConstructor
 public class MergeController {
-
-    private static final Pattern QUOTE_WRAP_PATTERN = Pattern.compile("^\"|\"$");
    private final CustomPDFDocumentFactory pdfDocumentFactory;
    private final TempFileManager tempFileManager;

@@ -161,30 +158,6 @@ public class MergeController {
        };
    }

-    private String[] parseClientFileIds(String clientFileIds) {
-        if (clientFileIds == null || clientFileIds.trim().isEmpty()) {
-            return new String[0];
-        }
-        try {
-            String trimmed = clientFileIds.trim();
-            if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
-                String inside = trimmed.substring(1, trimmed.length() - 1).trim();
-                if (inside.isEmpty()) {
-                    return new String[0];
-                }
-                String[] parts = inside.split(",");
-                String[] result = new String[parts.length];
-                for (int i = 0; i < parts.length; i++) {
-                    result[i] = QUOTE_WRAP_PATTERN.matcher(parts[i].trim()).replaceAll("");
-                }
-                return result;
-            }
-        } catch (Exception e) {
-            log.warn("Failed to parse client file IDs: {}", clientFileIds, e);
-        }
-        return new String[0];
-    }
-
    private void addTableOfContents(PDDocument mergedDocument, MultipartFile[] files) {
        PDDocumentOutline outline = new PDDocumentOutline();
        mergedDocument.getDocumentCatalog().setDocumentOutline(outline);
@@ -3,9 +3,12 @@ package stirling.software.SPDF.controller.api;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
+import java.util.Set;

+import org.apache.pdfbox.cos.COSDictionary;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.PDPageTree;
@@ -261,10 +264,19 @@ public class RearrangePagesPDFController {
                log.info("newPageOrder = {}", newPageOrder);
                log.info("totalPages = {}", totalPages);

-                // Snapshot the desired pages before mutating the source document's page tree.
+                // Snapshot desired pages before mutating the tree; clone repeats (e.g. DUPLICATE)
+                // so each slot is a distinct node, not one PDPage under multiple /Kids.
                List<PDPage> newPages = new ArrayList<>(newPageOrder.size());
+                Set<Integer> seenIndices = new HashSet<>();
                for (Integer idx : newPageOrder) {
-                    newPages.add(document.getPage(idx));
+                    PDPage page = document.getPage(idx);
+                    if (!seenIndices.add(idx)) {
+                        // Duplicate index: distinct page node sharing content/resources.
+                        COSDictionary clonedDict = new COSDictionary();
+                        clonedDict.addAll(page.getCOSObject());
+                        page = new PDPage(clonedDict);
+                    }
+                    newPages.add(page);
                }

                // Rearrange in-place on the source document rather than copying pages into a
@@ -125,17 +125,14 @@ public class UIDataController {
                    pipelineConfigs.add(content);
                }

-                for (String config : pipelineConfigs) {
+                for (int i = 0; i < pipelineConfigs.size(); i++) {
+                    String config = pipelineConfigs.get(i);
                    Map<String, Object> jsonContent =
                            objectMapper.readValue(
                                    config, new TypeReference<Map<String, Object>>() {});
                    String name = (String) jsonContent.get("name");
                    if (name == null || name.length() < 1) {
-                        String filename =
-                                jsonFiles
-                                        .get(pipelineConfigs.indexOf(config))
-                                        .getFileName()
-                                        .toString();
+                        String filename = jsonFiles.get(i).getFileName().toString();
                        name = filename.substring(0, filename.lastIndexOf('.'));
                    }
                    Map<String, String> configWithName = new HashMap<>();
@@ -301,20 +298,14 @@ public class UIDataController {
        }

        private static String getFormatFromExtension(String extension) {
-            switch (extension) {
-                case "ttf":
-                    return "truetype";
-                case "woff":
-                    return "woff";
-                case "woff2":
-                    return "woff2";
-                case "eot":
-                    return "embedded-opentype";
-                case "svg":
-                    return "svg";
-                default:
-                    return "";
-            }
+            return switch (extension) {
+                case "ttf" -> "truetype";
+                case "woff" -> "woff";
+                case "woff2" -> "woff2";
+                case "eot" -> "embedded-opentype";
+                case "svg" -> "svg";
+                default -> "";
+            };
        }
    }
 }
@@ -187,7 +187,7 @@ public class ConvertImgPDFController {
                }

                if (webpFiles.size() == 1) {
-                    Path webpFilePath = webpFiles.get(0);
+                    Path webpFilePath = webpFiles.getFirst();
                    byte[] webpBytes = Files.readAllBytes(webpFilePath);
                    Files.deleteIfExists(tempFile);
                    tempFile = null;
@@ -147,7 +147,7 @@ public class ConvertSvgToPDF {
            String outputFilename =
                    filenames.isEmpty()
                            ? "combined_svgs.pdf"
-                            : GeneralUtils.generateFilename(filenames.get(0), "_combined.pdf");
+                            : GeneralUtils.generateFilename(filenames.getFirst(), "_combined.pdf");

            log.info("Successfully combined {} SVGs into single PDF", sanitizedSvgs.size());

@@ -203,7 +203,7 @@ public class ConvertSvgToPDF {

        try {
            if (convertedPdfs.size() == 1) {
-                ConvertedPdf pdf = convertedPdfs.get(0);
+                ConvertedPdf pdf = convertedPdfs.getFirst();
                TempFile tempOut = tempFileManager.createManagedTempFile(".pdf");
                try {
                    Files.write(tempOut.getPath(), pdf.content);
@@ -218,7 +218,7 @@ public class ConvertSvgToPDF {
                    filenames.isEmpty()
                            ? "converted_svgs.zip"
                            : GeneralUtils.generateFilename(
-                                    filenames.get(0), "_converted_svgs.zip");
+                                    filenames.getFirst(), "_converted_svgs.zip");
            TempFile zipFile = createZipFromPdfs(convertedPdfs);
            return WebResponseUtils.zipFileToWebResponse(zipFile, zipFilename);
        } catch (IOException e) {
@@ -82,7 +82,7 @@ public class ExtractCSVController {
            if (csvEntries.isEmpty()) {
                return ResponseEntity.noContent().build();
            } else if (csvEntries.size() == 1) {
-                return createCsvResponse(csvEntries.get(0), baseName);
+                return createCsvResponse(csvEntries.getFirst(), baseName);
            } else {
                return createZipResponse(csvEntries, baseName);
            }
@@ -113,7 +113,9 @@ public class AutoRenameController {
                            mergedLineInfos.sort(
                                    Comparator.comparing((LineInfo li) -> li.fontSize).reversed());
                            String title =
-                                    mergedLineInfos.isEmpty() ? null : mergedLineInfos.get(0).text;
+                                    mergedLineInfos.isEmpty()
+                                            ? null
+                                            : mergedLineInfos.getFirst().text;

                            return title != null
                                    ? title
@@ -333,7 +333,7 @@ public class AutoSplitPdfController {
                }

                if (!splitDocuments.isEmpty() && !isValidQrCode) {
-                    splitDocuments.get(splitDocuments.size() - 1).addPage(document.getPage(page));
+                    splitDocuments.getLast().addPage(document.getPage(page));
                } else if (page == 0) {
                    PDDocument firstDocument = new PDDocument();
                    firstDocument.addPage(document.getPage(page));
@@ -267,7 +267,7 @@ public class CompressController {
            if (references.isEmpty()) continue;

            // Get the first instance of this image
-            PDImageXObject originalImage = getOriginalImage(doc, references.get(0));
+            PDImageXObject originalImage = getOriginalImage(doc, references.getFirst());

            // Track original size
            int originalSize = (int) originalImage.getCOSObject().getLength();
@@ -1167,7 +1167,7 @@ public class CompressController {
            List<ImageReference> references = entry.getValue();
            if (references.isEmpty()) continue;

-            PDImageXObject originalImage = getOriginalImage(doc, references.get(0));
+            PDImageXObject originalImage = getOriginalImage(doc, references.getFirst());

            int originalSize = (int) originalImage.getCOSObject().getLength();
            stats.totalOriginalBytes += originalSize;
@@ -22,6 +22,7 @@ import stirling.software.SPDF.config.InitialSetup;
 import stirling.software.SPDF.controller.api.security.TimestampController;
 import stirling.software.common.annotations.api.ConfigApi;
 import stirling.software.common.configuration.AppConfig;
+import stirling.software.common.configuration.interfaces.ShowAdminInterface;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.service.ServerCertificateServiceInterface;
 import stirling.software.common.service.UserServiceInterface;
@@ -37,6 +38,7 @@ public class ConfigController {
    private final EndpointConfiguration endpointConfiguration;
    private final ServerCertificateServiceInterface serverCertificateService;
    private final UserServiceInterface userService;
+    private final ShowAdminInterface showAdmin;
    private final stirling.software.common.service.LicenseServiceInterface licenseService;
    private final stirling.software.SPDF.config.ExternalAppDepConfig externalAppDepConfig;

@@ -48,6 +50,8 @@ public class ConfigController {
                    ServerCertificateServiceInterface serverCertificateService,
            @org.springframework.beans.factory.annotation.Autowired(required = false)
                    UserServiceInterface userService,
+            @org.springframework.beans.factory.annotation.Autowired(required = false)
+                    ShowAdminInterface showAdmin,
            @org.springframework.beans.factory.annotation.Autowired(required = false)
                    stirling.software.common.service.LicenseServiceInterface licenseService,
            stirling.software.SPDF.config.ExternalAppDepConfig externalAppDepConfig) {
@@ -56,6 +60,7 @@ public class ConfigController {
        this.endpointConfiguration = endpointConfiguration;
        this.serverCertificateService = serverCertificateService;
        this.userService = userService;
+        this.showAdmin = showAdmin;
        this.licenseService = licenseService;
        this.externalAppDepConfig = externalAppDepConfig;
    }
@@ -315,6 +320,10 @@ public class ConfigController {
            configData.put(
                    "enableAlphaFunctionality",
                    applicationProperties.getSystem().isEnableAlphaFunctionality());
+            boolean shouldShowUpdate =
+                    applicationProperties.getSystem().isShowUpdate()
+                            && (showAdmin == null || showAdmin.getShowUpdateOnlyAdmins());
+            configData.put("shouldShowUpdate", shouldShowUpdate);
            configData.put(
                    "enableAnalytics", applicationProperties.getSystem().getEnableAnalytics());
            configData.put("enablePosthog", applicationProperties.getSystem().getEnablePosthog());
@@ -341,6 +350,18 @@ public class ConfigController {
                    "serverCertificateEnabled",
                    serverCertificateService != null && serverCertificateService.isEnabled());

+            // Hardware-backed signing (Windows store / USB PKCS#11 tokens) is only viable on the
+            // desktop bundle, where the backend runs locally in the user's session. The Tauri
+            // bundle signals this via STIRLING_PDF_TAURI_MODE (machineType is Server-jar there);
+            // the bare-jar desktop launcher signals it via a Client-* machineType.
+            boolean hardwareSigningAvailable =
+                    Boolean.parseBoolean(System.getProperty("STIRLING_PDF_TAURI_MODE", "false"));
+            if (!hardwareSigningAvailable && applicationContext.containsBean("machineType")) {
+                String mt = applicationContext.getBean("machineType", String.class);
+                hardwareSigningAvailable = mt != null && mt.startsWith("Client-");
+            }
+            configData.put("hardwareSigningAvailable", hardwareSigningAvailable);
+
            // Legal settings
            configData.put(
                    "termsAndConditions", applicationProperties.getLegal().getTermsAndConditions());
@@ -211,7 +211,7 @@ public class ExtractImageScansController {
            } else {

                // Return the processed image as a response
-                byte[] imageBytes = processedImageBytes.get(0);
+                byte[] imageBytes = processedImageBytes.getFirst();
                finalOutput = tempFileManager.createManagedTempFile(".png");
                try (OutputStream out = Files.newOutputStream(finalOutput.getPath())) {
                    out.write(imageBytes);
@@ -0,0 +1,49 @@
+package stirling.software.SPDF.controller.api.misc;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.annotations.api.ConfigApi;
+import stirling.software.common.service.LoginAgreementService;
+
+/**
+ * Serves the login agreement / disclaimer for the frontend. Shares the /api/v1/config access rules:
+ * it requires authentication when login is enabled (the modal is shown after login, never on the
+ * login screen) and is permit-all in anonymous/no-login mode and in SaaS. The text is read live
+ * from disk, so admin edits take effect on the next login without a restart.
+ */
+@ConfigApi
+@Hidden
+@RequiredArgsConstructor
+public class LoginDisclaimerController {
+
+    private final LoginAgreementService loginAgreementService;
+
+    @GetMapping("/login-disclaimer")
+    @Operation(
+            summary = "Get the login agreement/disclaimer",
+            description =
+                    "Returns whether the login agreement is enabled and, if so, the markdown to"
+                            + " display for the requested language.")
+    public LoginDisclaimerResponse getLoginDisclaimer(
+            @RequestParam(name = "lang", required = false) String lang) {
+        boolean showInAnonymousMode = loginAgreementService.isShowInAnonymousMode();
+        if (!loginAgreementService.isEnabled()) {
+            return new LoginDisclaimerResponse(false, showInAnonymousMode, "", "markdown");
+        }
+        String content = loginAgreementService.resolveContent(lang);
+        // Enabled but no resolvable text (no file for any candidate locale and no fallbackText):
+        // report disabled so clients don't try to render an empty agreement.
+        boolean hasContent = content != null && !content.isBlank();
+        return new LoginDisclaimerResponse(
+                hasContent, showInAnonymousMode, hasContent ? content : "", "markdown");
+    }
+
+    public record LoginDisclaimerResponse(
+            boolean enabled, boolean showInAnonymousMode, String content, String format) {}
+}
@@ -70,10 +70,13 @@ import io.micrometer.common.util.StringUtils;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;

+import jakarta.servlet.http.HttpServletRequest;
+
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.security.SignPDFWithCertRequest;
+import stirling.software.SPDF.service.HardwareKeyStoreService;
 import stirling.software.common.annotations.AutoJobPostMapping;
 import stirling.software.common.enumeration.ResourceWeight;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -109,14 +112,17 @@ public class CertSignController {
    private final CustomPDFDocumentFactory pdfDocumentFactory;
    private final ServerCertificateServiceInterface serverCertificateService;
    private final TempFileManager tempFileManager;
+    private final HardwareKeyStoreService hardwareKeyStoreService;

    public CertSignController(
            CustomPDFDocumentFactory pdfDocumentFactory,
            @Autowired(required = false) ServerCertificateServiceInterface serverCertificateService,
-            TempFileManager tempFileManager) {
+            TempFileManager tempFileManager,
+            HardwareKeyStoreService hardwareKeyStoreService) {
        this.pdfDocumentFactory = pdfDocumentFactory;
        this.serverCertificateService = serverCertificateService;
        this.tempFileManager = tempFileManager;
+        this.hardwareKeyStoreService = hardwareKeyStoreService;
    }

    public static void sign(
@@ -170,7 +176,8 @@ public class CertSignController {
                    "This endpoint accepts a PDF file, a digital certificate and related"
                            + " information to sign the PDF. It then returns the digitally signed PDF"
                            + " file. Input:PDF Output:PDF Type:SISO")
-    public ResponseEntity<Resource> signPDFWithCert(@ModelAttribute SignPDFWithCertRequest request)
+    public ResponseEntity<Resource> signPDFWithCert(
+            @ModelAttribute SignPDFWithCertRequest request, HttpServletRequest httpRequest)
            throws Exception {
        MultipartFile pdf = request.getFileInput();
        String certType = request.getCertType();
@@ -196,6 +203,8 @@ public class CertSignController {

        KeyStore ks = null;
        String keystorePassword = password;
+        Provider signingProvider = null;
+        HardwareKeyStoreService.Pkcs11Session pkcs11Session = null;

        switch (certType) {
            case "PEM":
@@ -245,6 +254,31 @@ public class CertSignController {
                ks = serverCertificateService.getServerKeyStore();
                keystorePassword = serverCertificateService.getServerCertificatePassword();
                break;
+            case "WINDOWS_STORE":
+                hardwareKeyStoreService.assertLocalDesktop(httpRequest);
+                ks = hardwareKeyStoreService.loadWindowsKeyStore();
+                signingProvider = hardwareKeyStoreService.windowsProvider();
+                // PIN is prompted by the Windows CSP / token middleware, not passed here.
+                keystorePassword = password;
+                break;
+            case "PKCS11":
+                hardwareKeyStoreService.assertLocalDesktop(httpRequest);
+                char[] pkcs11Pin = password != null ? password.toCharArray() : null;
+                try {
+                    pkcs11Session =
+                            hardwareKeyStoreService.openPkcs11(
+                                    request.getPkcs11LibraryPath(),
+                                    request.getPkcs11Slot(),
+                                    pkcs11Pin);
+                } finally {
+                    if (pkcs11Pin != null) {
+                        java.util.Arrays.fill(pkcs11Pin, '\0');
+                    }
+                }
+                ks = pkcs11Session.keyStore();
+                signingProvider = pkcs11Session.provider();
+                keystorePassword = password;
+                break;
            default:
                throw ExceptionUtils.createIllegalArgumentException(
                        "error.invalidArgument",
@@ -252,7 +286,9 @@ public class CertSignController {
                        "certificate type: " + certType);
        }

-        CreateSignature createSignature = new CreateSignature(ks, keystorePassword.toCharArray());
+        char[] pin = keystorePassword != null ? keystorePassword.toCharArray() : null;
+        CreateSignature createSignature =
+                new CreateSignature(ks, pin, request.getAlias(), signingProvider);
        TempFile signedOut = tempFileManager.createManagedTempFile(".pdf");
        try (OutputStream os = new FileOutputStream(signedOut.getFile())) {
            sign(
@@ -269,6 +305,14 @@ public class CertSignController {
        } catch (IOException e) {
            signedOut.close();
            throw e;
+        } finally {
+            // Clear the PIN copy and log out the token session once signing is done.
+            if (pin != null) {
+                java.util.Arrays.fill(pin, '\0');
+            }
+            if (pkcs11Session != null) {
+                pkcs11Session.close();
+            }
        }
        // Return the signed PDF
        return WebResponseUtils.pdfFileToWebResponse(
@@ -324,7 +368,22 @@ public class CertSignController {
                        NoSuchAlgorithmException,
                        IOException,
                        CertificateException {
-            super(keystore, pin);
+            this(keystore, pin, null, null);
+        }
+
+        public CreateSignature(
+                KeyStore keystore, char[] pin, String alias, Provider signingProvider)
+                throws KeyStoreException,
+                        UnrecoverableKeyException,
+                        NoSuchAlgorithmException,
+                        IOException,
+                        CertificateException {
+            super(keystore, pin, alias);
+            setSigningProvider(signingProvider);
+            loadLogo();
+        }
+
+        private void loadLogo() throws IOException {
            ClassPathResource resource = new ClassPathResource("static/images/signature.png");
            try (InputStream is = resource.getInputStream()) {
                logoFile = Files.createTempFile("signature", ".png").toFile();
@@ -345,7 +404,7 @@ public class CertSignController {
                PDAcroForm acroForm = new PDAcroForm(doc);
                doc.getDocumentCatalog().setAcroForm(acroForm);
                PDSignatureField signatureField = new PDSignatureField(acroForm);
-                PDAnnotationWidget widget = signatureField.getWidgets().get(0);
+                PDAnnotationWidget widget = signatureField.getWidgets().getFirst();
                List<PDField> acroFormFields = acroForm.getFields();
                acroForm.setSignaturesExist(true);
                acroForm.setAppendOnly(true);
@@ -305,6 +305,23 @@ public class GetInfoOnPDF {
        }
    }

+    /**
+     * Info-dictionary keys exposed above via typed getters; any other key in the dictionary is
+     * surfaced as custom metadata (e.g. the classification policy's StirlingPDFClassification
+     * entry).
+     */
+    private static final java.util.Set<String> STANDARD_INFO_KEYS =
+            java.util.Set.of(
+                    "Title",
+                    "Author",
+                    "Subject",
+                    "Keywords",
+                    "Producer",
+                    "Creator",
+                    "CreationDate",
+                    "ModDate",
+                    "Trapped");
+
    private static ObjectNode extractMetadata(PDDocument document) {
        ObjectNode metadata = objectMapper.createObjectNode();

@@ -335,6 +352,18 @@ public class GetInfoOnPDF {
                if (modificationDate != null) {
                    metadata.put("ModificationDate", modificationDate);
                }
+
+                // Surface custom Info-dictionary entries (anything beyond the
+                // standard fields above) — e.g. StirlingPDFClassification
+                for (String key : info.getMetadataKeys()) {
+                    if (STANDARD_INFO_KEYS.contains(key)) {
+                        continue;
+                    }
+                    String value = info.getCustomMetadataValue(key);
+                    if (value != null && !value.isBlank()) {
+                        metadata.put(key, value);
+                    }
+                }
            }
        } catch (Exception e) {
            log.error("Error extracting metadata: {}", e.getMessage());
@@ -0,0 +1,85 @@
+package stirling.software.SPDF.controller.api.security;
+
+import java.util.List;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import jakarta.servlet.http.HttpServletRequest;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.SPDF.model.api.security.HardwareCertificateInfo;
+import stirling.software.SPDF.model.api.security.HardwareSigningCapabilities;
+import stirling.software.SPDF.model.api.security.Pkcs11CertificatesRequest;
+import stirling.software.SPDF.service.HardwareKeyStoreService;
+
+/**
+ * Lets the desktop frontend discover which hardware-backed signing options the local backend can
+ * reach (Windows certificate store, plugged-in USB / PKCS#11 tokens) and enumerate the certificates
+ * available to sign with. Enumeration endpoints are restricted to the desktop bundle, reached over
+ * loopback - see {@link HardwareKeyStoreService#assertLocalDesktop}.
+ */
+@RestController
+@RequestMapping("/api/v1/security/cert-sign/hardware")
+@RequiredArgsConstructor
+@Slf4j
+@Tag(name = "Security", description = "Security APIs")
+public class HardwareSigningController {
+
+    private final HardwareKeyStoreService hardwareKeyStoreService;
+
+    @GetMapping("/capabilities")
+    @Operation(
+            summary = "Hardware signing capabilities",
+            description =
+                    "Reports whether hardware-backed signing is available on this device and which"
+                            + " PKCS#11 driver libraries were detected. Returns desktop=false when"
+                            + " not running as the desktop app.")
+    public ResponseEntity<HardwareSigningCapabilities> getCapabilities() {
+        return ResponseEntity.ok(hardwareKeyStoreService.capabilities());
+    }
+
+    @GetMapping("/windows-certificates")
+    @Operation(
+            summary = "List Windows certificate store signing certificates",
+            description =
+                    "Enumerates certificates with a usable private key from the current user's"
+                            + " Windows certificate store. Desktop-only, loopback-only.")
+    public ResponseEntity<List<HardwareCertificateInfo>> getWindowsCertificates(
+            HttpServletRequest request) throws Exception {
+        hardwareKeyStoreService.assertLocalDesktop(request);
+        return ResponseEntity.ok(hardwareKeyStoreService.listWindowsCertificates());
+    }
+
+    @PostMapping("/pkcs11-certificates")
+    @Operation(
+            summary = "List PKCS#11 token signing certificates",
+            description =
+                    "Logs into a PKCS#11 token with the supplied PIN and enumerates its signing"
+                            + " certificates. The PIN is used only for this call. Desktop-only,"
+                            + " loopback-only.")
+    public ResponseEntity<List<HardwareCertificateInfo>> getPkcs11Certificates(
+            HttpServletRequest request, @RequestBody Pkcs11CertificatesRequest body)
+            throws Exception {
+        hardwareKeyStoreService.assertLocalDesktop(request);
+        char[] pin = body.pin() != null ? body.pin().toCharArray() : null;
+        try {
+            return ResponseEntity.ok(
+                    hardwareKeyStoreService.listPkcs11Certificates(
+                            body.libraryPath(), body.slot(), pin));
+        } finally {
+            if (pin != null) {
+                java.util.Arrays.fill(pin, '\0');
+            }
+        }
+    }
+}
@@ -634,7 +634,7 @@ class RedactExecuteService {
        PageColumnLayout layout =
                PageColumnLayout.fromLineBoxes(extractor.getLineBoxes(), pageWidth);
        if (layout.columnCount() > 1) {
-            float[] g = layout.gutters().get(0);
+            float[] g = layout.gutters().getFirst();
            log.info(
                    "[redact/execute] page {} layout: 2 cols, gutter x=[{}, {}]",
                    pageIdx + 1,
@@ -60,7 +60,7 @@ public class RemoveCertSignController {
                // Remove signature fields safely
                List<PDField> fieldsToRemove =
                        acroForm.getFields().stream()
-                                .filter(field -> field instanceof PDSignatureField)
+                                .filter(PDSignatureField.class::isInstance)
                                .toList();

                if (!fieldsToRemove.isEmpty()) {
@@ -102,8 +102,27 @@ public class ValidateSignatureController {
        try (PDDocument document = pdfDocumentFactory.load(file.getInputStream())) {
            List<PDSignature> signatures = document.getSignatureDictionaries();

+            // Detect content appended outside every signature's ByteRange (added after signing). A
+            // properly signed document has its last signature cover all the way to EOF; if the
+            // furthest any signature reaches stops short of the file length, the tail is unsigned.
+            // Taking the max across all signatures avoids false positives on legitimately
+            // multi-signed PDFs, where an earlier signature intentionally omits later revisions.
+            long fileLength = file.getSize();
+            long maxCovered = 0;
+            for (PDSignature sig : signatures) {
+                int[] byteRange = sig.getByteRange();
+                if (byteRange != null && byteRange.length == 4) {
+                    long end = (long) byteRange[2] + byteRange[3];
+                    if (end > maxCovered) {
+                        maxCovered = end;
+                    }
+                }
+            }
+            boolean documentCovered = maxCovered <= 0 || maxCovered >= fileLength;
+
            for (PDSignature sig : signatures) {
                SignatureValidationResult result = new SignatureValidationResult();
+                result.setCoversEntireDocument(documentCovered);

                try {
                    byte[] signedContent = sig.getSignedContent(file.getInputStream());
@@ -0,0 +1,30 @@
+package stirling.software.SPDF.controller.web;
+
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+import org.springframework.web.bind.annotation.RestController;
+
+import stirling.software.common.model.ApplicationProperties;
+
+/**
+ * Serves /robots.txt dynamically so the system.googlevisibility flag actually controls
+ * search-engine indexing. 'true' returns an allow-all policy; 'false' returns a disallow-all policy
+ * to keep the instance out of search engines (useful for embedded/internal deployments).
+ */
+@RestController
+public class RobotsController {
+
+    private final ApplicationProperties applicationProperties;
+
+    public RobotsController(ApplicationProperties applicationProperties) {
+        this.applicationProperties = applicationProperties;
+    }
+
+    @GetMapping(value = "/robots.txt", produces = MediaType.TEXT_PLAIN_VALUE)
+    @ResponseBody
+    public String robotsTxt() {
+        boolean allowIndexing = applicationProperties.getSystem().isGooglevisibility();
+        return "User-agent: *\n" + (allowIndexing ? "Allow: /\n" : "Disallow: /\n");
+    }
+}
@@ -2,7 +2,6 @@ package stirling.software.SPDF.controller.web;

 import java.util.Locale;

-import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;

 import lombok.extern.slf4j.Slf4j;
@@ -13,7 +12,11 @@ import stirling.software.common.model.ApplicationProperties;
@Slf4j
 public class UploadLimitService {

-    @Autowired private ApplicationProperties applicationProperties;
+    private final ApplicationProperties applicationProperties;
+
+    public UploadLimitService(ApplicationProperties applicationProperties) {
+        this.applicationProperties = applicationProperties;
+    }

    public long getUploadLimit() {
        String raw =
@@ -1,5 +1,7 @@
 package stirling.software.SPDF.model.api.general;

+import com.fasterxml.jackson.annotation.JsonProperty;
+
 import io.swagger.v3.oas.annotations.media.Schema;

 import lombok.Data;
@@ -17,20 +19,8 @@ public class PosterPdfRequest extends PDFFile {
            allowableValues = {"A4", "Letter", "A3", "A5", "Legal", "Tabloid"})
    private String pageSize = "A4";

-    @Schema(
-            description = "Horizontal decimation factor (how many columns to split into)",
-            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
-            defaultValue = "2",
-            minimum = "1",
-            maximum = "10")
    private int xFactor = 2;

-    @Schema(
-            description = "Vertical decimation factor (how many rows to split into)",
-            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
-            defaultValue = "2",
-            minimum = "1",
-            maximum = "10")
    private int yFactor = 2;

    @Schema(
@@ -38,4 +28,36 @@ public class PosterPdfRequest extends PDFFile {
            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
            defaultValue = "false")
    private boolean rightToLeft = false;
+
+    @JsonProperty("xFactor")
+    @Schema(
+            description = "Horizontal decimation factor (how many columns to split into)",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
+            defaultValue = "2",
+            minimum = "1",
+            maximum = "10")
+    public int getXFactor() {
+        return xFactor;
+    }
+
+    @JsonProperty("xFactor")
+    public void setXFactor(int xFactor) {
+        this.xFactor = xFactor;
+    }
+
+    @JsonProperty("yFactor")
+    @Schema(
+            description = "Vertical decimation factor (how many rows to split into)",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
+            defaultValue = "2",
+            minimum = "1",
+            maximum = "10")
+    public int getYFactor() {
+        return yFactor;
+    }
+
+    @JsonProperty("yFactor")
+    public void setYFactor(int yFactor) {
+        this.yFactor = yFactor;
+    }
 }
@@ -29,7 +29,8 @@ public class AddPasswordRequest extends PDFFile {
            description = "The length of the encryption key",
            type = "integer",
            allowableValues = {"40", "128", "256"},
-            requiredMode = Schema.RequiredMode.REQUIRED)
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED,
+            defaultValue = "256")
    private int keyLength = 256;

    @Schema(description = "Whether document assembly is prevented", defaultValue = "false")
--- a/Show More
+++ b/Show More