Update PolicyExecutor.java

## What this does

Reworks the portal's policy setup screens so a policy reads as **its own
settings**
rather than a list of tools you wire together, and rebuilds the forms on
the
shared design system so they match the rest of the portal.

## Why

Setup showed one card per underlying tool (tool name + a toggle), which
exposed
the "a policy is a pipeline of tools" plumbing. A policy should read in
terms of
what it does to a document, not which tools run under the hood.

## Changes

- **Setup reads as policy settings.** The per-tool cards are now a
plain-language
list of what the policy does — "Redact sensitive information", "Strip
active
content", "Apply a watermark", and so on — each with a short description
and a
  toggle, with its options appearing inline when turned on.
- **Consistent design system.** The setup and edit forms use the shared
  components instead of one-off styling.
- **Simpler setup.** Removed two sections that aren't part of what ships
here:
  Document Types (scope-by-type) and Retries.
- **Watermarks are text-only.** A policy watermark is a text stamp, so
the image
  option and the type picker are hidden.
- **The editor always shows as a source** (it used to disappear when no
other
  sources were connected), and the source tiles now lay out correctly.
- **Clearer upsell copy.** Locked policies read **"Upgrade to
Enterprise"**
  instead of "Coming soon".

## Scope

UI only — no backend changes. Keeping a policy's settings in sync
between the
portal and the editor is a known, separate issue and is **not** part of
this PR.

## Testing

Prettier, ESLint, typecheck (proprietary + saas), and the
unused-translation
guard all pass. Setup screens verified in Storybook.

.claude/skills/feature-walkthrough/SKILL.md

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

.claude/skills/ui-before-after/SKILL.md

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

.claude/skills/ui-before-after/capture-spec.template.ts

@@ -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 });
+  });
+}

.claude/skills/ui-before-after/diff-shots.mjs

@@ -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 : ""}`);
+}

.claude/skills/ui-before-after/make_example.py

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

.claude/skills/ui-before-after/montage-template.html

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

.claude/skills/ui-before-after/shoot-sections.mjs

@@ -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();

.claude/skills/ui-walkthrough/SKILL.md

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

.claude/skills/ui-walkthrough/make_example.py

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

.claude/skills/ui-walkthrough/report-template.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>

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

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

AGENTS.md

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

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

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

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

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

app/common/src/main/java/stirling/software/common/pdf/PdfMarkdownConverter.java

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

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

@@ -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);
         }

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

@@ -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);
+    }
 }

app/common/src/main/java/stirling/software/common/util/ChecksumUtils.java

@@ -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);
             }
         }
 

app/common/src/main/java/stirling/software/common/util/ExceptionUtils.java

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

app/common/src/main/java/stirling/software/common/util/FormFieldTypeSupport.java

@@ -114,7 +114,7 @@ public enum FormFieldTypeSupport {
                     return;
                 }
 
-                PDAnnotationWidget widget = checkBox.getWidgets().get(0);
+                PDAnnotationWidget widget = checkBox.getWidgets().getFirst();
 
                 PDAppearanceCharacteristicsDictionary appearanceChars =
                         widget.getAppearanceCharacteristics();

app/common/src/main/java/stirling/software/common/util/FormUtils.java

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

app/common/src/main/java/stirling/software/common/util/ImageProcessingUtils.java

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

app/common/src/main/java/stirling/software/common/util/PDFToFile.java

@@ -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";
                     }

app/common/src/main/java/stirling/software/common/util/ProcessExecutor.java

@@ -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");
         }

app/common/src/main/java/stirling/software/common/util/RequestUriUtils.java

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

app/common/src/main/java/stirling/software/common/util/YamlHelper.java

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

app/common/src/test/java/stirling/software/common/util/PDFToFileTest.java

@@ -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;
                             });

app/common/src/test/java/stirling/software/common/util/RequestUriUtilsTest.java

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

app/core/build.gradle

@@ -175,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/.
@@ -297,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})"
     }
 }
 

app/core/src/main/java/stirling/software/SPDF/config/MultipartConfiguration.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/BookletImpositionController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/MergeController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java

@@ -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 -> "";
+            };
         }
     }
 }

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertSvgToPDF.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java

@@ -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);
             }

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoRenameController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoSplitPdfController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java

@@ -404,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);

app/core/src/main/java/stirling/software/SPDF/controller/api/security/GetInfoOnPDF.java

@@ -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());

app/core/src/main/java/stirling/software/SPDF/controller/api/security/RedactExecuteService.java

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

app/core/src/main/java/stirling/software/SPDF/controller/api/security/RemoveCertSignController.java

@@ -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()) {

app/core/src/main/java/stirling/software/SPDF/controller/web/UploadLimitService.java

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

app/core/src/main/java/stirling/software/SPDF/service/PdfJsonConversionService.java

@@ -2688,7 +2688,7 @@ public class PdfJsonConversionService {
 
                     // Find which page the field is on
                     PDAnnotationWidget widget =
-                            field.getWidgets().isEmpty() ? null : field.getWidgets().get(0);
+                            field.getWidgets().isEmpty() ? null : field.getWidgets().getFirst();
                     if (widget != null) {
                         PDPage fieldPage = widget.getPage();
                         if (fieldPage != null) {
@@ -3164,7 +3164,7 @@ public class PdfJsonConversionService {
                         && imageObjectNames != null
                         && !imageObjectNames.isEmpty()
                         && !targetTokens.isEmpty()) {
-                    Object previous = targetTokens.get(targetTokens.size() - 1);
+                    Object previous = targetTokens.getLast();
                     if (previous instanceof COSName cosName
                             && imageObjectNames.contains(cosName.getName())) {
                         targetTokens.remove(targetTokens.size() - 1);
@@ -5246,7 +5246,7 @@ public class PdfJsonConversionService {
                 throws IOException {
             if (OperatorName.DRAW_OBJECT.equals(operator.getName())
                     && !operands.isEmpty()
-                    && operands.get(0) instanceof COSName name) {
+                    && operands.getFirst() instanceof COSName name) {
                 currentXObjectName = name;
             }
             super.processOperator(operator, operands);

app/core/src/main/java/stirling/software/SPDF/service/pdfjson/PdfJsonImageService.java

@@ -420,7 +420,7 @@ public class PdfJsonImageService {
                 throws IOException {
             if (OperatorName.DRAW_OBJECT.equals(operator.getName())
                     && !operands.isEmpty()
-                    && operands.get(0) instanceof COSName name) {
+                    && operands.getFirst() instanceof COSName name) {
                 currentXObjectName = name;
             }
             super.processOperator(operator, operands);

app/core/src/main/java/stirling/software/common/controller/JobController.java

@@ -137,7 +137,7 @@ public class JobController {
         if (result.hasFiles() && !result.hasMultipleFiles()) {
             try {
                 List<ResultFile> files = result.getAllResultFiles();
-                ResultFile singleFile = files.get(0);
+                ResultFile singleFile = files.getFirst();
 
                 byte[] fileContent = fileStorage.retrieveBytes(singleFile.getFileId());
                 return ResponseEntity.ok()

app/core/src/test/java/stirling/software/SPDF/config/MultipartConfigurationTest.java

@@ -4,8 +4,6 @@ import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
-import java.lang.reflect.Field;
-
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
@@ -24,10 +22,7 @@ class MultipartConfigurationTest {
     void setUp() throws Exception {
         // Manually constructed config with a mocked service, so Spring env overrides do not apply.
         uploadLimitService = mock(UploadLimitService.class);
-        configuration = new MultipartConfiguration();
-        Field field = MultipartConfiguration.class.getDeclaredField("uploadLimitService");
-        field.setAccessible(true);
-        field.set(configuration, uploadLimitService);
+        configuration = new MultipartConfiguration(uploadLimitService);
     }
 
     @Nested

app/core/src/test/java/stirling/software/SPDF/controller/api/MergeControllerGapTest.java

@@ -84,12 +84,6 @@ class MergeControllerGapTest {
         return (MultipartFile[]) m.invoke(null, files, fileOrder);
     }
 
-    private String[] parseClientFileIds(String value) throws Exception {
-        Method m = MergeController.class.getDeclaredMethod("parseClientFileIds", String.class);
-        m.setAccessible(true);
-        return (String[]) m.invoke(mergeController, value);
-    }
-
     private long getPdfDateTimeSafe(MultipartFile file) throws Exception {
         Method m =
                 MergeController.class.getDeclaredMethod("getPdfDateTimeSafe", MultipartFile.class);
@@ -331,58 +325,6 @@ class MergeControllerGapTest {
         }
     }
 
-    // ---- parseClientFileIds -------------------------------------------------
-
-    @Nested
-    @DisplayName("parseClientFileIds")
-    class ParseClientFileIds {
-
-        @Test
-        @DisplayName("null input returns empty array")
-        void nullReturnsEmpty() throws Exception {
-            assertEquals(0, parseClientFileIds(null).length);
-        }
-
-        @Test
-        @DisplayName("blank input returns empty array")
-        void blankReturnsEmpty() throws Exception {
-            assertEquals(0, parseClientFileIds("   ").length);
-        }
-
-        @Test
-        @DisplayName("empty JSON array returns empty array")
-        void emptyArrayReturnsEmpty() throws Exception {
-            assertEquals(0, parseClientFileIds("[]").length);
-            assertEquals(0, parseClientFileIds("[   ]").length);
-        }
-
-        @Test
-        @DisplayName("non-array text returns empty array")
-        void nonArrayReturnsEmpty() throws Exception {
-            assertEquals(0, parseClientFileIds("not-an-array").length);
-        }
-
-        @Test
-        @DisplayName("parses quoted, comma-separated ids and strips surrounding quotes")
-        void parsesQuotedIds() throws Exception {
-            String[] result = parseClientFileIds("[\"id1\", \"id2\",\"id3\"]");
-            assertArrayEquals(new String[] {"id1", "id2", "id3"}, result);
-        }
-
-        @Test
-        @DisplayName("parses unquoted ids as-is after trimming")
-        void parsesUnquotedIds() throws Exception {
-            String[] result = parseClientFileIds("[a, b , c]");
-            assertArrayEquals(new String[] {"a", "b", "c"}, result);
-        }
-
-        @Test
-        @DisplayName("single element array yields a one-element result")
-        void singleElement() throws Exception {
-            assertArrayEquals(new String[] {"only"}, parseClientFileIds("[\"only\"]"));
-        }
-    }
-
     // ---- reorderFilesByProvidedOrder ----------------------------------------
 
     @Nested

app/core/src/test/java/stirling/software/SPDF/controller/api/UIDataControllerTest.java

@@ -0,0 +1,66 @@
+package stirling.software.SPDF.controller.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.core.io.DefaultResourceLoader;
+import org.springframework.http.ResponseEntity;
+
+import stirling.software.SPDF.service.SharedSignatureService;
+import stirling.software.common.configuration.RuntimePathConfig;
+import stirling.software.common.model.ApplicationProperties;
+
+import tools.jackson.databind.ObjectMapper;
+
+class UIDataControllerTest {
+
+    @TempDir Path tempDir;
+
+    @Test
+    void getPipelineData_usesEachSourceFilenameWhenJsonContentIsIdentical() throws Exception {
+        Path configDir = tempDir.resolve("defaultWebUIConfigs");
+        Files.createDirectories(configDir);
+
+        String configJson = "{\"steps\":[]}";
+        Files.writeString(configDir.resolve("first-config.json"), configJson);
+        Files.writeString(configDir.resolve("second-config.json"), configJson);
+
+        ApplicationProperties applicationProperties = mock(ApplicationProperties.class);
+        SharedSignatureService signatureService = mock(SharedSignatureService.class);
+        RuntimePathConfig runtimePathConfig = mock(RuntimePathConfig.class);
+
+        when(runtimePathConfig.getPipelineDefaultWebUiConfigs()).thenReturn(configDir.toString());
+
+        UIDataController controller =
+                new UIDataController(
+                        applicationProperties,
+                        signatureService,
+                        null,
+                        new DefaultResourceLoader(),
+                        runtimePathConfig,
+                        new ObjectMapper());
+
+        ResponseEntity<UIDataController.PipelineData> response = controller.getPipelineData();
+
+        assertThat(response.getStatusCode().is2xxSuccessful()).isTrue();
+        UIDataController.PipelineData body = response.getBody();
+        assertThat(body).isNotNull();
+
+        List<Map<String, String>> configsWithNames = body.getPipelineConfigsWithNames();
+        assertThat(configsWithNames).hasSize(2);
+        assertThat(configsWithNames)
+                .extracting(entry -> entry.get("name"))
+                .containsExactlyInAnyOrder("first-config", "second-config");
+        assertThat(configsWithNames)
+                .extracting(entry -> entry.get("json"))
+                .containsOnly(configJson);
+    }
+}

app/core/src/test/java/stirling/software/SPDF/controller/api/converters/ConvertOfficeControllerTest.java

@@ -204,7 +204,7 @@ class ConvertOfficeControllerTest {
                                 inv -> {
                                     // unoconvert writes directly to the output path (last arg)
                                     List<String> command = inv.getArgument(0);
-                                    Path out = Path.of(command.get(command.size() - 1));
+                                    Path out = Path.of(command.getLast());
                                     Files.writeString(out, "%PDF-1.4 produced");
                                     return result;
                                 });
@@ -239,7 +239,7 @@ class ConvertOfficeControllerTest {
                                 inv -> {
                                     // soffice writes <basename>.pdf into the --outdir (workDir)
                                     List<String> command = inv.getArgument(0);
-                                    Path inputPath = Path.of(command.get(command.size() - 1));
+                                    Path inputPath = Path.of(command.getLast());
                                     Path out = inputPath.getParent().resolve("report.pdf");
                                     Files.writeString(out, "%PDF soffice");
                                     return result;
@@ -311,7 +311,7 @@ class ConvertOfficeControllerTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> command = inv.getArgument(0);
-                                    Path inputPath = Path.of(command.get(command.size() - 1));
+                                    Path inputPath = Path.of(command.getLast());
                                     Path out = inputPath.getParent().resolve("report.pdf");
                                     Files.write(out, new byte[0]);
                                     return result;
@@ -344,7 +344,7 @@ class ConvertOfficeControllerTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> command = inv.getArgument(0);
-                                    Path inputPath = Path.of(command.get(command.size() - 1));
+                                    Path inputPath = Path.of(command.getLast());
                                     Path out = inputPath.getParent().resolve("page.pdf");
                                     Files.writeString(out, "%PDF html");
                                     return result;
@@ -398,7 +398,7 @@ class ConvertOfficeControllerTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> command = inv.getArgument(0);
-                                    Path inputPath = Path.of(command.get(command.size() - 1));
+                                    Path inputPath = Path.of(command.getLast());
                                     Path out = inputPath.getParent().resolve("report.pdf");
                                     Files.writeString(out, "%PDF produced");
                                     return result;

app/core/src/test/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFAMoreTest.java

@@ -197,7 +197,7 @@ class ConvertPDFToPDFAMoreTest {
                             // qpdf normalize/clean writes its (last-arg) output file
                             if (command.contains("--normalize-content=y")) {
                                 // qpdf produced file is the last argument
-                                Path out = Path.of(command.get(command.size() - 1));
+                                Path out = Path.of(command.getLast());
                                 Files.write(out, simplePdfBytes());
                             }
                             return okResult;

app/core/src/test/java/stirling/software/SPDF/controller/api/converters/ConvertPdfToVideoControllerTest.java

@@ -262,7 +262,7 @@ class ConvertPdfToVideoControllerTest {
             assertTrue(command.contains("+faststart"));
             assertFalse(command.contains("libvpx-vp9"));
             // Output path is always the last argument.
-            assertEquals(backing.getAbsolutePath(), command.get(command.size() - 1));
+            assertEquals(backing.getAbsolutePath(), command.getLast());
         }
 
         @Test
@@ -278,7 +278,7 @@ class ConvertPdfToVideoControllerTest {
             assertTrue(command.contains("30"));
             assertFalse(command.contains("libx264"));
             assertFalse(command.contains("+faststart"));
-            assertEquals(backing.getAbsolutePath(), command.get(command.size() - 1));
+            assertEquals(backing.getAbsolutePath(), command.getLast());
         }
 
         @Test

app/core/src/test/java/stirling/software/SPDF/controller/api/misc/CompressControllerMoreTest.java

@@ -195,7 +195,7 @@ class CompressControllerMoreTest {
 
     // The qpdf output path is the last argument of the command.
     private static Path qpdfOutputPath(List<String> command) {
-        return Path.of(command.get(command.size() - 1));
+        return Path.of(command.getLast());
     }
 
     /** Stub gs to write a valid PDF to its output file and report success. */

app/core/src/test/java/stirling/software/SPDF/controller/api/misc/RemoveImagesControllerTest.java

@@ -162,7 +162,7 @@ class RemoveImagesControllerTest {
     /** Counts every PDImageXObject reachable through page + nested form resources. */
     private int countImagesInSavedOutput() throws IOException {
         assertFalse(savedTempFiles.isEmpty(), "expected the controller to create a temp file");
-        File out = savedTempFiles.get(savedTempFiles.size() - 1);
+        File out = savedTempFiles.getLast();
         try (PDDocument doc = Loader.loadPDF(out)) {
             int count = 0;
             for (PDPage page : doc.getPages()) {
@@ -245,7 +245,7 @@ class RemoveImagesControllerTest {
 
             assertEquals(0, countImagesInSavedOutput());
             // page count must be preserved
-            File out = savedTempFiles.get(savedTempFiles.size() - 1);
+            File out = savedTempFiles.getLast();
             try (PDDocument result = Loader.loadPDF(out)) {
                 assertEquals(3, result.getNumberOfPages());
             }

app/core/src/test/java/stirling/software/SPDF/controller/api/misc/RepairControllerMoreTest.java

@@ -98,12 +98,8 @@ class RepairControllerMoreTest {
         }
     }
 
-    /**
-     * Writes a valid PDF to the path at the given command index, mimicking a successful tool run.
-     */
-    private static void writeValidPdfTo(List<String> command, int outputPathIndex)
-            throws Exception {
-        Path out = Path.of(command.get(outputPathIndex));
+    /** Writes a valid PDF to the given output path, mimicking a successful tool run. */
+    private static void writeValidPdfTo(Path out) throws Exception {
         byte[] pdf = buildPdfBytes(1);
         Files.write(out, pdf);
     }
@@ -133,7 +129,7 @@ class RepairControllerMoreTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> cmd = inv.getArgument(0);
-                                    writeValidPdfTo(cmd, 2);
+                                    writeValidPdfTo(Path.of(cmd.get(2)));
                                     return okResult;
                                 });
 
@@ -176,7 +172,7 @@ class RepairControllerMoreTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> cmd = inv.getArgument(0);
-                                    writeValidPdfTo(cmd, cmd.size() - 1);
+                                    writeValidPdfTo(Path.of(cmd.getLast()));
                                     return okResult;
                                 });
 
@@ -216,7 +212,7 @@ class RepairControllerMoreTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> cmd = inv.getArgument(0);
-                                    writeValidPdfTo(cmd, cmd.size() - 1);
+                                    writeValidPdfTo(Path.of(cmd.getLast()));
                                     return okResult;
                                 });
 
@@ -256,7 +252,7 @@ class RepairControllerMoreTest {
                         .thenAnswer(
                                 inv -> {
                                     List<String> cmd = inv.getArgument(0);
-                                    writeValidPdfTo(cmd, cmd.size() - 1);
+                                    writeValidPdfTo(Path.of(cmd.getLast()));
                                     return okResult;
                                 });
 

app/core/src/test/java/stirling/software/SPDF/controller/web/UploadLimitServiceTest.java

@@ -49,15 +49,7 @@ class UploadLimitServiceTest {
         systemProps = mock(ApplicationProperties.System.class);
         when(applicationProperties.getSystem()).thenReturn(systemProps);
 
-        uploadLimitService = new UploadLimitService();
-        // inject mock
-        try {
-            var field = UploadLimitService.class.getDeclaredField("applicationProperties");
-            field.setAccessible(true);
-            field.set(uploadLimitService, applicationProperties);
-        } catch (ReflectiveOperationException e) {
-            throw new RuntimeException(e);
-        }
+        uploadLimitService = new UploadLimitService(applicationProperties);
     }
 
     @ParameterizedTest(name = "getReadableUploadLimit case #{index}: rawValue={0}, expected={1}")

app/proprietary/src/main/java/stirling/software/proprietary/access/config/AccessConfig.java

@@ -4,7 +4,9 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
+import stirling.software.proprietary.access.service.DefaultPrincipalResolver;
 import stirling.software.proprietary.access.service.DefaultTeamLeadLookup;
+import stirling.software.proprietary.access.service.PrincipalResolver;
 import stirling.software.proprietary.access.service.TeamLeadLookup;
 
 /** Access-layer bean wiring. */
@@ -17,4 +19,11 @@ public class AccessConfig {
     TeamLeadLookup defaultTeamLeadLookup() {
         return new DefaultTeamLeadLookup();
     }
+
+    /** USER/TEAM projection unless another bean is defined (e.g. the saas resolver). */
+    @Bean
+    @ConditionalOnMissingBean(PrincipalResolver.class)
+    PrincipalResolver defaultPrincipalResolver() {
+        return new DefaultPrincipalResolver();
+    }
 }

app/proprietary/src/main/java/stirling/software/proprietary/access/controller/ResourceGrantController.java

@@ -25,7 +25,9 @@ import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
 import stirling.software.proprietary.access.service.ResourceAccessService;
+import stirling.software.proprietary.security.database.repository.UserRepository;
 import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamRepository;
 
 /** Admin endpoints to grant/revoke access to gated resources (the portal, integration configs). */
 @RestController
@@ -36,6 +38,8 @@ import stirling.software.proprietary.security.model.User;
 public class ResourceGrantController {
 
     private final ResourceAccessService accessService;
+    private final UserRepository userRepository;
+    private final TeamRepository teamRepository;
 
     @GetMapping("/grants")
     public ResponseEntity<?> list(
@@ -45,6 +49,14 @@ public class ResourceGrantController {
         return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
     }
 
+    @GetMapping("/grants/by-principal")
+    public ResponseEntity<?> listByPrincipal(
+            @RequestParam PrincipalType principalType, @RequestParam Long principalId) {
+        List<ResourceGrant> grants =
+                accessService.listGrantsForPrincipal(principalType, principalId);
+        return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
+    }
+
     @PostMapping("/grants")
     public ResponseEntity<?> create(
             @RequestBody GrantRequest request, @AuthenticationPrincipal User admin) {
@@ -57,17 +69,26 @@ public class ResourceGrantController {
                                     "error",
                                     "resourceType, principalType and principalId are required"));
         }
+        // PORTAL is a singleton (empty resourceId); every other type must name a resource.
+        boolean portal = request.resourceType() == ResourceType.PORTAL;
+        if (!portal && (request.resourceId() == null || request.resourceId().isBlank())) {
+            return ResponseEntity.badRequest()
+                    .body(Map.of("error", "resourceId is required for " + request.resourceType()));
+        }
+        Long principalId = request.principalId();
+        String principalError = validatePrincipalExists(request.principalType(), principalId);
+        if (principalError != null) {
+            return ResponseEntity.badRequest().body(Map.of("error", principalError));
+        }
         AccessPermission permission =
                 request.permission() == null ? AccessPermission.USE : request.permission();
-        // PORTAL is a singleton resource; its grants always target the whole type.
-        String resourceId =
-                request.resourceType() == ResourceType.PORTAL ? "" : request.resourceId();
+        String resourceId = portal ? "" : request.resourceId();
         ResourceGrant grant =
                 accessService.grant(
                         request.resourceType(),
                         resourceId,
                         request.principalType(),
-                        request.principalId(),
+                        principalId,
                         permission,
                         admin);
         return ResponseEntity.ok(toDto(grant));
@@ -79,6 +100,14 @@ public class ResourceGrantController {
         return ResponseEntity.ok(Map.of("message", "Grant revoked"));
     }
 
+    // Rejects grants to nonexistent principals (dead rows otherwise).
+    private String validatePrincipalExists(PrincipalType type, Long id) {
+        return switch (type) {
+            case USER -> userRepository.existsById(id) ? null : "User " + id + " does not exist";
+            case TEAM -> teamRepository.existsById(id) ? null : "Team " + id + " does not exist";
+        };
+    }
+
     private Map<String, Object> toDto(ResourceGrant g) {
         Map<String, Object> m = new HashMap<>();
         m.put("id", g.getId());

app/proprietary/src/main/java/stirling/software/proprietary/access/model/OwnedResource.java

@@ -54,4 +54,15 @@ public abstract class OwnedResource {
     public Long getOwnerTeamId() {
         return ownerTeam != null ? ownerTeam.getId() : null;
     }
+
+    /** Owner as a principal ref; null when server-owned (admin-only ownership). */
+    public PrincipalRef getOwnerRef() {
+        if (getOwnerUserId() != null) {
+            return PrincipalRef.user(getOwnerUserId());
+        }
+        if (getOwnerTeamId() != null) {
+            return PrincipalRef.team(getOwnerTeamId());
+        }
+        return null;
+    }
 }

app/proprietary/src/main/java/stirling/software/proprietary/access/model/PrincipalRef.java

@@ -0,0 +1,20 @@
+package stirling.software.proprietary.access.model;
+
+import java.util.Locale;
+
+/** A (type, id) principal pair; the atom grants and ownership are expressed in. */
+public record PrincipalRef(PrincipalType type, Long id) {
+
+    public static PrincipalRef user(Long id) {
+        return new PrincipalRef(PrincipalType.USER, id);
+    }
+
+    public static PrincipalRef team(Long id) {
+        return new PrincipalRef(PrincipalType.TEAM, id);
+    }
+
+    /** Canonical engine wire form, e.g. "user:12". */
+    public String token() {
+        return type.name().toLowerCase(Locale.ROOT) + ":" + id;
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/access/model/PrincipalType.java

@@ -1,6 +1,6 @@
 package stirling.software.proprietary.access.model;
 
-/** Who a {@link ResourceGrant} is granted to. Org-wide access is expressed via default policy. */
+/** Who a {@link ResourceGrant} is granted to. */
 public enum PrincipalType {
     USER,
     TEAM

app/proprietary/src/main/java/stirling/software/proprietary/access/repository/ResourceGrantRepository.java

@@ -3,11 +3,15 @@ package stirling.software.proprietary.access.repository;
 import java.util.List;
 
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
 import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.security.model.User;
 
 @Repository
 public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Long> {
@@ -18,8 +22,20 @@ public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Lo
     List<ResourceGrant> findByResourceTypeAndPrincipalTypeAndPrincipalId(
             ResourceType resourceType, PrincipalType principalType, Long principalId);
 
+    /** All grants held by a principal, across resource types (for the manage-access view). */
+    List<ResourceGrant> findByPrincipalTypeAndPrincipalId(
+            PrincipalType principalType, Long principalId);
+
     void deleteByResourceTypeAndResourceId(ResourceType resourceType, String resourceId);
 
+    /** Removes every grant held by a principal; used when the user/team behind it is deleted. */
+    void deleteByPrincipalTypeAndPrincipalId(PrincipalType principalType, Long principalId);
+
+    // Detach issued grants so deleting the granting user does not hit the FK.
+    @Modifying
+    @Query("update ResourceGrant g set g.grantedBy = null where g.grantedBy = :user")
+    void clearGrantedBy(@Param("user") User user);
+
     boolean existsByResourceTypeAndResourceIdAndPrincipalTypeAndPrincipalId(
             ResourceType resourceType,
             String resourceId,

app/proprietary/src/main/java/stirling/software/proprietary/access/security/ResourceAccessSecurity.java

@@ -11,7 +11,12 @@ import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.security.model.User;
 import stirling.software.proprietary.security.service.UserService;
 
-/** {@code @PreAuthorize} bean for portal-access checks. Active in self-hosted and saas. */
+/**
+ * {@code @PreAuthorize} bean for portal-access checks. Active in self-hosted and saas. Convention:
+ * every portal-exclusive endpoint is gated with
+ * {@code @PreAuthorize("@resourceAccess.canUsePortal()")}; endpoints shared with the editor (e.g.
+ * the policies API) must NOT be.
+ */
 @Component("resourceAccess")
 @RequiredArgsConstructor
 public class ResourceAccessSecurity {

app/proprietary/src/main/java/stirling/software/proprietary/access/service/DefaultPrincipalResolver.java

@@ -0,0 +1,32 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import stirling.software.proprietary.access.model.PrincipalRef;
+import stirling.software.proprietary.security.model.User;
+
+/**
+ * Self-hosted projection: the user and their team. One deployment = one org, so ORG_ALL is open.
+ */
+public class DefaultPrincipalResolver implements PrincipalResolver {
+
+    @Override
+    public Set<PrincipalRef> principalsOf(User user) {
+        if (user == null) {
+            return Set.of();
+        }
+        Set<PrincipalRef> principals = new HashSet<>();
+        principals.add(PrincipalRef.user(user.getId()));
+        if (user.getTeam() != null) {
+            principals.add(PrincipalRef.team(user.getTeam().getId()));
+        }
+        return principals;
+    }
+
+    // Self-hosted is a single deployment-wide org, so ORG_ALL admits every authenticated user.
+    @Override
+    public boolean allowsDeploymentWideAccess() {
+        return true;
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/access/service/MembershipTeamLeadLookup.java

@@ -0,0 +1,33 @@
+package stirling.software.proprietary.access.service;
+
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.enumeration.TeamRole;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamMembershipRepository;
+
+/** Real lookup backed by team_memberships LEADER rows; wins over the no-op default bean. */
+@Component
+@RequiredArgsConstructor
+public class MembershipTeamLeadLookup implements TeamLeadLookup {
+
+    private final TeamMembershipRepository memberships;
+
+    @Override
+    public boolean isAnyTeamLeader(User user) {
+        return user != null
+                && user.getId() != null
+                && memberships.existsByUserIdAndRole(user.getId(), TeamRole.LEADER);
+    }
+
+    @Override
+    public boolean isLeaderOfTeam(User user, Long teamId) {
+        return user != null
+                && user.getId() != null
+                && teamId != null
+                && memberships.existsByTeamIdAndUserIdAndRole(
+                        teamId, user.getId(), TeamRole.LEADER);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/access/service/OwnershipService.java

@@ -36,15 +36,19 @@ public class OwnershipService {
         return accessService.canUseResource(
                 type,
                 String.valueOf(resource.getId()),
-                resource.getOwnerUserId(),
+                resource.getOwnerRef(),
                 resource.getDefaultAccess(),
                 user);
     }
 
     /** Whether the user may manage the resource. */
     public boolean canManage(ResourceType type, OwnedResource resource, User user) {
+        // Disabled resources bypass grants for MANAGE too: admin/owner only.
+        if (!resource.isEnabled()) {
+            return isAdmin(user) || isOwner(resource, user);
+        }
         return accessService.canManageResource(
-                type, String.valueOf(resource.getId()), resource.getOwnerUserId(), user);
+                type, String.valueOf(resource.getId()), resource.getOwnerRef(), user);
     }
 
     /**

app/proprietary/src/main/java/stirling/software/proprietary/access/service/PrincipalResolver.java

@@ -0,0 +1,28 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import stirling.software.proprietary.access.model.PrincipalRef;
+import stirling.software.proprietary.security.model.User;
+
+/** Projects a user onto the set of principals they act as. */
+public interface PrincipalResolver {
+
+    /** Every principal the user acts as; empty for a null user. */
+    Set<PrincipalRef> principalsOf(User user);
+
+    /**
+     * Whether this deployment treats every authenticated user as one org, so the {@code ORG_ALL}
+     * default policy admits anyone. Self-hosted: true. Multi-tenant saas: false, so an {@code
+     * ORG_ALL} resource can't leak across tenants. Defaults to false (deny) for safety.
+     */
+    default boolean allowsDeploymentWideAccess() {
+        return false;
+    }
+
+    /** Canonical wire tokens for the engine, e.g. "user:12". */
+    default Set<String> principalTokens(User user) {
+        return principalsOf(user).stream().map(PrincipalRef::token).collect(Collectors.toSet());
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/access/service/ResourceAccessService.java

@@ -14,6 +14,7 @@ import lombok.extern.slf4j.Slf4j;
 import stirling.software.common.model.enumeration.Role;
 import stirling.software.proprietary.access.model.AccessPermission;
 import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.PrincipalRef;
 import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
@@ -29,6 +30,7 @@ public class ResourceAccessService {
 
     private final ResourceGrantRepository grantRepository;
     private final TeamLeadLookup teamLeadLookup;
+    private final PrincipalResolver principalResolver;
 
     @Value("${security.portal.defaultAccess:ADMINS_AND_TEAM_LEADS}")
     private DefaultAccessPolicy portalDefaultPolicy;
@@ -44,28 +46,28 @@ public class ResourceAccessService {
     public boolean canUseResource(
             ResourceType type,
             String resourceId,
-            Long ownerUserId,
+            PrincipalRef owner,
             DefaultAccessPolicy defaultPolicy,
             User user) {
         if (user == null) {
             return false;
         }
-        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+        if (isOwner(owner, user) || isAdmin(user)) {
             return true;
         }
         if (hasGrant(type, normalize(resourceId), user, AccessPermission.USE)) {
             return true;
         }
-        return matchesDefault(defaultPolicy, user);
+        return matchesDefault(defaultPolicy, owner, user);
     }
 
     /** Whether the user may manage (edit/delete/share) a resource. No default-policy fallback. */
     public boolean canManageResource(
-            ResourceType type, String resourceId, Long ownerUserId, User user) {
+            ResourceType type, String resourceId, PrincipalRef owner, User user) {
         if (user == null) {
             return false;
         }
-        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+        if (isOwner(owner, user) || isAdmin(user)) {
             return true;
         }
         return hasGrant(type, normalize(resourceId), user, AccessPermission.MANAGE);
@@ -110,21 +112,22 @@ public class ResourceAccessService {
         return grantRepository.findByResourceTypeAndResourceId(type, normalize(resourceId));
     }
 
-    /** Resource ids of the given type that this user (or their team) holds any grant on. */
+    /** Every grant a principal holds, for the per-user/per-team manage-access view. */
+    public List<ResourceGrant> listGrantsForPrincipal(
+            PrincipalType principalType, Long principalId) {
+        return grantRepository.findByPrincipalTypeAndPrincipalId(principalType, principalId);
+    }
+
+    /** Resource ids of the given type that any of the user's principals holds a grant on. */
     public Set<String> grantedResourceIds(ResourceType type, User user) {
         if (user == null) {
             return Set.of();
         }
         Set<String> ids = new HashSet<>();
-        for (ResourceGrant g :
-                grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
-                        type, PrincipalType.USER, user.getId())) {
-            ids.add(g.getResourceId());
-        }
-        if (user.getTeam() != null) {
+        for (PrincipalRef principal : principalResolver.principalsOf(user)) {
             for (ResourceGrant g :
                     grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
-                            type, PrincipalType.TEAM, user.getTeam().getId())) {
+                            type, principal.type(), principal.id())) {
                 ids.add(g.getResourceId());
             }
         }
@@ -135,18 +138,12 @@ public class ResourceAccessService {
 
     private boolean hasGrant(
             ResourceType type, String resourceId, User user, AccessPermission required) {
-        Long teamId = user.getTeam() != null ? user.getTeam().getId() : null;
+        Set<PrincipalRef> principals = principalResolver.principalsOf(user);
         for (ResourceGrant g : grantRepository.findByResourceTypeAndResourceId(type, resourceId)) {
             if (!permissionSatisfies(g.getPermission(), required)) {
                 continue;
             }
-            if (g.getPrincipalType() == PrincipalType.USER
-                    && g.getPrincipalId().equals(user.getId())) {
-                return true;
-            }
-            if (g.getPrincipalType() == PrincipalType.TEAM
-                    && teamId != null
-                    && g.getPrincipalId().equals(teamId)) {
+            if (principals.contains(new PrincipalRef(g.getPrincipalType(), g.getPrincipalId()))) {
                 return true;
             }
         }
@@ -161,20 +158,40 @@ public class ResourceAccessService {
         return held == AccessPermission.MANAGE;
     }
 
-    private boolean matchesDefault(DefaultAccessPolicy policy, User user) {
+    private boolean matchesDefault(DefaultAccessPolicy policy, PrincipalRef owner, User user) {
         if (policy == null) {
             return false;
         }
         return switch (policy) {
-            case ORG_ALL -> true;
-            // Admins already pass above; only team leads here.
-            case ADMINS_AND_TEAM_LEADS -> teamLeadLookup.isAnyTeamLeader(user);
+            // Deployment-wide only where the resolver treats everyone as one org; saas resolvers
+            // return false, so ORG_ALL cannot leak a tenant's resource to another tenant's users.
+            case ORG_ALL -> principalResolver.allowsDeploymentWideAccess();
+            // Admins already pass above; only team leads here, scoped to the owning team.
+            case ADMINS_AND_TEAM_LEADS -> matchesTeamLeadDefault(owner, user);
             case EXPLICIT_ONLY -> false;
         };
     }
 
-    private boolean isOwner(Long ownerUserId, User user) {
-        return ownerUserId != null && ownerUserId.equals(user.getId());
+    // Portal (no owner) admits any team lead; a team-owned resource admits only that team's
+    // leads; a user-owned resource admits no extra leads.
+    private boolean matchesTeamLeadDefault(PrincipalRef owner, User user) {
+        if (owner == null) {
+            return teamLeadLookup.isAnyTeamLeader(user);
+        }
+        return owner.type() == PrincipalType.TEAM
+                && owner.id() != null
+                && teamLeadLookup.isLeaderOfTeam(user, owner.id());
+    }
+
+    // Team owners are the owning team's leaders; plain members are not.
+    private boolean isOwner(PrincipalRef owner, User user) {
+        if (owner == null || owner.id() == null) {
+            return false;
+        }
+        return switch (owner.type()) {
+            case USER -> owner.id().equals(user.getId());
+            case TEAM -> teamLeadLookup.isLeaderOfTeam(user, owner.id());
+        };
     }
 
     private boolean isAdmin(User user) {

app/proprietary/src/main/java/stirling/software/proprietary/access/service/SecretMasker.java

@@ -18,15 +18,26 @@ public class SecretMasker {
     // Cap recursion so a pathologically nested payload cannot overflow the stack.
     private static final int MAX_DEPTH = 32;
 
+    // Key-name substrings that mark a value sensitive. Over-masking a non-secret is
+    // safe; leaking a secret is not, so this errs broad - but a per-type schema
+    // whitelist would be a stronger boundary for free-form config (follow-up).
     private static final Set<String> SENSITIVE_HINTS =
             Set.of(
                     "secret",
                     "password",
+                    "passphrase",
+                    "pwd",
                     "token",
                     "apikey",
                     "accesskey",
                     "credential",
-                    "privatekey");
+                    "privatekey",
+                    "authorization",
+                    "cookie",
+                    "session",
+                    "connectionstring",
+                    "bearer",
+                    "signature");
 
     /** Replace sensitive values with the mask (recursively) for safe display. */
     public Map<String, Object> mask(Map<String, Object> config) {
@@ -73,18 +84,24 @@ public class SecretMasker {
 
     private Map<String, Object> merge(
             Map<String, Object> stored, Map<String, Object> incoming, int depth) {
-        Map<String, Object> out = new LinkedHashMap<>(stored);
+        // Replace semantics (PUT): the result is the incoming document, except a redacted secret
+        // keeps its stored value. Keys absent from incoming are dropped, so edits can remove them.
+        Map<String, Object> out = new LinkedHashMap<>();
         for (Map.Entry<String, Object> e : incoming.entrySet()) {
             String key = e.getKey();
             Object value = e.getValue();
             if (isSensitive(key)) {
-                if (!isRedacted(value, depth)) {
+                if (isRedacted(value, depth)) {
+                    if (stored.containsKey(key)) {
+                        out.put(key, stored.get(key)); // keep the stored secret
+                    }
+                } else {
                     out.put(key, value); // a real new secret replaces the stored one
                 }
-                continue; // redacted (blank / mask) -> keep stored
+                continue;
             }
             if (depth < MAX_DEPTH
-                    && out.get(key) instanceof Map<?, ?> s
+                    && stored.get(key) instanceof Map<?, ?> s
                     && value instanceof Map<?, ?> i) {
                 out.put(key, merge(castMap(s), castMap(i), depth + 1));
             } else {

app/proprietary/src/main/java/stirling/software/proprietary/audit/ControllerAuditAspect.java

@@ -130,6 +130,7 @@ public class ControllerAuditAspect {
 
         String previousPrincipal = MDC.get("auditPrincipal");
         String previousOrigin = MDC.get("auditOrigin");
+        String previousSource = MDC.get("auditSource");
         String previousIp = MDC.get("auditIp");
 
         // EARLY CAPTURE: Capture from SecurityContext on request thread, store in MDC for async
@@ -161,6 +162,14 @@ public class ControllerAuditAspect {
                 return joinPoint.proceed();
             }
 
+            // Stamp the free-UI source only for non-@Audited controller traffic — an actual
+            // tool / UI action. @Audited events (login, settings) return above without a source,
+            // so they never count as an "active editor" or a free UI run. The finally block
+            // restores auditSource, so a pooled thread can't leak a stale "WEB" into them.
+            if (previousSource == null) {
+                MDC.put("auditSource", auditService.captureCurrentSource());
+            }
+
             long start = System.currentTimeMillis();
 
             // Use auditService to create the base audit data
@@ -247,6 +256,7 @@ public class ControllerAuditAspect {
         } finally {
             restoreMdcValue("auditPrincipal", previousPrincipal);
             restoreMdcValue("auditOrigin", previousOrigin);
+            restoreMdcValue("auditSource", previousSource);
             restoreMdcValue("auditIp", previousIp);
         }
     }

app/proprietary/src/main/java/stirling/software/proprietary/audit/DefaultPortalAuditScopeResolver.java

@@ -0,0 +1,15 @@
+package stirling.software.proprietary.audit;
+
+import org.springframework.stereotype.Component;
+
+/** Self-hosted default: admins see the whole-server audit log, everyone else is denied. */
+@Component
+public class DefaultPortalAuditScopeResolver implements PortalAuditScopeResolver {
+
+    @Override
+    public PortalAuditScope resolve() {
+        return PortalAuditScopeResolver.hasAdminAuthority()
+                ? PortalAuditScope.server()
+                : PortalAuditScope.denied();
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/audit/PortalAuditEventRow.java

@@ -0,0 +1,7 @@
+package stirling.software.proprietary.audit;
+
+import java.time.Instant;
+
+/** Immutable, cacheable projection of an {@code audit_events} row, shared across portal views. */
+public record PortalAuditEventRow(
+        long id, String principal, String type, String data, Instant timestamp) {}

app/proprietary/src/main/java/stirling/software/proprietary/audit/PortalAuditScope.java

@@ -0,0 +1,21 @@
+package stirling.software.proprietary.audit;
+
+import java.util.List;
+
+/** Resolved audit visibility: fullServer (admin), principals-scoped (team lead), or !allowed. */
+public record PortalAuditScope(
+        boolean allowed, boolean fullServer, List<String> principals, String cacheKey) {
+
+    public static PortalAuditScope denied() {
+        return new PortalAuditScope(false, false, List.of(), "denied");
+    }
+
+    // Named server()/team() to avoid colliding with the record's fullServer() accessor.
+    public static PortalAuditScope server() {
+        return new PortalAuditScope(true, true, List.of(), "server");
+    }
+
+    public static PortalAuditScope team(String cacheKey, List<String> principals) {
+        return new PortalAuditScope(true, false, List.copyOf(principals), cacheKey);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/audit/PortalAuditScopeResolver.java

@@ -0,0 +1,18 @@
+package stirling.software.proprietary.audit;
+
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+/** Resolves which slice of the audit log the caller may see. */
+public interface PortalAuditScopeResolver {
+
+    PortalAuditScope resolve();
+
+    /** True when the current authentication carries {@code ROLE_ADMIN}. */
+    static boolean hasAdminAuthority() {
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        return auth != null
+                && auth.getAuthorities().stream()
+                        .anyMatch(a -> "ROLE_ADMIN".equals(a.getAuthority()));
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/ClassificationLabelsController.java

@@ -0,0 +1,136 @@
+package stirling.software.proprietary.classification;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+import stirling.software.proprietary.classification.model.LabelsValidator;
+import stirling.software.proprietary.classification.store.ClassificationLabelStore;
+import stirling.software.proprietary.classification.store.TeamLabelsEntity;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+
+/**
+ * Read/write the team's classification label set — the flat vocabulary the document classifier runs
+ * against. Shared and team-scoped exactly like policies: every user reads their own team's labels,
+ * and only a user who may edit policies (a team leader on SaaS, the global admin self-hosted; see
+ * {@link PolicyManagementAuthority}) may change it — gated only when login is enabled, since
+ * single-user deployments trust the local operator. A team with no stored labels reads as {@code
+ * 204}; that team has no vocabulary, so its documents are not classified (there is no built-in
+ * default on the backend or the engine — the label data lives only in the frontend).
+ */
+@RestController
+@RequestMapping("/api/v1/classification/labels")
+@Hidden
+@RequiredArgsConstructor
+@Tag(name = "Classification", description = "Team-scoped document-classification labels")
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class ClassificationLabelsController {
+
+    private final ClassificationLabelStore labelStore;
+    private final PolicyManagementAuthority policyManagementAuthority;
+    private final ApplicationProperties applicationProperties;
+    private final UserServiceInterface userService;
+
+    @GetMapping
+    @Operation(
+            summary = "Get the team's classification labels",
+            description =
+                    "Returns the caller's team label set, or 204 when the team has none (its"
+                            + " documents are then not classified).")
+    public ResponseEntity<ClassificationLabels> getTeamLabels() {
+        return labelStore
+                .findByTeam(currentTeamId())
+                .map(ResponseEntity::ok)
+                .orElseGet(() -> ResponseEntity.noContent().build());
+    }
+
+    @PutMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
+    @Operation(
+            summary = "Save the team's classification labels",
+            description =
+                    "Validates and stores the label set for the caller's team, shared by everyone"
+                            + " on the team. Requires the policy-editor role for the team.")
+    public ResponseEntity<ClassificationLabels> saveTeamLabels(
+            @RequestBody ClassificationLabels labels) {
+        requireEditingAllowed();
+        validate(labels);
+        ClassificationLabels saved = labelStore.save(currentTeamId(), labels, currentUsername());
+        return ResponseEntity.ok(saved);
+    }
+
+    @DeleteMapping
+    @Operation(
+            summary = "Reset the team's classification labels",
+            description =
+                    "Removes the team's stored label set; its documents are then not classified"
+                            + " until labels are saved again. Requires the policy-editor role for the"
+                            + " team.")
+    public ResponseEntity<Void> resetTeamLabels() {
+        requireEditingAllowed();
+        labelStore.deleteByTeam(currentTeamId());
+        return ResponseEntity.noContent().build();
+    }
+
+    private static void validate(ClassificationLabels labels) {
+        try {
+            LabelsValidator.validate(labels);
+        } catch (IllegalArgumentException e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+        }
+    }
+
+    /**
+     * Editing the team labels requires the editor role for the caller's team — the same gate
+     * policies use (team leader on SaaS, global admin self-hosted). Single-user deployments (login
+     * disabled) have no such role, so they trust the local operator.
+     */
+    private void requireEditingAllowed() {
+        if (!applicationProperties.getSecurity().isEnableLogin()) {
+            return;
+        }
+        if (!policyManagementAuthority.canEditPolicies()) {
+            throw new ResponseStatusException(
+                    HttpStatus.FORBIDDEN,
+                    "The team classification labels may only be changed by a team leader");
+        }
+    }
+
+    /**
+     * The caller's team key. With login disabled the single operator owns the {@link
+     * TeamLabelsEntity#NO_TEAM} sentinel row; with login enabled a caller with no resolvable team
+     * is an error rather than being dropped into the shared sentinel bucket (which would let
+     * unteamed users read and overwrite each other's "team" labels).
+     */
+    private Long currentTeamId() {
+        Long teamId = policyManagementAuthority.currentUserTeamId();
+        if (teamId != null) {
+            return teamId;
+        }
+        if (!applicationProperties.getSecurity().isEnableLogin()) {
+            return TeamLabelsEntity.NO_TEAM;
+        }
+        throw new ResponseStatusException(
+                HttpStatus.UNAUTHORIZED, "Could not resolve the current user's team");
+    }
+
+    private String currentUsername() {
+        return userService == null ? null : userService.getCurrentUsername();
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/model/ClassificationLabel.java

@@ -0,0 +1,9 @@
+package stirling.software.proprietary.classification.model;
+
+/**
+ * One entry in the classification vocabulary. {@code id} is the label's stable identity (a slug,
+ * unique within a set): it is what the engine returns and what is stored on the document. {@code
+ * name} is the human display text the classifier model reasons over. {@code icon} is an optional
+ * presentational key (a Material Symbols name shown in the file sidebar); the engine never sees it.
+ */
+public record ClassificationLabel(String id, String name, String icon) {}

app/proprietary/src/main/java/stirling/software/proprietary/classification/model/ClassificationLabels.java

@@ -0,0 +1,16 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * A flat multi-label classification vocabulary — the set of labels a document may be assigned.
+ * Stored per team (admin-edited, shared by everyone on the team); the classifier runs against these
+ * label names. A team with no stored set has no vocabulary, so its documents are not classified —
+ * neither the backend nor the engine holds a default of its own.
+ */
+public record ClassificationLabels(List<ClassificationLabel> labels) {
+
+    public ClassificationLabels {
+        labels = labels == null ? List.of() : List.copyOf(labels);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/model/LabelsValidator.java

@@ -0,0 +1,71 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.HashSet;
+import java.util.Locale;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Structural validation for a user- or admin-supplied label set, run before it is stored so a
+ * malformed vocabulary can never reach the classifier. Mirrors the invariants the engine relies on:
+ * non-blank ids and names, each unique within the set (ids exactly, names case-insensitively).
+ */
+public final class LabelsValidator {
+
+    private LabelsValidator() {}
+
+    // Generous upper bounds so a legitimate label set is never blocked, but a single team or user
+    // can't store an unbounded blob that would bloat the row, balloon the classifier prompt, or
+    // exhaust memory on deserialize.
+    static final int MAX_LABELS = 500;
+    static final int MAX_TEXT_LENGTH = 128;
+
+    // Icon is a Material Symbols key (lowercase, digits, hyphens). Enforce the SHAPE server-side —
+    // the exact allowlist lives in the frontend — so a client bypassing the UI can't store
+    // arbitrary
+    // text that would render as garbage (or worse) in every teammate's sidebar.
+    private static final Pattern ICON_KEY = Pattern.compile("^[a-z0-9-]+$");
+
+    /**
+     * @throws IllegalArgumentException with a human-readable message when the label set is invalid.
+     */
+    public static void validate(ClassificationLabels labels) {
+        if (labels == null || labels.labels() == null) {
+            throw new IllegalArgumentException("Labels are required");
+        }
+        if (labels.labels().size() > MAX_LABELS) {
+            throw new IllegalArgumentException("Too many labels (max " + MAX_LABELS + ")");
+        }
+        Set<String> ids = new HashSet<>();
+        Set<String> names = new HashSet<>();
+        for (ClassificationLabel label : labels.labels()) {
+            requireText(label.id(), "Label id");
+            requireText(label.name(), "Label name");
+            if (label.icon() != null && !label.icon().isEmpty()) {
+                if (label.icon().length() > MAX_TEXT_LENGTH) {
+                    throw new IllegalArgumentException(
+                            "Label icon is too long (max " + MAX_TEXT_LENGTH + " characters)");
+                }
+                if (!ICON_KEY.matcher(label.icon()).matches()) {
+                    throw new IllegalArgumentException("Invalid label icon: " + label.icon());
+                }
+            }
+            if (!ids.add(label.id().trim())) {
+                throw new IllegalArgumentException("Duplicate label id: " + label.id());
+            }
+            if (!names.add(label.name().trim().toLowerCase(Locale.ROOT))) {
+                throw new IllegalArgumentException("Duplicate label name: " + label.name());
+            }
+        }
+    }
+
+    private static void requireText(String value, String field) {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException(field + " must not be blank");
+        }
+        if (value.trim().length() > MAX_TEXT_LENGTH) {
+            throw new IllegalArgumentException(
+                    field + " is too long (max " + MAX_TEXT_LENGTH + " characters)");
+        }
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/ClassificationLabelStore.java

@@ -0,0 +1,22 @@
+package stirling.software.proprietary.classification.store;
+
+import java.util.Optional;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+/**
+ * Stores one {@link ClassificationLabels} set per team. A {@code null} teamId addresses the
+ * unteamed set (login disabled / no resolvable team), mirroring how the policy store treats a null
+ * team.
+ */
+public interface ClassificationLabelStore {
+
+    /** The team's stored labels, or empty when it has none (callers then skip classification). */
+    Optional<ClassificationLabels> findByTeam(Long teamId);
+
+    /** Create or replace the team's labels. Returns the stored value. */
+    ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy);
+
+    /** Remove the team's labels (reset to default). Returns whether a set existed. */
+    boolean deleteByTeam(Long teamId);
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/InProcessClassificationLabelStore.java

@@ -0,0 +1,36 @@
+package stirling.software.proprietary.classification.store;
+
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+/**
+ * In-memory {@link ClassificationLabelStore} for tests and any future no-database mode. {@link
+ * JpaClassificationLabelStore} is the runtime bean.
+ */
+public class InProcessClassificationLabelStore implements ClassificationLabelStore {
+
+    private final Map<Long, ClassificationLabels> byTeam = new ConcurrentHashMap<>();
+
+    @Override
+    public Optional<ClassificationLabels> findByTeam(Long teamId) {
+        return Optional.ofNullable(byTeam.get(key(teamId)));
+    }
+
+    @Override
+    public ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy) {
+        byTeam.put(key(teamId), labels);
+        return labels;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        return byTeam.remove(key(teamId)) != null;
+    }
+
+    private static long key(Long teamId) {
+        return teamId == null ? TeamLabelsEntity.NO_TEAM : teamId;
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/JpaClassificationLabelStore.java

@@ -0,0 +1,76 @@
+package stirling.software.proprietary.classification.store;
+
+import java.time.Instant;
+import java.util.Optional;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Durable {@link ClassificationLabelStore} backed by JPA; the runtime store. Gated on {@code
+ * policies.enabled} — stored labels only matter when the Classification policy can run — so it
+ * shares the policy subsystem's on/off switch. Each label set is persisted as JSON via {@link
+ * TeamLabelsEntity}.
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class JpaClassificationLabelStore implements ClassificationLabelStore {
+
+    private final TeamLabelsRepository teamRepository;
+    private final ObjectMapper objectMapper;
+
+    @Override
+    public Optional<ClassificationLabels> findByTeam(Long teamId) {
+        return teamRepository
+                .findById(key(teamId))
+                .flatMap(entity -> parse(entity.getLabelsJson(), "team " + teamId));
+    }
+
+    @Override
+    public ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy) {
+        TeamLabelsEntity entity = new TeamLabelsEntity();
+        entity.setTeamId(key(teamId));
+        entity.setLabelsJson(objectMapper.writeValueAsString(labels));
+        entity.setUpdatedAt(Instant.now());
+        entity.setUpdatedBy(updatedBy);
+        teamRepository.save(entity);
+        return labels;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        long id = key(teamId);
+        if (!teamRepository.existsById(id)) {
+            return false;
+        }
+        teamRepository.deleteById(id);
+        return true;
+    }
+
+    private Optional<ClassificationLabels> parse(String json, String owner) {
+        try {
+            return Optional.of(objectMapper.readValue(json, ClassificationLabels.class));
+        } catch (JacksonException e) {
+            // A stored label set that no longer parses (corruption / manual DB edit) must not break
+            // classification: drop it so the caller treats the team as having no labels (and skips
+            // classification) rather than surfacing a 500 on every upload.
+            log.warn("Discarding unparseable stored labels for {}: {}", owner, e.getMessage());
+            return Optional.empty();
+        }
+    }
+
+    /** Map the nullable team id onto the entity's non-null key (sentinel for the unteamed case). */
+    private static long key(Long teamId) {
+        return teamId == null ? TeamLabelsEntity.NO_TEAM : teamId;
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/TeamLabelsEntity.java

@@ -0,0 +1,47 @@
+package stirling.software.proprietary.classification.store;
+
+import java.io.Serializable;
+import java.time.Instant;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * JPA row for a team's classification labels — one row per team. The label set lives as JSON in
+ * {@code labelsJson} (authoritative on read). {@code teamId} is the natural key; the sentinel
+ * {@link #NO_TEAM} stands in for the unteamed (login-disabled / self-hosted single-team) case,
+ * since a primary key can't be null (policies store a nullable {@code team_id}, but this table is
+ * keyed one-per-team). Kept decoupled from the security entities — {@code teamId} is a plain value,
+ * not a foreign key — so classification can be enabled or disabled without touching them.
+ */
+@Entity
+@Table(name = "classification_labels")
+@NoArgsConstructor
+@Getter
+@Setter
+public class TeamLabelsEntity implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /** Sentinel key for the unteamed label set (login disabled / no resolvable team). */
+    public static final long NO_TEAM = 0L;
+
+    @Id
+    @Column(name = "team_id")
+    private long teamId;
+
+    @Column(name = "labels_json", columnDefinition = "text")
+    private String labelsJson;
+
+    @Column(name = "updated_at")
+    private Instant updatedAt;
+
+    @Column(name = "updated_by")
+    private String updatedBy;
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/TeamLabelsRepository.java

@@ -0,0 +1,7 @@
+package stirling.software.proprietary.classification.store;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public interface TeamLabelsRepository extends JpaRepository<TeamLabelsEntity, Long> {}

app/proprietary/src/main/java/stirling/software/proprietary/config/CustomAuditEventRepository.java

@@ -60,6 +60,8 @@ public class CustomAuditEventRepository implements AuditEventRepository {
                 clean.put("requestId", rid);
             }
 
+            String source = MDC.get("auditSource");
+
             String auditEventData = mapper.writeValueAsString(clean);
             log.debug("AuditEvent data (JSON): {}", auditEventData);
 
@@ -67,6 +69,7 @@ public class CustomAuditEventRepository implements AuditEventRepository {
                     PersistentAuditEvent.builder()
                             .principal(safePrincipal(ev.getPrincipal()))
                             .type(ev.getType())
+                            .source(source)
                             .data(auditEventData)
                             .timestamp(ev.getTimestamp())
                             .build();

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/AuditRestController.java

@@ -143,19 +143,12 @@ public class AuditRestController {
             @RequestParam(value = "period", defaultValue = "week") String period) {
 
         // Calculate days based on period
-        int days;
-        switch (period.toLowerCase()) {
-            case "day":
-                days = 1;
-                break;
-            case "month":
-                days = 30;
-                break;
-            case "week":
-            default:
-                days = 7;
-                break;
-        }
+        int days =
+                switch (period.toLowerCase()) {
+                    case "day" -> 1;
+                    case "month" -> 30;
+                    default -> 7;
+                };
 
         // Get events from the specified period
         Instant startDate = Instant.now().minus(java.time.Duration.ofDays(days));
@@ -269,19 +262,12 @@ public class AuditRestController {
             @RequestParam(value = "period", defaultValue = "week") String period) {
 
         // Calculate days based on period
-        int days;
-        switch (period.toLowerCase()) {
-            case "day":
-                days = 1;
-                break;
-            case "month":
-                days = 30;
-                break;
-            case "week":
-            default:
-                days = 7;
-                break;
-        }
+        int days =
+                switch (period.toLowerCase()) {
+                    case "day" -> 1;
+                    case "month" -> 30;
+                    default -> 7;
+                };
 
         // Get events from the specified period and previous period
         Instant now = Instant.now();
@@ -754,7 +740,7 @@ public class AuditRestController {
                 List<Map<String, Object>> files =
                         (List<Map<String, Object>>) eventData.get("files");
                 if (files != null && !files.isEmpty()) {
-                    Map<String, Object> firstFile = files.get(0);
+                    Map<String, Object> firstFile = files.getFirst();
                     data.put("documentname", String.valueOf(firstFile.getOrDefault("name", "")));
                     data.put("author", String.valueOf(firstFile.getOrDefault("pdfAuthor", "")));
                     data.put("filehash", String.valueOf(firstFile.getOrDefault("fileHash", "")));

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/ClassifyLabelController.java

@@ -0,0 +1,218 @@
+package stirling.software.proprietary.controller.api;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.Resource;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.github.pixee.security.Filenames;
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.PdfMetadataService;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.common.util.TempFileManager;
+import stirling.software.common.util.WebResponseUtils;
+import stirling.software.proprietary.classification.model.ClassificationLabel;
+import stirling.software.proprietary.classification.store.ClassificationLabelStore;
+import stirling.software.proprietary.model.api.ai.AiPageText;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+import stirling.software.proprietary.service.AiEngineClient;
+import stirling.software.proprietary.service.PdfContentExtractor;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.node.ObjectNode;
+
+/**
+ * Dispatchable tool that classifies a PDF and writes the result into its metadata.
+ *
+ * <p>Runs as a Classification-policy pipeline step: it reads a bounded page window, asks the AI
+ * engine to classify the document against the caller's team label set, and stores the engine's JSON
+ * answer — minus the transport-only {@code outcome} field — in the custom Info-dictionary key
+ * {@link PdfMetadataService#CLASSIFICATION_KEY}. Returns the labelled PDF. Not intended for direct
+ * client use.
+ */
+@Slf4j
+@Hidden
+@RestController
+@RequestMapping("/api/v1/ai/tools")
+@Tag(name = "AI Tools", description = "Dispatchable AI-backed tools.")
+public class ClassifyLabelController {
+
+    /** Pages read from each end of the document — mirrors the engine's window. */
+    private static final int WINDOW_PAGES = 2;
+
+    private static final String CLASSIFY_ENDPOINT = "/api/v1/documents/classify";
+
+    private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final TempFileManager tempFileManager;
+    private final PdfContentExtractor pdfContentExtractor;
+    private final PdfMetadataService pdfMetadataService;
+    private final AiEngineClient aiEngineClient;
+    private final ObjectMapper objectMapper;
+    private final UserServiceInterface userService;
+
+    /**
+     * Present only when the policy subsystem is enabled ({@code policies.enabled}); the store and
+     * team authority are gated on it. Null otherwise, in which case there are no team labels to
+     * classify against and the document is passed through unlabelled.
+     */
+    private final ClassificationLabelStore labelStore;
+
+    private final PolicyManagementAuthority policyManagementAuthority;
+
+    public ClassifyLabelController(
+            CustomPDFDocumentFactory pdfDocumentFactory,
+            TempFileManager tempFileManager,
+            PdfContentExtractor pdfContentExtractor,
+            PdfMetadataService pdfMetadataService,
+            AiEngineClient aiEngineClient,
+            ObjectMapper objectMapper,
+            @Autowired(required = false) UserServiceInterface userService,
+            @Autowired(required = false) ClassificationLabelStore labelStore,
+            @Autowired(required = false) PolicyManagementAuthority policyManagementAuthority) {
+        this.pdfDocumentFactory = pdfDocumentFactory;
+        this.tempFileManager = tempFileManager;
+        this.pdfContentExtractor = pdfContentExtractor;
+        this.pdfMetadataService = pdfMetadataService;
+        this.aiEngineClient = aiEngineClient;
+        this.objectMapper = objectMapper;
+        this.userService = userService;
+        this.labelStore = labelStore;
+        this.policyManagementAuthority = policyManagementAuthority;
+    }
+
+    @PostMapping(value = "/classify-and-label", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Classify a PDF and label its metadata",
+            description =
+                    "Reads the first two and last two pages, classifies the document via the AI"
+                            + " engine, and stores the result in the StirlingPDFClassification"
+                            + " metadata field. Dispatched by the Classification policy; not"
+                            + " intended for direct client use.")
+    public ResponseEntity<Resource> classifyAndLabel(
+            @RequestParam("fileInput") MultipartFile fileInput) throws IOException {
+        try (PDDocument document = pdfDocumentFactory.load(fileInput, true)) {
+            String fileName = safeFileName(fileInput.getOriginalFilename());
+
+            List<EngineLabel> allowed = resolveAllowedLabels();
+            if (allowed.isEmpty()) {
+                // No vocabulary to classify against (the team stored no labels): pass the file
+                // through unlabelled rather than ask the engine to classify against nothing.
+                log.debug("[classify-and-label] {} has no team labels; skipping", fileName);
+                return WebResponseUtils.pdfDocToWebResponse(document, fileName, tempFileManager);
+            }
+
+            List<AiPageText> pages = extractWindow(document);
+            String requestBody =
+                    objectMapper.writeValueAsString(
+                            new ClassifyEngineRequest(fileName, pages, allowed));
+
+            String userId = userService != null ? userService.getCurrentUsername() : null;
+            String responseJson = aiEngineClient.post(CLASSIFY_ENDPOINT, requestBody, userId);
+
+            pdfMetadataService.setClassificationMetadata(document, toMetadataValue(responseJson));
+            log.debug("[classify-and-label] labelled {} ({} window pages)", fileName, pages.size());
+
+            return WebResponseUtils.pdfDocToWebResponse(document, fileName, tempFileManager);
+        }
+    }
+
+    private List<AiPageText> extractWindow(PDDocument document) throws IOException {
+        List<AiPageText> pages = new ArrayList<>();
+        for (int pageNumber : windowPageNumbers(document.getNumberOfPages(), WINDOW_PAGES)) {
+            String text = pdfContentExtractor.extractPageTextRaw(document, pageNumber);
+            if (text != null && !text.isBlank()) {
+                pages.add(new AiPageText(pageNumber, text));
+            }
+        }
+        return pages;
+    }
+
+    /** First and last {@code window} page numbers (1-based), de-duplicated and in order. */
+    static List<Integer> windowPageNumbers(int pageCount, int window) {
+        Set<Integer> numbers = new LinkedHashSet<>();
+        for (int page = 1; page <= Math.min(window, pageCount); page++) {
+            numbers.add(page);
+        }
+        for (int page = Math.max(1, pageCount - window + 1); page <= pageCount; page++) {
+            numbers.add(page);
+        }
+        return new ArrayList<>(numbers);
+    }
+
+    /** Drop the transport-only {@code outcome} discriminator; keep the rest verbatim. */
+    private String toMetadataValue(String engineResponseJson) {
+        JsonNode node = objectMapper.readTree(engineResponseJson);
+        if (node instanceof ObjectNode object) {
+            object.remove("outcome");
+        }
+        return objectMapper.writeValueAsString(node);
+    }
+
+    private static String safeFileName(String originalFilename) {
+        String name = Filenames.toSimpleFileName(originalFilename);
+        return (name == null || name.isBlank()) ? "classified.pdf" : name;
+    }
+
+    /**
+     * The allowed labels for the caller's team as {@code {id, name}} pairs, de-duplicated by id.
+     * The engine shows the model the names and returns the ids (icons are presentational and never
+     * sent). Returns an empty list — the caller then skips classification — when the policy
+     * subsystem is disabled (no store) or the team has no stored labels. The engine holds no
+     * default vocabulary of its own, so a team's stored labels are the only source.
+     */
+    private List<EngineLabel> resolveAllowedLabels() {
+        if (labelStore == null) {
+            return List.of();
+        }
+        Long teamId =
+                policyManagementAuthority == null
+                        ? null
+                        : policyManagementAuthority.currentUserTeamId();
+
+        Map<String, EngineLabel> byId = new LinkedHashMap<>();
+        labelStore.findByTeam(teamId).ifPresent(labels -> collectLabels(labels.labels(), byId));
+
+        return List.copyOf(byId.values());
+    }
+
+    private static void collectLabels(
+            List<ClassificationLabel> labels, Map<String, EngineLabel> into) {
+        for (ClassificationLabel label : labels) {
+            if (label.id() == null
+                    || label.id().isBlank()
+                    || label.name() == null
+                    || label.name().isBlank()) {
+                continue;
+            }
+            into.putIfAbsent(label.id(), new EngineLabel(label.id(), label.name()));
+        }
+    }
+
+    /** One allowed label sent to the engine: stable id + the name the model reasons over. */
+    private record EngineLabel(String id, String name) {}
+
+    /** Request body for the engine's {@code /api/v1/documents/classify} endpoint. */
+    private record ClassifyEngineRequest(
+            String fileName, List<AiPageText> pages, List<EngineLabel> labels) {}
+}

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/FleetUsageController.java

@@ -0,0 +1,71 @@
+package stirling.software.proprietary.controller.api;
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.List;
+
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.audit.AuditLevel;
+import stirling.software.proprietary.config.AuditConfigurationProperties;
+import stirling.software.proprietary.model.api.usage.FleetUsageStats;
+import stirling.software.proprietary.repository.PersistentAuditEventRepository;
+import stirling.software.proprietary.security.config.EnterpriseEndpoint;
+import stirling.software.proprietary.security.database.repository.UserRepository;
+
+/**
+ * Admin endpoint exposing free-editor fleet usage for the portal Usage card. Audit-derived figures
+ * (active editors, PDFs processed) are null (rendered as "N/A") rather than a misleading 0 whenever
+ * the data can't exist: the events they count (PDF_PROCESS, FILE_OPERATION, HTTP_REQUEST) are all
+ * STANDARD level, so a gate on {@code isEnabled()} alone would still return 0 at level=OFF/BASIC —
+ * we gate on {@code isLevelEnabled(STANDARD)} instead.
+ *
+ * <p>Known limitation: on a login-disabled self-hosted instance every request is anonymous, so its
+ * audit origin is SYSTEM (not WEB) and it is excluded from these WEB-only counts — active/PDFs then
+ * read 0 despite real usage. Historical audit rows written before the {@code source} column existed
+ * carry {@code source=null}, so the cumulative "PDFs edited" figure effectively starts at deploy.
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/v1/usage")
+@PreAuthorize("hasRole('ADMIN')")
+@RequiredArgsConstructor
+@EnterpriseEndpoint
+public class FleetUsageController {
+
+    private final PersistentAuditEventRepository auditRepository;
+    private final UserRepository userRepository;
+    private final AuditConfigurationProperties auditConfig;
+
+    @GetMapping("/fleet-stats")
+    public FleetUsageStats fleetStats() {
+        // Exclude the reserved INTERNAL_API_USER row that InitialSecuritySetup creates on every
+        // install, so a fresh single-admin instance reads 1 editor, not 2.
+        Long deployed = userRepository.countByUsernameNot(Role.INTERNAL_API_USER.getRoleId());
+        // STANDARD is the level at which the counted events are recorded; below it the data
+        // can't exist, so report N/A instead of a 0 that would misrepresent an empty table.
+        boolean auditOn = auditConfig.isLevelEnabled(AuditLevel.STANDARD);
+        Instant since = Instant.now().minus(30, ChronoUnit.DAYS);
+        Long active =
+                auditOn
+                        ? auditRepository.countDistinctPrincipalsBySourceExcludingTypeAfter(
+                                "WEB", "UI_DATA", since)
+                        : null;
+        Long pdfs =
+                auditOn
+                        ? auditRepository.countByTypeInAndSourceAndTimestampAfter(
+                                List.of("PDF_PROCESS", "FILE_OPERATION"), "WEB", Instant.EPOCH)
+                        : null;
+        if (active != null && deployed != null && active > deployed) {
+            active = deployed; // active editors are a subset of those deployed
+        }
+        return new FleetUsageStats(deployed, active, pdfs);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/PortalDocumentsController.java

@@ -0,0 +1,46 @@
+package stirling.software.proprietary.controller.api;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.annotations.api.ProprietaryUiDataApi;
+import stirling.software.proprietary.audit.PortalAuditScope;
+import stirling.software.proprietary.audit.PortalAuditScopeResolver;
+import stirling.software.proprietary.model.api.documents.PortalDocumentsResponseDto;
+import stirling.software.proprietary.security.config.EnterpriseEndpoint;
+import stirling.software.proprietary.service.PortalDocumentsService;
+
+/** Serves the portal Documents review queue, derived from real audit data and scoped per caller. */
+@ProprietaryUiDataApi
+@RequiredArgsConstructor
+@EnterpriseEndpoint
+public class PortalDocumentsController {
+
+    private final PortalDocumentsService portalDocumentsService;
+    private final PortalAuditScopeResolver auditScopeResolver;
+
+    // tier accepted for mock-seam symmetry; ignored (queue isn't tier-scoped).
+    @GetMapping("/documents")
+    @Operation(
+            summary = "Documents review queue",
+            description = "Files processed through the org, derived from the audit trail.")
+    public ResponseEntity<PortalDocumentsResponseDto> getDocuments(
+            @RequestParam(value = "tier", required = false) String tier) {
+        PortalAuditScope scope = auditScopeResolver.resolve();
+        if (!scope.allowed()) {
+            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        }
+        PortalDocumentsResponseDto body =
+                scope.fullServer()
+                        ? portalDocumentsService.serverDocuments()
+                        : portalDocumentsService.scopedDocuments(
+                                scope.cacheKey(), scope.principals());
+        return ResponseEntity.ok(body);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/PortalInfraAuditController.java

@@ -0,0 +1,47 @@
+package stirling.software.proprietary.controller.api;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.annotations.api.ProprietaryUiDataApi;
+import stirling.software.proprietary.audit.PortalAuditScope;
+import stirling.software.proprietary.audit.PortalAuditScopeResolver;
+import stirling.software.proprietary.model.api.audit.InfraAuditLogResponse;
+import stirling.software.proprietary.security.config.EnterpriseEndpoint;
+import stirling.software.proprietary.service.PortalInfraAuditService;
+
+/** Serves the Infrastructure → Audit tab from real audit data, scoped and cached per caller. */
+@ProprietaryUiDataApi
+@RequiredArgsConstructor
+@EnterpriseEndpoint
+public class PortalInfraAuditController {
+
+    private final PortalInfraAuditService portalInfraAuditService;
+    private final PortalAuditScopeResolver auditScopeResolver;
+
+    // tier accepted for endpoint symmetry; ignored (audit log isn't tier-scoped).
+    @GetMapping("/infrastructure/audit-log")
+    @Operation(
+            summary = "Infrastructure audit log",
+            description = "Recent audit events shaped for the portal Infrastructure → Audit tab.")
+    public ResponseEntity<InfraAuditLogResponse> getInfrastructureAuditLog(
+            @RequestParam(value = "tier", required = false) String tier) {
+        PortalAuditScope scope = auditScopeResolver.resolve();
+        if (!scope.allowed()) {
+            // Return 403 (not throw) so the tab shows its access message, not a generic 500.
+            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        }
+        InfraAuditLogResponse body =
+                scope.fullServer()
+                        ? portalInfraAuditService.serverAuditLog()
+                        : portalInfraAuditService.scopedAuditLog(
+                                scope.cacheKey(), scope.principals());
+        return ResponseEntity.ok(body);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/controller/api/ProprietaryUIDataController.java

@@ -5,6 +5,7 @@ import static stirling.software.common.util.ProviderUtils.validateProvider;
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.*;
+import java.util.stream.Collectors;
 
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.http.ResponseEntity;
@@ -28,13 +29,16 @@ import stirling.software.common.model.ApplicationProperties.Security.OAUTH2.Clie
 import stirling.software.common.model.ApplicationProperties.Security.SAML2;
 import stirling.software.common.model.FileInfo;
 import stirling.software.common.model.enumeration.Role;
+import stirling.software.common.model.enumeration.TeamRole;
 import stirling.software.common.model.oauth2.GitHubProvider;
 import stirling.software.common.model.oauth2.GoogleProvider;
 import stirling.software.common.model.oauth2.KeycloakProvider;
+import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.audit.AuditEventType;
 import stirling.software.proprietary.audit.AuditLevel;
 import stirling.software.proprietary.config.AuditConfigurationProperties;
 import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.model.TeamMembership;
 import stirling.software.proprietary.model.dto.TeamWithUserCountDTO;
 import stirling.software.proprietary.repository.PersistentAuditEventRepository;
 import stirling.software.proprietary.security.config.EnterpriseEndpoint;
@@ -44,6 +48,7 @@ import stirling.software.proprietary.security.model.Authority;
 import stirling.software.proprietary.security.model.SessionEntity;
 import stirling.software.proprietary.security.model.User;
 import stirling.software.proprietary.security.model.dto.AdminUserSummary;
+import stirling.software.proprietary.security.repository.TeamMembershipRepository;
 import stirling.software.proprietary.security.repository.TeamRepository;
 import stirling.software.proprietary.security.saml2.CustomSaml2AuthenticatedPrincipal;
 import stirling.software.proprietary.security.service.DatabaseServiceInterface;
@@ -65,6 +70,7 @@ public class ProprietaryUIDataController {
     private final SessionPersistentRegistry sessionPersistentRegistry;
     private final UserRepository userRepository;
     private final TeamRepository teamRepository;
+    private final TeamMembershipRepository teamMembershipRepository;
     private final SessionRepository sessionRepository;
     private final DatabaseServiceInterface databaseService;
     private final boolean runningEE;
@@ -73,6 +79,7 @@ public class ProprietaryUIDataController {
     private final PersistentAuditEventRepository auditRepository;
     private final MfaService mfaService;
     private final LoginAttemptService loginAttemptService;
+    private final ResourceAccessService resourceAccessService;
 
     public ProprietaryUIDataController(
             ApplicationProperties applicationProperties,
@@ -80,6 +87,7 @@ public class ProprietaryUIDataController {
             SessionPersistentRegistry sessionPersistentRegistry,
             UserRepository userRepository,
             TeamRepository teamRepository,
+            TeamMembershipRepository teamMembershipRepository,
             SessionRepository sessionRepository,
             DatabaseServiceInterface databaseService,
             ObjectMapper objectMapper,
@@ -87,12 +95,14 @@ public class ProprietaryUIDataController {
             UserLicenseSettingsService licenseSettingsService,
             PersistentAuditEventRepository auditRepository,
             MfaService mfaService,
-            LoginAttemptService loginAttemptService) {
+            LoginAttemptService loginAttemptService,
+            ResourceAccessService resourceAccessService) {
         this.applicationProperties = applicationProperties;
         this.auditConfig = auditConfig;
         this.sessionPersistentRegistry = sessionPersistentRegistry;
         this.userRepository = userRepository;
         this.teamRepository = teamRepository;
+        this.teamMembershipRepository = teamMembershipRepository;
         this.sessionRepository = sessionRepository;
         this.databaseService = databaseService;
         this.objectMapper = objectMapper;
@@ -101,6 +111,7 @@ public class ProprietaryUIDataController {
         this.auditRepository = auditRepository;
         this.mfaService = mfaService;
         this.loginAttemptService = loginAttemptService;
+        this.resourceAccessService = resourceAccessService;
     }
 
     /**
@@ -370,8 +381,11 @@ public class ProprietaryUIDataController {
         boolean premiumEnabled = applicationProperties.getPremium().isEnabled();
 
         // Convert User entities to AdminUserSummary DTOs to exclude sensitive fields
+        Set<Long> leaderUserIds = leaderUserIds();
         List<AdminUserSummary> userSummaries =
-                sortedUsers.stream().map(this::convertUserToSummary).toList();
+                sortedUsers.stream()
+                        .map(user -> convertUserToSummary(user, leaderUserIds))
+                        .toList();
 
         AdminSettingsData data = new AdminSettingsData();
         data.setUsers(userSummaries);
@@ -390,6 +404,10 @@ public class ProprietaryUIDataController {
         data.setLicenseMaxUsers(licenseMaxUsers);
         data.setPremiumEnabled(premiumEnabled);
         data.setMailEnabled(applicationProperties.getMail().isEnabled());
+        // Email invites need the invites toggle AND SMTP on; matches the inviteUsers precondition.
+        data.setEmailInvitesEnabled(
+                applicationProperties.getMail().isEnableInvites()
+                        && applicationProperties.getMail().isEnabled());
         data.setUserSettings(userSettings);
         data.setLockedUsers(loginAttemptService.getAllBlockedUsers());
 
@@ -468,9 +486,18 @@ public class ProprietaryUIDataController {
             teamLastRequest.put(teamId, lastActivity);
         }
 
+        Map<Long, List<String>> teamOwners = new HashMap<>();
+        for (TeamMembership row :
+                teamMembershipRepository.findByRoleFetchingUserAndTeam(TeamRole.LEADER)) {
+            teamOwners
+                    .computeIfAbsent(row.getTeam().getId(), id -> new ArrayList<>())
+                    .add(row.getUser().getUsername());
+        }
+
         TeamsData data = new TeamsData();
         data.setTeamsWithCounts(teamsWithCounts);
         data.setTeamLastRequest(teamLastRequest);
+        data.setTeamOwners(teamOwners);
 
         return ResponseEntity.ok(data);
     }
@@ -510,11 +537,17 @@ public class ProprietaryUIDataController {
             userLastRequest.put(username, lastRequest);
         }
 
+        Set<Long> ownerUserIds =
+                teamMembershipRepository.findByTeamIdAndRole(id, TeamRole.LEADER).stream()
+                        .map(row -> row.getUser().getId())
+                        .collect(Collectors.toSet());
+
         TeamDetailsData data = new TeamDetailsData();
         data.setTeam(team);
         data.setTeamUsers(teamUsers);
         data.setAvailableUsers(availableUsers);
         data.setUserLastRequest(userLastRequest);
+        data.setOwnerUserIds(ownerUserIds);
 
         return ResponseEntity.ok(data);
     }
@@ -535,13 +568,24 @@ public class ProprietaryUIDataController {
         return ResponseEntity.ok(data);
     }
 
+    /** User ids holding a LEADER membership on any team. */
+    private Set<Long> leaderUserIds() {
+        return teamMembershipRepository.findByRoleFetchingUserAndTeam(TeamRole.LEADER).stream()
+                .map(row -> row.getUser().getId())
+                .collect(Collectors.toSet());
+    }
+
     /**
      * Convert User entity to AdminUserSummary DTO, excluding sensitive fields like password and
      * apiKey.
      */
-    private AdminUserSummary convertUserToSummary(User user) {
+    private AdminUserSummary convertUserToSummary(User user, Set<Long> leaderUserIds) {
         AdminUserSummary summary = new AdminUserSummary();
         summary.setId(user.getId());
+        summary.setTeamLead(leaderUserIds.contains(user.getId()));
+        // Authoritative portal access, same call /me uses, so the roster honors the configured
+        // policy instead of the frontend guessing from role/team-leadership.
+        summary.setPortalAccess(resourceAccessService.canAccessPortal(user));
         summary.setUsername(user.getUsername());
         summary.setEmail(user.getUsername()); // Use username as email for consistency
         summary.setRoleName(user.getRoleName());
@@ -609,6 +653,7 @@ public class ProprietaryUIDataController {
         private int licenseMaxUsers;
         private boolean premiumEnabled;
         private boolean mailEnabled;
+        private boolean emailInvitesEnabled;
         private Map<String, Map<String, String>> userSettings;
         private List<String> lockedUsers;
     }
@@ -629,6 +674,7 @@ public class ProprietaryUIDataController {
     public static class TeamsData {
         private List<TeamWithUserCountDTO> teamsWithCounts;
         private Map<Long, Date> teamLastRequest;
+        private Map<Long, List<String>> teamOwners;
     }
 
     @Data
@@ -637,6 +683,7 @@ public class ProprietaryUIDataController {
         private List<User> teamUsers;
         private List<User> availableUsers;
         private Map<String, Date> userLastRequest;
+        private Set<Long> ownerUserIds;
     }
 
     @Data

app/proprietary/src/main/java/stirling/software/proprietary/integration/controller/IntegrationConfigController.java

@@ -29,7 +29,9 @@ import stirling.software.proprietary.security.model.User;
 @RestController
 @RequestMapping("/api/v1/integrations")
 @RequiredArgsConstructor
-@PreAuthorize("isAuthenticated()")
+// Portal-exclusive: server-side portal-access boundary, not just isAuthenticated. Per-config
+// ownership is still enforced in the service layer.
+@PreAuthorize("@resourceAccess.canUsePortal()")
 @Tag(name = "Integrations", description = "Manage S3/MCP/API integration configurations")
 public class IntegrationConfigController {
 

app/proprietary/src/main/java/stirling/software/proprietary/integration/crypto/CredentialEncryption.java

@@ -1,12 +1,16 @@
 package stirling.software.proprietary.integration.crypto;
 
+import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.attribute.PosixFilePermission;
+import java.nio.file.attribute.PosixFilePermissions;
 import java.security.GeneralSecurityException;
 import java.security.SecureRandom;
 import java.util.Arrays;
 import java.util.Base64;
+import java.util.EnumSet;
 
 import javax.crypto.Cipher;
 import javax.crypto.KeyGenerator;
@@ -74,7 +78,7 @@ public class CredentialEncryption {
             generator.init(256);
             SecretKey generated = generator.generateKey();
             Files.createDirectories(path.getParent());
-            Files.writeString(path, Base64.getEncoder().encodeToString(generated.getEncoded()));
+            writeOwnerOnly(path, Base64.getEncoder().encodeToString(generated.getEncoded()));
             log.warn(
                     "Generated a new credential encryption key at {}. Back this file up: losing it"
                             + " makes stored integration secrets unrecoverable.",
@@ -85,6 +89,25 @@ public class CredentialEncryption {
         }
     }
 
+    // The master key decrypts every stored integration secret, so create it 0600
+    // (owner-only) atomically. On non-POSIX filesystems (Windows) the config-dir
+    // ACL is the protection; we still create the file, just without POSIX perms.
+    private static void writeOwnerOnly(Path path, String content) throws IOException {
+        EnumSet<PosixFilePermission> ownerOnly =
+                EnumSet.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE);
+        try {
+            Files.createFile(path, PosixFilePermissions.asFileAttribute(ownerOnly));
+        } catch (UnsupportedOperationException e) {
+            Files.createFile(path);
+        }
+        Files.writeString(path, content);
+        try {
+            Files.setPosixFilePermissions(path, ownerOnly);
+        } catch (UnsupportedOperationException ignored) {
+            // Non-POSIX filesystem: nothing to tighten here.
+        }
+    }
+
     public static String encrypt(String plaintext) {
         if (plaintext == null) {
             return null;

app/proprietary/src/main/java/stirling/software/proprietary/integration/repository/IntegrationConfigRepository.java

@@ -18,4 +18,13 @@ public interface IntegrationConfigRepository extends JpaRepository<IntegrationCo
     List<IntegrationConfig> findByOwnerTeam(Team ownerTeam);
 
     List<IntegrationConfig> findByScope(OwnerScope scope);
+
+    // Nested path: OwnedResource has a getOwnerTeamId() convenience getter but no such persistent
+    // attribute, so the plain "...OwnerTeamId" derivation resolves to a phantom property and throws
+    // UnknownPathException. The underscore forces the real ownerTeam.id association path.
+    boolean existsByOwnerTeam_Id(Long teamId);
+
+    void deleteByOwnerUser(User ownerUser);
+
+    void deleteByOwnerTeam_Id(Long teamId);
 }

app/proprietary/src/main/java/stirling/software/proprietary/integration/service/IntegrationConfigService.java

@@ -16,6 +16,7 @@ import lombok.extern.slf4j.Slf4j;
 import stirling.software.proprietary.access.model.DefaultAccessPolicy;
 import stirling.software.proprietary.access.model.OwnerScope;
 import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.access.repository.ResourceGrantRepository;
 import stirling.software.proprietary.access.service.OwnershipService;
 import stirling.software.proprietary.access.service.SecretMasker;
 import stirling.software.proprietary.integration.dto.IntegrationConfigRequest;
@@ -41,6 +42,7 @@ public class IntegrationConfigService {
     private final IntegrationConfigRepository repository;
     private final OwnershipService ownership;
     private final SecretMasker secretMasker;
+    private final ResourceGrantRepository grantRepository;
 
     // ---- commands ----
 
@@ -49,6 +51,13 @@ public class IntegrationConfigService {
         OwnerScope scope = request.scope() == null ? OwnerScope.USER : request.scope();
         IntegrationConfig cfg = new IntegrationConfig();
         cfg.setIntegrationType(require(request.integrationType(), "integrationType"));
+        // S3 is infrastructure, not self-serve: no personal S3 for regular users. TEAM/SERVER
+        // scopes are already restricted to admins/team owners by assignOwnership.
+        if (cfg.getIntegrationType() == IntegrationType.S3
+                && scope == OwnerScope.USER
+                && !ownership.isAdmin(currentUser)) {
+            throw forbidden("S3 connections can only be created by administrators or team owners");
+        }
         cfg.setName(require(request.name(), "name"));
         cfg.setEnabled(request.enabled() == null || request.enabled());
         cfg.setLocked(request.locked() != null && request.locked());
@@ -104,6 +113,8 @@ public class IntegrationConfigService {
         if (!ownership.canManage(TYPE, cfg, currentUser)) {
             throw forbidden("You cannot manage this integration");
         }
+        // Drop grants sharing this config so they do not dangle as dead rows.
+        grantRepository.deleteByResourceTypeAndResourceId(TYPE, String.valueOf(cfg.getId()));
         repository.delete(cfg);
     }
 

app/proprietary/src/main/java/stirling/software/proprietary/model/TeamMembership.java

@@ -1,4 +1,4 @@
-package stirling.software.saas.model;
+package stirling.software.proprietary.model;
 
 import java.io.Serializable;
 import java.time.LocalDateTime;
@@ -15,7 +15,6 @@ import lombok.Setter;
 import lombok.ToString;
 
 import stirling.software.common.model.enumeration.TeamRole;
-import stirling.software.proprietary.model.Team;
 import stirling.software.proprietary.security.model.User;
 
 /**

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowResultFile.java

@@ -21,4 +21,11 @@ public class AiWorkflowResultFile {
 
     @Schema(description = "MIME type of the file", example = "application/pdf")
     private String contentType;
+
+    @Schema(
+            description =
+                    "Index into the request's fileInputs that this output was derived from, or null"
+                            + " when it has no single source (e.g. a merge, or a generated file)."
+                            + " Lets the client replace that input in place as a new version.")
+    private Integer sourceIndex;
 }

app/proprietary/src/main/java/stirling/software/proprietary/model/api/audit/InfraAuditEventDto.java

@@ -0,0 +1,44 @@
+package stirling.software.proprietary.model.api.audit;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * A single infrastructure audit-log row, shaped for the portal Infrastructure → Audit tab. Derived
+ * from a {@code audit_events} row: the real {@link
+ * stirling.software.proprietary.audit.AuditEventType} is mapped to a display category/action.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class InfraAuditEventDto {
+
+    @Schema(description = "Audit event id", example = "8841")
+    private String id;
+
+    @Schema(description = "Display timestamp (UTC)", example = "2026-07-07 18:59:31")
+    private String timestamp;
+
+    @Schema(description = "Category: auth | config | elevation | processing | security")
+    private String category;
+
+    @Schema(description = "Human-readable action", example = "Compress PDF")
+    private String action;
+
+    @Schema(description = "Actor principal", example = "alice.chen@acme.com")
+    private String actor;
+
+    @Schema(description = "Affected target (file, endpoint, or session)")
+    private String target;
+
+    @Schema(description = "Status: success | warning | danger | info")
+    private String status;
+
+    @Schema(description = "Operation latency in milliseconds", example = "412")
+    private long latencyMs;
+}

app/proprietary/src/main/java/stirling/software/proprietary/model/api/audit/InfraAuditLogResponse.java

@@ -0,0 +1,30 @@
+package stirling.software.proprietary.model.api.audit;
+
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/** Response for the portal Infrastructure → Audit tab: summary strip + recent event rows. */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class InfraAuditLogResponse {
+
+    @Schema(description = "Headline counts")
+    private InfraAuditSummary summary;
+
+    @Schema(description = "Most-recent audit events, newest first")
+    private List<InfraAuditEventDto> events;
+
+    @Schema(
+            description =
+                    "True when this is the whole-server (admin) view. Team-scoped views are false; "
+                            + "drives whether the admin-only, whole-server CSV export is offered.")
+    private boolean fullServer;
+}