Merge branch 'main' of https://github.com/Stirling-Tools/Stirling-PDF into feature/documentClassifierAgent

.taskfiles/frontend.yml

@@ -55,6 +55,15 @@ tasks:
       - editor/src/core/data/ogImageMap.json
       - editor/public/og-metadata.json
 
+  prepare:classifier-categories:
+    internal: true
+    run: when_changed
+    desc: "Regenerate the engine classifier categories JSON from the TS source of truth"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts
+    sources:
+      - editor/src/proprietary/data/classificationTaxonomy.ts
+
   prepare:
     desc: "Set up dev environment"
     run: when_changed
@@ -65,6 +74,7 @@ tasks:
         vars: { MODE: '{{.MODE}}' }
       - prepare:icons
       - prepare:og
+      - prepare:classifier-categories
 
   # ============================================================
   # Development
@@ -401,12 +411,23 @@ tasks:
     cmds:
       - node editor/scripts/generate-og-metadata.mjs --check
 
+  classifier-categories:
+    desc: "Regenerate the engine classifier categories JSON from the TS source"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts
+
+  classifier-categories:check:
+    desc: "Fail if the committed classifier categories JSON is out of date"
+    cmds:
+      - npx tsx editor/scripts/generate-classification-taxonomy.mts --check
+
   check:all:
     desc: "Full CI quality gate"
     cmds:
       # Runs first, before prepare regenerates: guards the committed og-metadata.json /
       # ogImageMap.json that the Cloudflare Pages (plain `vite build`) deploy relies on.
       - task: og:check
+      - task: classifier-categories:check
       - task: typecheck:all
       - task: lint
       - task: format:check

Taskfile.yml

@@ -95,6 +95,7 @@ tasks:
         vars:
           PORT: '{{.PORTAL_PORT}}'
           BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          MOCKS: 'false'
           OPEN: "true"
 
   dev:portal:all:
@@ -117,6 +118,32 @@ tasks:
           BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
           # Point the portal's "Editor" app switcher at the editor we spawn here.
           EDITOR_URL: 'http://localhost:{{.EDITOR_PORT}}/'
+          MOCKS: 'false'
+          OPEN: "true"
+      - task: frontend:dev
+        vars:
+          PORT: '{{.EDITOR_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+
+  dev:portal:all:saas:
+    desc: "Start SaaS backend + developer portal + editor concurrently on free ports"
+    vars:
+      PORTS:
+        sh: '{{if eq OS "windows"}}{{.FIND_FREE_PORT_PS}} 8080 5173 5174{{else}}{{.FIND_FREE_PORT_SH}} 8080 5173 5174{{end}}'
+      BACKEND_PORT: '{{index (splitList "\n" .PORTS) 0}}'
+      PORTAL_PORT: '{{index (splitList "\n" .PORTS) 1}}'
+      EDITOR_PORT: '{{index (splitList "\n" .PORTS) 2}}'
+    deps:
+      - task: backend:dev:saas
+        vars:
+          PORT: '{{.BACKEND_PORT}}'
+          POLICIES_ENABLED: "true"
+      - task: frontend:dev:portal
+        vars:
+          PORT: '{{.PORTAL_PORT}}'
+          BACKEND_URL: 'http://localhost:{{.BACKEND_PORT}}'
+          EDITOR_URL: 'http://localhost:{{.EDITOR_PORT}}/'
+          MOCKS: 'false'
           OPEN: "true"
       - task: frontend:dev
         vars:

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,11 @@ import stirling.software.common.model.PdfMetadata;
 @Service
 public class PdfMetadataService {
 
+    /**
+     * ({@code {category, docType, typeConfidence, tags}}). Written by the classify-and-tag tool.
+     */
+    public static final String CLASSIFICATION_KEY = "StirlingPDFClassification";
+
     private final ApplicationProperties applicationProperties;
     private final String stirlingPDFLabel;
     private final UserServiceInterface userService;
@@ -177,4 +183,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/core/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java

@@ -3,9 +3,12 @@ package stirling.software.SPDF.controller.api;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Locale;
+import java.util.Set;
 
+import org.apache.pdfbox.cos.COSDictionary;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.PDPageTree;
@@ -261,10 +264,19 @@ public class RearrangePagesPDFController {
                 log.info("newPageOrder = {}", newPageOrder);
                 log.info("totalPages = {}", totalPages);
 
-                // Snapshot the desired pages before mutating the source document's page tree.
+                // Snapshot desired pages before mutating the tree; clone repeats (e.g. DUPLICATE)
+                // so each slot is a distinct node, not one PDPage under multiple /Kids.
                 List<PDPage> newPages = new ArrayList<>(newPageOrder.size());
+                Set<Integer> seenIndices = new HashSet<>();
                 for (Integer idx : newPageOrder) {
-                    newPages.add(document.getPage(idx));
+                    PDPage page = document.getPage(idx);
+                    if (!seenIndices.add(idx)) {
+                        // Duplicate index: distinct page node sharing content/resources.
+                        COSDictionary clonedDict = new COSDictionary();
+                        clonedDict.addAll(page.getCOSObject());
+                        page = new PDPage(clonedDict);
+                    }
+                    newPages.add(page);
                 }
 
                 // Rearrange in-place on the source document rather than copying pages into a

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/test/java/stirling/software/SPDF/controller/api/RearrangePagesPDFControllerTest.java

@@ -9,6 +9,7 @@ import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
 
 import org.apache.pdfbox.Loader;
@@ -302,6 +303,11 @@ class RearrangePagesPDFControllerTest {
             assertNotNull(response);
             // 2 pages * 3 duplicates = 6 final pages
             assertEquals(6, realDoc.getNumberOfPages());
+            // Each duplicate must be a distinct page node in the saved output; a shared
+            // node under multiple /Kids is an invalid tree readers reject as cyclic.
+            List<Object> savedPages = reloadAndSnapshot(response);
+            assertEquals(6, savedPages.size());
+            assertEquals(6, new HashSet<>(savedPages).size());
         }
     }
 
@@ -323,4 +329,29 @@ class RearrangePagesPDFControllerTest {
             assertEquals(4, realDoc.getNumberOfPages());
         }
     }
+
+    @Test
+    void testRearrangePages_SideStitchBooklet_RepeatedPaddingPagesAreDistinctNodes()
+            throws IOException {
+        MockMultipartFile file = createMockPdf();
+        RearrangePagesRequest request = new RearrangePagesRequest();
+        request.setFileInput(file);
+        request.setPageNumbers("");
+        request.setCustomMode("SIDE_STITCH_BOOKLET_SORT");
+
+        // 6 pages is not a multiple of 4, so booklet padding repeats the last page index
+        // several times; each repeat must be a distinct page node, not one shared node.
+        try (PDDocument realDoc = buildRealPdf(6)) {
+            when(pdfDocumentFactory.load(file)).thenReturn(realDoc);
+
+            ResponseEntity<Resource> response = controller.rearrangePages(request);
+
+            assertNotNull(response);
+            assertEquals(200, response.getStatusCode().value());
+            assertEquals(8, realDoc.getNumberOfPages());
+            List<Object> savedPages = reloadAndSnapshot(response);
+            assertEquals(8, savedPages.size());
+            assertEquals(8, new HashSet<>(savedPages).size());
+        }
+    }
 }

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

@@ -0,0 +1,20 @@
+package stirling.software.proprietary.access.config;
+
+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.DefaultTeamLeadLookup;
+import stirling.software.proprietary.access.service.TeamLeadLookup;
+
+/** Access-layer bean wiring. */
+@Configuration
+public class AccessConfig {
+
+    /** No-op {@link TeamLeadLookup} unless another bean is defined. */
+    @Bean
+    @ConditionalOnMissingBean(TeamLeadLookup.class)
+    TeamLeadLookup defaultTeamLeadLookup() {
+        return new DefaultTeamLeadLookup();
+    }
+}

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

@@ -0,0 +1,101 @@
+package stirling.software.proprietary.access.controller;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.proprietary.access.model.AccessPermission;
+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.model.User;
+
+/** Admin endpoints to grant/revoke access to gated resources (the portal, integration configs). */
+@RestController
+@RequestMapping("/api/v1/admin/access")
+@RequiredArgsConstructor
+@PreAuthorize("hasRole('ADMIN')")
+@Tag(name = "Access Control", description = "Manage resource access grants (portal, integrations)")
+public class ResourceGrantController {
+
+    private final ResourceAccessService accessService;
+
+    @GetMapping("/grants")
+    public ResponseEntity<?> list(
+            @RequestParam ResourceType resourceType,
+            @RequestParam(required = false, defaultValue = "") String resourceId) {
+        List<ResourceGrant> grants = accessService.listGrants(resourceType, resourceId);
+        return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
+    }
+
+    @PostMapping("/grants")
+    public ResponseEntity<?> create(
+            @RequestBody GrantRequest request, @AuthenticationPrincipal User admin) {
+        if (request.resourceType() == null
+                || request.principalType() == null
+                || request.principalId() == null) {
+            return ResponseEntity.badRequest()
+                    .body(
+                            Map.of(
+                                    "error",
+                                    "resourceType, principalType and principalId are required"));
+        }
+        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();
+        ResourceGrant grant =
+                accessService.grant(
+                        request.resourceType(),
+                        resourceId,
+                        request.principalType(),
+                        request.principalId(),
+                        permission,
+                        admin);
+        return ResponseEntity.ok(toDto(grant));
+    }
+
+    @DeleteMapping("/grants/{id}")
+    public ResponseEntity<?> delete(@PathVariable Long id) {
+        accessService.revoke(id);
+        return ResponseEntity.ok(Map.of("message", "Grant revoked"));
+    }
+
+    private Map<String, Object> toDto(ResourceGrant g) {
+        Map<String, Object> m = new HashMap<>();
+        m.put("id", g.getId());
+        m.put("resourceType", g.getResourceType());
+        m.put("resourceId", g.getResourceId());
+        m.put("principalType", g.getPrincipalType());
+        m.put("principalId", g.getPrincipalId());
+        m.put("permission", g.getPermission());
+        m.put("createdAt", g.getCreatedAt());
+        return m;
+    }
+
+    /** Request body for creating a grant. */
+    public record GrantRequest(
+            ResourceType resourceType,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId,
+            AccessPermission permission) {}
+}

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

@@ -0,0 +1,7 @@
+package stirling.software.proprietary.access.model;
+
+/** Permission level a grant confers. MANAGE implies USE. */
+public enum AccessPermission {
+    USE,
+    MANAGE
+}

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

@@ -0,0 +1,14 @@
+package stirling.software.proprietary.access.model;
+
+/**
+ * Fallback policy applied when no explicit {@link ResourceGrant} matches. Admins (org owners)
+ * always pass regardless of this policy.
+ */
+public enum DefaultAccessPolicy {
+    // Every authenticated user in the deployment (org) may use the resource.
+    ORG_ALL,
+    // Only org admins and team leaders. This is the default for the portal.
+    ADMINS_AND_TEAM_LEADS,
+    // Nobody but the owner, admins, and explicit grantees.
+    EXPLICIT_ONLY
+}

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

@@ -0,0 +1,57 @@
+package stirling.software.proprietary.access.model;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.MappedSuperclass;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.User;
+
+/** Base for a resource owned by a user, a team, or the server, with grant-based access. */
+@MappedSuperclass
+@Getter
+@Setter
+public abstract class OwnedResource {
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "scope", nullable = false, length = 32)
+    private OwnerScope scope;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "owner_user_id")
+    private User ownerUser;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "owner_team_id")
+    private Team ownerTeam;
+
+    @Column(name = "enabled", nullable = false)
+    private boolean enabled = true;
+
+    // Server resource that users cannot override with their own of the same kind.
+    @Column(name = "locked", nullable = false)
+    private boolean locked = false;
+
+    // Who, besides owner/admin/grantees, may use this resource.
+    @Enumerated(EnumType.STRING)
+    @Column(name = "default_access", nullable = false, length = 32)
+    private DefaultAccessPolicy defaultAccess = DefaultAccessPolicy.EXPLICIT_ONLY;
+
+    /** Subclass primary key. */
+    public abstract Long getId();
+
+    public Long getOwnerUserId() {
+        return ownerUser != null ? ownerUser.getId() : null;
+    }
+
+    public Long getOwnerTeamId() {
+        return ownerTeam != null ? ownerTeam.getId() : null;
+    }
+}

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

@@ -0,0 +1,8 @@
+package stirling.software.proprietary.access.model;
+
+/** Ownership scope of an {@link OwnedResource}: a single user, a team, or the whole server. */
+public enum OwnerScope {
+    USER,
+    TEAM,
+    SERVER
+}

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

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

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

@@ -0,0 +1,86 @@
+package stirling.software.proprietary.access.model;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Index;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import stirling.software.proprietary.security.model.User;
+
+/** Grants a user or team access to a resource. Owner and admin access are implicit. */
+@Entity
+@Table(
+        name = "resource_grants",
+        uniqueConstraints =
+                @UniqueConstraint(
+                        name = "uk_resource_grant",
+                        columnNames = {
+                            "resource_type",
+                            "resource_id",
+                            "principal_type",
+                            "principal_id",
+                            "permission"
+                        }),
+        indexes = {
+            @Index(name = "idx_resource_grants_lookup", columnList = "resource_type,resource_id"),
+            @Index(
+                    name = "idx_resource_grants_principal",
+                    columnList = "principal_type,principal_id")
+        })
+@NoArgsConstructor
+@Getter
+@Setter
+public class ResourceGrant implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "resource_grant_id")
+    private Long id;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "resource_type", nullable = false, length = 64)
+    private ResourceType resourceType;
+
+    // Empty string (never null) for a whole-type grant such as the portal.
+    @Column(name = "resource_id", nullable = false, length = 255)
+    private String resourceId = "";
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "principal_type", nullable = false, length = 32)
+    private PrincipalType principalType;
+
+    @Column(name = "principal_id", nullable = false)
+    private Long principalId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "permission", nullable = false, length = 32)
+    private AccessPermission permission;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "granted_by_user_id")
+    private User grantedBy;
+
+    @CreationTimestamp
+    @Column(name = "created_at", updatable = false)
+    private LocalDateTime createdAt;
+}

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

@@ -0,0 +1,9 @@
+package stirling.software.proprietary.access.model;
+
+/** Types of resources whose access can be gated by {@link ResourceGrant}. */
+public enum ResourceType {
+    // The admin portal / processor (frontend/portal). Singleton resource (empty resourceId).
+    PORTAL,
+    // A stored S3/MCP/API integration configuration.
+    INTEGRATION_CONFIG
+}

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

@@ -0,0 +1,28 @@
+package stirling.software.proprietary.access.repository;
+
+import java.util.List;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+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;
+
+@Repository
+public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Long> {
+
+    List<ResourceGrant> findByResourceTypeAndResourceId(
+            ResourceType resourceType, String resourceId);
+
+    List<ResourceGrant> findByResourceTypeAndPrincipalTypeAndPrincipalId(
+            ResourceType resourceType, PrincipalType principalType, Long principalId);
+
+    void deleteByResourceTypeAndResourceId(ResourceType resourceType, String resourceId);
+
+    boolean existsByResourceTypeAndResourceIdAndPrincipalTypeAndPrincipalId(
+            ResourceType resourceType,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId);
+}

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

@@ -0,0 +1,44 @@
+package stirling.software.proprietary.access.security;
+
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+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. */
+@Component("resourceAccess")
+@RequiredArgsConstructor
+public class ResourceAccessSecurity {
+
+    private final ResourceAccessService accessService;
+    private final UserService userService;
+
+    public boolean canUsePortal() {
+        User user = currentUser();
+        return user != null && accessService.canAccessPortal(user);
+    }
+
+    private User currentUser() {
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        if (auth == null || !auth.isAuthenticated()) {
+            return null;
+        }
+        Object principal = auth.getPrincipal();
+        if (principal instanceof User user) {
+            return user;
+        }
+        if (principal instanceof UserDetails userDetails) {
+            return userService.findByUsername(userDetails.getUsername()).orElse(null);
+        }
+        if (principal instanceof String username && !"anonymousUser".equals(username)) {
+            return userService.findByUsername(username).orElse(null);
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,17 @@
+package stirling.software.proprietary.access.service;
+
+import stirling.software.proprietary.security.model.User;
+
+/** No-op {@link TeamLeadLookup}: always false. */
+public class DefaultTeamLeadLookup implements TeamLeadLookup {
+
+    @Override
+    public boolean isAnyTeamLeader(User user) {
+        return false;
+    }
+
+    @Override
+    public boolean isLeaderOfTeam(User user, Long teamId) {
+        return false;
+    }
+}

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

@@ -0,0 +1,116 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.Set;
+import java.util.function.BooleanSupplier;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.access.model.OwnedResource;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamRepository;
+
+/** Ownership and access checks for {@link OwnedResource}, backed by the resource-grant ACL. */
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OwnershipService {
+
+    private final ResourceAccessService accessService;
+    private final TeamLeadLookup teamLeadLookup;
+    private final TeamRepository teamRepository;
+
+    /** Whether the user may use the resource. */
+    public boolean canUse(ResourceType type, OwnedResource resource, User user) {
+        if (!resource.isEnabled()) {
+            return isAdmin(user) || isOwner(resource, user);
+        }
+        return accessService.canUseResource(
+                type,
+                String.valueOf(resource.getId()),
+                resource.getOwnerUserId(),
+                resource.getDefaultAccess(),
+                user);
+    }
+
+    /** Whether the user may manage the resource. */
+    public boolean canManage(ResourceType type, OwnedResource resource, User user) {
+        return accessService.canManageResource(
+                type, String.valueOf(resource.getId()), resource.getOwnerUserId(), user);
+    }
+
+    /**
+     * Authorizes the scope and assigns ownership; {@code lockedOverrideBlocks} guards USER scope.
+     */
+    public void assignOwnership(
+            OwnedResource resource,
+            OwnerScope scope,
+            Long teamId,
+            User user,
+            BooleanSupplier lockedOverrideBlocks) {
+        resource.setScope(scope);
+        switch (scope) {
+            case USER -> {
+                if (lockedOverrideBlocks.getAsBoolean() && !isAdmin(user)) {
+                    throw forbidden(
+                            "This is locked to the server configuration by an administrator");
+                }
+                resource.setOwnerUser(user);
+            }
+            case SERVER -> {
+                if (!isAdmin(user)) {
+                    throw forbidden("Only administrators can create server-owned resources");
+                }
+            }
+            case TEAM -> {
+                if (teamId == null) {
+                    throw new ResponseStatusException(
+                            HttpStatus.BAD_REQUEST, "ownerTeamId is required");
+                }
+                Team team =
+                        teamRepository
+                                .findById(teamId)
+                                .orElseThrow(() -> notFound("Team not found"));
+                if (!isAdmin(user) && !teamLeadLookup.isLeaderOfTeam(user, team.getId())) {
+                    throw forbidden("Only admins or team leaders can create team-owned resources");
+                }
+                resource.setOwnerTeam(team);
+            }
+        }
+    }
+
+    /** Resource ids of the given type the user or their team holds a grant on. */
+    public Set<String> grantedResourceIds(ResourceType type, User user) {
+        return accessService.grantedResourceIds(type, user);
+    }
+
+    public boolean isAdmin(User user) {
+        return user.getAuthorities().stream()
+                .anyMatch(a -> Role.ADMIN.getRoleId().equals(a.getAuthority()));
+    }
+
+    public boolean isOwner(OwnedResource resource, User user) {
+        if (resource.getOwnerUserId() != null && resource.getOwnerUserId().equals(user.getId())) {
+            return true;
+        }
+        // Team-owned: the lead of the owning team owns it.
+        return resource.getOwnerTeamId() != null
+                && teamLeadLookup.isLeaderOfTeam(user, resource.getOwnerTeamId());
+    }
+
+    private ResponseStatusException forbidden(String message) {
+        return new ResponseStatusException(HttpStatus.FORBIDDEN, message);
+    }
+
+    private ResponseStatusException notFound(String message) {
+        return new ResponseStatusException(HttpStatus.NOT_FOUND, message);
+    }
+}

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

@@ -0,0 +1,188 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import lombok.RequiredArgsConstructor;
+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.PrincipalType;
+import stirling.software.proprietary.access.model.ResourceGrant;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.access.repository.ResourceGrantRepository;
+import stirling.software.proprietary.security.model.User;
+
+/** Resolves access to gated resources: owner, then admin, then grant, then default policy. */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+@Transactional(readOnly = true)
+public class ResourceAccessService {
+
+    private final ResourceGrantRepository grantRepository;
+    private final TeamLeadLookup teamLeadLookup;
+
+    @Value("${security.portal.defaultAccess:ADMINS_AND_TEAM_LEADS}")
+    private DefaultAccessPolicy portalDefaultPolicy;
+
+    // ---- public checks ----
+
+    /** Whether the user may use the portal / processor. */
+    public boolean canAccessPortal(User user) {
+        return canUseResource(ResourceType.PORTAL, "", null, portalDefaultPolicy, user);
+    }
+
+    /** Whether the user may use a resource, falling back to its default policy. */
+    public boolean canUseResource(
+            ResourceType type,
+            String resourceId,
+            Long ownerUserId,
+            DefaultAccessPolicy defaultPolicy,
+            User user) {
+        if (user == null) {
+            return false;
+        }
+        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+            return true;
+        }
+        if (hasGrant(type, normalize(resourceId), user, AccessPermission.USE)) {
+            return true;
+        }
+        return matchesDefault(defaultPolicy, 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) {
+        if (user == null) {
+            return false;
+        }
+        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+            return true;
+        }
+        return hasGrant(type, normalize(resourceId), user, AccessPermission.MANAGE);
+    }
+
+    // ---- grant management ----
+
+    @Transactional
+    public ResourceGrant grant(
+            ResourceType type,
+            String resourceId,
+            PrincipalType principalType,
+            Long principalId,
+            AccessPermission permission,
+            User grantedBy) {
+        String rid = normalize(resourceId);
+        ResourceGrant grant =
+                grantRepository.findByResourceTypeAndResourceId(type, rid).stream()
+                        .filter(
+                                g ->
+                                        g.getPrincipalType() == principalType
+                                                && g.getPrincipalId().equals(principalId))
+                        .findFirst()
+                        .orElseGet(ResourceGrant::new);
+        grant.setResourceType(type);
+        grant.setResourceId(rid);
+        grant.setPrincipalType(principalType);
+        grant.setPrincipalId(principalId);
+        grant.setPermission(permission);
+        if (grantedBy != null) {
+            grant.setGrantedBy(grantedBy);
+        }
+        return grantRepository.save(grant);
+    }
+
+    @Transactional
+    public void revoke(Long grantId) {
+        grantRepository.deleteById(grantId);
+    }
+
+    public List<ResourceGrant> listGrants(ResourceType type, String resourceId) {
+        return grantRepository.findByResourceTypeAndResourceId(type, normalize(resourceId));
+    }
+
+    /** Resource ids of the given type that this user (or their team) holds any 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 (ResourceGrant g :
+                    grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
+                            type, PrincipalType.TEAM, user.getTeam().getId())) {
+                ids.add(g.getResourceId());
+            }
+        }
+        return ids;
+    }
+
+    // ---- internals ----
+
+    private boolean hasGrant(
+            ResourceType type, String resourceId, User user, AccessPermission required) {
+        Long teamId = user.getTeam() != null ? user.getTeam().getId() : null;
+        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)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // MANAGE implies USE.
+    private boolean permissionSatisfies(AccessPermission held, AccessPermission required) {
+        if (required == AccessPermission.USE) {
+            return held == AccessPermission.USE || held == AccessPermission.MANAGE;
+        }
+        return held == AccessPermission.MANAGE;
+    }
+
+    private boolean matchesDefault(DefaultAccessPolicy policy, 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);
+            case EXPLICIT_ONLY -> false;
+        };
+    }
+
+    private boolean isOwner(Long ownerUserId, User user) {
+        return ownerUserId != null && ownerUserId.equals(user.getId());
+    }
+
+    private boolean isAdmin(User user) {
+        return user.getAuthorities().stream()
+                .anyMatch(a -> Role.ADMIN.getRoleId().equals(a.getAuthority()));
+    }
+
+    private String normalize(String resourceId) {
+        return resourceId == null ? "" : resourceId;
+    }
+}

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

@@ -0,0 +1,151 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.stereotype.Component;
+
+/** Masks, merges and sanitizes secret values in a config map, recursing into nested maps/lists. */
+@Component
+public class SecretMasker {
+
+    public static final String MASK = "********";
+
+    // Cap recursion so a pathologically nested payload cannot overflow the stack.
+    private static final int MAX_DEPTH = 32;
+
+    private static final Set<String> SENSITIVE_HINTS =
+            Set.of(
+                    "secret",
+                    "password",
+                    "token",
+                    "apikey",
+                    "accesskey",
+                    "credential",
+                    "privatekey");
+
+    /** Replace sensitive values with the mask (recursively) for safe display. */
+    public Map<String, Object> mask(Map<String, Object> config) {
+        return mask(config, 0);
+    }
+
+    /** Drop sensitive blank/masked values from an incoming create payload. */
+    public Map<String, Object> sanitize(Map<String, Object> config) {
+        return sanitize(config, 0);
+    }
+
+    /**
+     * Merge an update over the stored map, keeping stored secrets where the incoming is redacted.
+     */
+    public Map<String, Object> merge(Map<String, Object> stored, Map<String, Object> incoming) {
+        return merge(stored, incoming, 0);
+    }
+
+    private Map<String, Object> mask(Map<String, Object> config, int depth) {
+        Map<String, Object> out = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> e : config.entrySet()) {
+            out.put(e.getKey(), maskValue(e.getKey(), e.getValue(), depth));
+        }
+        return out;
+    }
+
+    private Map<String, Object> sanitize(Map<String, Object> config, int depth) {
+        if (config == null) {
+            return new LinkedHashMap<>();
+        }
+        Map<String, Object> out = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> e : config.entrySet()) {
+            if (isSensitive(e.getKey()) && isRedacted(e.getValue(), depth)) {
+                continue;
+            }
+            out.put(
+                    e.getKey(),
+                    e.getValue() instanceof Map<?, ?> m && depth < MAX_DEPTH
+                            ? sanitize(castMap(m), depth + 1)
+                            : e.getValue());
+        }
+        return out;
+    }
+
+    private Map<String, Object> merge(
+            Map<String, Object> stored, Map<String, Object> incoming, int depth) {
+        Map<String, Object> out = new LinkedHashMap<>(stored);
+        for (Map.Entry<String, Object> e : incoming.entrySet()) {
+            String key = e.getKey();
+            Object value = e.getValue();
+            if (isSensitive(key)) {
+                if (!isRedacted(value, depth)) {
+                    out.put(key, value); // a real new secret replaces the stored one
+                }
+                continue; // redacted (blank / mask) -> keep stored
+            }
+            if (depth < MAX_DEPTH
+                    && out.get(key) instanceof Map<?, ?> s
+                    && value instanceof Map<?, ?> i) {
+                out.put(key, merge(castMap(s), castMap(i), depth + 1));
+            } else {
+                out.put(key, value);
+            }
+        }
+        return out;
+    }
+
+    // A sensitive key masks its whole value; recurse into non-sensitive containers.
+    private Object maskValue(String key, Object value, int depth) {
+        if (isSensitive(key)) {
+            if (value == null || (value instanceof String s && s.isBlank())) {
+                return value;
+            }
+            return MASK;
+        }
+        if (depth >= MAX_DEPTH) {
+            // Too deep to descend; mask containers rather than risk leaking an unmasked secret.
+            return value instanceof Map<?, ?> || value instanceof List<?> ? MASK : value;
+        }
+        if (value instanceof Map<?, ?> m) {
+            return mask(castMap(m), depth + 1);
+        }
+        if (value instanceof List<?> list) {
+            List<Object> out = new ArrayList<>();
+            for (Object item : list) {
+                out.add(item instanceof Map<?, ?> m ? mask(castMap(m), depth + 1) : item);
+            }
+            return out;
+        }
+        return value;
+    }
+
+    private boolean isSensitive(String key) {
+        String lower = key.toLowerCase(Locale.ROOT);
+        return SENSITIVE_HINTS.stream().anyMatch(lower::contains);
+    }
+
+    /** Blank, the mask placeholder, or any structure that still contains the mask. */
+    private boolean isRedacted(Object value, int depth) {
+        if (value == null) {
+            return true;
+        }
+        if (value instanceof String s) {
+            return s.isBlank() || MASK.equals(s);
+        }
+        if (depth >= MAX_DEPTH) {
+            return false;
+        }
+        if (value instanceof Map<?, ?> m) {
+            return m.values().stream().anyMatch(v -> isRedacted(v, depth + 1));
+        }
+        if (value instanceof List<?> list) {
+            return list.stream().anyMatch(v -> isRedacted(v, depth + 1));
+        }
+        return false;
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> castMap(Map<?, ?> map) {
+        return (Map<String, Object>) map;
+    }
+}

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

@@ -0,0 +1,13 @@
+package stirling.software.proprietary.access.service;
+
+import stirling.software.proprietary.security.model.User;
+
+/** Resolves whether a user leads a team. */
+public interface TeamLeadLookup {
+
+    /** Whether the user leads at least one team. */
+    boolean isAnyTeamLeader(User user);
+
+    /** Whether the user leads the given team. */
+    boolean isLeaderOfTeam(User user, Long teamId);
+}

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

@@ -0,0 +1,116 @@
+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.ClassificationTaxonomy;
+import stirling.software.proprietary.classification.model.TaxonomyValidator;
+import stirling.software.proprietary.classification.store.TaxonomyStore;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+
+/**
+ * Read/write the caller's team classification taxonomy — the vocabulary the document classifier
+ * runs against. Team-scoped exactly like policies: every user reads their own team's taxonomy, and
+ * only a user who may edit policies (a team leader on SaaS, the global admin self-hosted; see
+ * {@link PolicyManagementAuthority}) may change it. Editing is gated only when login is enabled;
+ * single-user deployments trust the local operator. A team with no stored taxonomy reads as {@code
+ * 204} and the classifier falls back to the engine's built-in default.
+ */
+@RestController
+@RequestMapping("/api/v1/classification/taxonomy")
+@Hidden
+@RequiredArgsConstructor
+@Tag(name = "Classification", description = "Team-scoped document-classification taxonomy")
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class TaxonomyController {
+
+    private final TaxonomyStore taxonomyStore;
+    private final PolicyManagementAuthority policyManagementAuthority;
+    private final ApplicationProperties applicationProperties;
+    private final UserServiceInterface userService;
+
+    @GetMapping
+    @Operation(
+            summary = "Get the team's classification taxonomy",
+            description =
+                    "Returns the caller's team taxonomy, or 204 when the team has none (the"
+                            + " classifier then uses the built-in default).")
+    public ResponseEntity<ClassificationTaxonomy> getTaxonomy() {
+        return taxonomyStore
+                .findByTeam(currentTeamId())
+                .map(ResponseEntity::ok)
+                .orElseGet(() -> ResponseEntity.noContent().build());
+    }
+
+    @PutMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
+    @Operation(
+            summary = "Save the team's classification taxonomy",
+            description =
+                    "Validates and stores the taxonomy for the caller's team, shared by everyone on"
+                            + " the team. Requires the policy-editor role for the team.")
+    public ResponseEntity<ClassificationTaxonomy> saveTaxonomy(
+            @RequestBody ClassificationTaxonomy taxonomy) {
+        requireEditingAllowed();
+        try {
+            TaxonomyValidator.validate(taxonomy);
+        } catch (IllegalArgumentException e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+        }
+        ClassificationTaxonomy saved =
+                taxonomyStore.save(currentTeamId(), taxonomy, currentUsername());
+        return ResponseEntity.ok(saved);
+    }
+
+    @DeleteMapping
+    @Operation(
+            summary = "Reset the team's classification taxonomy",
+            description =
+                    "Removes the team's stored taxonomy so the classifier falls back to the built-in"
+                            + " default. Requires the policy-editor role for the team.")
+    public ResponseEntity<Void> resetTaxonomy() {
+        requireEditingAllowed();
+        taxonomyStore.deleteByTeam(currentTeamId());
+        return ResponseEntity.noContent().build();
+    }
+
+    /**
+     * Editing the taxonomy 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 classification taxonomy may only be changed by a team leader");
+        }
+    }
+
+    private Long currentTeamId() {
+        return policyManagementAuthority.currentUserTeamId();
+    }
+
+    private String currentUsername() {
+        return userService == null ? null : userService.getCurrentUsername();
+    }
+}

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

@@ -0,0 +1,18 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * The vocabulary a document is classified against — team-scoped and admin-editable. Its shape
+ * mirrors the engine's {@code ClassificationTaxonomy} contract (categories owning doc_types, plus
+ * free-standing cross-cutting tags), so a stored taxonomy is passed to the engine verbatim as the
+ * per-request override. When a team has no stored taxonomy the engine falls back to its built-in
+ * default.
+ */
+public record ClassificationTaxonomy(List<TaxonomyCategory> categories, List<String> tags) {
+
+    public ClassificationTaxonomy {
+        categories = categories == null ? List.of() : List.copyOf(categories);
+        tags = tags == null ? List.of() : List.copyOf(tags);
+    }
+}

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

@@ -0,0 +1,15 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * A structural family of documents, owning the doc_types shaped like it. {@code docTypes} is
+ * serialized in the engine's camelCase shape (the engine's {@code ClassificationTaxonomy} model
+ * aliases {@code doc_types} onto it), so a stored taxonomy passes straight through to the engine.
+ */
+public record TaxonomyCategory(String id, String label, List<TaxonomyDocumentType> docTypes) {
+
+    public TaxonomyCategory {
+        docTypes = docTypes == null ? List.of() : List.copyOf(docTypes);
+    }
+}

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

@@ -0,0 +1,7 @@
+package stirling.software.proprietary.classification.model;
+
+/**
+ * A specific instrument within a category (e.g. {@code nda} under {@code contract}).
+ * Category-scoped: the engine enforces that a doc_type can only apply to its owning category.
+ */
+public record TaxonomyDocumentType(String id, String label) {}

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

@@ -0,0 +1,87 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Structural validation for an admin-supplied (or imported) taxonomy, run before it is stored so a
+ * malformed vocabulary can never reach the classifier. Mirrors the invariants the engine relies on:
+ * at least one category, non-blank ids/labels everywhere, ids unique among categories and among the
+ * doc_types within a category, and non-blank unique tags.
+ */
+public final class TaxonomyValidator {
+
+    private TaxonomyValidator() {}
+
+    // Generous upper bounds so a legitimate taxonomy is never blocked, but a single team can't
+    // store an unbounded blob that would bloat the row, balloon the classifier prompt, or exhaust
+    // memory on deserialize.
+    static final int MAX_CATEGORIES = 200;
+    static final int MAX_DOC_TYPES_PER_CATEGORY = 200;
+    static final int MAX_TAGS = 500;
+    static final int MAX_TEXT_LENGTH = 128;
+
+    /**
+     * @throws IllegalArgumentException with a human-readable message when the taxonomy is invalid.
+     */
+    public static void validate(ClassificationTaxonomy taxonomy) {
+        if (taxonomy == null) {
+            throw new IllegalArgumentException("Taxonomy is required");
+        }
+        if (taxonomy.categories().isEmpty()) {
+            throw new IllegalArgumentException("Taxonomy must have at least one category");
+        }
+        if (taxonomy.categories().size() > MAX_CATEGORIES) {
+            throw new IllegalArgumentException("Too many categories (max " + MAX_CATEGORIES + ")");
+        }
+        if (taxonomy.tags().size() > MAX_TAGS) {
+            throw new IllegalArgumentException("Too many tags (max " + MAX_TAGS + ")");
+        }
+        Set<String> categoryIds = new HashSet<>();
+        for (TaxonomyCategory category : taxonomy.categories()) {
+            requireText(category.id(), "Category id");
+            requireText(category.label(), "Category label");
+            if (category.docTypes().size() > MAX_DOC_TYPES_PER_CATEGORY) {
+                throw new IllegalArgumentException(
+                        "Too many sub-categories in '"
+                                + category.id()
+                                + "' (max "
+                                + MAX_DOC_TYPES_PER_CATEGORY
+                                + ")");
+            }
+            if (!categoryIds.add(category.id())) {
+                throw new IllegalArgumentException("Duplicate category id: " + category.id());
+            }
+            Set<String> docTypeIds = new HashSet<>();
+            for (TaxonomyDocumentType docType : category.docTypes()) {
+                requireText(docType.id(), "Doc type id");
+                requireText(docType.label(), "Doc type label");
+                if (!docTypeIds.add(docType.id())) {
+                    throw new IllegalArgumentException(
+                            "Duplicate doc type id '"
+                                    + docType.id()
+                                    + "' in category '"
+                                    + category.id()
+                                    + "'");
+                }
+            }
+        }
+        Set<String> tags = new HashSet<>();
+        for (String tag : taxonomy.tags()) {
+            requireText(tag, "Tag");
+            if (!tags.add(tag)) {
+                throw new IllegalArgumentException("Duplicate tag: " + tag);
+            }
+        }
+    }
+
+    private static void requireText(String value, String field) {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException(field + " must not be blank");
+        }
+        if (value.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/InProcessTaxonomyStore.java

@@ -0,0 +1,37 @@
+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.ClassificationTaxonomy;
+
+/**
+ * In-memory {@link TaxonomyStore} for tests and any future no-database mode. {@link
+ * JpaTaxonomyStore} is the runtime bean.
+ */
+public class InProcessTaxonomyStore implements TaxonomyStore {
+
+    private final Map<Long, ClassificationTaxonomy> byTeam = new ConcurrentHashMap<>();
+
+    @Override
+    public Optional<ClassificationTaxonomy> findByTeam(Long teamId) {
+        return Optional.ofNullable(byTeam.get(key(teamId)));
+    }
+
+    @Override
+    public ClassificationTaxonomy save(
+            Long teamId, ClassificationTaxonomy taxonomy, String updatedBy) {
+        byTeam.put(key(teamId), taxonomy);
+        return taxonomy;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        return byTeam.remove(key(teamId)) != null;
+    }
+
+    private static long key(Long teamId) {
+        return teamId == null ? TaxonomyEntity.NO_TEAM : teamId;
+    }
+}

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

@@ -0,0 +1,79 @@
+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.ClassificationTaxonomy;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Durable {@link TaxonomyStore} backed by JPA; the runtime store. Gated on {@code policies.enabled}
+ * — a team taxonomy only matters when the Classification policy can run — so it shares the policy
+ * subsystem's on/off switch. The taxonomy is persisted as JSON via {@link TaxonomyEntity}.
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class JpaTaxonomyStore implements TaxonomyStore {
+
+    private final TaxonomyRepository repository;
+    private final ObjectMapper objectMapper;
+
+    @Override
+    public Optional<ClassificationTaxonomy> findByTeam(Long teamId) {
+        Optional<TaxonomyEntity> entity = repository.findById(key(teamId));
+        if (entity.isEmpty()) {
+            return Optional.empty();
+        }
+        try {
+            return Optional.of(
+                    objectMapper.readValue(
+                            entity.get().getTaxonomyJson(), ClassificationTaxonomy.class));
+        } catch (JacksonException e) {
+            // A stored taxonomy that no longer parses (corruption / manual DB edit) must not break
+            // classification: drop it so the caller falls back to the built-in default rather than
+            // surfacing a 500 on every upload for the team.
+            log.warn(
+                    "Discarding unparseable stored taxonomy for team {}: {}",
+                    teamId,
+                    e.getMessage());
+            return Optional.empty();
+        }
+    }
+
+    @Override
+    public ClassificationTaxonomy save(
+            Long teamId, ClassificationTaxonomy taxonomy, String updatedBy) {
+        TaxonomyEntity entity = new TaxonomyEntity();
+        entity.setTeamId(key(teamId));
+        entity.setTaxonomyJson(objectMapper.writeValueAsString(taxonomy));
+        entity.setUpdatedAt(Instant.now());
+        entity.setUpdatedBy(updatedBy);
+        repository.save(entity);
+        return taxonomy;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        long id = key(teamId);
+        if (!repository.existsById(id)) {
+            return false;
+        }
+        repository.deleteById(id);
+        return true;
+    }
+
+    /** 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 ? TaxonomyEntity.NO_TEAM : teamId;
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/TaxonomyEntity.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 taxonomy — one row per team. The taxonomy lives as JSON in
+ * {@code taxonomyJson} (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_taxonomies")
+@NoArgsConstructor
+@Getter
+@Setter
+public class TaxonomyEntity implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /** Sentinel key for the unteamed taxonomy (login disabled / no resolvable team). */
+    public static final long NO_TEAM = 0L;
+
+    @Id
+    @Column(name = "team_id")
+    private long teamId;
+
+    @Column(name = "taxonomy_json", columnDefinition = "text")
+    private String taxonomyJson;
+
+    @Column(name = "updated_at")
+    private Instant updatedAt;
+
+    @Column(name = "updated_by")
+    private String updatedBy;
+}

app/proprietary/src/main/java/stirling/software/proprietary/classification/store/TaxonomyRepository.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 TaxonomyRepository extends JpaRepository<TaxonomyEntity, Long> {}

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

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

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

@@ -0,0 +1,193 @@
+package stirling.software.proprietary.controller.api;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+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 com.fasterxml.jackson.annotation.JsonInclude;
+
+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.store.TaxonomyStore;
+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, 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 tagged 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 ClassifyTagController {
+
+    /** 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 classification falls back to
+     * the engine's built-in default taxonomy.
+     */
+    private final TaxonomyStore taxonomyStore;
+
+    private final PolicyManagementAuthority policyManagementAuthority;
+
+    public ClassifyTagController(
+            CustomPDFDocumentFactory pdfDocumentFactory,
+            TempFileManager tempFileManager,
+            PdfContentExtractor pdfContentExtractor,
+            PdfMetadataService pdfMetadataService,
+            AiEngineClient aiEngineClient,
+            ObjectMapper objectMapper,
+            @Autowired(required = false) UserServiceInterface userService,
+            @Autowired(required = false) TaxonomyStore taxonomyStore,
+            @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.taxonomyStore = taxonomyStore;
+        this.policyManagementAuthority = policyManagementAuthority;
+    }
+
+    @PostMapping(value = "/classify-and-tag", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Classify a PDF and tag 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> classifyAndTag(
+            @RequestParam("fileInput") MultipartFile fileInput) throws IOException {
+        try (PDDocument document = pdfDocumentFactory.load(fileInput, true)) {
+            String fileName = safeFileName(fileInput.getOriginalFilename());
+
+            List<AiPageText> pages = extractWindow(document);
+            String requestBody =
+                    objectMapper.writeValueAsString(
+                            new ClassifyEngineRequest(fileName, pages, resolveTaxonomyOverride()));
+
+            String userId = userService != null ? userService.getCurrentUsername() : null;
+            String responseJson = aiEngineClient.post(CLASSIFY_ENDPOINT, requestBody, userId);
+
+            pdfMetadataService.setClassificationMetadata(document, toMetadataValue(responseJson));
+            log.debug("[classify-and-tag] tagged {} ({} 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;
+    }
+
+    /**
+     * Resolve the caller's team taxonomy and return it in the engine's shape to classify against;
+     * {@code null} falls back to the engine's generated default. The stored taxonomy is already in
+     * the engine's camelCase shape ({@code categories}/{@code docTypes}/{@code tags}), so it is
+     * passed through verbatim. Returns null when the policy subsystem is disabled (no store), when
+     * the team has no stored taxonomy, or when the team can't be resolved.
+     */
+    private JsonNode resolveTaxonomyOverride() {
+        if (taxonomyStore == null) {
+            return null;
+        }
+        Long teamId =
+                policyManagementAuthority == null
+                        ? null
+                        : policyManagementAuthority.currentUserTeamId();
+        return taxonomyStore
+                .findByTeam(teamId)
+                .map(taxonomy -> (JsonNode) objectMapper.valueToTree(taxonomy))
+                .orElse(null);
+    }
+
+    /** Request body for the engine's {@code /api/v1/documents/classify} endpoint. */
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    private record ClassifyEngineRequest(
+            String fileName, List<AiPageText> pages, JsonNode taxonomy) {}
+}

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

@@ -0,0 +1,81 @@
+package stirling.software.proprietary.integration.controller;
+
+import java.util.List;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+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.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.proprietary.integration.dto.IntegrationConfigRequest;
+import stirling.software.proprietary.integration.dto.IntegrationConfigResponse;
+import stirling.software.proprietary.integration.service.IntegrationConfigService;
+import stirling.software.proprietary.security.model.User;
+
+/** CRUD for S3/MCP/API integration configs. Secrets are never returned. */
+@RestController
+@RequestMapping("/api/v1/integrations")
+@RequiredArgsConstructor
+@PreAuthorize("isAuthenticated()")
+@Tag(name = "Integrations", description = "Manage S3/MCP/API integration configurations")
+public class IntegrationConfigController {
+
+    private final IntegrationConfigService service;
+
+    @GetMapping
+    public ResponseEntity<List<IntegrationConfigResponse>> list(
+            @AuthenticationPrincipal User user) {
+        requireUser(user);
+        return ResponseEntity.ok(
+                service.listVisible(user).stream().map(c -> service.toResponse(c, user)).toList());
+    }
+
+    @PostMapping
+    public ResponseEntity<IntegrationConfigResponse> create(
+            @RequestBody IntegrationConfigRequest request, @AuthenticationPrincipal User user) {
+        requireUser(user);
+        return ResponseEntity.ok(service.toResponse(service.create(request, user), user));
+    }
+
+    @GetMapping("/{id}")
+    public ResponseEntity<IntegrationConfigResponse> get(
+            @PathVariable Long id, @AuthenticationPrincipal User user) {
+        requireUser(user);
+        return ResponseEntity.ok(service.toResponse(service.getForUse(id, user), user));
+    }
+
+    @PutMapping("/{id}")
+    public ResponseEntity<IntegrationConfigResponse> update(
+            @PathVariable Long id,
+            @RequestBody IntegrationConfigRequest request,
+            @AuthenticationPrincipal User user) {
+        requireUser(user);
+        return ResponseEntity.ok(service.toResponse(service.update(id, request, user), user));
+    }
+
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> delete(@PathVariable Long id, @AuthenticationPrincipal User user) {
+        requireUser(user);
+        service.delete(id, user);
+        return ResponseEntity.noContent().build();
+    }
+
+    private void requireUser(User user) {
+        if (user == null) {
+            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "Authentication required");
+        }
+    }
+}

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

@@ -0,0 +1,135 @@
+package stirling.software.proprietary.integration.crypto;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.GeneralSecurityException;
+import java.security.SecureRandom;
+import java.util.Arrays;
+import java.util.Base64;
+
+import javax.crypto.Cipher;
+import javax.crypto.KeyGenerator;
+import javax.crypto.SecretKey;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import jakarta.annotation.PostConstruct;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.configuration.InstallationPathConfig;
+
+/**
+ * AES-256-GCM for stored credentials. Key from property, env var, or an auto-generated key file.
+ */
+@Component
+@Slf4j
+public class CredentialEncryption {
+
+    private static final String ALGORITHM = "AES";
+    private static final String TRANSFORMATION = "AES/GCM/NoPadding";
+    private static final int GCM_TAG_BITS = 128;
+    private static final int IV_BYTES = 12;
+    private static final String KEY_FILE = "credential-encryption.key";
+    private static final SecureRandom RANDOM = new SecureRandom();
+
+    private static volatile SecretKey key;
+
+    private final String configuredKey;
+
+    public CredentialEncryption(
+            @Value("${stirling.security.credentialEncryptionKey:}") String configuredKey) {
+        this.configuredKey = configuredKey;
+    }
+
+    @PostConstruct
+    void init() {
+        key = resolveKey();
+        log.info("Credential encryption initialised (AES-256-GCM)");
+    }
+
+    private SecretKey resolveKey() {
+        String configured = configuredKey;
+        if (configured == null || configured.isBlank()) {
+            configured = System.getenv("STIRLING_CREDENTIAL_ENCRYPTION_KEY");
+        }
+        if (configured != null && !configured.isBlank()) {
+            return new SecretKeySpec(Base64.getDecoder().decode(configured.trim()), ALGORITHM);
+        }
+        return loadOrCreateKeyFile();
+    }
+
+    private SecretKey loadOrCreateKeyFile() {
+        Path path = Path.of(InstallationPathConfig.getConfigPath(), KEY_FILE);
+        try {
+            if (Files.exists(path)) {
+                String encoded = Files.readString(path).trim();
+                return new SecretKeySpec(Base64.getDecoder().decode(encoded), ALGORITHM);
+            }
+            KeyGenerator generator = KeyGenerator.getInstance(ALGORITHM);
+            generator.init(256);
+            SecretKey generated = generator.generateKey();
+            Files.createDirectories(path.getParent());
+            Files.writeString(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.",
+                    path);
+            return generated;
+        } catch (Exception e) {
+            throw new IllegalStateException("Unable to initialise credential encryption key", e);
+        }
+    }
+
+    public static String encrypt(String plaintext) {
+        if (plaintext == null) {
+            return null;
+        }
+        try {
+            byte[] iv = new byte[IV_BYTES];
+            RANDOM.nextBytes(iv);
+            Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+            cipher.init(Cipher.ENCRYPT_MODE, requireKey(), new GCMParameterSpec(GCM_TAG_BITS, iv));
+            byte[] ciphertext = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
+            byte[] combined = new byte[iv.length + ciphertext.length];
+            System.arraycopy(iv, 0, combined, 0, iv.length);
+            System.arraycopy(ciphertext, 0, combined, iv.length, ciphertext.length);
+            return Base64.getEncoder().encodeToString(combined);
+        } catch (GeneralSecurityException e) {
+            throw new IllegalStateException("Failed to encrypt credential", e);
+        }
+    }
+
+    public static String decrypt(String stored) {
+        if (stored == null) {
+            return null;
+        }
+        try {
+            byte[] combined = Base64.getDecoder().decode(stored);
+            byte[] iv = Arrays.copyOfRange(combined, 0, IV_BYTES);
+            byte[] ciphertext = Arrays.copyOfRange(combined, IV_BYTES, combined.length);
+            Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+            cipher.init(Cipher.DECRYPT_MODE, requireKey(), new GCMParameterSpec(GCM_TAG_BITS, iv));
+            return new String(cipher.doFinal(ciphertext), StandardCharsets.UTF_8);
+        } catch (GeneralSecurityException e) {
+            throw new IllegalStateException("Failed to decrypt credential", e);
+        }
+    }
+
+    private static SecretKey requireKey() {
+        SecretKey current = key;
+        if (current == null) {
+            throw new IllegalStateException("Credential encryption not initialised");
+        }
+        return current;
+    }
+
+    /** For tests. */
+    static void initialiseForTesting(SecretKey testKey) {
+        key = testKey;
+    }
+}

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

@@ -0,0 +1,19 @@
+package stirling.software.proprietary.integration.crypto;
+
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+/** Transparently encrypts/decrypts a string column at rest via {@link CredentialEncryption}. */
+@Converter
+public class EncryptedStringConverter implements AttributeConverter<String, String> {
+
+    @Override
+    public String convertToDatabaseColumn(String attribute) {
+        return CredentialEncryption.encrypt(attribute);
+    }
+
+    @Override
+    public String convertToEntityAttribute(String dbData) {
+        return CredentialEncryption.decrypt(dbData);
+    }
+}

app/proprietary/src/main/java/stirling/software/proprietary/integration/dto/IntegrationConfigRequest.java

@@ -0,0 +1,18 @@
+package stirling.software.proprietary.integration.dto;
+
+import java.util.Map;
+
+import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.integration.model.IntegrationType;
+
+/** Create/update payload for an integration config. Sensitive config values left blank are kept. */
+public record IntegrationConfigRequest(
+        IntegrationType integrationType,
+        String name,
+        OwnerScope scope,
+        Long ownerTeamId,
+        Boolean enabled,
+        Boolean locked,
+        DefaultAccessPolicy defaultAccess,
+        Map<String, Object> config) {}

app/proprietary/src/main/java/stirling/software/proprietary/integration/dto/IntegrationConfigResponse.java

@@ -0,0 +1,24 @@
+package stirling.software.proprietary.integration.dto;
+
+import java.time.LocalDateTime;
+import java.util.Map;
+
+import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.integration.model.IntegrationType;
+
+/** Integration config view. Sensitive config values are masked. */
+public record IntegrationConfigResponse(
+        Long id,
+        IntegrationType integrationType,
+        String name,
+        OwnerScope scope,
+        Long ownerUserId,
+        Long ownerTeamId,
+        boolean enabled,
+        boolean locked,
+        DefaultAccessPolicy defaultAccess,
+        Map<String, Object> config,
+        boolean canManage,
+        LocalDateTime createdAt,
+        LocalDateTime updatedAt) {}

app/proprietary/src/main/java/stirling/software/proprietary/integration/model/IntegrationConfig.java

@@ -0,0 +1,67 @@
+package stirling.software.proprietary.integration.model;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Convert;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import stirling.software.proprietary.access.model.OwnedResource;
+import stirling.software.proprietary.integration.crypto.EncryptedStringConverter;
+
+/** A named S3/MCP/API integration config; scope and ownership live on {@link OwnedResource}. */
+@Entity
+@Table(
+        name = "integration_configs",
+        indexes = {
+            @Index(name = "idx_integration_configs_owner", columnList = "owner_user_id"),
+            @Index(name = "idx_integration_configs_type", columnList = "integration_type"),
+            @Index(name = "idx_integration_configs_scope", columnList = "scope")
+        })
+@NoArgsConstructor
+@Getter
+@Setter
+public class IntegrationConfig extends OwnedResource implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "integration_config_id")
+    private Long id;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "integration_type", nullable = false, length = 32)
+    private IntegrationType integrationType;
+
+    @Column(name = "name", nullable = false)
+    private String name;
+
+    // Type-specific fields as an AES-GCM encrypted JSON blob.
+    @Convert(converter = EncryptedStringConverter.class)
+    @Column(name = "config_encrypted", columnDefinition = "text")
+    private String config;
+
+    @CreationTimestamp
+    @Column(name = "created_at", updatable = false)
+    private LocalDateTime createdAt;
+
+    @UpdateTimestamp
+    @Column(name = "updated_at")
+    private LocalDateTime updatedAt;
+}

app/proprietary/src/main/java/stirling/software/proprietary/integration/model/IntegrationType.java

@@ -0,0 +1,8 @@
+package stirling.software.proprietary.integration.model;
+
+/** Kind of external integration a stored config describes. */
+public enum IntegrationType {
+    S3,
+    MCP,
+    API
+}

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

@@ -0,0 +1,21 @@
+package stirling.software.proprietary.integration.repository;
+
+import java.util.List;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.integration.model.IntegrationConfig;
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.User;
+
+@Repository
+public interface IntegrationConfigRepository extends JpaRepository<IntegrationConfig, Long> {
+
+    List<IntegrationConfig> findByOwnerUser(User ownerUser);
+
+    List<IntegrationConfig> findByOwnerTeam(Team ownerTeam);
+
+    List<IntegrationConfig> findByScope(OwnerScope scope);
+}

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

@@ -0,0 +1,226 @@
+package stirling.software.proprietary.integration.service;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+
+import lombok.RequiredArgsConstructor;
+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.service.OwnershipService;
+import stirling.software.proprietary.access.service.SecretMasker;
+import stirling.software.proprietary.integration.dto.IntegrationConfigRequest;
+import stirling.software.proprietary.integration.dto.IntegrationConfigResponse;
+import stirling.software.proprietary.integration.model.IntegrationConfig;
+import stirling.software.proprietary.integration.model.IntegrationType;
+import stirling.software.proprietary.integration.repository.IntegrationConfigRepository;
+import stirling.software.proprietary.security.model.User;
+
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+
+/** CRUD for {@link IntegrationConfig}; delegates ownership and masking to shared services. */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+@Transactional(readOnly = true)
+public class IntegrationConfigService {
+
+    private static final ResourceType TYPE = ResourceType.INTEGRATION_CONFIG;
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    private final IntegrationConfigRepository repository;
+    private final OwnershipService ownership;
+    private final SecretMasker secretMasker;
+
+    // ---- commands ----
+
+    @Transactional
+    public IntegrationConfig create(IntegrationConfigRequest request, User currentUser) {
+        OwnerScope scope = request.scope() == null ? OwnerScope.USER : request.scope();
+        IntegrationConfig cfg = new IntegrationConfig();
+        cfg.setIntegrationType(require(request.integrationType(), "integrationType"));
+        cfg.setName(require(request.name(), "name"));
+        cfg.setEnabled(request.enabled() == null || request.enabled());
+        cfg.setLocked(request.locked() != null && request.locked());
+        cfg.setDefaultAccess(
+                request.defaultAccess() == null
+                        ? DefaultAccessPolicy.EXPLICIT_ONLY
+                        : request.defaultAccess());
+
+        ownership.assignOwnership(
+                cfg,
+                scope,
+                request.ownerTeamId(),
+                currentUser,
+                () -> lockedServerExists(cfg.getIntegrationType()));
+        cfg.setConfig(writeJson(secretMasker.sanitize(request.config())));
+        return repository.save(cfg);
+    }
+
+    @Transactional
+    public IntegrationConfig update(Long id, IntegrationConfigRequest request, User currentUser) {
+        IntegrationConfig cfg = load(id);
+        if (!ownership.canManage(TYPE, cfg, currentUser)) {
+            throw forbidden("You cannot manage this integration");
+        }
+        if (cfg.isLocked() && !ownership.isAdmin(currentUser)) {
+            throw forbidden("This integration is locked by an administrator");
+        }
+        if (request.name() != null) {
+            cfg.setName(request.name());
+        }
+        if (request.enabled() != null) {
+            cfg.setEnabled(request.enabled());
+        }
+        if (request.locked() != null && request.locked() != cfg.isLocked()) {
+            if (!ownership.isAdmin(currentUser)) {
+                throw forbidden("Only administrators can change the locked flag");
+            }
+            cfg.setLocked(request.locked());
+        }
+        if (request.defaultAccess() != null) {
+            cfg.setDefaultAccess(request.defaultAccess());
+        }
+        if (request.config() != null) {
+            cfg.setConfig(
+                    writeJson(secretMasker.merge(readJson(cfg.getConfig()), request.config())));
+        }
+        return repository.save(cfg);
+    }
+
+    @Transactional
+    public void delete(Long id, User currentUser) {
+        IntegrationConfig cfg = load(id);
+        if (!ownership.canManage(TYPE, cfg, currentUser)) {
+            throw forbidden("You cannot manage this integration");
+        }
+        repository.delete(cfg);
+    }
+
+    // ---- queries ----
+
+    public IntegrationConfig getForUse(Long id, User currentUser) {
+        IntegrationConfig cfg = load(id);
+        if (!ownership.canUse(TYPE, cfg, currentUser)) {
+            throw forbidden("You cannot access this integration");
+        }
+        return cfg;
+    }
+
+    /**
+     * All configs the user owns, plus server/team configs and grant-shared configs they may use.
+     */
+    public List<IntegrationConfig> listVisible(User currentUser) {
+        Map<Long, IntegrationConfig> byId = new LinkedHashMap<>();
+        for (IntegrationConfig c : repository.findByOwnerUser(currentUser)) {
+            byId.put(c.getId(), c);
+        }
+        for (IntegrationConfig c : repository.findByScope(OwnerScope.SERVER)) {
+            if (ownership.canUse(TYPE, c, currentUser)) {
+                byId.put(c.getId(), c);
+            }
+        }
+        if (currentUser.getTeam() != null) {
+            for (IntegrationConfig c : repository.findByOwnerTeam(currentUser.getTeam())) {
+                if (ownership.canUse(TYPE, c, currentUser)) {
+                    byId.put(c.getId(), c);
+                }
+            }
+        }
+        for (String rid : ownership.grantedResourceIds(TYPE, currentUser)) {
+            if (rid == null || rid.isBlank()) {
+                continue;
+            }
+            Long cid;
+            try {
+                cid = Long.valueOf(rid);
+            } catch (NumberFormatException e) {
+                continue;
+            }
+            if (byId.containsKey(cid)) {
+                continue;
+            }
+            repository
+                    .findById(cid)
+                    .filter(c -> ownership.canUse(TYPE, c, currentUser))
+                    .ifPresent(c -> byId.put(c.getId(), c));
+        }
+        return new ArrayList<>(byId.values());
+    }
+
+    public IntegrationConfigResponse toResponse(IntegrationConfig cfg, User user) {
+        return new IntegrationConfigResponse(
+                cfg.getId(),
+                cfg.getIntegrationType(),
+                cfg.getName(),
+                cfg.getScope(),
+                cfg.getOwnerUserId(),
+                cfg.getOwnerTeamId(),
+                cfg.isEnabled(),
+                cfg.isLocked(),
+                cfg.getDefaultAccess(),
+                secretMasker.mask(readJson(cfg.getConfig())),
+                ownership.canManage(TYPE, cfg, user),
+                cfg.getCreatedAt(),
+                cfg.getUpdatedAt());
+    }
+
+    // ---- integration-specific glue ----
+
+    /** A non-admin can't create a personal config of a type an admin has locked at server scope. */
+    private boolean lockedServerExists(IntegrationType type) {
+        return repository.findByScope(OwnerScope.SERVER).stream()
+                .anyMatch(c -> c.getIntegrationType() == type && c.isLocked());
+    }
+
+    private IntegrationConfig load(Long id) {
+        return repository
+                .findById(id)
+                .orElseThrow(
+                        () ->
+                                new ResponseStatusException(
+                                        HttpStatus.NOT_FOUND, "Integration not found"));
+    }
+
+    private String writeJson(Map<String, Object> config) {
+        try {
+            return OBJECT_MAPPER.writeValueAsString(config == null ? Map.of() : config);
+        } catch (Exception e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Invalid config payload");
+        }
+    }
+
+    private Map<String, Object> readJson(String json) {
+        if (json == null || json.isBlank()) {
+            return new LinkedHashMap<>();
+        }
+        try {
+            return OBJECT_MAPPER.readValue(
+                    json, new TypeReference<LinkedHashMap<String, Object>>() {});
+        } catch (Exception e) {
+            log.error("Failed to parse integration config JSON", e);
+            return new LinkedHashMap<>();
+        }
+    }
+
+    private <T> T require(T value, String field) {
+        if (value == null || (value instanceof String s && s.isBlank())) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, field + " is required");
+        }
+        return value;
+    }
+
+    private ResponseStatusException forbidden(String message) {
+        return new ResponseStatusException(HttpStatus.FORBIDDEN, message);
+    }
+}

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/policy/engine/PolicyExecutionResult.java

@@ -8,7 +8,11 @@ import tools.jackson.databind.JsonNode;
 
 /**
  * Result of a {@link PolicyExecutor} run. {@code files} are final temp files (not yet stored).
- * {@code report}/{@code reportTool} carry the last step's structured report and its operation, or
- * null if no step produced one.
+ * {@code origins} is parallel to {@code files}: each entry is the index into the original pipeline
+ * inputs that the output traces back to, or {@code null} when it has no single source (e.g. a merge
+ * combining several inputs, or a generated file). Callers use it to map an output back onto the
+ * file it came from. {@code report}/{@code reportTool} carry the last step's structured report and
+ * its operation, or null if no step produced one.
  */
-public record PolicyExecutionResult(List<Resource> files, JsonNode report, String reportTool) {}
+public record PolicyExecutionResult(
+        List<Resource> files, List<Integer> origins, JsonNode report, String reportTool) {}

app/proprietary/src/main/java/stirling/software/proprietary/policy/engine/PolicyExecutor.java

@@ -58,6 +58,11 @@ public class PolicyExecutor {
     // payload the tool surfaced alongside or instead of a file.
     private record ToolResult(List<Resource> files, JsonNode report) {}
 
+    // A step's output files paired with each file's origin (the index into the original pipeline
+    // inputs it traces back to, or null when it has no single source). Origins compose across steps
+    // so the final result can be mapped back onto the files that entered the pipeline.
+    private record StepOutput(List<Resource> files, List<Integer> origins, JsonNode report) {}
+
     /**
      * Run every step in order, feeding each step's output into the next. Supporting files in {@code
      * inputs} bind to named file fields and never enter the document stream.
@@ -75,6 +80,12 @@ public class PolicyExecutor {
 
         List<Resource> currentFiles = inputs.primary();
         Map<String, List<Resource>> supportingFiles = inputs.supportingFiles();
+        // Seed each input with its own index as origin; steps carry these through so the final
+        // outputs can be traced back to the files that entered the pipeline.
+        List<Integer> currentOrigins = new ArrayList<>();
+        for (int k = 0; k < currentFiles.size(); k++) {
+            currentOrigins.add(k);
+        }
         // Last non-null report wins: the terminal step defines the output.
         JsonNode lastReport = null;
         String lastReportTool = null;
@@ -87,8 +98,10 @@ public class PolicyExecutor {
                         "Pipeline step " + (i + 1) + " has no operation");
             }
             listener.onStepStart(i + 1, steps.size(), operation);
-            ToolResult stepResult = executeStep(step, currentFiles, supportingFiles);
+            StepOutput stepResult =
+                    executeStep(step, currentFiles, currentOrigins, supportingFiles);
             currentFiles = stepResult.files();
+            currentOrigins = stepResult.origins();
             if (stepResult.report() != null) {
                 lastReport = stepResult.report();
                 lastReportTool = operation;
@@ -96,7 +109,7 @@ public class PolicyExecutor {
             listener.onStepComplete(i + 1, steps.size(), operation);
         }
 
-        return new PolicyExecutionResult(currentFiles, lastReport, lastReportTool);
+        return new PolicyExecutionResult(currentFiles, currentOrigins, lastReport, lastReportTool);
     }
 
     /**
@@ -104,32 +117,50 @@ public class PolicyExecutor {
      * responses are unpacked so each inner file is its own result (e.g. split). For per-file
      * dispatch the first non-null report wins.
      */
-    private ToolResult executeStep(
+    private StepOutput executeStep(
             PipelineStep step,
             List<Resource> inputFiles,
+            List<Integer> inputOrigins,
             Map<String, List<Resource>> supportingFiles)
             throws IOException {
         requireAcceptedTypes(step.operation(), inputFiles);
         List<Resource> files = new ArrayList<>();
+        List<Integer> origins = new ArrayList<>();
         JsonNode report = null;
         if (toolMetadataService.isMultiInput(step.operation())) {
+            // One call over all inputs. The outputs derive from a single input only when exactly
+            // one entered; otherwise (a genuine merge) there is no single source.
             ToolResult r = callEndpoint(step, inputFiles, supportingFiles);
-            files.addAll(r.files());
+            Integer origin = inputOrigins.size() == 1 ? inputOrigins.get(0) : null;
+            for (Resource file : r.files()) {
+                files.add(file);
+                origins.add(origin);
+            }
             report = r.report();
         } else if (inputFiles.isEmpty()) {
             ToolResult r = callEndpoint(step, List.of(), supportingFiles);
-            files.addAll(r.files());
+            for (Resource file : r.files()) {
+                files.add(file);
+                origins.add(null);
+            }
             report = r.report();
         } else {
-            for (Resource file : inputFiles) {
-                ToolResult r = callEndpoint(step, List.of(file), supportingFiles);
-                files.addAll(r.files());
+            // One call per file: every output of this call inherits that input's origin, so a 1:1
+            // op keeps its chain and a split (one input, many outputs) tags each output with the
+            // same source.
+            for (int k = 0; k < inputFiles.size(); k++) {
+                Integer origin = inputOrigins.get(k);
+                ToolResult r = callEndpoint(step, List.of(inputFiles.get(k)), supportingFiles);
+                for (Resource file : r.files()) {
+                    files.add(file);
+                    origins.add(origin);
+                }
                 if (report == null) {
                     report = r.report();
                 }
             }
         }
-        return new ToolResult(files, report);
+        return new StepOutput(files, origins, report);
     }
 
     /**

app/proprietary/src/main/java/stirling/software/proprietary/security/configuration/DatabaseConfig.java

@@ -33,8 +33,11 @@ import stirling.software.common.model.exception.UnsupportedProviderException;
             "stirling.software.proprietary.storage.repository",
             "stirling.software.proprietary.workflow.repository",
             "stirling.software.proprietary.policy.store",
+            "stirling.software.proprietary.policy.source",
             "stirling.software.proprietary.accountlink",
-            "stirling.software.proprietary.policy.source"
+            "stirling.software.proprietary.access.repository",
+            "stirling.software.proprietary.integration.repository",
+            "stirling.software.proprietary.classification.store"
         })
 @EntityScan({
     "stirling.software.proprietary.security.model",
@@ -42,8 +45,11 @@ import stirling.software.common.model.exception.UnsupportedProviderException;
     "stirling.software.proprietary.storage.model",
     "stirling.software.proprietary.workflow.model",
     "stirling.software.proprietary.policy.store",
+    "stirling.software.proprietary.policy.source",
     "stirling.software.proprietary.accountlink",
-    "stirling.software.proprietary.policy.source"
+    "stirling.software.proprietary.access.model",
+    "stirling.software.proprietary.integration.model",
+    "stirling.software.proprietary.classification.store"
 })
 public class DatabaseConfig {
 

app/proprietary/src/main/java/stirling/software/proprietary/security/controller/api/AuthController.java

@@ -28,6 +28,7 @@ import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.common.constants.JwtConstants;
 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.audit.AuditEventType;
 import stirling.software.proprietary.audit.AuditLevel;
 import stirling.software.proprietary.audit.Audited;
@@ -64,6 +65,7 @@ public class AuthController {
     private final ApplicationProperties.Security securityProperties;
     private final ApplicationProperties applicationProperties;
     private final AiUserDataService aiUserDataService;
+    private final ResourceAccessService resourceAccessService;
 
     /**
      * Login endpoint - replaces Supabase signInWithPassword
@@ -628,6 +630,7 @@ public class AuthController {
         userMap.put("username", user.getUsername());
         userMap.put("role", user.getRolesAsString());
         userMap.put("enabled", user.isEnabled());
+        userMap.put("portalAccess", resourceAccessService.canAccessPortal(user));
         userMap.put(
                 "authenticationType",
                 user.getAuthenticationType()); // Expose authentication type for SSO detection

app/proprietary/src/main/java/stirling/software/proprietary/service/AiWorkflowService.java

@@ -352,6 +352,7 @@ public class AiWorkflowService {
 
         try {
             List<Resource> resultFiles = new ArrayList<>();
+            List<Integer> origins = new ArrayList<>();
             List<String> inputNames = new ArrayList<>();
             for (int i = 0; i < filesToConvert.size(); i++) {
                 AiFile file = filesToConvert.get(i);
@@ -376,11 +377,15 @@ public class AiWorkflowService {
                                 definition,
                                 PolicyInputs.of(List.of(input)),
                                 PolicyProgressListener.NOOP);
-                resultFiles.addAll(result.files());
+                // Each conversion runs on one input, so every output traces back to file i.
+                for (Resource output : result.files()) {
+                    resultFiles.add(output);
+                    origins.add(i);
+                }
                 inputNames.add(multipartFile.getOriginalFilename());
             }
             return new WorkflowState.Terminal(
-                    buildCompletedResponse(null, resultFiles, inputNames, null));
+                    buildCompletedResponse(null, resultFiles, origins, inputNames, null));
         } catch (InternalApiTimeoutException e) {
             log.error("PDF to Markdown conversion timed out: {}", e.getMessage());
             return new WorkflowState.Terminal(
@@ -472,6 +477,7 @@ public class AiWorkflowService {
                     buildCompletedResponse(
                             response.getRationale(),
                             result.files(),
+                            result.origins(),
                             inputFileNames(filesById),
                             result.report()));
         } catch (InternalApiTimeoutException e) {
@@ -533,7 +539,8 @@ public class AiWorkflowService {
                     }
                 };
         return new WorkflowState.Terminal(
-                buildCompletedResponse(response.getSummary(), List.of(resource), List.of(), null));
+                buildCompletedResponse(
+                        response.getSummary(), List.of(resource), null, List.of(), null));
     }
 
     @SuppressWarnings("unchecked")
@@ -591,7 +598,11 @@ public class AiWorkflowService {
 
             return new WorkflowState.Terminal(
                     buildCompletedResponse(
-                            summary, result.files(), inputFileNames(filesById), result.report()));
+                            summary,
+                            result.files(),
+                            result.origins(),
+                            inputFileNames(filesById),
+                            result.report()));
         } catch (InternalApiTimeoutException e) {
             log.error("Plan step on tool {} timed out: {}", e.getEndpointPath(), e.getMessage());
             return new WorkflowState.Terminal(
@@ -680,19 +691,35 @@ public class AiWorkflowService {
     private AiWorkflowResponse buildCompletedResponse(
             String summary,
             List<Resource> resultFiles,
+            List<Integer> origins,
             List<String> inputFileNames,
             JsonNode report)
             throws IOException {
         // Store every output file individually so each gets its own Stirling file ID and the
         // frontend can add them as independent variants without going through a zip.
-        boolean preserveInputNames = inputFileNames.size() == resultFiles.size();
+        // Count outputs per source so only a clean 1:1 transform (one output for a source) reuses
+        // the input's name; a split (one input → many outputs) keeps each entry's own name.
+        Map<Integer, Long> outputsPerOrigin =
+                origins == null
+                        ? Map.of()
+                        : origins.stream()
+                                .filter(o -> o != null)
+                                .collect(Collectors.groupingBy(o -> o, Collectors.counting()));
         List<AiWorkflowResultFile> descriptors = new ArrayList<>();
         for (int i = 0; i < resultFiles.size(); i++) {
             Resource resource = resultFiles.get(i);
             String responseName = resource.getFilename();
-            String inputName = preserveInputNames ? inputFileNames.get(i) : null;
-            // Prefer the input name only for 1:1 operations where the output keeps the same
-            // extension (rotate, compress, etc.). For converters and other extension-changing
+            // The output's source input (from the executor), used both to name it and to tell the
+            // client which file to version in place.
+            Integer origin = origins != null && i < origins.size() ? origins.get(i) : null;
+            boolean uniqueOrigin =
+                    origin != null && outputsPerOrigin.getOrDefault(origin, 0L) == 1L;
+            String inputName =
+                    uniqueOrigin && origin >= 0 && origin < inputFileNames.size()
+                            ? inputFileNames.get(origin)
+                            : null;
+            // Prefer the source input's name only for 1:1 operations where the output keeps the
+            // same extension (rotate, compress, etc.). For converters and other extension-changing
             // tools, the response filename from Content-Disposition is authoritative.
             String name;
             if (inputName != null
@@ -712,7 +739,11 @@ public class AiWorkflowService {
             try (java.io.InputStream is = resource.getInputStream()) {
                 fileId = fileStorage.storeInputStream(is, name).fileId();
             }
-            descriptors.add(new AiWorkflowResultFile(fileId, name, contentType));
+            // Only expose the source when this is a clean 1:1 transform, so the client can treat a
+            // present sourceIndex as "replace that input in place" without further disambiguation.
+            descriptors.add(
+                    new AiWorkflowResultFile(
+                            fileId, name, contentType, uniqueOrigin ? origin : null));
         }
 
         AiWorkflowResponse completed = new AiWorkflowResponse();

app/proprietary/src/test/java/stirling/software/proprietary/access/service/OwnershipServiceTest.java

@@ -0,0 +1,174 @@
+package stirling.software.proprietary.access.service;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+
+import java.util.Optional;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+import stirling.software.proprietary.access.model.OwnedResource;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.Authority;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamRepository;
+
+@ExtendWith(MockitoExtension.class)
+class OwnershipServiceTest {
+
+    private static final ResourceType TYPE = ResourceType.INTEGRATION_CONFIG;
+
+    @Mock private ResourceAccessService accessService;
+    @Mock private TeamLeadLookup teamLeadLookup;
+    @Mock private TeamRepository teamRepository;
+
+    @InjectMocks private OwnershipService ownership;
+
+    /** Minimal concrete OwnedResource for exercising the base behaviour. */
+    static class TestResource extends OwnedResource {
+        private final Long id;
+
+        TestResource(Long id) {
+            this.id = id;
+        }
+
+        @Override
+        public Long getId() {
+            return id;
+        }
+    }
+
+    // ---- scope-based create authorization ----
+
+    @Test
+    void userScopeSetsOwner() {
+        User user = user(7);
+        TestResource r = new TestResource(1L);
+
+        ownership.assignOwnership(r, OwnerScope.USER, null, user, () -> false);
+
+        assertThat(r.getScope()).isEqualTo(OwnerScope.USER);
+        assertThat(r.getOwnerUser()).isSameAs(user);
+    }
+
+    @Test
+    void userScopeBlockedByLockedServerOverride() {
+        assertForbidden(
+                () ->
+                        ownership.assignOwnership(
+                                new TestResource(1L), OwnerScope.USER, null, user(7), () -> true));
+    }
+
+    @Test
+    void adminMayCreateServerScope() {
+        TestResource r = new TestResource(1L);
+        ownership.assignOwnership(r, OwnerScope.SERVER, null, admin(1), () -> false);
+        assertThat(r.getOwnerUser()).isNull();
+    }
+
+    @Test
+    void nonAdminCannotCreateServerScope() {
+        assertForbidden(
+                () ->
+                        ownership.assignOwnership(
+                                new TestResource(1L),
+                                OwnerScope.SERVER,
+                                null,
+                                user(7),
+                                () -> false));
+    }
+
+    @Test
+    void teamLeaderMayCreateTeamScope() {
+        Team team = new Team();
+        team.setId(5L);
+        User user = user(7);
+        when(teamRepository.findById(5L)).thenReturn(Optional.of(team));
+        when(teamLeadLookup.isLeaderOfTeam(user, 5L)).thenReturn(true);
+
+        TestResource r = new TestResource(1L);
+        ownership.assignOwnership(r, OwnerScope.TEAM, 5L, user, () -> false);
+
+        assertThat(r.getOwnerTeam()).isSameAs(team);
+    }
+
+    @Test
+    void nonLeaderCannotCreateTeamScope() {
+        Team team = new Team();
+        team.setId(5L);
+        when(teamRepository.findById(5L)).thenReturn(Optional.of(team));
+
+        assertForbidden(
+                () ->
+                        ownership.assignOwnership(
+                                new TestResource(1L), OwnerScope.TEAM, 5L, user(7), () -> false));
+    }
+
+    // ---- use / manage ----
+
+    @Test
+    void enabledResourceUseDelegatesToTheAcl() {
+        TestResource r = new TestResource(1L);
+        User user = user(7);
+        when(accessService.canUseResource(any(), any(), any(), any(), any())).thenReturn(true);
+
+        assertThat(ownership.canUse(TYPE, r, user)).isTrue();
+    }
+
+    @Test
+    void disabledResourceUsableOnlyByOwnerOrAdmin() {
+        TestResource r = new TestResource(1L);
+        r.setEnabled(false);
+        r.setOwnerUser(user(7));
+
+        assertThat(ownership.canUse(TYPE, r, user(7))).isTrue(); // owner
+        assertThat(ownership.canUse(TYPE, r, user(8))).isFalse(); // someone else
+        assertThat(ownership.canUse(TYPE, r, admin(2))).isTrue(); // admin
+    }
+
+    @Test
+    void disabledTeamResourceUsableByLeaderOfOwningTeam() {
+        Team team = new Team();
+        team.setId(5L);
+        TestResource r = new TestResource(1L);
+        r.setEnabled(false);
+        r.setOwnerTeam(team);
+        User leader = user(7);
+        when(teamLeadLookup.isLeaderOfTeam(leader, 5L)).thenReturn(true);
+
+        assertThat(ownership.canUse(TYPE, r, leader)).isTrue(); // lead of the owning team
+        assertThat(ownership.canUse(TYPE, r, user(8))).isFalse(); // not a lead
+    }
+
+    // ---- helpers ----
+
+    private void assertForbidden(org.assertj.core.api.ThrowableAssert.ThrowingCallable call) {
+        assertThatThrownBy(call)
+                .isInstanceOf(ResponseStatusException.class)
+                .extracting(e -> ((ResponseStatusException) e).getStatusCode())
+                .isEqualTo(HttpStatus.FORBIDDEN);
+    }
+
+    private User user(long id) {
+        User u = new User();
+        u.setId(id);
+        u.setUsername("user" + id);
+        return u;
+    }
+
+    private User admin(long id) {
+        User u = user(id);
+        new Authority("ROLE_ADMIN", u);
+        return u;
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/access/service/ResourceAccessServiceTest.java

@@ -0,0 +1,217 @@
+package stirling.software.proprietary.access.service;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Field;
+import java.util.List;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import stirling.software.proprietary.access.model.AccessPermission;
+import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+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.repository.ResourceGrantRepository;
+import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.security.model.Authority;
+import stirling.software.proprietary.security.model.User;
+
+@ExtendWith(MockitoExtension.class)
+class ResourceAccessServiceTest {
+
+    private static final ResourceType TYPE = ResourceType.INTEGRATION_CONFIG;
+    private static final String RID = "42";
+
+    @Mock private ResourceGrantRepository grantRepository;
+    @Mock private TeamLeadLookup teamLeadLookup;
+
+    @InjectMocks private ResourceAccessService service;
+
+    @BeforeEach
+    void setPortalDefault() throws Exception {
+        Field f = ResourceAccessService.class.getDeclaredField("portalDefaultPolicy");
+        f.setAccessible(true);
+        f.set(service, DefaultAccessPolicy.ADMINS_AND_TEAM_LEADS);
+    }
+
+    // ---- owner / admin short-circuits ----
+
+    @Test
+    void adminMayUseEvenWithExplicitOnlyAndNoGrants() {
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, null, DefaultAccessPolicy.EXPLICIT_ONLY, admin(1)))
+                .isTrue();
+    }
+
+    @Test
+    void ownerMayUseEvenWithExplicitOnly() {
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, 5L, DefaultAccessPolicy.EXPLICIT_ONLY, user(5)))
+                .isTrue();
+    }
+
+    @Test
+    void nullUserIsAlwaysDenied() {
+        assertThat(service.canUseResource(TYPE, RID, 5L, DefaultAccessPolicy.ORG_ALL, null))
+                .isFalse();
+        assertThat(service.canManageResource(TYPE, RID, 5L, null)).isFalse();
+    }
+
+    // ---- explicit grants ----
+
+    @Test
+    void explicitUserGrantAllowsUse() {
+        stubGrants(grant(PrincipalType.USER, 5L, AccessPermission.USE));
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, null, DefaultAccessPolicy.EXPLICIT_ONLY, user(5)))
+                .isTrue();
+    }
+
+    @Test
+    void teamGrantAllowsUseForTeamMember() {
+        stubGrants(grant(PrincipalType.TEAM, 7L, AccessPermission.USE));
+        assertThat(
+                        service.canUseResource(
+                                TYPE,
+                                RID,
+                                null,
+                                DefaultAccessPolicy.EXPLICIT_ONLY,
+                                userInTeam(5, 7)))
+                .isTrue();
+    }
+
+    @Test
+    void teamGrantDoesNotLeakToOtherTeams() {
+        stubGrants(grant(PrincipalType.TEAM, 7L, AccessPermission.USE));
+        assertThat(
+                        service.canUseResource(
+                                TYPE,
+                                RID,
+                                null,
+                                DefaultAccessPolicy.EXPLICIT_ONLY,
+                                userInTeam(5, 99)))
+                .isFalse();
+    }
+
+    @Test
+    void manageGrantImpliesUse() {
+        stubGrants(grant(PrincipalType.USER, 5L, AccessPermission.MANAGE));
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, null, DefaultAccessPolicy.EXPLICIT_ONLY, user(5)))
+                .isTrue();
+    }
+
+    @Test
+    void useGrantDoesNotImplyManage() {
+        stubGrants(grant(PrincipalType.USER, 5L, AccessPermission.USE));
+        assertThat(service.canManageResource(TYPE, RID, null, user(5))).isFalse();
+    }
+
+    @Test
+    void manageGrantAllowsManage() {
+        stubGrants(grant(PrincipalType.USER, 5L, AccessPermission.MANAGE));
+        assertThat(service.canManageResource(TYPE, RID, null, user(5))).isTrue();
+    }
+
+    // ---- default policies ----
+
+    @Test
+    void orgAllDefaultAllowsAnyUser() {
+        stubGrants();
+        assertThat(service.canUseResource(TYPE, RID, null, DefaultAccessPolicy.ORG_ALL, user(5)))
+                .isTrue();
+    }
+
+    @Test
+    void explicitOnlyDefaultDeniesUngrantedUser() {
+        stubGrants();
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, null, DefaultAccessPolicy.EXPLICIT_ONLY, user(5)))
+                .isFalse();
+    }
+
+    @Test
+    void teamLeadDefaultAllowsLeaderButNotRegularUser() {
+        stubGrants();
+        User leader = user(5);
+        when(teamLeadLookup.isAnyTeamLeader(leader)).thenReturn(true);
+        assertThat(
+                        service.canUseResource(
+                                TYPE, RID, null, DefaultAccessPolicy.ADMINS_AND_TEAM_LEADS, leader))
+                .isTrue();
+
+        stubGrants();
+        assertThat(
+                        service.canUseResource(
+                                TYPE,
+                                RID,
+                                null,
+                                DefaultAccessPolicy.ADMINS_AND_TEAM_LEADS,
+                                user(6)))
+                .isFalse();
+    }
+
+    // ---- portal convenience (default policy ADMINS_AND_TEAM_LEADS) ----
+
+    @Test
+    void portalAccessibleByAdmin() {
+        assertThat(service.canAccessPortal(admin(1))).isTrue();
+    }
+
+    @Test
+    void portalDeniedToRegularUser() {
+        when(grantRepository.findByResourceTypeAndResourceId(ResourceType.PORTAL, ""))
+                .thenReturn(List.of());
+        assertThat(service.canAccessPortal(user(5))).isFalse();
+    }
+
+    // ---- helpers ----
+
+    private void stubGrants(ResourceGrant... grants) {
+        when(grantRepository.findByResourceTypeAndResourceId(TYPE, RID))
+                .thenReturn(List.of(grants));
+    }
+
+    private ResourceGrant grant(PrincipalType type, long principalId, AccessPermission permission) {
+        ResourceGrant g = new ResourceGrant();
+        g.setResourceType(TYPE);
+        g.setResourceId(RID);
+        g.setPrincipalType(type);
+        g.setPrincipalId(principalId);
+        g.setPermission(permission);
+        return g;
+    }
+
+    private User user(long id) {
+        User u = new User();
+        u.setId(id);
+        u.setUsername("user" + id);
+        return u;
+    }
+
+    private User admin(long id) {
+        User u = user(id);
+        new Authority("ROLE_ADMIN", u);
+        return u;
+    }
+
+    private User userInTeam(long id, long teamId) {
+        User u = user(id);
+        Team team = new Team();
+        team.setId(teamId);
+        u.setTeam(team);
+        return u;
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/access/service/SecretMaskerTest.java

@@ -0,0 +1,80 @@
+package stirling.software.proprietary.access.service;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+class SecretMaskerTest {
+
+    private final SecretMasker masker = new SecretMasker();
+
+    @Test
+    void maskHidesFlatAndNestedSecretsButKeepsPlainFields() {
+        Map<String, Object> nested = new LinkedHashMap<>();
+        nested.put("host", "h.example");
+        nested.put("secretKey", "sk-real");
+        Map<String, Object> config = new LinkedHashMap<>();
+        config.put("bucket", "acme");
+        config.put("accessKey", "AKIA123");
+        config.put("connection", nested); // non-sensitive parent, sensitive child
+
+        Map<String, Object> masked = masker.mask(config);
+
+        assertThat(masked.get("bucket")).isEqualTo("acme");
+        assertThat(masked.get("accessKey")).isEqualTo(SecretMasker.MASK);
+        @SuppressWarnings("unchecked")
+        Map<String, Object> conn = (Map<String, Object>) masked.get("connection");
+        assertThat(conn.get("host")).isEqualTo("h.example");
+        assertThat(conn.get("secretKey")).isEqualTo(SecretMasker.MASK);
+    }
+
+    @Test
+    void mergeKeepsStoredSecretWhenIncomingIsMasked() {
+        Map<String, Object> stored = Map.of("bucket", "old", "secretKey", "REAL");
+        Map<String, Object> incoming = Map.of("bucket", "new", "secretKey", SecretMasker.MASK);
+
+        Map<String, Object> merged = masker.merge(stored, incoming);
+
+        assertThat(merged.get("bucket")).isEqualTo("new"); // non-secret updated
+        assertThat(merged.get("secretKey")).isEqualTo("REAL"); // secret retained
+    }
+
+    @Test
+    void mergeAcceptsARealNewSecret() {
+        Map<String, Object> merged =
+                masker.merge(Map.of("secretKey", "OLD"), Map.of("secretKey", "NEW"));
+        assertThat(merged.get("secretKey")).isEqualTo("NEW");
+    }
+
+    @Test
+    void sanitizeDropsBlankSecretsOnCreate() {
+        Map<String, Object> incoming = new LinkedHashMap<>();
+        incoming.put("bucket", "b");
+        incoming.put("secretKey", "");
+
+        Map<String, Object> clean = masker.sanitize(incoming);
+
+        assertThat(clean).containsEntry("bucket", "b").doesNotContainKey("secretKey");
+    }
+
+    @Test
+    void deeplyNestedInputIsBoundedNotOverflowing() {
+        // Build a structure far deeper than the recursion cap.
+        Map<String, Object> root = new LinkedHashMap<>();
+        Map<String, Object> cur = root;
+        for (int i = 0; i < 2000; i++) {
+            Map<String, Object> next = new LinkedHashMap<>();
+            cur.put("child", next);
+            cur = next;
+        }
+        cur.put("secretKey", "deep");
+
+        // Must return (bounded recursion), not throw StackOverflowError.
+        assertThat(masker.mask(root)).isNotNull();
+        assertThat(masker.sanitize(root)).isNotNull();
+        assertThat(masker.merge(root, root)).isNotNull();
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/classification/TaxonomyControllerTest.java

@@ -0,0 +1,134 @@
+package stirling.software.proprietary.classification;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.server.ResponseStatusException;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.proprietary.classification.model.ClassificationTaxonomy;
+import stirling.software.proprietary.classification.model.TaxonomyCategory;
+import stirling.software.proprietary.classification.model.TaxonomyDocumentType;
+import stirling.software.proprietary.classification.store.InProcessTaxonomyStore;
+import stirling.software.proprietary.classification.store.TaxonomyStore;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+
+@ExtendWith(MockitoExtension.class)
+@DisplayName("TaxonomyController")
+class TaxonomyControllerTest {
+
+    private static final Long TEAM = 7L;
+
+    @Mock private PolicyManagementAuthority policyManagementAuthority;
+    @Mock private UserServiceInterface userService;
+
+    private TaxonomyStore store;
+    private ApplicationProperties applicationProperties;
+    private TaxonomyController controller;
+
+    @BeforeEach
+    void setUp() {
+        store = new InProcessTaxonomyStore();
+        applicationProperties = new ApplicationProperties();
+        controller =
+                new TaxonomyController(
+                        store, policyManagementAuthority, applicationProperties, userService);
+    }
+
+    private static ClassificationTaxonomy sample() {
+        return new ClassificationTaxonomy(
+                List.of(
+                        new TaxonomyCategory(
+                                "invoice",
+                                "Invoice",
+                                List.of(new TaxonomyDocumentType("receipt", "Receipt")))),
+                List.of("finance"));
+    }
+
+    private void loginEnabled(boolean enabled) {
+        applicationProperties.getSecurity().setEnableLogin(enabled);
+    }
+
+    @Test
+    @DisplayName("GET returns 204 when the team has no taxonomy")
+    void getEmpty() {
+        when(policyManagementAuthority.currentUserTeamId()).thenReturn(TEAM);
+        ResponseEntity<ClassificationTaxonomy> response = controller.getTaxonomy();
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
+    }
+
+    @Test
+    @DisplayName("PUT then GET round-trips the team's taxonomy (login disabled)")
+    void saveThenGet() {
+        loginEnabled(false);
+        when(policyManagementAuthority.currentUserTeamId()).thenReturn(TEAM);
+
+        controller.saveTaxonomy(sample());
+        ResponseEntity<ClassificationTaxonomy> got = controller.getTaxonomy();
+
+        assertThat(got.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(got.getBody()).isNotNull();
+        assertThat(got.getBody().categories()).hasSize(1);
+        assertThat(got.getBody().categories().getFirst().id()).isEqualTo("invoice");
+    }
+
+    @Test
+    @DisplayName("PUT is scoped per team")
+    void perTeam() {
+        loginEnabled(false);
+        when(policyManagementAuthority.currentUserTeamId()).thenReturn(TEAM);
+        controller.saveTaxonomy(sample());
+
+        when(policyManagementAuthority.currentUserTeamId()).thenReturn(99L);
+        assertThat(controller.getTaxonomy().getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
+    }
+
+    @Test
+    @DisplayName("PUT is rejected for a non-editor when login is enabled")
+    void putForbiddenForNonEditor() {
+        loginEnabled(true);
+        when(policyManagementAuthority.canEditPolicies()).thenReturn(false);
+
+        assertThatThrownBy(() -> controller.saveTaxonomy(sample()))
+                .isInstanceOf(ResponseStatusException.class)
+                .hasFieldOrPropertyWithValue("statusCode", HttpStatus.FORBIDDEN);
+    }
+
+    @Test
+    @DisplayName("PUT rejects an invalid taxonomy with 400")
+    void putInvalid() {
+        loginEnabled(false);
+
+        assertThatThrownBy(
+                        () ->
+                                controller.saveTaxonomy(
+                                        new ClassificationTaxonomy(List.of(), List.of())))
+                .isInstanceOf(ResponseStatusException.class)
+                .hasFieldOrPropertyWithValue("statusCode", HttpStatus.BAD_REQUEST);
+    }
+
+    @Test
+    @DisplayName("DELETE resets the team back to no stored taxonomy")
+    void deleteResets() {
+        loginEnabled(false);
+        when(policyManagementAuthority.currentUserTeamId()).thenReturn(TEAM);
+        controller.saveTaxonomy(sample());
+
+        ResponseEntity<Void> response = controller.resetTaxonomy();
+
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
+        assertThat(controller.getTaxonomy().getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/classification/model/TaxonomyValidatorTest.java

@@ -0,0 +1,110 @@
+package stirling.software.proprietary.classification.model;
+
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.List;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("TaxonomyValidator")
+class TaxonomyValidatorTest {
+
+    private static TaxonomyCategory category(String id, TaxonomyDocumentType... docTypes) {
+        return new TaxonomyCategory(id, id + " label", List.of(docTypes));
+    }
+
+    private static TaxonomyDocumentType docType(String id) {
+        return new TaxonomyDocumentType(id, id + " label");
+    }
+
+    @Test
+    @DisplayName("accepts a well-formed taxonomy")
+    void acceptsValid() {
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(category("invoice", docType("receipt")), category("contract")),
+                        List.of("finance", "legal"));
+        assertThatCode(() -> TaxonomyValidator.validate(taxonomy)).doesNotThrowAnyException();
+    }
+
+    @Test
+    @DisplayName("rejects a taxonomy with no categories")
+    void rejectsEmpty() {
+        ClassificationTaxonomy taxonomy = new ClassificationTaxonomy(List.of(), List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("at least one category");
+    }
+
+    @Test
+    @DisplayName("rejects duplicate category ids")
+    void rejectsDuplicateCategory() {
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(category("invoice"), category("invoice")), List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("Duplicate category id");
+    }
+
+    @Test
+    @DisplayName("rejects duplicate doc type ids within a category")
+    void rejectsDuplicateDocType() {
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(category("invoice", docType("receipt"), docType("receipt"))),
+                        List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("Duplicate doc type id");
+    }
+
+    @Test
+    @DisplayName("rejects blank ids and labels")
+    void rejectsBlank() {
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(new TaxonomyCategory(" ", "label", List.of())), List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("must not be blank");
+    }
+
+    @Test
+    @DisplayName("rejects duplicate tags")
+    void rejectsDuplicateTags() {
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(category("invoice")), List.of("finance", "finance"));
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("Duplicate tag");
+    }
+
+    @Test
+    @DisplayName("rejects more categories than the cap")
+    void rejectsTooManyCategories() {
+        List<TaxonomyCategory> categories =
+                java.util.stream.IntStream.rangeClosed(0, TaxonomyValidator.MAX_CATEGORIES)
+                        .mapToObj(i -> category("cat" + i))
+                        .toList();
+        ClassificationTaxonomy taxonomy = new ClassificationTaxonomy(categories, List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("Too many categories");
+    }
+
+    @Test
+    @DisplayName("rejects an over-long label")
+    void rejectsOverLongLabel() {
+        String longLabel = "x".repeat(TaxonomyValidator.MAX_TEXT_LENGTH + 1);
+        ClassificationTaxonomy taxonomy =
+                new ClassificationTaxonomy(
+                        List.of(new TaxonomyCategory("invoice", longLabel, List.of())), List.of());
+        assertThatThrownBy(() -> TaxonomyValidator.validate(taxonomy))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("too long");
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/controller/api/ClassifyTagControllerTest.java

@@ -0,0 +1,105 @@
+package stirling.software.proprietary.controller.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.mockito.junit.jupiter.MockitoSettings;
+import org.mockito.quality.Strictness;
+import org.springframework.web.multipart.MultipartFile;
+
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.PdfMetadataService;
+import stirling.software.common.util.TempFileManager;
+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.json.JsonMapper;
+
+@ExtendWith(MockitoExtension.class)
+@MockitoSettings(strictness = Strictness.LENIENT)
+class ClassifyTagControllerTest {
+
+    @Mock private CustomPDFDocumentFactory pdfDocumentFactory;
+    @Mock private TempFileManager tempFileManager;
+    @Mock private PdfContentExtractor pdfContentExtractor;
+    @Mock private PdfMetadataService pdfMetadataService;
+    @Mock private AiEngineClient aiEngineClient;
+
+    private final ObjectMapper objectMapper = JsonMapper.builder().build();
+    private ClassifyTagController controller;
+
+    @BeforeEach
+    void setUp() {
+        controller =
+                new ClassifyTagController(
+                        pdfDocumentFactory,
+                        tempFileManager,
+                        pdfContentExtractor,
+                        pdfMetadataService,
+                        aiEngineClient,
+                        objectMapper,
+                        null,
+                        null,
+                        null);
+    }
+
+    @Test
+    void classifyAndTag_writesClassificationWithoutOutcome() throws Exception {
+        PDDocument document = mock(PDDocument.class);
+        MultipartFile file = mock(MultipartFile.class);
+        when(file.getOriginalFilename()).thenReturn("invoice.pdf");
+        when(pdfDocumentFactory.load(any(MultipartFile.class), eq(true))).thenReturn(document);
+        when(document.getNumberOfPages()).thenReturn(1);
+        when(pdfContentExtractor.extractPageTextRaw(document, 1))
+                .thenReturn("Invoice total due 100.00");
+        when(aiEngineClient.post(eq("/api/v1/documents/classify"), anyString(), isNull()))
+                .thenReturn(
+                        "{\"outcome\":\"classification\",\"category\":\"invoice\","
+                                + "\"docType\":\"invoice\",\"typeConfidence\":0.98,"
+                                + "\"tags\":[\"finance\"]}");
+
+        try {
+            controller.classifyAndTag(file);
+        } catch (Exception ignored) {
+            // WebResponseUtils.pdfDocToWebResponse needs a real temp file; the metadata write we
+            // assert on has already happened by the time it runs.
+        }
+
+        ArgumentCaptor<String> value = ArgumentCaptor.forClass(String.class);
+        verify(pdfMetadataService).setClassificationMetadata(eq(document), value.capture());
+
+        JsonNode written = objectMapper.readTree(value.getValue());
+        assertThat(written.has("outcome")).isFalse();
+        assertThat(written.get("category").asText()).isEqualTo("invoice");
+        assertThat(written.get("docType").asText()).isEqualTo("invoice");
+        assertThat(written.get("tags").get(0).asText()).isEqualTo("finance");
+    }
+
+    @Test
+    void windowPageNumbers_takesFirstAndLastWithoutOverlap() {
+        assertEquals(List.of(1, 2, 4, 5), ClassifyTagController.windowPageNumbers(5, 2));
+        assertEquals(List.of(1, 2, 3), ClassifyTagController.windowPageNumbers(3, 2));
+        // Short docs clamp + dedupe rather than throwing or going out of range.
+        assertEquals(List.of(1, 2), ClassifyTagController.windowPageNumbers(2, 2));
+        assertEquals(List.of(1), ClassifyTagController.windowPageNumbers(1, 2));
+        assertEquals(List.of(), ClassifyTagController.windowPageNumbers(0, 2));
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/integration/crypto/CredentialEncryptionTest.java

@@ -0,0 +1,64 @@
+package stirling.software.proprietary.integration.crypto;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.Base64;
+
+import javax.crypto.KeyGenerator;
+import javax.crypto.SecretKey;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class CredentialEncryptionTest {
+
+    @BeforeAll
+    static void initKey() throws Exception {
+        KeyGenerator generator = KeyGenerator.getInstance("AES");
+        generator.init(256);
+        SecretKey key = generator.generateKey();
+        CredentialEncryption.initialiseForTesting(key);
+    }
+
+    @Test
+    void roundTripRecoversPlaintext() {
+        String plaintext = "s3-secret-key-ABC123/+=value";
+        String encrypted = CredentialEncryption.encrypt(plaintext);
+
+        assertThat(encrypted).isNotNull().isNotEqualTo(plaintext);
+        assertThat(CredentialEncryption.decrypt(encrypted)).isEqualTo(plaintext);
+    }
+
+    @Test
+    void sameInputProducesDifferentCiphertext() {
+        String plaintext = "repeated-secret";
+
+        // Random IV per encryption => ciphertext must differ, but both decrypt back.
+        String first = CredentialEncryption.encrypt(plaintext);
+        String second = CredentialEncryption.encrypt(plaintext);
+
+        assertThat(first).isNotEqualTo(second);
+        assertThat(CredentialEncryption.decrypt(first)).isEqualTo(plaintext);
+        assertThat(CredentialEncryption.decrypt(second)).isEqualTo(plaintext);
+    }
+
+    @Test
+    void nullsPassThrough() {
+        assertThat(CredentialEncryption.encrypt(null)).isNull();
+        assertThat(CredentialEncryption.decrypt(null)).isNull();
+    }
+
+    @Test
+    void tamperedCiphertextIsRejected() {
+        // GCM is authenticated: flipping a byte of the stored blob must fail decryption, not
+        // silently return corrupted plaintext.
+        String encrypted = CredentialEncryption.encrypt("top-secret");
+        byte[] raw = Base64.getDecoder().decode(encrypted);
+        raw[raw.length - 1] ^= 0x01;
+        String tampered = Base64.getEncoder().encodeToString(raw);
+
+        assertThatThrownBy(() -> CredentialEncryption.decrypt(tampered))
+                .isInstanceOf(IllegalStateException.class);
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/integration/service/IntegrationConfigServiceTest.java

@@ -0,0 +1,182 @@
+package stirling.software.proprietary.integration.service;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+
+import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.OwnerScope;
+import stirling.software.proprietary.access.service.OwnershipService;
+import stirling.software.proprietary.access.service.SecretMasker;
+import stirling.software.proprietary.integration.dto.IntegrationConfigRequest;
+import stirling.software.proprietary.integration.dto.IntegrationConfigResponse;
+import stirling.software.proprietary.integration.model.IntegrationConfig;
+import stirling.software.proprietary.integration.model.IntegrationType;
+import stirling.software.proprietary.integration.repository.IntegrationConfigRepository;
+import stirling.software.proprietary.security.model.User;
+
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Integration-glue tests. Ownership authorization and secret masking are covered by {@code
+ * OwnershipServiceTest} / {@code SecretMaskerTest}; here those collaborators are mocked and we
+ * assert this service delegates to them correctly.
+ */
+@ExtendWith(MockitoExtension.class)
+class IntegrationConfigServiceTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    @Mock private IntegrationConfigRepository repository;
+    @Mock private OwnershipService ownership;
+    @Mock private SecretMasker secretMasker;
+
+    @InjectMocks private IntegrationConfigService service;
+
+    @Test
+    void createDelegatesOwnershipAndSanitizesConfig() {
+        when(secretMasker.sanitize(any())).thenReturn(Map.of("bucket", "b"));
+        when(repository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+        User user = user(7);
+
+        IntegrationConfig created =
+                service.create(request(IntegrationType.S3, OwnerScope.USER, null), user);
+
+        assertThat(created.getIntegrationType()).isEqualTo(IntegrationType.S3);
+        assertThat(created.getName()).isEqualTo("name");
+        verify(ownership)
+                .assignOwnership(eq(created), eq(OwnerScope.USER), isNull(), eq(user), any());
+        verify(secretMasker).sanitize(any());
+    }
+
+    @Test
+    void updateMergesConfigViaSecretMasker() throws Exception {
+        IntegrationConfig cfg = config(2L);
+        cfg.setConfig("{\"bucket\":\"old\",\"secretKey\":\"REAL\"}");
+        when(repository.findById(2L)).thenReturn(Optional.of(cfg));
+        when(ownership.canManage(any(), eq(cfg), any())).thenReturn(true);
+        when(secretMasker.merge(any(), any()))
+                .thenReturn(Map.of("bucket", "new", "secretKey", "REAL"));
+        when(repository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        IntegrationConfigRequest req =
+                new IntegrationConfigRequest(
+                        null,
+                        null,
+                        null,
+                        null,
+                        null,
+                        null,
+                        null,
+                        Map.of("bucket", "new", "secretKey", "********"));
+        service.update(2L, req, user(7));
+
+        Map<String, Object> stored =
+                MAPPER.readValue(cfg.getConfig(), new TypeReference<Map<String, Object>>() {});
+        assertThat(stored.get("bucket")).isEqualTo("new");
+        assertThat(stored.get("secretKey")).isEqualTo("REAL");
+    }
+
+    @Test
+    void updateForbiddenWhenCannotManage() {
+        IntegrationConfig cfg = config(3L);
+        when(repository.findById(3L)).thenReturn(Optional.of(cfg));
+        when(ownership.canManage(any(), eq(cfg), any())).thenReturn(false);
+
+        assertThatThrownBy(
+                        () ->
+                                service.update(
+                                        3L,
+                                        request(IntegrationType.S3, OwnerScope.USER, null),
+                                        user(7)))
+                .isInstanceOf(ResponseStatusException.class)
+                .extracting(e -> ((ResponseStatusException) e).getStatusCode())
+                .isEqualTo(HttpStatus.FORBIDDEN);
+    }
+
+    @Test
+    void toResponseMasksConfig() {
+        IntegrationConfig cfg = config(4L);
+        cfg.setConfig("{\"secretKey\":\"x\"}");
+        when(secretMasker.mask(any())).thenReturn(Map.of("secretKey", SecretMasker.MASK));
+        when(ownership.canManage(any(), eq(cfg), any())).thenReturn(false);
+
+        IntegrationConfigResponse resp = service.toResponse(cfg, user(7));
+
+        assertThat(resp.config().get("secretKey")).isEqualTo(SecretMasker.MASK);
+        assertThat(resp.canManage()).isFalse();
+    }
+
+    @Test
+    void listIncludesAConfigSharedViaAnExplicitGrant() {
+        User user = user(7);
+        when(repository.findByOwnerUser(user)).thenReturn(List.of());
+        when(repository.findByScope(OwnerScope.SERVER)).thenReturn(List.of());
+        when(ownership.grantedResourceIds(any(), eq(user))).thenReturn(Set.of("99"));
+        IntegrationConfig shared = config(99L);
+        when(repository.findById(99L)).thenReturn(Optional.of(shared));
+        when(ownership.canUse(any(), eq(shared), eq(user))).thenReturn(true);
+
+        List<IntegrationConfig> visible = service.listVisible(user);
+
+        assertThat(visible).extracting(IntegrationConfig::getId).contains(99L);
+    }
+
+    @Test
+    void nonAdminCannotChangeLockedFlag() {
+        IntegrationConfig cfg = config(5L); // locked = false
+        when(repository.findById(5L)).thenReturn(Optional.of(cfg));
+        when(ownership.canManage(any(), eq(cfg), any())).thenReturn(true);
+        when(ownership.isAdmin(any())).thenReturn(false);
+
+        IntegrationConfigRequest req =
+                new IntegrationConfigRequest(null, null, null, null, null, true, null, null);
+
+        assertThatThrownBy(() -> service.update(5L, req, user(7)))
+                .isInstanceOf(ResponseStatusException.class)
+                .extracting(e -> ((ResponseStatusException) e).getStatusCode())
+                .isEqualTo(HttpStatus.FORBIDDEN);
+    }
+
+    // ---- helpers ----
+
+    private IntegrationConfig config(long id) {
+        IntegrationConfig cfg = new IntegrationConfig();
+        cfg.setId(id);
+        cfg.setIntegrationType(IntegrationType.S3);
+        cfg.setName("cfg" + id);
+        cfg.setEnabled(true);
+        cfg.setDefaultAccess(DefaultAccessPolicy.EXPLICIT_ONLY);
+        return cfg;
+    }
+
+    private IntegrationConfigRequest request(IntegrationType type, OwnerScope scope, Long teamId) {
+        return new IntegrationConfigRequest(
+                type, "name", scope, teamId, null, null, null, Map.of("bucket", "b"));
+    }
+
+    private User user(long id) {
+        User u = new User();
+        u.setId(id);
+        u.setUsername("user" + id);
+        return u;
+    }
+}

app/proprietary/src/test/java/stirling/software/proprietary/security/controller/api/AuthControllerLoginTest.java

@@ -28,6 +28,7 @@ import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.security.model.AuthenticationType;
 import stirling.software.proprietary.security.model.Authority;
 import stirling.software.proprietary.security.model.User;
@@ -58,6 +59,7 @@ class AuthControllerLoginTest {
     @Mock private MfaService mfaService;
     @Mock private TotpService totpService;
     @Mock private RefreshRateLimitService refreshRateLimitService;
+    @Mock private ResourceAccessService resourceAccessService;
 
     @BeforeEach
     void setUp() {
@@ -80,7 +82,8 @@ class AuthControllerLoginTest {
                         refreshRateLimitService,
                         securityProperties,
                         applicationProperties,
-                        new stirling.software.proprietary.service.AiUserDataService(null));
+                        new stirling.software.proprietary.service.AiUserDataService(null),
+                        resourceAccessService);
         mockMvc = MockMvcBuilders.standaloneSetup(controller).build();
     }
 

app/proprietary/src/test/java/stirling/software/proprietary/security/controller/api/AuthControllerMoreTest.java

@@ -28,6 +28,7 @@ import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.model.enumeration.Role;
+import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.security.model.AuthenticationType;
 import stirling.software.proprietary.security.model.Authority;
 import stirling.software.proprietary.security.model.User;
@@ -59,6 +60,7 @@ class AuthControllerMoreTest {
     @Mock private MfaService mfaService;
     @Mock private TotpService totpService;
     @Mock private RefreshRateLimitService refreshRateLimitService;
+    @Mock private ResourceAccessService resourceAccessService;
 
     @BeforeEach
     void setUp() {
@@ -81,7 +83,8 @@ class AuthControllerMoreTest {
                         refreshRateLimitService,
                         securityProperties,
                         applicationProperties,
-                        new stirling.software.proprietary.service.AiUserDataService(null));
+                        new stirling.software.proprietary.service.AiUserDataService(null),
+                        resourceAccessService);
         mockMvc = MockMvcBuilders.standaloneSetup(controller).build();
     }
 

app/proprietary/src/test/java/stirling/software/proprietary/service/AiWorkflowServiceTest.java

@@ -2,6 +2,7 @@ package stirling.software.proprietary.service;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyBoolean;
@@ -229,6 +230,57 @@ class AiWorkflowServiceTest {
         // 1:1 mapping preserves each input's filename.
         assertEquals("a.pdf", result.getResultFiles().get(0).getFileName());
         assertEquals("b.pdf", result.getResultFiles().get(1).getFileName());
+        // Each output points back at the input it came from so the client versions it in place.
+        assertEquals(0, result.getResultFiles().get(0).getSourceIndex());
+        assertEquals(1, result.getResultFiles().get(1).getSourceIndex());
+    }
+
+    @Test
+    void mergeOutputHasNoSourceIndex() throws IOException {
+        MockMultipartFile a = pdf("a.pdf", "a-bytes");
+        MockMultipartFile b = pdf("b.pdf", "b-bytes");
+        stubOrchestrator(
+                """
+                {"outcome":"tool_call","tool":"%s","parameters":{},"rationale":"Merging"}
+                """
+                        .formatted(MERGE_ENDPOINT));
+        when(toolMetadataService.isMultiInput(MERGE_ENDPOINT)).thenReturn(true);
+        when(toolMetadataService.shouldUnpackZipResponse(MERGE_ENDPOINT)).thenReturn(false);
+        stubEndpoint(MERGE_ENDPOINT, pdfResource("merged-bytes", "merged.pdf"));
+        stubFileStorage();
+
+        AiWorkflowResponse result =
+                service.orchestrate(requestFor(new MockMultipartFile[] {a, b}, "merge these"));
+
+        // A merge draws on several inputs, so there is no single source to version in place.
+        assertNull(result.getResultFiles().get(0).getSourceIndex());
+    }
+
+    @Test
+    void splitOutputsHaveNoSourceIndex() throws IOException {
+        MockMultipartFile input = pdf("doc.pdf", "original");
+        stubOrchestrator(
+                """
+                {"outcome":"tool_call","tool":"%s","parameters":{},"rationale":"Splitting"}
+                """
+                        .formatted(SPLIT_ENDPOINT));
+        when(toolMetadataService.isMultiInput(SPLIT_ENDPOINT)).thenReturn(false);
+        when(toolMetadataService.shouldUnpackZipResponse(SPLIT_ENDPOINT)).thenReturn(true);
+        stubEndpoint(
+                SPLIT_ENDPOINT,
+                zipResource(
+                        "doc.zip",
+                        List.of(
+                                new ZipEntryBytes("page-1.pdf", "page-one"),
+                                new ZipEntryBytes("page-2.pdf", "page-two"))));
+        stubFileStorage();
+
+        AiWorkflowResponse result = service.orchestrate(requestFor(input, "split"));
+
+        // One input fanned out to many outputs, so none is a clean 1:1 version — the client adds
+        // them as fresh files and leaves the original in place.
+        assertNull(result.getResultFiles().get(0).getSourceIndex());
+        assertNull(result.getResultFiles().get(1).getSourceIndex());
     }
 
     @Test

app/saas/src/main/resources/db/migration/saas/V25__classification_taxonomy.sql

@@ -0,0 +1,14 @@
+-- Per-team classification taxonomy (gated by policies.enabled): the admin-editable vocabulary the
+-- document classifier runs against. One row per team; the whole taxonomy lives as JSON in
+-- taxonomy_json (authoritative on read). team_id is the natural key and a plain value (not a foreign
+-- key) to stay decoupled from the security entities, so classification can be enabled or disabled
+-- without touching them; the sentinel 0 holds the unteamed (login-disabled) taxonomy. Hibernate
+-- ddl-auto would also create this, but this keeps the schema explicit for the Flyway-managed
+-- deployments.
+
+CREATE TABLE IF NOT EXISTS classification_taxonomies (
+    team_id       BIGINT PRIMARY KEY,
+    taxonomy_json TEXT,
+    updated_at    TIMESTAMP,
+    updated_by    VARCHAR(255)
+);

app/saas/src/main/resources/db/migration/saas/V25__resource_grants.sql

@@ -0,0 +1,21 @@
+-- Resource access grants: which user/team may use a gated resource (portal, integration config).
+
+CREATE TABLE IF NOT EXISTS resource_grants (
+    resource_grant_id  BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    resource_type      VARCHAR(64)  NOT NULL,
+    resource_id        VARCHAR(255) NOT NULL DEFAULT '',
+    principal_type     VARCHAR(32)  NOT NULL,
+    principal_id       BIGINT       NOT NULL,
+    permission         VARCHAR(32)  NOT NULL,
+    granted_by_user_id BIGINT,
+    created_at         TIMESTAMP    NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS uk_resource_grant
+    ON resource_grants (resource_type, resource_id, principal_type, principal_id, permission);
+
+CREATE INDEX IF NOT EXISTS idx_resource_grants_lookup
+    ON resource_grants (resource_type, resource_id);
+
+CREATE INDEX IF NOT EXISTS idx_resource_grants_principal
+    ON resource_grants (principal_type, principal_id);

app/saas/src/main/resources/db/migration/saas/V26__integration_configs.sql

@@ -0,0 +1,25 @@
+-- S3/MCP/API integration configs; config_encrypted holds an AES-GCM encrypted JSON blob.
+
+CREATE TABLE IF NOT EXISTS integration_configs (
+    integration_config_id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    integration_type      VARCHAR(32)  NOT NULL,
+    name                  VARCHAR(255) NOT NULL,
+    scope                 VARCHAR(32)  NOT NULL,
+    owner_user_id         BIGINT,
+    owner_team_id         BIGINT,
+    enabled               BOOLEAN      NOT NULL DEFAULT TRUE,
+    locked                BOOLEAN      NOT NULL DEFAULT FALSE,
+    default_access        VARCHAR(32)  NOT NULL DEFAULT 'EXPLICIT_ONLY',
+    config_encrypted      TEXT,
+    created_at            TIMESTAMP    NOT NULL DEFAULT now(),
+    updated_at            TIMESTAMP    NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_integration_configs_owner
+    ON integration_configs (owner_user_id);
+
+CREATE INDEX IF NOT EXISTS idx_integration_configs_type
+    ON integration_configs (integration_type);
+
+CREATE INDEX IF NOT EXISTS idx_integration_configs_scope
+    ON integration_configs (scope);

engine/src/stirling/agents/__init__.py

@@ -1,5 +1,6 @@
 """Agent modules for Stirling AI reasoning flows."""
 
+from .document_classifier import DocumentClassifierAgent
 from .execution import ExecutionPlanningAgent
 from .orchestrator import OrchestratorAgent
 from .pdf_create import PdfCreateAgent
@@ -9,6 +10,7 @@ from .pdf_review import PdfReviewAgent
 from .user_spec import UserSpecAgent
 
 __all__ = [
+    "DocumentClassifierAgent",
     "ExecutionPlanningAgent",
     "OrchestratorAgent",
     "PdfCreateAgent",

engine/src/stirling/agents/default_classification_taxonomy.generated.json

@@ -0,0 +1,569 @@
+{
+  "_generated": "AUTO-GENERATED from frontend/editor/src/proprietary/data/classificationTaxonomy.ts by editor/scripts/generate-classification-taxonomy.mts — do NOT edit by hand; run `task frontend:classifier-categories`.",
+  "categories": [
+    {
+      "id": "invoice",
+      "label": "Invoice",
+      "docTypes": [
+        {
+          "id": "invoice",
+          "label": "Invoice"
+        },
+        {
+          "id": "receipt",
+          "label": "Receipt"
+        },
+        {
+          "id": "credit_note",
+          "label": "Credit note"
+        },
+        {
+          "id": "purchase_order",
+          "label": "Purchase order"
+        },
+        {
+          "id": "quote",
+          "label": "Quote"
+        }
+      ]
+    },
+    {
+      "id": "contract",
+      "label": "Contract",
+      "docTypes": [
+        {
+          "id": "nda",
+          "label": "Non-disclosure agreement"
+        },
+        {
+          "id": "employment_agreement",
+          "label": "Employment agreement"
+        },
+        {
+          "id": "service_agreement",
+          "label": "Service agreement"
+        },
+        {
+          "id": "lease_agreement",
+          "label": "Lease agreement"
+        },
+        {
+          "id": "master_service_agreement",
+          "label": "Master service agreement"
+        },
+        {
+          "id": "statement_of_work",
+          "label": "Statement of work"
+        },
+        {
+          "id": "terms_of_service",
+          "label": "Terms of service"
+        }
+      ]
+    },
+    {
+      "id": "financial_statement",
+      "label": "Financial statement",
+      "docTypes": [
+        {
+          "id": "balance_sheet",
+          "label": "Balance sheet"
+        },
+        {
+          "id": "income_statement",
+          "label": "Income statement"
+        },
+        {
+          "id": "cash_flow_statement",
+          "label": "Cash flow statement"
+        },
+        {
+          "id": "bank_statement",
+          "label": "Bank statement"
+        },
+        {
+          "id": "annual_report",
+          "label": "Annual report"
+        }
+      ]
+    },
+    {
+      "id": "report",
+      "label": "Report",
+      "docTypes": [
+        {
+          "id": "business_report",
+          "label": "Business report"
+        },
+        {
+          "id": "project_report",
+          "label": "Project report"
+        },
+        {
+          "id": "research_report",
+          "label": "Research report"
+        },
+        {
+          "id": "status_report",
+          "label": "Status report"
+        },
+        {
+          "id": "incident_report",
+          "label": "Incident report"
+        }
+      ]
+    },
+    {
+      "id": "letter",
+      "label": "Letter",
+      "docTypes": [
+        {
+          "id": "business_letter",
+          "label": "Business letter"
+        },
+        {
+          "id": "cover_letter",
+          "label": "Cover letter"
+        },
+        {
+          "id": "recommendation_letter",
+          "label": "Recommendation letter"
+        },
+        {
+          "id": "complaint_letter",
+          "label": "Complaint letter"
+        },
+        {
+          "id": "demand_letter",
+          "label": "Demand letter"
+        }
+      ]
+    },
+    {
+      "id": "form",
+      "label": "Form",
+      "docTypes": [
+        {
+          "id": "application_form",
+          "label": "Application form"
+        },
+        {
+          "id": "registration_form",
+          "label": "Registration form"
+        },
+        {
+          "id": "consent_form",
+          "label": "Consent form"
+        },
+        {
+          "id": "survey",
+          "label": "Survey"
+        },
+        {
+          "id": "questionnaire",
+          "label": "Questionnaire"
+        }
+      ]
+    },
+    {
+      "id": "resume",
+      "label": "Resume",
+      "docTypes": [
+        {
+          "id": "resume",
+          "label": "Resume"
+        },
+        {
+          "id": "curriculum_vitae",
+          "label": "Curriculum vitae"
+        },
+        {
+          "id": "portfolio",
+          "label": "Portfolio"
+        },
+        {
+          "id": "reference_sheet",
+          "label": "Reference sheet"
+        }
+      ]
+    },
+    {
+      "id": "tax_form",
+      "label": "Tax form",
+      "docTypes": [
+        {
+          "id": "tax_return",
+          "label": "Tax return"
+        },
+        {
+          "id": "w2",
+          "label": "W-2"
+        },
+        {
+          "id": "w9",
+          "label": "W-9"
+        },
+        {
+          "id": "form_1099",
+          "label": "Form 1099"
+        },
+        {
+          "id": "vat_return",
+          "label": "VAT return"
+        }
+      ]
+    },
+    {
+      "id": "expense_report",
+      "label": "Expense report",
+      "docTypes": [
+        {
+          "id": "expense_report",
+          "label": "Expense report"
+        },
+        {
+          "id": "reimbursement_request",
+          "label": "Reimbursement request"
+        },
+        {
+          "id": "mileage_log",
+          "label": "Mileage log"
+        },
+        {
+          "id": "per_diem_claim",
+          "label": "Per diem claim"
+        }
+      ]
+    },
+    {
+      "id": "presentation",
+      "label": "Presentation",
+      "docTypes": [
+        {
+          "id": "slide_deck",
+          "label": "Slide deck"
+        },
+        {
+          "id": "pitch_deck",
+          "label": "Pitch deck"
+        },
+        {
+          "id": "training_deck",
+          "label": "Training deck"
+        },
+        {
+          "id": "webinar_deck",
+          "label": "Webinar deck"
+        }
+      ]
+    },
+    {
+      "id": "medical_record",
+      "label": "Medical record",
+      "docTypes": [
+        {
+          "id": "lab_result",
+          "label": "Lab result"
+        },
+        {
+          "id": "prescription",
+          "label": "Prescription"
+        },
+        {
+          "id": "discharge_summary",
+          "label": "Discharge summary"
+        },
+        {
+          "id": "medical_history",
+          "label": "Medical history"
+        },
+        {
+          "id": "imaging_report",
+          "label": "Imaging report"
+        },
+        {
+          "id": "vaccination_record",
+          "label": "Vaccination record"
+        }
+      ]
+    },
+    {
+      "id": "legal_filing",
+      "label": "Legal filing",
+      "docTypes": [
+        {
+          "id": "court_filing",
+          "label": "Court filing"
+        },
+        {
+          "id": "complaint",
+          "label": "Complaint"
+        },
+        {
+          "id": "motion",
+          "label": "Motion"
+        },
+        {
+          "id": "subpoena",
+          "label": "Subpoena"
+        },
+        {
+          "id": "affidavit",
+          "label": "Affidavit"
+        },
+        {
+          "id": "deposition",
+          "label": "Deposition"
+        }
+      ]
+    },
+    {
+      "id": "identity_document",
+      "label": "Identity document",
+      "docTypes": [
+        {
+          "id": "passport",
+          "label": "Passport"
+        },
+        {
+          "id": "drivers_license",
+          "label": "Driver's license"
+        },
+        {
+          "id": "national_id",
+          "label": "National ID"
+        },
+        {
+          "id": "birth_certificate",
+          "label": "Birth certificate"
+        },
+        {
+          "id": "visa",
+          "label": "Visa"
+        }
+      ]
+    },
+    {
+      "id": "insurance",
+      "label": "Insurance",
+      "docTypes": [
+        {
+          "id": "insurance_policy",
+          "label": "Insurance policy"
+        },
+        {
+          "id": "insurance_claim",
+          "label": "Insurance claim"
+        },
+        {
+          "id": "certificate_of_insurance",
+          "label": "Certificate of insurance"
+        },
+        {
+          "id": "explanation_of_benefits",
+          "label": "Explanation of benefits"
+        }
+      ]
+    },
+    {
+      "id": "real_estate",
+      "label": "Real estate",
+      "docTypes": [
+        {
+          "id": "deed",
+          "label": "Deed"
+        },
+        {
+          "id": "mortgage_agreement",
+          "label": "Mortgage agreement"
+        },
+        {
+          "id": "property_appraisal",
+          "label": "Property appraisal"
+        },
+        {
+          "id": "closing_disclosure",
+          "label": "Closing disclosure"
+        },
+        {
+          "id": "title_report",
+          "label": "Title report"
+        }
+      ]
+    },
+    {
+      "id": "shipping",
+      "label": "Shipping",
+      "docTypes": [
+        {
+          "id": "bill_of_lading",
+          "label": "Bill of lading"
+        },
+        {
+          "id": "packing_slip",
+          "label": "Packing slip"
+        },
+        {
+          "id": "customs_declaration",
+          "label": "Customs declaration"
+        },
+        {
+          "id": "delivery_note",
+          "label": "Delivery note"
+        },
+        {
+          "id": "air_waybill",
+          "label": "Air waybill"
+        }
+      ]
+    },
+    {
+      "id": "hr_document",
+      "label": "HR document",
+      "docTypes": [
+        {
+          "id": "offer_letter",
+          "label": "Offer letter"
+        },
+        {
+          "id": "performance_review",
+          "label": "Performance review"
+        },
+        {
+          "id": "payslip",
+          "label": "Payslip"
+        },
+        {
+          "id": "employee_handbook",
+          "label": "Employee handbook"
+        },
+        {
+          "id": "termination_letter",
+          "label": "Termination letter"
+        },
+        {
+          "id": "timesheet",
+          "label": "Timesheet"
+        }
+      ]
+    },
+    {
+      "id": "academic_record",
+      "label": "Academic record",
+      "docTypes": [
+        {
+          "id": "transcript",
+          "label": "Transcript"
+        },
+        {
+          "id": "diploma",
+          "label": "Diploma"
+        },
+        {
+          "id": "certificate",
+          "label": "Certificate"
+        },
+        {
+          "id": "syllabus",
+          "label": "Syllabus"
+        },
+        {
+          "id": "thesis",
+          "label": "Thesis"
+        },
+        {
+          "id": "report_card",
+          "label": "Report card"
+        }
+      ]
+    },
+    {
+      "id": "marketing_material",
+      "label": "Marketing material",
+      "docTypes": [
+        {
+          "id": "brochure",
+          "label": "Brochure"
+        },
+        {
+          "id": "flyer",
+          "label": "Flyer"
+        },
+        {
+          "id": "case_study",
+          "label": "Case study"
+        },
+        {
+          "id": "white_paper",
+          "label": "White paper"
+        },
+        {
+          "id": "press_release",
+          "label": "Press release"
+        }
+      ]
+    },
+    {
+      "id": "technical_document",
+      "label": "Technical document",
+      "docTypes": [
+        {
+          "id": "user_manual",
+          "label": "User manual"
+        },
+        {
+          "id": "specification",
+          "label": "Specification"
+        },
+        {
+          "id": "api_documentation",
+          "label": "API documentation"
+        },
+        {
+          "id": "installation_guide",
+          "label": "Installation guide"
+        },
+        {
+          "id": "datasheet",
+          "label": "Datasheet"
+        },
+        {
+          "id": "release_notes",
+          "label": "Release notes"
+        }
+      ]
+    }
+  ],
+  "tags": [
+    "finance",
+    "legal",
+    "medical",
+    "hr",
+    "tax",
+    "insurance",
+    "marketing",
+    "technical",
+    "operations",
+    "academic",
+    "government",
+    "draft",
+    "final",
+    "signed",
+    "unsigned",
+    "executed",
+    "expired",
+    "amended",
+    "void",
+    "confidential",
+    "internal",
+    "public",
+    "pii",
+    "phi",
+    "certified",
+    "notarized",
+    "scanned",
+    "redacted",
+    "template",
+    "urgent"
+  ]
+}

engine/src/stirling/agents/document_classifier.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_ai import Agent
+from pydantic_ai.output import NativeOutput
+
+from stirling.contracts import (
+    ClassificationTaxonomy,
+    ClassifyDocumentRequest,
+    ClassifyDocumentResponse,
+    DocumentClassificationResponse,
+    PageText,
+)
+from stirling.models import ApiModel
+from stirling.services import AppRuntime
+
+logger = logging.getLogger(__name__)
+
+# Sentinel id for an answer that fell outside the supplied vocabulary.
+UNKNOWN_LABEL = "unknown"
+# Human-readable label shown for the off-list sentinel.
+UNKNOWN_DISPLAY_LABEL = "Unknown"
+# An off-list answer can never be reported as more confident than this, so a
+# confident-but-wrong model answer can't clear an organisation's accept
+# threshold downstream. See the design doc's "Validate" step.
+UNKNOWN_MAX_CONFIDENCE = 0.2
+# Pages read from each end of the document. A document's type is evident from
+# its opening (and closing) pages, so a fixed window keeps cost and latency flat
+# regardless of length. Promote to AppSettings if it ever needs tuning.
+WINDOW_PAGES = 2
+
+# The built-in vocabulary the classifier falls back to when a request doesn't
+# supply its own. GENERATED from the TS source of truth
+# (frontend/editor/src/proprietary/data/classificationTaxonomy.ts) via
+# `task frontend:classifier-categories` — edit that file, not this JSON. Validated into the
+# typed contract on import, so a malformed entry fails fast.
+_DEFAULT_TAXONOMY_PATH = Path(__file__).with_name("default_classification_taxonomy.generated.json")
+# The file carries an underscore-prefixed "_generated" notice (JSON has no
+# comments); drop meta keys before validating against the strict contract.
+_raw_taxonomy = json.loads(_DEFAULT_TAXONOMY_PATH.read_text(encoding="utf-8"))
+DEFAULT_TAXONOMY = ClassificationTaxonomy.model_validate(
+    {key: value for key, value in _raw_taxonomy.items() if not key.startswith("_")}
+)
+
+
+_SYSTEM_PROMPT = (
+    "You identify what a document is, choosing only from a fixed vocabulary you "
+    "are given. Decide along three axes:\n"
+    "- category: the document's structural family. Choose EXACTLY ONE category id.\n"
+    "- doc_type: the specific instrument within that family. Choose EXACTLY ONE "
+    "doc_type id listed under the category you chose.\n"
+    "- tags: zero or more descriptor ids from the tag list.\n"
+    "\n"
+    "Rules:\n"
+    "- Use only ids from the supplied vocabulary. If nothing fits, return "
+    f'"{UNKNOWN_LABEL}" for category and/or doc_type.\n'
+    "- The doc_type you pick must belong to the category you pick.\n"
+    "- type_confidence (0.0-1.0) is how sure you are that doc_type is correct.\n"
+    "- Judge from the document's content and structure, not from keywords alone. "
+    "The document may be in any language.\n"
+    "- You are shown only the first and last pages; that is enough to identify the type."
+)
+
+
+class _ClassifierOutput(ApiModel):
+    """Raw model answer, before it is validated against the taxonomy."""
+
+    category: str = Field(description="A category id from the vocabulary, or 'unknown'.")
+    doc_type: str = Field(description="A doc_type id belonging to the chosen category, or 'unknown'.")
+    type_confidence: float = Field(ge=0.0, le=1.0, description="Confidence that doc_type is correct.")
+    tags: list[str] = Field(default_factory=list, description="Descriptor ids drawn from the tag list.")
+
+
+def render_taxonomy(taxonomy: ClassificationTaxonomy) -> str:
+    """Render the vocabulary for the prompt, ids first so the model echoes them."""
+    lines = ["Categories (id (label): doc_types as id (label)):"]
+    for category in taxonomy.categories:
+        types = ", ".join(f"{doc_type.id} ({doc_type.label})" for doc_type in category.doc_types) or "(none)"
+        lines.append(f"- {category.id} ({category.label}): {types}")
+    lines.append(f"Tags: {', '.join(taxonomy.tags) or '(none)'}")
+    return "\n".join(lines)
+
+
+def select_window(pages: list[PageText], window: int = WINDOW_PAGES) -> list[PageText]:
+    """Return the first and last ``window`` pages, never overlapping.
+
+    Documents short enough that the two ends would meet are returned whole. The
+    caller usually sends just the window already; this is a defensive trim in
+    case it sends more.
+    """
+    if window <= 0 or len(pages) <= window * 2:
+        return list(pages)
+    return [*pages[:window], *pages[-window:]]
+
+
+def format_window(pages: list[PageText]) -> str:
+    if not pages:
+        return "(no extractable text)"
+    return "\n\n".join(f"[Page {page.page_number}]\n{page.text}" for page in pages)
+
+
+def validate_against_taxonomy(
+    output: _ClassifierOutput,
+    taxonomy: ClassificationTaxonomy,
+) -> DocumentClassificationResponse:
+    """Coerce a raw model answer onto the supplied vocabulary.
+
+    An off-list category collapses both axes to ``unknown``; a doc_type that
+    isn't a child of its (valid) category collapses the type alone. Either
+    collapse caps confidence. Tags are filtered to the known set, de-duplicated,
+    and returned in the model's order. The model identifies; these rules decide
+    what is allowed to stand.
+    """
+    categories_by_id = {category.id.lower(): category for category in taxonomy.categories}
+    allowed_tags = {tag.lower(): tag for tag in taxonomy.tags}
+
+    kept_tags: list[str] = []
+    for tag in output.tags:
+        canonical = allowed_tags.get(tag.strip().lower())
+        if canonical is not None and canonical not in kept_tags:
+            kept_tags.append(canonical)
+
+    category = categories_by_id.get(output.category.strip().lower())
+    if category is None:
+        return DocumentClassificationResponse(
+            category=UNKNOWN_LABEL,
+            category_label=UNKNOWN_DISPLAY_LABEL,
+            doc_type=UNKNOWN_LABEL,
+            doc_type_label=UNKNOWN_DISPLAY_LABEL,
+            type_confidence=min(output.type_confidence, UNKNOWN_MAX_CONFIDENCE),
+            tags=kept_tags,
+        )
+
+    types_by_id = {doc_type.id.lower(): doc_type for doc_type in category.doc_types}
+    doc_type = types_by_id.get(output.doc_type.strip().lower())
+    if doc_type is None:
+        return DocumentClassificationResponse(
+            category=category.id,
+            category_label=category.label,
+            doc_type=UNKNOWN_LABEL,
+            doc_type_label=UNKNOWN_DISPLAY_LABEL,
+            type_confidence=min(output.type_confidence, UNKNOWN_MAX_CONFIDENCE),
+            tags=kept_tags,
+        )
+
+    return DocumentClassificationResponse(
+        category=category.id,
+        category_label=category.label,
+        doc_type=doc_type.id,
+        doc_type_label=doc_type.label,
+        type_confidence=output.type_confidence,
+        tags=kept_tags,
+    )
+
+
+class DocumentClassifierAgent:
+    """Identifies a document's category, type, and tags against a taxonomy.
+
+    Reads the bounded page window supplied on the request (first/last
+    ``WINDOW_PAGES``) and runs a single fast-model pass, then validates the
+    answer against the vocabulary so nothing off-list survives.
+    """
+
+    def __init__(self, runtime: AppRuntime) -> None:
+        self.runtime = runtime
+        self._agent = Agent(
+            model=runtime.fast_model,
+            output_type=NativeOutput(_ClassifierOutput),
+            system_prompt=_SYSTEM_PROMPT,
+            model_settings=runtime.fast_model_settings,
+        )
+
+    async def classify(self, request: ClassifyDocumentRequest) -> ClassifyDocumentResponse:
+        # Override point: a request-supplied taxonomy (e.g. a future per-org / DB
+        # vocabulary the backend resolves) wins; the generated default is the fallback.
+        taxonomy = request.taxonomy or DEFAULT_TAXONOMY
+        window = select_window(request.pages)
+        prompt = self._build_prompt(request.file_name, taxonomy, window)
+        logger.debug("[classify] prompt:\n%s", prompt)
+        result = await self._agent.run(prompt)
+        return validate_against_taxonomy(result.output, taxonomy)
+
+    @staticmethod
+    def _build_prompt(file_name: str, taxonomy: ClassificationTaxonomy, window: list[PageText]) -> str:
+        return (
+            f"{render_taxonomy(taxonomy)}\n\n"
+            f"Document file name: {file_name}\n"
+            f"Document content (first and last pages):\n{format_window(window)}"
+        )

engine/src/stirling/api/app.py

@@ -10,6 +10,7 @@ from pydantic_ai import Agent
 from pydantic_ai.models.instrumented import InstrumentationSettings
 
 from stirling.agents import (
+    DocumentClassifierAgent,
     ExecutionPlanningAgent,
     OrchestratorAgent,
     PdfEditAgent,
@@ -24,6 +25,7 @@ from stirling.api.middleware import UserIdMiddleware
 from stirling.api.routes import (
     agent_capabilities_router,
     agent_draft_router,
+    document_classifier_router,
     document_router,
     execution_router,
     ledger_router,
@@ -95,6 +97,7 @@ async def lifespan(fast_api: FastAPI):
     fast_api.state.execution_planning_agent = ExecutionPlanningAgent(runtime)
     fast_api.state.math_auditor_agent = MathAuditorAgent(runtime)
     fast_api.state.pdf_comment_agent = PdfCommentAgent(runtime)
+    fast_api.state.document_classifier_agent = DocumentClassifierAgent(runtime)
     tracer_provider = setup_posthog_tracking(settings)
     if tracer_provider:
         Agent.instrument_all(InstrumentationSettings(tracer_provider=tracer_provider))
@@ -131,6 +134,7 @@ app.include_router(document_router, dependencies=_user_gate)
 app.include_router(ledger_router, dependencies=_user_gate)
 app.include_router(pdf_comments_router, dependencies=_user_gate)
 app.include_router(agent_capabilities_router, dependencies=_user_gate)
+app.include_router(document_classifier_router, dependencies=_user_gate)
 
 
 @app.get("/health", response_model=HealthResponse)

engine/src/stirling/api/dependencies.py

@@ -5,6 +5,7 @@ from typing import Annotated
 from fastapi import Depends, HTTPException, Request, status
 
 from stirling.agents import (
+    DocumentClassifierAgent,
     ExecutionPlanningAgent,
     OrchestratorAgent,
     PdfEditAgent,
@@ -55,6 +56,10 @@ def get_pdf_comment_agent(request: Request) -> PdfCommentAgent:
     return request.app.state.pdf_comment_agent
 
 
+def get_document_classifier_agent(request: Request) -> DocumentClassifierAgent:
+    return request.app.state.document_classifier_agent
+
+
 def require_user_id() -> UserId:
     """FastAPI dependency for routes that touch per-user storage.
 

engine/src/stirling/api/routes/__init__.py

@@ -1,5 +1,6 @@
 from .agent_capabilities import router as agent_capabilities_router
 from .agent_drafts import router as agent_draft_router
+from .document_classifier import router as document_classifier_router
 from .documents import router as document_router
 from .execution import router as execution_router
 from .ledger import router as ledger_router
@@ -11,6 +12,7 @@ from .pdf_questions import router as pdf_question_router
 __all__ = [
     "agent_capabilities_router",
     "agent_draft_router",
+    "document_classifier_router",
     "document_router",
     "execution_router",
     "ledger_router",

engine/src/stirling/api/routes/document_classifier.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from stirling.agents import DocumentClassifierAgent
+from stirling.api.dependencies import get_document_classifier_agent
+from stirling.contracts import ClassifyDocumentRequest, ClassifyDocumentResponse
+
+router = APIRouter(prefix="/api/v1/documents/classify", tags=["document-classifier"])
+
+
+@router.post("", response_model=ClassifyDocumentResponse)
+async def classify_document(
+    request: ClassifyDocumentRequest,
+    agent: Annotated[DocumentClassifierAgent, Depends(get_document_classifier_agent)],
+) -> ClassifyDocumentResponse:
+    """Classify a document from its supplied page text against the default taxonomy.
+
+    The caller sends the bounded page window inline, so no per-user document
+    storage is touched here — the request is self-contained.
+    """
+    return await agent.classify(request)

engine/src/stirling/contracts/__init__.py

@@ -36,6 +36,14 @@ from .contradiction import (
     ContradictionReport,
     ContradictionSeverity,
 )
+from .document_classifier import (
+    ClassificationTaxonomy,
+    ClassifyDocumentRequest,
+    ClassifyDocumentResponse,
+    DocumentCategory,
+    DocumentClassificationResponse,
+    DocumentType,
+)
 from .documents import (
     DeleteDocumentResponse,
     IngestDocumentRequest,
@@ -129,6 +137,9 @@ __all__ = [
     "AiToolAgentStep",
     "ArtifactKind",
     "CannotContinueExecutionAction",
+    "ClassificationTaxonomy",
+    "ClassifyDocumentRequest",
+    "ClassifyDocumentResponse",
     "Claim",
     "CommentSpec",
     "CompletedExecutionAction",
@@ -139,8 +150,11 @@ __all__ = [
     "DeleteDocumentResponse",
     "PurgeOwnerResponse",
     "Discrepancy",
+    "DocumentCategory",
+    "DocumentClassificationResponse",
     "DocumentMeta",
     "DocumentSections",
+    "DocumentType",
     "DiscrepancyKind",
     "EditCannotDoResponse",
     "EditClarificationRequest",

engine/src/stirling/contracts/document_classifier.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from stirling.models import ApiModel
+
+from .documents import PageText
+
+
+class DocumentType(ApiModel):
+    """A specific instrument within a category (e.g. ``nda`` inside ``contract``)."""
+
+    id: str = Field(min_length=1)
+    label: str = Field(min_length=1)
+
+
+class DocumentCategory(ApiModel):
+    """A structural family of documents, owning the doc_types shaped like it."""
+
+    id: str = Field(min_length=1)
+    label: str = Field(min_length=1)
+    doc_types: list[DocumentType] = Field(default_factory=list)
+
+
+class ClassificationTaxonomy(ApiModel):
+    """The vocabulary a document is classified against.
+
+    Supplied per request by the backend. When omitted, the engine falls back to
+    its small built-in default (see ``DEFAULT_TAXONOMY``). Tags are free-standing
+    descriptors that never own doc_types.
+    """
+
+    categories: list[DocumentCategory] = Field(min_length=1)
+    tags: list[str] = Field(default_factory=list)
+
+
+class ClassifyDocumentRequest(ApiModel):
+    """Classify one document from its page text.
+
+    The caller sends the page text directly — typically just the bounded window
+    (first/last pages), since the classifier reads no more than that. There is no
+    ingestion or RAG step.
+    """
+
+    file_name: str = Field(min_length=1)
+    pages: list[PageText] = Field(default_factory=list)
+    taxonomy: ClassificationTaxonomy | None = None
+
+
+class DocumentClassificationResponse(ApiModel):
+    """Terminal classification result.
+
+    ``category`` and ``doc_type`` are ids drawn from the taxonomy (the internal
+    matching keys), or the sentinel ``"unknown"`` when the model's answer fell
+    outside it. ``category_label`` and ``doc_type_label`` are the human-readable
+    labels for those ids (what the UI shows); Python derives them from the
+    matched taxonomy entry so the two never drift. ``tags`` are the subset of the
+    model's tags that exist in the taxonomy. This is a plain answer from a
+    dedicated endpoint — it carries no ``outcome`` discriminator (it isn't one of
+    the orchestrator's WorkflowOutcome-routed union responses).
+    """
+
+    category: str
+    category_label: str
+    doc_type: str
+    doc_type_label: str
+    type_confidence: float = Field(ge=0.0, le=1.0)
+    tags: list[str] = Field(default_factory=list)
+
+
+# Only one response shape today; kept as a named alias so routes and agents have
+# a stable response type to import.
+ClassifyDocumentResponse = DocumentClassificationResponse

engine/tests/test_document_classifier.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from stirling.agents.document_classifier import (
+    DEFAULT_TAXONOMY,
+    UNKNOWN_LABEL,
+    UNKNOWN_MAX_CONFIDENCE,
+    DocumentClassifierAgent,
+    _ClassifierOutput,
+    render_taxonomy,
+    select_window,
+    validate_against_taxonomy,
+)
+from stirling.contracts import (
+    ClassificationTaxonomy,
+    ClassifyDocumentRequest,
+    DocumentCategory,
+    DocumentClassificationResponse,
+    PageText,
+)
+from stirling.services.runtime import AppRuntime
+
+
+def _page(number: int, text: str = "x") -> PageText:
+    return PageText(page_number=number, text=text)
+
+
+# ── select_window ───────────────────────────────────────────────────────────
+
+
+def test_select_window_returns_short_documents_whole() -> None:
+    pages = [_page(1), _page(2), _page(3), _page(4)]
+    assert select_window(pages, window=2) == pages
+
+
+def test_select_window_takes_both_ends_without_overlap() -> None:
+    pages = [_page(n) for n in range(1, 6)]  # 5 pages
+    selected = select_window(pages, window=2)
+    assert [p.page_number for p in selected] == [1, 2, 4, 5]
+
+
+def test_select_window_handles_empty() -> None:
+    assert select_window([], window=2) == []
+
+
+def test_select_window_zero_returns_all() -> None:
+    pages = [_page(1), _page(2), _page(3)]
+    assert select_window(pages, window=0) == pages
+
+
+# ── validate_against_taxonomy ────────────────────────────────────────────────
+
+
+def test_valid_classification_is_preserved() -> None:
+    output = _ClassifierOutput(category="contract", doc_type="nda", type_confidence=0.95, tags=["legal", "signed"])
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert isinstance(result, DocumentClassificationResponse)
+    assert result.category == "contract"
+    assert result.doc_type == "nda"
+    assert result.type_confidence == 0.95
+    assert result.tags == ["legal", "signed"]
+
+
+def test_off_list_category_collapses_to_unknown_with_capped_confidence() -> None:
+    output = _ClassifierOutput(category="spaceship", doc_type="warp_core", type_confidence=0.99)
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.category == UNKNOWN_LABEL
+    assert result.doc_type == UNKNOWN_LABEL
+    assert result.type_confidence == UNKNOWN_MAX_CONFIDENCE
+
+
+def test_off_list_type_keeps_category_but_unknown_type() -> None:
+    output = _ClassifierOutput(category="contract", doc_type="invoice", type_confidence=0.9)
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.category == "contract"
+    assert result.doc_type == UNKNOWN_LABEL
+    assert result.type_confidence == UNKNOWN_MAX_CONFIDENCE
+
+
+def test_type_from_a_different_category_is_not_a_child() -> None:
+    # "lab_result" is a valid type, but only under medical_record, not contract.
+    output = _ClassifierOutput(category="contract", doc_type="lab_result", type_confidence=0.8)
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.category == "contract"
+    assert result.doc_type == UNKNOWN_LABEL
+
+
+def test_matching_is_case_insensitive_and_returns_canonical_ids() -> None:
+    output = _ClassifierOutput(category="Contract", doc_type="NDA", type_confidence=0.7, tags=["LEGAL"])
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.category == "contract"
+    assert result.doc_type == "nda"
+    assert result.tags == ["legal"]
+
+
+def test_unknown_tags_dropped_and_deduplicated_in_order() -> None:
+    output = _ClassifierOutput(
+        category="invoice",
+        doc_type="invoice",
+        type_confidence=0.9,
+        tags=["finance", "made-up", "finance", "legal"],
+    )
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.tags == ["finance", "legal"]
+
+
+def test_low_confidence_is_not_raised_when_collapsing() -> None:
+    output = _ClassifierOutput(category="nope", doc_type="nope", type_confidence=0.05)
+    result = validate_against_taxonomy(output, DEFAULT_TAXONOMY)
+    assert result.type_confidence == 0.05  # min(0.05, 0.2)
+
+
+# ── render_taxonomy ──────────────────────────────────────────────────────────
+
+
+def test_render_taxonomy_lists_ids_and_tags() -> None:
+    rendered = render_taxonomy(DEFAULT_TAXONOMY)
+    assert "contract" in rendered
+    assert "nda" in rendered
+    assert "finance" in rendered
+
+
+def test_render_taxonomy_handles_category_without_types() -> None:
+    taxonomy = ClassificationTaxonomy(
+        categories=[DocumentCategory(id="memo", label="Memo", doc_types=[])],
+        tags=[],
+    )
+    rendered = render_taxonomy(taxonomy)
+    assert "(none)" in rendered
+
+
+# ── DocumentClassifierAgent (inline page text) ───────────────────────────────
+
+
+@pytest.mark.anyio
+async def test_classify_validates_model_output_against_default_taxonomy(runtime: AppRuntime) -> None:
+    agent = DocumentClassifierAgent(runtime)
+    agent._agent.run = AsyncMock(
+        return_value=SimpleNamespace(
+            output=_ClassifierOutput(category="invoice", doc_type="invoice", type_confidence=0.97, tags=["finance"])
+        )
+    )
+
+    result = await agent.classify(
+        ClassifyDocumentRequest(
+            file_name="invoice.pdf",
+            pages=[PageText(page_number=1, text="Invoice INV-1 total due 100.00")],
+        )
+    )
+
+    assert isinstance(result, DocumentClassificationResponse)
+    assert result.category == "invoice"
+    assert result.doc_type == "invoice"
+    assert result.tags == ["finance"]
+
+
+@pytest.mark.anyio
+async def test_classify_collapses_off_list_model_answer(runtime: AppRuntime) -> None:
+    agent = DocumentClassifierAgent(runtime)
+    agent._agent.run = AsyncMock(
+        return_value=SimpleNamespace(
+            output=_ClassifierOutput(category="boarding_pass", doc_type="seat", type_confidence=0.9)
+        )
+    )
+
+    result = await agent.classify(
+        ClassifyDocumentRequest(file_name="weird.pdf", pages=[PageText(page_number=1, text="Some text")])
+    )
+
+    assert isinstance(result, DocumentClassificationResponse)
+    assert result.category == UNKNOWN_LABEL
+    assert result.doc_type == UNKNOWN_LABEL
+    assert result.type_confidence == UNKNOWN_MAX_CONFIDENCE

engine/tests/test_document_classifier_routes.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from fastapi.testclient import TestClient
+
+from stirling.api import app
+from stirling.api.dependencies import get_document_classifier_agent
+from stirling.contracts import (
+    ClassifyDocumentRequest,
+    ClassifyDocumentResponse,
+    DocumentClassificationResponse,
+)
+
+
+class StubClassifierAgent:
+    """Stands in for DocumentClassifierAgent so route tests don't call a model."""
+
+    def __init__(self, response: ClassifyDocumentResponse) -> None:
+        self._response = response
+
+    async def classify(self, _request: ClassifyDocumentRequest) -> ClassifyDocumentResponse:
+        return self._response
+
+
+@pytest.fixture
+def classification_client() -> Iterator[TestClient]:
+    app.dependency_overrides[get_document_classifier_agent] = lambda: StubClassifierAgent(
+        DocumentClassificationResponse(
+            category="contract",
+            category_label="Contract",
+            doc_type="nda",
+            doc_type_label="Non-disclosure agreement",
+            type_confidence=0.96,
+            tags=["legal", "signed"],
+        )
+    )
+    try:
+        yield TestClient(app)
+    finally:
+        app.dependency_overrides.pop(get_document_classifier_agent, None)
+
+
+def test_classify_returns_camel_cased_result(classification_client: TestClient) -> None:
+    response = classification_client.post(
+        "/api/v1/documents/classify",
+        json={"fileName": "nda.pdf", "pages": [{"pageNumber": 1, "text": "Mutual NDA between A and B."}]},
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["category"] == "contract"
+    assert body["categoryLabel"] == "Contract"
+    assert body["docType"] == "nda"
+    assert body["docTypeLabel"] == "Non-disclosure agreement"
+    assert body["typeConfidence"] == 0.96
+    assert body["tags"] == ["legal", "signed"]
+
+
+def test_classify_accepts_empty_pages(classification_client: TestClient) -> None:
+    response = classification_client.post(
+        "/api/v1/documents/classify",
+        json={"fileName": "blank.pdf", "pages": []},
+    )
+    assert response.status_code == 200
+
+
+def test_classify_rejects_empty_file_name(classification_client: TestClient) -> None:
+    response = classification_client.post(
+        "/api/v1/documents/classify",
+        json={"fileName": "", "pages": []},
+    )
+    assert response.status_code == 422

frontend/editor/public/locales/en-US/translation.toml

@@ -3715,6 +3715,7 @@ backToFolder = "Back to {{folder}}"
 backToMyFiles = "Back to My Files"
 breadcrumbs = "Folder path"
 cancel = "Cancel"
+classification = "Classification"
 clearSearch = "Clear search"
 clearSelection = "Clear selection"
 closeDetails = "Close details"
@@ -3872,12 +3873,14 @@ uploadFilesFailedDetail = "Could not upload files: {{message}}"
 
 [filesPage.field]
 added = "Added"
+category = "Category"
+confidence = "Confidence"
 count = "Files"
 folder = "Folder"
 modified = "Modified"
 name = "Name"
 size = "Size"
-toolHistory = "Tool history"
+tags = "Tags"
 toolHistoryAtVersion = "Cumulative tool chain"
 totalSize = "Total size"
 type = "Type"
@@ -5979,21 +5982,68 @@ ssn = "Social Security numbers"
 
 [policies.sidebar]
 activeCount = "{{count}} active"
-infoAriaLabel = "What is a policy?"
 infoTooltip = "A policy is a fixed set of tools that runs automatically whenever it's triggered — for example when a new document arrives — enforcing rules like redacting PII with no manual steps."
 loading = "Loading…"
+optionsAriaLabel = "Policy options"
+policySettings = "Policy settings"
 railAriaLabel = "{{label}} policy — {{status}}"
 railSuffixActive = " (Active)"
 railSuffixPaused = " (Paused)"
 setUp = "Set up"
 title = "Policies"
 upgradeToEnterprise = "Upgrade to enterprise"
+whatIsPolicy = "What is a policy?"
+
+[policies.settings]
+onExport = "On export"
+onUpload = "On upload"
+noneExport = "No policies currently run on export."
+noneUpload = "No policies currently run on upload."
+reorderHandle = "Drag to reorder"
+runOrderDesc = "When more than one policy runs on the same trigger, they run in this order — each on the previous policy's output. Drag to reorder."
+title = "Policy settings"
 
 [policies.status]
 active = "Active"
 paused = "Paused"
 setup = "Set up"
 
+[policies.taxonomy]
+add = "Add"
+addCategory = "Add category"
+addSub = "Add sub-category"
+addTag = "Add a tag"
+addTagPlaceholder = "Add a tag"
+categories = "categories"
+categoryLabel = "Category"
+collapse = "Collapse"
+customNote = "Customized for your team."
+defaultNote = "Using the built-in default, shared with your team."
+edit = "Edit taxonomy"
+emptyCategories = "No categories yet — add one to get started."
+expand = "Expand"
+export = "Export JSON"
+id = "ID"
+import = "Import JSON"
+importError = "Couldn't import that file."
+managedNote = "The taxonomy is managed by your team leader."
+modalSubtitle = "Shared with your whole team. Categories, their sub-categories, and tags the classifier uses."
+modalTitle = "Classification taxonomy"
+noTags = "No tags yet."
+removeCategory = "Remove category"
+removeSub = "Remove sub-category"
+removeTag = "Remove {{tag}}"
+resetToDefault = "Reset to default"
+saveForTeam = "Save for team"
+saving = "Saving…"
+sectionLabel = "Classification taxonomy"
+startFromScratch = "Start from scratch"
+subCategories = "sub-categories"
+subCount = "{{count}} sub"
+subLabel = "Sub-category"
+tags = "Tags"
+view = "View taxonomy"
+
 [policies.toolConfig]
 enableAriaLabel = "Enable {{tool}}"
 infoAriaLabel = "What does {{tool}} do?"

frontend/editor/scripts/generate-classification-taxonomy.mts

@@ -0,0 +1,64 @@
+/**
+ * Generates the engine's default classification taxonomy JSON from the type-safe
+ * TS source of truth (src/proprietary/data/classificationTaxonomy.ts).
+ *
+ * The Python engine can't import TypeScript, so it reads the generated JSON at
+ * startup. Editing the .ts and regenerating keeps the two in lockstep — the .ts
+ * is type-checked, so a malformed entry fails the build rather than shipping.
+ *
+ * Run: `npx tsx editor/scripts/generate-classification-taxonomy.mts`         (writes the JSON)
+ *      `npx tsx editor/scripts/generate-classification-taxonomy.mts --check` (CI drift guard)
+ *
+ * .mts (not .ts) so `import.meta.url` resolves paths relative to this script —
+ * Task invokes it from the workspace root (frontend/), same as setup-env.mts.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// frontend/package.json has no "type": "module", so tsx treats the source .ts as
+// CommonJS. require() it (tsx hooks require for .ts) to read its named export
+// reliably — a named ESM import can't see the export of a CJS-interpreted file.
+const require = createRequire(import.meta.url);
+const {
+  DEFAULT_CLASSIFICATION_TAXONOMY,
+} = require("../src/proprietary/data/classificationTaxonomy");
+
+const here = dirname(fileURLToPath(import.meta.url));
+// editor/scripts -> repo root is three levels up (scripts -> editor -> frontend).
+const repoRoot = resolve(here, "../../..");
+const outPath = resolve(
+  repoRoot,
+  "engine/src/stirling/agents/default_classification_taxonomy.generated.json",
+);
+
+const NOTICE =
+  "AUTO-GENERATED from frontend/editor/src/proprietary/data/classificationTaxonomy.ts " +
+  "by editor/scripts/generate-classification-taxonomy.mts — do NOT edit by hand; run `task frontend:classifier-categories`.";
+const json =
+  JSON.stringify(
+    { _generated: NOTICE, ...DEFAULT_CLASSIFICATION_TAXONOMY },
+    null,
+    2,
+  ) + "\n";
+
+if (process.argv.includes("--check")) {
+  const current = existsSync(outPath) ? readFileSync(outPath, "utf8") : "";
+  if (current !== json) {
+    console.error(
+      "default_classification_taxonomy.generated.json is stale. Run `task frontend:classifier-categories` " +
+        "(npx tsx editor/scripts/generate-classification-taxonomy.mts).",
+    );
+    process.exit(1);
+  }
+  console.log("default_classification_taxonomy.generated.json is up to date.");
+} else {
+  writeFileSync(outPath, json);
+  const categories = DEFAULT_CLASSIFICATION_TAXONOMY.categories.length;
+  const tags = DEFAULT_CLASSIFICATION_TAXONOMY.tags.length;
+  console.log(
+    `Wrote ${outPath}\n  ${categories} categories, ${tags} loose tags`,
+  );
+}

frontend/editor/src/core/components/filesPage/FileDetailsPanel.tsx

@@ -20,15 +20,75 @@ import {
   downloadFileFromStorage,
   downloadMultipleFiles,
 } from "@app/utils/downloadUtils";
-import ToolChain from "@app/components/shared/ToolChain";
 import ShareManagementModal from "@app/components/shared/ShareManagementModal";
 import { useSharingEnabled } from "@app/hooks/useSharingEnabled";
 import { fileStorage } from "@app/services/fileStorage";
+import { extractPDFMetadata } from "@app/services/pdfMetadataService";
 import {
   VersionTimeline,
   DetailField,
 } from "@app/components/filesPage/VersionTimeline";
 
+/** Custom PDF Info-dictionary key the classify-and-tag tool writes (must match
+ *  the backend's PdfMetadataService.CLASSIFICATION_KEY). */
+const CLASSIFICATION_KEY = "StirlingPDFClassification";
+
+/** Reading classification means loading the file's bytes through PDF.js, so cap
+ *  the auto-read by size — the app handles very large PDFs and we won't pull a
+ *  multi-GB file into memory just to surface a metadata tag. */
+const MAX_CLASSIFICATION_READ_BYTES = 25 * 1024 * 1024;
+
+interface DocumentClassification {
+  category: string;
+  categoryLabel: string;
+  docType: string;
+  docTypeLabel: string;
+  typeConfidence?: number;
+  tags: string[];
+}
+
+/** Parse the classification JSON stored in PDF metadata; null if absent/invalid. */
+function parseClassification(value: string): DocumentClassification | null {
+  try {
+    const raw = JSON.parse(value) as Record<string, unknown>;
+    const category = typeof raw.category === "string" ? raw.category : "";
+    const docType = typeof raw.docType === "string" ? raw.docType : "";
+    if (!category && !docType) return null;
+    // The classifier stores the human label alongside the id; older files
+    // predate it, so fall back to prettifying the id.
+    const categoryLabel =
+      typeof raw.categoryLabel === "string" && raw.categoryLabel
+        ? raw.categoryLabel
+        : prettyLabel(category);
+    const docTypeLabel =
+      typeof raw.docTypeLabel === "string" && raw.docTypeLabel
+        ? raw.docTypeLabel
+        : prettyLabel(docType);
+    return {
+      category,
+      categoryLabel,
+      docType,
+      docTypeLabel,
+      typeConfidence:
+        typeof raw.typeConfidence === "number" ? raw.typeConfidence : undefined,
+      tags: Array.isArray(raw.tags)
+        ? raw.tags.filter((tag): tag is string => typeof tag === "string")
+        : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** "lab_result" / "lab-result" → "Lab result" — fallback for pre-label files. */
+function prettyLabel(id: string): string {
+  return id
+    .split(/[_\-\s]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
 interface FileDetailsPanelProps {
   selectedFileIds: FileId[];
   fileMap: Map<FileId, StirlingFileStub>;
@@ -76,6 +136,12 @@ export function FileDetailsPanel({
   // Metadata (size/type/dates) is collapsed by default so the panel stays
   // short and the action buttons keep their pinned footer in view.
   const [fieldsOpen, setFieldsOpen] = useState(false);
+  // Version journey is collapsed by default so the panel stays short.
+  const [versionsOpen, setVersionsOpen] = useState(false);
+  // Document classification read from PDF metadata, plus its (collapsed) section.
+  const [classification, setClassification] =
+    useState<DocumentClassification | null>(null);
+  const [classificationOpen, setClassificationOpen] = useState(false);
   // Version chain for the selected file; empty for v1 or multi-select.
   const [versionChain, setVersionChain] = useState<StirlingFileStub[]>([]);
   const singleFileForChain = files.length === 1 ? files[0] : null;
@@ -101,6 +167,35 @@ export function FileDetailsPanel({
     };
   }, [singleFileForChain]);
 
+  // Read the classification the policy wrote into PDF metadata
+  useEffect(() => {
+    setClassification(null);
+    const stub = singleFileForChain;
+    if (!stub) return;
+    if (stub.type && !stub.type.toLowerCase().includes("pdf")) return;
+    if (stub.size > MAX_CLASSIFICATION_READ_BYTES) return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const file = await fileStorage.getStirlingFile(stub.id);
+        if (cancelled || !file) return;
+        const result = await extractPDFMetadata(file);
+        if (cancelled || !result.success) return;
+        const entry = result.metadata.customMetadata.find(
+          (item) => item.key === CLASSIFICATION_KEY,
+        );
+        if (!entry) return;
+        const parsed = parseClassification(entry.value);
+        if (parsed && !cancelled) setClassification(parsed);
+      } catch (err) {
+        console.error("Failed to read classification metadata", err);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [singleFileForChain]);
+
   if (files.length === 0) {
     return null;
   }
@@ -232,17 +327,74 @@ export function FileDetailsPanel({
                 />
               </div>
             )}
-            {single.toolHistory && single.toolHistory.length > 0 && (
-              <div className="files-page-details-tool-history">
-                <div className="files-page-details-tool-history-label">
-                  {t("filesPage.field.toolHistory", "Tool history")}
-                </div>
-                <ToolChain
-                  toolChain={single.toolHistory}
-                  displayStyle="badges"
-                  size="xs"
-                />
-              </div>
+            {classification && (
+              <>
+                <button
+                  type="button"
+                  className="files-page-details-collapse-toggle"
+                  onClick={() => setClassificationOpen((o) => !o)}
+                  aria-expanded={classificationOpen}
+                >
+                  <span>{t("filesPage.classification", "Classification")}</span>
+                  <KeyboardArrowDownIcon
+                    className={`files-page-details-collapse-chevron${
+                      classificationOpen ? " is-open" : ""
+                    }`}
+                    fontSize="small"
+                  />
+                </button>
+                {classificationOpen && (
+                  <div className="files-page-details-fieldlist">
+                    {classification.category && (
+                      <DetailField
+                        label={t("filesPage.field.category", "Category")}
+                        value={classification.categoryLabel}
+                      />
+                    )}
+                    {classification.docType && (
+                      <DetailField
+                        label={t("filesPage.field.type", "Type")}
+                        value={classification.docTypeLabel}
+                      />
+                    )}
+                    {classification.typeConfidence != null && (
+                      <DetailField
+                        label={t("filesPage.field.confidence", "Confidence")}
+                        value={`${Math.round(
+                          classification.typeConfidence * 100,
+                        )}%`}
+                      />
+                    )}
+                    {classification.tags.length > 0 && (
+                      <div className="files-page-details-field">
+                        <span className="files-page-details-field-label">
+                          {t("filesPage.field.tags", "Tags")}
+                        </span>
+                        <span
+                          className="files-page-details-field-value"
+                          style={{
+                            display: "flex",
+                            flexWrap: "wrap",
+                            gap: "0.25rem",
+                            justifyContent: "flex-end",
+                          }}
+                        >
+                          {classification.tags.map((tag) => (
+                            <Badge
+                              key={tag}
+                              size="xs"
+                              variant="light"
+                              color="orange"
+                            >
+                              {tag}
+                            </Badge>
+                          ))}
+                        </span>
+                      </div>
+                    )}
+                  </div>
+                )}
+              </>
             )}
             {/* Version journey. Each tool run writes a new StirlingFile
                 with the same `originalFileId` and an incremented
@@ -266,12 +418,37 @@ export function FileDetailsPanel({
                   )}
                 </Button>
               ) : (
-                <VersionTimeline
-                  chain={versionChain}
-                  currentId={single.id}
-                  onAddToWorkspace={onAddToWorkspace}
-                  onRemove={onRemove}
-                />
+                <>
+                  <button
+                    type="button"
+                    className="files-page-details-collapse-toggle"
+                    onClick={() => setVersionsOpen((o) => !o)}
+                    aria-expanded={versionsOpen}
+                  >
+                    <span>
+                      {t(
+                        "filesPage.viewVersionHistory",
+                        "Version journey ({{count}})",
+                        { count: versionChain.length },
+                      )}
+                    </span>
+                    <KeyboardArrowDownIcon
+                      className={`files-page-details-collapse-chevron${
+                        versionsOpen ? " is-open" : ""
+                      }`}
+                      fontSize="small"
+                    />
+                  </button>
+                  {versionsOpen && (
+                    <VersionTimeline
+                      chain={versionChain}
+                      currentId={single.id}
+                      onAddToWorkspace={onAddToWorkspace}
+                      onRemove={onRemove}
+                      hideHeader
+                    />
+                  )}
+                </>
               ))}
           </>
         ) : (

frontend/editor/src/core/components/filesPage/VersionTimeline.tsx

@@ -55,6 +55,7 @@ export interface VersionTimelineProps {
   currentId: FileId;
   onAddToWorkspace: (fileIds: FileId[]) => void;
   onRemove: (fileIds: FileId[]) => void;
+  hideHeader?: boolean;
 }
 
 /** Version timeline with per-row tool deltas and collapse-when-long. */
@@ -63,6 +64,7 @@ export function VersionTimeline({
   currentId,
   onAddToWorkspace,
   onRemove,
+  hideHeader = false,
 }: VersionTimelineProps) {
   const { t } = useTranslation();
   const [expandedIds, setExpandedIds] = useState<Set<FileId>>(new Set());
@@ -120,15 +122,17 @@ export function VersionTimeline({
 
   return (
     <div className="files-page-details-version-timeline">
-      <div className="files-page-details-version-timeline-label">
-        <HistoryIcon fontSize="small" />
-        <span>{t("filesPage.field.versionHistory", "Version journey")}</span>
-        <span className="files-page-details-version-timeline-count">
-          {t("filesPage.versionsCount", "{{count}} versions", {
-            count: ordered.length,
-          })}
-        </span>
-      </div>
+      {!hideHeader && (
+        <div className="files-page-details-version-timeline-label">
+          <HistoryIcon fontSize="small" />
+          <span>{t("filesPage.field.versionHistory", "Version journey")}</span>
+          <span className="files-page-details-version-timeline-count">
+            {t("filesPage.versionsCount", "{{count}} versions", {
+              count: ordered.length,
+            })}
+          </span>
+        </div>
+      )}
       <ol className="files-page-details-version-timeline-list">
         {rows.map((row, idx) => {
           const isLast = idx === rows.length - 1;

frontend/editor/src/core/components/shared/FileSidebarFileItem.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef } from "react";
+import { useState, useCallback, useRef, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { Menu, Tooltip } from "@mantine/core";
 import { useTranslation } from "react-i18next";
@@ -135,6 +135,8 @@ export interface FileItemFolderRef {
 export interface FileItemPolicyRef {
   id: string;
   name: string;
+  /** Badge glyph — the policy's own icon; falls back to a shield. */
+  icon?: ReactNode;
   /** CSS colour for the badge (matches the policy's accent). */
   accentColor: string;
   /** True only just after the policy was applied — drives the one-off glow, so
@@ -313,7 +315,9 @@ export function FileItem({
                       className="file-sidebar-policy-badge"
                       style={{ color: policy.accentColor }}
                     >
-                      <ShieldOutlinedIcon sx={{ fontSize: "0.7rem" }} />
+                      {policy.icon ?? (
+                        <ShieldOutlinedIcon sx={{ fontSize: "0.7rem" }} />
+                      )}
                     </span>
                   </Tooltip>
                 ))}

frontend/editor/src/core/contexts/FileContext.tsx

@@ -267,10 +267,13 @@ function FileContextInner({
       if (options?.selectFiles && stirlingFiles.length > 0) {
         selectFiles(stirlingFiles);
       }
+      if (stirlingFiles.length > 0) {
+        indexedDB?.bumpRevision?.();
+      }
 
       return stirlingFiles;
     },
-    [enablePersistence, requestConfirmation],
+    [enablePersistence, requestConfirmation, indexedDB],
   );
 
   const addFilesWithOptions = useCallback(
@@ -306,9 +309,13 @@ function FileContextInner({
         selectFiles(stirlingFiles);
       }
 
+      if (stirlingFiles.length > 0) {
+        indexedDB?.bumpRevision?.();
+      }
+
       return stirlingFiles;
     },
-    [enablePersistence],
+    [enablePersistence, indexedDB],
   );
 
   const addStirlingFileStubsAction = useCallback(

frontend/editor/src/core/utils/slug.ts

@@ -0,0 +1,13 @@
+/**
+ * Turn a human label into a url/id-safe slug: lowercased, with every run of
+ * non-alphanumerics collapsed to a single hyphen and leading/trailing hyphens
+ * trimmed. May return an empty string (e.g. an all-symbol input); callers that
+ * need a non-empty id should supply their own fallback.
+ */
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

frontend/editor/src/proprietary/components/chat/ChatContext.tsx

@@ -162,6 +162,11 @@ interface AiWorkflowResultFile {
   fileId: string;
   fileName: string;
   contentType: string;
+  /**
+   * Index into the files we sent that this output was derived from, or null/undefined when it has
+   * no single source (merge, generated file). Used to replace that input in place as a new version.
+   */
+  sourceIndex?: number | null;
 }
 
 interface AiWorkflowResponse {
@@ -432,9 +437,11 @@ export function ChatProvider({ children }: { children: ReactNode }) {
 
   // Import the files produced by an AI workflow result into FileContext.
   //
-  // If the workflow produced the same number of outputs as inputs, map each output to its
-  // corresponding input as a new version in the same chain. Otherwise (merge, split, etc.)
-  // add the outputs as new root files.
+  // Each output carries a sourceIndex telling us which input it came from. An input that produced
+  // exactly one output is replaced in place as a new version of that file; everything else (merge,
+  // split, generated files, or an input that produced nothing) is added as a fresh root and leaves
+  // the original files untouched — we never remove or deselect a file the workflow didn't clearly
+  // transform 1:1.
   const importResultFile = useCallback(
     async (
       result: AiWorkflowResponse,
@@ -456,27 +463,43 @@ export function ChatProvider({ children }: { children: ReactNode }) {
       const files = await Promise.all(descriptors.map(downloadFile));
 
       if (sourceStubs.length > 0) {
-        // Always consume the inputs so merge/split inputs are removed from the workbench.
-        // For 1:1 operations (rotate, compress) the outputs carry the version chain; for
-        // merge/split they're fresh roots.
         const operation: ToolOperation = {
           toolId: "ai-workflow",
           timestamp: Date.now(),
         };
-        const isVersionMapping = files.length === sourceStubs.length;
-        const stubs = files.map((file, i) =>
-          isVersionMapping
-            ? createChildStub(sourceStubs[i], operation, file)
-            : createNewStirlingFileStub(file),
-        );
+        // Resolve each output to the input it came from (sourceIndex, from the backend).
+        const sourceForOutput = descriptors.map((descriptor) => {
+          const idx = descriptor.sourceIndex;
+          return typeof idx === "number" && idx >= 0 && idx < sourceStubs.length
+            ? sourceStubs[idx]
+            : null;
+        });
+        // Only replace a source in place when it maps to exactly one output (a clean 1:1 transform).
+        // A split (one input → many outputs) or a source shared by several outputs stays a set of
+        // fresh roots so we don't collapse them onto one version chain.
+        const outputsPerSource = new Map<StirlingFileStub["id"], number>();
+        for (const source of sourceForOutput) {
+          if (source) {
+            outputsPerSource.set(
+              source.id,
+              (outputsPerSource.get(source.id) ?? 0) + 1,
+            );
+          }
+        }
+        const consumedIds: StirlingFileStub["id"][] = [];
+        const stubs = files.map((file, i) => {
+          const source = sourceForOutput[i];
+          if (source && outputsPerSource.get(source.id) === 1) {
+            consumedIds.push(source.id);
+            return createChildStub(source, operation, file);
+          }
+          return createNewStirlingFileStub(file);
+        });
         const stirlingFiles = files.map((file, i) =>
           createStirlingFile(file, stubs[i].id),
         );
-        await fileActions.consumeFiles(
-          sourceStubs.map((s) => s.id),
-          stirlingFiles,
-          stubs,
-        );
+        // Consume only the inputs we actually versioned; unrelated files are left in place.
+        await fileActions.consumeFiles(consumedIds, stirlingFiles, stubs);
       } else {
         // No inputs: pass raw files so addFiles assigns consistent IDs. Pre-assigning stub IDs
         // here would cause a fileId mismatch in filesRef, making getFiles() clone the file

frontend/editor/src/proprietary/components/policies/ClassificationTaxonomySection.tsx

@@ -0,0 +1,179 @@
+/**
+ * The Classification policy's taxonomy control, shown in its Edit-Settings view.
+ * Renders a compact summary (counts + category chips) with an Expand button that
+ * opens the fat {@link TaxonomyEditorModal}. Owns the editable draft and the
+ * load/save/reset/import/export wiring via {@link useClassificationTaxonomy}. The
+ * taxonomy is team-shared; only users who can configure policies may edit it.
+ */
+
+import { useEffect, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import OpenInFullIcon from "@mui/icons-material/OpenInFull";
+import LockOutlinedIcon from "@mui/icons-material/LockOutlined";
+import { Card } from "@shared/components/Card";
+import { Button } from "@shared/components/Button";
+import { Chip } from "@shared/components/Chip";
+import { Banner } from "@shared/components/Banner";
+import { useClassificationTaxonomy } from "@app/hooks/useClassificationTaxonomy";
+import { TaxonomyEditorModal } from "@app/components/policies/TaxonomyEditorModal";
+import {
+  downloadTaxonomy,
+  parseTaxonomyFile,
+  validateTaxonomy,
+} from "@app/services/taxonomyFile";
+import {
+  DEFAULT_CLASSIFICATION_TAXONOMY,
+  type ClassificationTaxonomy,
+} from "@app/data/classificationTaxonomy";
+import "@app/components/policies/TaxonomyEditor.css";
+
+interface ClassificationTaxonomySectionProps {
+  canConfigure: boolean;
+}
+
+export function ClassificationTaxonomySection({
+  canConfigure,
+}: ClassificationTaxonomySectionProps) {
+  const { t } = useTranslation();
+  const { taxonomy, isCustom, loading, saving, error, save } =
+    useClassificationTaxonomy(true);
+
+  const [draft, setDraft] = useState<ClassificationTaxonomy>(taxonomy);
+  const [open, setOpen] = useState(false);
+  const [localError, setLocalError] = useState<string | null>(null);
+
+  // Sync the draft to server truth whenever it changes (load / save / reset).
+  // Local edits don't change `taxonomy`, so this never clobbers them mid-edit.
+  useEffect(() => setDraft(taxonomy), [taxonomy]);
+
+  const dirty = useMemo(
+    () => JSON.stringify(draft) !== JSON.stringify(taxonomy),
+    [draft, taxonomy],
+  );
+
+  const subCount = useMemo(
+    () => taxonomy.categories.reduce((n, c) => n + c.docTypes.length, 0),
+    [taxonomy],
+  );
+
+  const close = () => {
+    setDraft(taxonomy);
+    setLocalError(null);
+    setOpen(false);
+  };
+
+  const onImportFile = (file: File) => {
+    setLocalError(null);
+    void parseTaxonomyFile(file)
+      .then(setDraft)
+      .catch((e: unknown) =>
+        setLocalError(
+          e instanceof Error
+            ? e.message
+            : t("policies.taxonomy.importError", "Couldn't import that file."),
+        ),
+      );
+  };
+
+  const onSave = () => {
+    const errors = validateTaxonomy(draft);
+    if (errors.length > 0) {
+      setLocalError(errors[0]);
+      return;
+    }
+    setLocalError(null);
+    void save(draft).then(() => setOpen(false));
+  };
+
+  return (
+    <div className="tax-summary">
+      <p className="pol-section-label">
+        {t("policies.taxonomy.sectionLabel", "Classification taxonomy")}
+      </p>
+      <Card>
+        {loading ? (
+          <span className="tax-empty">{t("loading", "Loading…")}</span>
+        ) : (
+          <div className="tax-summary">
+            <div className="tax-summary-stats">
+              <span>
+                <strong>{taxonomy.categories.length}</strong>{" "}
+                {t("policies.taxonomy.categories", "categories")}
+              </span>
+              <span>
+                <strong>{subCount}</strong>{" "}
+                {t("policies.taxonomy.subCategories", "sub-categories")}
+              </span>
+              <span>
+                <strong>{taxonomy.tags.length}</strong>{" "}
+                {t("policies.taxonomy.tags", "tags")}
+              </span>
+            </div>
+            <div className="tax-summary-cats">
+              {taxonomy.categories.map((c) => (
+                <Chip key={c.id} tone="neutral" size="sm">
+                  {c.label}
+                </Chip>
+              ))}
+            </div>
+            <span className="tax-empty">
+              {isCustom
+                ? t("policies.taxonomy.customNote", "Customized for your team.")
+                : t(
+                    "policies.taxonomy.defaultNote",
+                    "Using the built-in default, shared with your team.",
+                  )}
+            </span>
+            <Button
+              variant="outline"
+              size="sm"
+              leadingIcon={<OpenInFullIcon sx={{ fontSize: "1rem" }} />}
+              onClick={() => setOpen(true)}
+              style={{ alignSelf: "flex-start" }}
+            >
+              {canConfigure
+                ? t("policies.taxonomy.edit", "Edit taxonomy")
+                : t("policies.taxonomy.view", "View taxonomy")}
+            </Button>
+          </div>
+        )}
+      </Card>
+
+      {!canConfigure && (
+        <Banner
+          tone="neutral"
+          icon={<LockOutlinedIcon sx={{ fontSize: "1rem" }} />}
+          description={t(
+            "policies.taxonomy.managedNote",
+            "The taxonomy is managed by your team leader.",
+          )}
+        />
+      )}
+
+      <TaxonomyEditorModal
+        open={open}
+        onClose={close}
+        draft={draft}
+        onDraftChange={setDraft}
+        onImportFile={onImportFile}
+        onExport={() => downloadTaxonomy(draft)}
+        onReset={() => {
+          // Stage the built-in default into the draft — reversible via Cancel,
+          // only persisted on Save (no immediate destructive server delete).
+          setLocalError(null);
+          setDraft(DEFAULT_CLASSIFICATION_TAXONOMY);
+        }}
+        onClear={() => {
+          // Stage an empty taxonomy to build from scratch — also reversible until Save.
+          setLocalError(null);
+          setDraft({ categories: [], tags: [] });
+        }}
+        onSave={onSave}
+        dirty={dirty}
+        saving={saving}
+        readOnly={!canConfigure}
+        error={localError ?? error}
+      />
+    </div>
+  );
+}

frontend/editor/src/proprietary/components/policies/Policies.css

@@ -128,6 +128,81 @@
   flex-shrink: 0;
 }
 
+/* ── Policy settings: per-trigger run-order lists ── */
+.pol-reorder-section {
+  margin-top: var(--space-3);
+}
+.pol-reorder-list {
+  display: flex;
+  flex-direction: column;
+  margin-top: var(--space-1);
+}
+/* A reorder row: leading grip + tinted icon + label. Square (no radius) so the
+   drop line reads as one straight rule across the list. */
+.pol-reorder-row {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1_5) var(--space-2);
+}
+.pol-reorder-row[data-dragging] {
+  opacity: 0.4;
+}
+/* Straight, full-width blue insertion line at the drop position (no curves). */
+.pol-reorder-row[data-drop="above"]::before,
+.pol-reorder-row[data-drop="below"]::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: var(--color-blue);
+  pointer-events: none;
+}
+.pol-reorder-row[data-drop="above"]::before {
+  top: -1px;
+}
+.pol-reorder-row[data-drop="below"]::after {
+  bottom: -1px;
+}
+.pol-reorder-grip {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.25rem;
+  color: var(--color-text-4);
+  cursor: grab;
+}
+.pol-reorder-grip:active {
+  cursor: grabbing;
+}
+.pol-reorder-label {
+  flex: 1;
+  min-width: 0;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  color: var(--color-text-1);
+}
+/* The drag ghost (a cloned row): the whole row with a full blue outline, kept
+   translucent so the list shows through as it moves. */
+.pol-reorder-row--ghost {
+  border-radius: var(--radius-lg);
+  outline: 2px solid var(--color-blue);
+  outline-offset: -2px;
+  background: var(--color-surface);
+  box-shadow: var(--shadow-md);
+  opacity: 0.55;
+}
+/* Empty-state line for a trigger with no policies. */
+.pol-reorder-empty {
+  margin: var(--space-1) 0 0;
+  padding: var(--space-1_5) var(--space-2);
+  font-size: 0.8125rem;
+  color: var(--color-text-3);
+}
+
 /* Retry button on a failed activity row. */
 /* Expandable error text in the activity feed — long backend errors are clamped
    and collapsed by default so they don't blow up the row. */
@@ -273,6 +348,36 @@
   margin: 0 0 var(--space-2);
 }
 
+/* A section label rendered as a collapse toggle (Recent Activity): strip the
+   button chrome but keep the .pol-section-label typography, chevron pushed right. */
+.pol-section-toggle {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  width: 100%;
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  text-align: left;
+  font-family: inherit;
+}
+.pol-section-chevron {
+  margin-left: auto;
+  color: var(--color-text-4);
+  transition: transform 0.15s ease;
+}
+.pol-section-chevron.is-open {
+  transform: rotate(180deg);
+}
+
+/* Recent-activity feed: cap to ~4.5 rows (and never more than ~45% of the
+   viewport) then scroll, so a long history doesn't push the stats footer away. */
+.pol-activity-list {
+  max-height: min(22rem, 45vh);
+  overflow-y: auto;
+}
+
 /* Sub-section header inside a settings card (e.g. "Output filename"). The field
    directly below it carries data-first so the borders don't double up. */
 .pol-subhead {

frontend/editor/src/proprietary/components/policies/PoliciesSidebar.tsx

@@ -12,10 +12,20 @@
  *     collapsed; clicking an icon selects the policy and expands the rail.
  */
 
-import { useState, useEffect, useMemo, type ReactNode } from "react";
+import {
+  useState,
+  useEffect,
+  useMemo,
+  type DragEvent,
+  type ReactNode,
+} from "react";
 import { useTranslation } from "react-i18next";
+import { Menu } from "@mantine/core";
 import ChevronRightIcon from "@mui/icons-material/ChevronRight";
-import LocalIcon from "@app/components/shared/LocalIcon";
+import DragIndicatorRounded from "@mui/icons-material/DragIndicatorRounded";
+import MoreHorizRounded from "@mui/icons-material/MoreHorizRounded";
+import TuneRounded from "@mui/icons-material/TuneRounded";
+import InfoOutlined from "@mui/icons-material/InfoOutlined";
 import { usePolicies } from "@app/hooks/usePolicies";
 import { usePolicyCatalog } from "@app/hooks/usePolicyCatalog";
 import { useAppConfig } from "@app/contexts/AppConfigContext";
@@ -44,12 +54,15 @@ import { SectionHeader } from "@shared/components/SectionHeader";
 import { PolicySetupWizard } from "@app/components/policies/PolicySetupWizard";
 import { PolicyDetailPanel } from "@app/components/policies/PolicyDetailPanel";
 import { PolicyDeleteConfirmModal } from "@app/components/policies/PolicyDeleteConfirmModal";
-import type { PolicyConfigResult } from "@app/types/policies";
+import type { PolicyCategory, PolicyConfigResult } from "@app/types/policies";
+import { PanelHeader } from "@shared/components/PanelHeader";
 import {
   usePolicySelection,
   selectPolicy,
   setPolicyDetailView,
   closePolicy,
+  openPolicySettings,
+  closePolicySettings,
 } from "@app/components/policies/policySelectionStore";
 import "@app/components/policies/Policies.css";
 
@@ -95,8 +108,8 @@ function promptGuestSignup(): void {
  * place of the tool list. False when the feature is off or nothing is selected.
  */
 export function usePolicyDetailActive(): boolean {
-  const { selectedId } = usePolicySelection();
-  return POLICIES_ENABLED && selectedId != null;
+  const { selectedId, settingsOpen } = usePolicySelection();
+  return POLICIES_ENABLED && (selectedId != null || settingsOpen);
 }
 
 /** The collapsible policy list, rendered above the Tools section. */
@@ -146,6 +159,13 @@ export function PoliciesSection({
     (c) => pol.policies[c.id]?.configured,
   ).length;
 
+  // Rows render in execution order (defaults to catalog order until reordered
+  // on the Policy settings page).
+  const displayCategories = [...visibleCategories].sort(
+    (a, b) =>
+      (pol.policies[a.id]?.order ?? 0) - (pol.policies[b.id]?.order ?? 0),
+  );
+
   return (
     <div className="pol-list">
       <div className="pol-list-head">
@@ -159,36 +179,51 @@ export function PoliciesSection({
           expanded={expanded}
           onToggle={toggleExpanded}
         />
-        <AppTooltip
-          content={t(
-            "policies.sidebar.infoTooltip",
-            "A policy is a fixed set of tools that runs automatically whenever it's triggered — for example when a new document arrives — enforcing rules like redacting PII with no manual steps.",
-          )}
-          sidebarTooltip
-          pinOnClick
-        >
-          <button
-            type="button"
-            className="pol-info-btn"
-            aria-label={t(
-              "policies.sidebar.infoAriaLabel",
-              "What is a policy?",
+        <Menu position="bottom-end" width="13rem" withinPortal>
+          <Menu.Target>
+            <button
+              type="button"
+              className="pol-info-btn"
+              aria-label={t(
+                "policies.sidebar.optionsAriaLabel",
+                "Policy options",
+              )}
+            >
+              <MoreHorizRounded sx={{ fontSize: "1.25rem" }} />
+            </button>
+          </Menu.Target>
+          <Menu.Dropdown>
+            {/* Hovering surfaces the same explanation the info tooltip used to show. */}
+            <AppTooltip
+              content={t(
+                "policies.sidebar.infoTooltip",
+                "A policy is a fixed set of tools that runs automatically whenever it's triggered — for example when a new document arrives — enforcing rules like redacting PII with no manual steps.",
+              )}
+              position="left"
+              maxWidth="16rem"
+            >
+              <Menu.Item
+                leftSection={<InfoOutlined sx={{ fontSize: "1rem" }} />}
+              >
+                {t("policies.sidebar.whatIsPolicy", "What is a policy?")}
+              </Menu.Item>
+            </AppTooltip>
+            {pol.canConfigure && (
+              <Menu.Item
+                leftSection={<TuneRounded sx={{ fontSize: "1rem" }} />}
+                onClick={() => openPolicySettings()}
+              >
+                {t("policies.sidebar.policySettings", "Policy settings")}
+              </Menu.Item>
             )}
-          >
-            <LocalIcon
-              icon="info-outline-rounded"
-              width="1.25rem"
-              height="1.25rem"
-              style={{ color: "var(--icon-files-color)" }}
-            />
-          </button>
-        </AppTooltip>
+          </Menu.Dropdown>
+        </Menu>
       </div>
 
       {expanded && (
         <>
           <div className="pol-list-rows">
-            {visibleCategories.map((cat) => {
+            {displayCategories.map((cat) => {
               if (cat.comingSoon) {
                 return (
                   <div key={cat.id} className="pol-row pol-row--soon">
@@ -258,11 +293,25 @@ export function PoliciesSection({
   );
 }
 
+/**
+ * Takeover dispatcher: shows the policy-settings page (execution order), an open
+ * policy's detail, or nothing — whichever the selection store currently holds.
+ * The heavy per-policy hooks live in {@link PolicyOpenDetail}, so the settings
+ * page doesn't pay for (or trip over) them.
+ */
+export function PolicyDetailTakeover() {
+  const { selectedId, settingsOpen } = usePolicySelection();
+  if (!POLICIES_ENABLED) return null;
+  if (settingsOpen && selectedId == null) return <PolicySettingsPanel />;
+  if (selectedId == null) return null;
+  return <PolicyOpenDetail />;
+}
+
 /**
  * The open-policy view — narrative detail, setup wizard, or edit-settings —
  * which replaces the Tools area while a policy is selected.
  */
-export function PolicyDetailTakeover() {
+function PolicyOpenDetail() {
   const { t } = useTranslation();
   const pol = usePolicies();
   const { categories, configs, sources, docTypes } = usePolicyCatalog();
@@ -459,6 +508,232 @@ export function PolicyDetailTakeover() {
   );
 }
 
+/**
+ * The Policy settings takeover — reached from the section header's "…" menu.
+ * Each trigger (upload / export) gets its own run-order list, since a chain only
+ * spans policies that fire on the same trigger — reordering one never affects the
+ * other. Admin-only (the menu entry is gated on canConfigure).
+ */
+function PolicySettingsPanel() {
+  const { t } = useTranslation();
+  const pol = usePolicies();
+  const { categories } = usePolicyCatalog();
+
+  // Configured, live policies for a trigger, in execution order.
+  const inOrder = (trigger: "upload" | "export") =>
+    categories
+      .filter(
+        (c) =>
+          pol.policies[c.id]?.configured &&
+          !c.comingSoon &&
+          (pol.policies[c.id]?.runOn ?? "upload") === trigger,
+      )
+      .sort(
+        (a, b) =>
+          (pol.policies[a.id]?.order ?? 0) - (pol.policies[b.id]?.order ?? 0),
+      );
+
+  const uploadCats = inOrder("upload");
+  const exportCats = inOrder("export");
+
+  // Order is one global sort key, so persist both groups together (upload first)
+  // to keep each group's members contiguous — the auto-run chain reads relative
+  // order within a trigger.
+  const persist = (uploadIds: string[], exportIds: string[]) =>
+    pol.reorderPolicies([...uploadIds, ...exportIds]);
+
+  return (
+    <div className="pol-detail">
+      <PanelHeader
+        icon={<TuneRounded sx={{ fontSize: "1.1rem" }} />}
+        title={t("policies.settings.title", "Policy settings")}
+        onClose={() => closePolicySettings()}
+        closeLabel={t("policies.detail.close", "Close")}
+      />
+      <div className="pol-scroll">
+        <p className="pol-desc">
+          {t(
+            "policies.settings.runOrderDesc",
+            "When more than one policy runs on the same trigger, they run in this order — each on the previous policy's output. Drag to reorder.",
+          )}
+        </p>
+        {/* Both triggers are always shown so the run order for each is explicit,
+            with an empty note when a trigger has no policies. */}
+        <PolicyReorderSection
+          title={t("policies.settings.onUpload", "On upload")}
+          cats={uploadCats}
+          emptyText={t(
+            "policies.settings.noneUpload",
+            "No policies currently run on upload.",
+          )}
+          onReorder={(ids) =>
+            persist(
+              ids,
+              exportCats.map((c) => c.id),
+            )
+          }
+        />
+        <PolicyReorderSection
+          title={t("policies.settings.onExport", "On export")}
+          cats={exportCats}
+          emptyText={t(
+            "policies.settings.noneExport",
+            "No policies currently run on export.",
+          )}
+          onReorder={(ids) =>
+            persist(
+              uploadCats.map((c) => c.id),
+              ids,
+            )
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * One trigger's run-order list. Rows drag to reorder (only when there's more than
+ * one to order); the drag ghost is the whole row with a blue outline, and a
+ * straight blue line marks where the policy will land. Reorders in isolation and
+ * hands the new id order back to the parent to persist.
+ */
+function PolicyReorderSection({
+  title,
+  cats,
+  emptyText,
+  onReorder,
+}: {
+  title: string;
+  cats: PolicyCategory[];
+  emptyText: string;
+  onReorder: (orderedIds: string[]) => void;
+}) {
+  const { t } = useTranslation();
+  const [dragId, setDragId] = useState<string | null>(null);
+  const [overId, setOverId] = useState<string | null>(null);
+  // Whether the drop would land after (vs before) the hovered row.
+  const [overBelow, setOverBelow] = useState(false);
+  const draggable = cats.length >= 2;
+
+  const clear = () => {
+    setDragId(null);
+    setOverId(null);
+  };
+
+  const handleDrop = (targetId: string) => {
+    if (!dragId || dragId === targetId) return clear();
+    const ids = cats.map((c) => c.id);
+    const from = ids.indexOf(dragId);
+    let to = ids.indexOf(targetId) + (overBelow ? 1 : 0);
+    if (from < 0 || to < 0) return clear();
+    ids.splice(from, 1);
+    if (from < to) to -= 1;
+    ids.splice(to, 0, dragId);
+    onReorder(ids);
+    clear();
+  };
+
+  // The native drag image would be just the grip under the cursor; instead snapshot
+  // the whole row (a styled clone) so the ghost that follows the mouse is the full
+  // row with a blue outline.
+  const startDrag = (e: DragEvent<HTMLSpanElement>, catId: string) => {
+    setDragId(catId);
+    e.dataTransfer.effectAllowed = "move";
+    const row = (e.currentTarget as HTMLElement).closest(".pol-reorder-row");
+    if (row instanceof HTMLElement) {
+      const clone = row.cloneNode(true) as HTMLElement;
+      clone.classList.add("pol-reorder-row--ghost");
+      clone.style.width = `${row.offsetWidth}px`;
+      clone.style.position = "fixed";
+      clone.style.top = "-1000px";
+      clone.style.left = "-1000px";
+      clone.style.pointerEvents = "none";
+      document.body.appendChild(clone);
+      e.dataTransfer.setDragImage(clone, 24, row.offsetHeight / 2);
+      window.setTimeout(() => clone.remove(), 0);
+    }
+  };
+
+  if (cats.length === 0) {
+    return (
+      <section className="pol-reorder-section">
+        <p className="pol-section-label">{title}</p>
+        <p className="pol-reorder-empty">{emptyText}</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="pol-reorder-section">
+      <p className="pol-section-label">{title}</p>
+      <div className="pol-reorder-list">
+        {cats.map((cat) => (
+          <div
+            key={cat.id}
+            className="pol-reorder-row"
+            data-dragging={dragId === cat.id || undefined}
+            data-drop={
+              draggable && overId === cat.id && dragId !== cat.id
+                ? overBelow
+                  ? "below"
+                  : "above"
+                : undefined
+            }
+            onDragOver={
+              draggable
+                ? (e) => {
+                    if (!dragId) return;
+                    e.preventDefault();
+                    const rect = e.currentTarget.getBoundingClientRect();
+                    setOverId(cat.id);
+                    setOverBelow(e.clientY > rect.top + rect.height / 2);
+                  }
+                : undefined
+            }
+            onDragLeave={
+              draggable
+                ? () => setOverId((id) => (id === cat.id ? null : id))
+                : undefined
+            }
+            onDrop={
+              draggable
+                ? (e) => {
+                    e.preventDefault();
+                    handleDrop(cat.id);
+                  }
+                : undefined
+            }
+          >
+            {draggable && (
+              <span
+                className="pol-reorder-grip"
+                draggable
+                onDragStart={(e) => startDrag(e, cat.id)}
+                onDragEnd={clear}
+                role="button"
+                tabIndex={-1}
+                aria-label={t(
+                  "policies.settings.reorderHandle",
+                  "Drag to reorder",
+                )}
+              >
+                <DragIndicatorRounded sx={{ fontSize: "1rem" }} />
+              </span>
+            )}
+            <IconBadge size="sm" accent={ROW_ACCENT[cat.id] ?? "blue"}>
+              {cat.icon}
+            </IconBadge>
+            <span className="pol-reorder-label">
+              {t(`policies.catalog.${cat.id}`, cat.label)}
+            </span>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
 /**
  * Collapsed-rail policy icons. Each tints blue when active and carries a small
  * status dot (green active / amber paused). Clicking selects the policy and

frontend/editor/src/proprietary/components/policies/PolicyDetailPanel.tsx

@@ -7,6 +7,7 @@ import DescriptionIcon from "@mui/icons-material/Description";
 import CheckCircleIcon from "@mui/icons-material/CheckCircle";
 import WarningAmberIcon from "@mui/icons-material/WarningAmber";
 import AutorenewIcon from "@mui/icons-material/Autorenew";
+import KeyboardArrowDownIcon from "@mui/icons-material/KeyboardArrowDown";
 import LockIcon from "@mui/icons-material/Lock";
 import DeleteOutlineIcon from "@mui/icons-material/DeleteOutlined";
 import { PanelHeader } from "@shared/components/PanelHeader";
@@ -115,6 +116,7 @@ export function PolicyDetailPanel({
 }: PolicyDetailPanelProps) {
   const { t } = useTranslation();
   const isPaused = status === "paused";
+  const [activityOpen, setActivityOpen] = useState(true);
   // Real configured steps drive the flow; fall back to the preset's rule labels.
   const enforceItems =
     steps && steps.length > 0
@@ -181,70 +183,87 @@ export function PolicyDetailPanel({
 
         {/* Recent Activity */}
         <div>
-          <p className="pol-section-label">
-            {t("policies.detail.recentActivity", "Recent Activity")}
-          </p>
-          {activityItems.length > 0 ? (
-            <Card padding="none">
-              {activityItems.map((item, i) => (
-                <ListRow
-                  key={item.runId ?? `${item.doc}-${item.time}`}
-                  divider={i > 0}
-                  leadingTone={
-                    item.status === "flagged"
-                      ? "warning"
-                      : item.status === "processing"
-                        ? "info"
-                        : "success"
-                  }
-                  leading={
-                    item.status === "flagged" ? (
-                      <WarningAmberIcon sx={{ fontSize: "0.85rem" }} />
-                    ) : item.status === "processing" ? (
-                      <AutorenewIcon
-                        className="pol-spin"
-                        sx={{ fontSize: "0.85rem" }}
-                      />
-                    ) : (
-                      <CheckCircleIcon sx={{ fontSize: "0.85rem" }} />
-                    )
-                  }
-                  title={item.doc}
-                  description={
-                    item.status === "flagged" ? (
-                      <ActivityError message={item.action} t={t} />
-                    ) : (
-                      item.action
-                    )
-                  }
-                  meta={item.time}
-                  trailing={
-                    item.status === "flagged" && onRetry ? (
-                      <Button
-                        variant="ghost"
-                        size="sm"
-                        onClick={() => onRetry(item)}
-                      >
-                        {t("policies.detail.retry", "Retry")}
-                      </Button>
-                    ) : undefined
-                  }
+          <button
+            type="button"
+            className="pol-section-label pol-section-toggle"
+            onClick={() => setActivityOpen((o) => !o)}
+            aria-expanded={activityOpen}
+          >
+            <span>
+              {t("policies.detail.recentActivity", "Recent Activity")}
+            </span>
+            <KeyboardArrowDownIcon
+              className={`pol-section-chevron${activityOpen ? " is-open" : ""}`}
+              fontSize="small"
+            />
+          </button>
+          {activityOpen &&
+            (activityItems.length > 0 ? (
+              <Card padding="none">
+                <div className="pol-activity-list">
+                  {activityItems.map((item, i) => (
+                    <ListRow
+                      key={item.runId ?? `${item.doc}-${item.time}`}
+                      divider={i > 0}
+                      leadingTone={
+                        item.status === "flagged"
+                          ? "warning"
+                          : item.status === "processing"
+                            ? "info"
+                            : "success"
+                      }
+                      leading={
+                        item.status === "flagged" ? (
+                          <WarningAmberIcon sx={{ fontSize: "0.85rem" }} />
+                        ) : item.status === "processing" ? (
+                          <AutorenewIcon
+                            className="pol-spin"
+                            sx={{ fontSize: "0.85rem" }}
+                          />
+                        ) : (
+                          <CheckCircleIcon sx={{ fontSize: "0.85rem" }} />
+                        )
+                      }
+                      title={item.doc}
+                      description={
+                        item.status === "flagged" ? (
+                          <ActivityError message={item.action} t={t} />
+                        ) : (
+                          item.action
+                        )
+                      }
+                      meta={item.time}
+                      trailing={
+                        item.status === "flagged" && onRetry ? (
+                          <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => onRetry(item)}
+                          >
+                            {t("policies.detail.retry", "Retry")}
+                          </Button>
+                        ) : undefined
+                      }
+                    />
+                  ))}
+                </div>
+              </Card>
+            ) : (
+              <Card padding="default">
+                <EmptyState
+                  size="compact"
+                  icon={<DescriptionIcon sx={{ fontSize: "1.5rem" }} />}
+                  title={t(
+                    "policies.detail.noActivityTitle",
+                    "No activity yet",
+                  )}
+                  description={t(
+                    "policies.detail.noActivityDescription",
+                    "Documents will appear here once this policy runs.",
+                  )}
                 />
-              ))}
-            </Card>
-          ) : (
-            <Card padding="default">
-              <EmptyState
-                size="compact"
-                icon={<DescriptionIcon sx={{ fontSize: "1.5rem" }} />}
-                title={t("policies.detail.noActivityTitle", "No activity yet")}
-                description={t(
-                  "policies.detail.noActivityDescription",
-                  "Documents will appear here once this policy runs.",
-                )}
-              />
-            </Card>
-          )}
+              </Card>
+            ))}
         </div>
 
         {/* Stats — one grouped card with divided columns, intentionally

frontend/editor/src/proprietary/components/policies/PolicySetupWizard.tsx

@@ -36,6 +36,7 @@ import {
 } from "@app/components/policies/PolicyWorkflowStep";
 import { PolicyToolConfigStep } from "@app/components/policies/PolicyToolConfigStep";
 import { getPolicyToolChain } from "@app/components/policies/policyToolChains";
+import { ClassificationTaxonomySection } from "@app/components/policies/ClassificationTaxonomySection";
 
 // Sources are always "editor" for this release, so the Sources step is dropped
 // from the flow (its panel code is kept below for when other sources return).
@@ -103,6 +104,9 @@ export function PolicySetupWizard({
   // Preset (tool-chain) policies render the locked tool config as their Workflow
   // step instead of the add/remove builder.
   const toolChain = getPolicyToolChain(category.id);
+  // A single-tool chain has nothing to toggle/configure, so its config UI is
+  // hidden (kept mounted so the submit trigger still emits that one tool).
+  const singleToolChain = toolChain != null && toolChain.length === 1;
   const { user } = useAuth();
   const [step, setStep] = useState(1);
   const [fieldValues, setFieldValues] = useState(() =>
@@ -337,22 +341,29 @@ export function PolicySetupWizard({
         <div style={{ display: step === 1 ? undefined : "none" }}>
           {toolChain ? (
             <>
-              <p className="pol-desc">
-                {t(
-                  "policies.wizard.toolChainDesc",
-                  "Configure the tools this policy runs on each document.",
-                )}
-              </p>
-              <PolicyToolConfigStep
-                chainIds={toolChain}
-                initialOperations={
-                  existingAutomation?.operations ?? config.defaultOperations
-                }
-                presetOperations={config.defaultOperations}
-                categoryLabel={category.label}
-                saveTriggerRef={workflowSave}
-                onComplete={handleToolConfigSaved}
-              />
+              {/* Single-tool chains have nothing to configure — hide the prompt
+                  and the toggle, but keep the step mounted (display:none) so the
+                  final submit still emits that one tool. */}
+              {!singleToolChain && (
+                <p className="pol-desc">
+                  {t(
+                    "policies.wizard.toolChainDesc",
+                    "Configure the tools this policy runs on each document.",
+                  )}
+                </p>
+              )}
+              <div style={{ display: singleToolChain ? "none" : undefined }}>
+                <PolicyToolConfigStep
+                  chainIds={toolChain}
+                  initialOperations={
+                    existingAutomation?.operations ?? config.defaultOperations
+                  }
+                  presetOperations={config.defaultOperations}
+                  categoryLabel={category.label}
+                  saveTriggerRef={workflowSave}
+                  onComplete={handleToolConfigSaved}
+                />
+              </div>
             </>
           ) : (
             <>
@@ -371,6 +382,12 @@ export function PolicySetupWizard({
               />
             </>
           )}
+          {/* The Classification policy owns the editable, team-shared taxonomy
+              (categories → sub-categories → tags) the classifier runs against.
+              Kept on the first step alongside the tool so it's not buried. */}
+          {category.id === "classification" && (
+            <ClassificationTaxonomySection canConfigure={canConfigure} />
+          )}
         </div>
 
         {step === 2 && (

frontend/editor/src/proprietary/components/policies/TaxonomyEditor.css

@@ -0,0 +1,303 @@
+.tax-editor {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+/* --- Category / sub-category table (grid rows, not a <table>). --- */
+.tax-table {
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+  background: var(--color-surface);
+}
+
+.tax-head,
+.tax-row {
+  display: grid;
+  grid-template-columns: 1.5rem minmax(0, 1fr) minmax(3rem, 9rem) 1.75rem;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.tax-head {
+  padding: var(--space-2) var(--space-3);
+  background: var(--color-bg-muted);
+  border-bottom: 1px solid var(--border-subtle);
+}
+
+.tax-empty-row {
+  padding: var(--space-4, 1rem) var(--space-3);
+  text-align: center;
+  font-size: 0.82rem;
+  color: var(--color-text-4);
+}
+
+.tax-head-label,
+.tax-head-id {
+  grid-column: auto;
+  font-size: 0.68rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-3);
+}
+.tax-head-label {
+  grid-column: 2;
+}
+.tax-head-id {
+  grid-column: 3;
+}
+
+.tax-group + .tax-group {
+  border-top: 1px solid var(--border-subtle);
+}
+
+.tax-row {
+  padding: var(--space-2) var(--space-3);
+  transition: background var(--motion-fast);
+}
+
+.tax-row-category {
+  background: var(--color-surface);
+}
+.tax-row-category:hover {
+  background: var(--color-bg-hover);
+}
+
+.tax-name {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.tax-name .sui-input,
+.tax-name input {
+  min-width: 0;
+  width: 100%;
+}
+
+.tax-subcount {
+  flex: none;
+  font-size: 0.7rem;
+  color: var(--color-text-4);
+  white-space: nowrap;
+}
+
+.tax-label-text {
+  font-size: 0.85rem;
+  color: var(--color-text-1);
+}
+
+.tax-id-text {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.72rem;
+  color: var(--color-text-3);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Indented, guide-lined sub-category block. */
+.tax-subs {
+  margin: 0 var(--space-3) var(--space-2) 1.6rem;
+  padding: var(--space-1) 0;
+  border-left: 2px solid var(--border-default);
+  border-radius: 0 var(--radius-md) var(--radius-md) 0;
+  background: var(--color-bg-muted);
+}
+
+.tax-row-doctype {
+  grid-template-columns: minmax(0, 1fr) minmax(3rem, 9rem) 1.75rem;
+  padding-left: var(--space-3);
+}
+.tax-row-doctype:hover {
+  background: var(--color-bg-hover);
+}
+
+.tax-toggle,
+.tax-icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  background: transparent;
+  color: var(--color-text-3);
+  cursor: pointer;
+  border-radius: var(--radius-md);
+  padding: 2px;
+  transition:
+    background var(--motion-fast),
+    color var(--motion-fast);
+}
+
+.tax-toggle:hover,
+.tax-icon-btn:hover {
+  background: var(--color-bg-hover);
+  color: var(--color-text-1);
+}
+
+.tax-icon-btn-danger:hover {
+  background: var(--color-red-light);
+  color: var(--color-red);
+}
+
+/* Sub-category delete buttons are quiet until you hover (or keyboard-focus) the
+   row; the parent category's delete stays visible without hover. */
+.tax-row-doctype .tax-icon-btn {
+  opacity: 0;
+  transition:
+    opacity var(--motion-fast),
+    background var(--motion-fast),
+    color var(--motion-fast);
+}
+.tax-row-doctype:hover .tax-icon-btn,
+.tax-row-doctype:focus-within .tax-icon-btn {
+  opacity: 1;
+}
+
+.tax-add-sub {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  margin: var(--space-1) 0 var(--space-1) var(--space-3);
+  padding: 0.3rem 0;
+  border: none;
+  background: transparent;
+  color: var(--color-blue);
+  font-size: 0.8rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+.tax-add-sub:hover {
+  text-decoration: underline;
+}
+
+/* --- Tags --- */
+.tax-tags {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.tax-tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-1_5, 0.375rem);
+}
+
+.tax-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.15rem;
+  padding: 0.15rem 0.3rem 0.15rem 0.6rem;
+  border-radius: var(--radius-pill);
+  background: var(--color-bg-muted);
+  border: 1px solid var(--color-border);
+  font-size: 0.75rem;
+  color: var(--color-text-2);
+}
+
+.tax-tag-label {
+  line-height: 1.2;
+}
+
+.tax-tag-remove {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.05rem;
+  height: 1.05rem;
+  border: none;
+  background: transparent;
+  color: var(--color-text-4);
+  border-radius: 50%;
+  cursor: pointer;
+  transition:
+    background var(--motion-fast),
+    color var(--motion-fast);
+}
+.tax-tag-remove:hover {
+  background: var(--color-red-light);
+  color: var(--color-red);
+}
+
+.tax-tag-add {
+  display: flex;
+  gap: var(--space-2);
+  align-items: center;
+}
+
+.tax-empty {
+  font-size: 0.8rem;
+  color: var(--color-text-4);
+}
+
+/* --- Fat modal: give the editor room beyond the sidebar's width. --- */
+.tax-modal {
+  width: min(1100px, 94vw);
+  max-width: min(1100px, 94vw);
+}
+
+.tax-modal-body {
+  max-height: min(70vh, 640px);
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+/* --- Compact summary shown inline in the settings step. --- */
+.tax-summary {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.tax-summary-stats {
+  display: flex;
+  gap: var(--space-3);
+  font-size: 0.78rem;
+  color: var(--color-text-3);
+}
+
+.tax-summary-stats strong {
+  color: var(--color-text-1);
+}
+
+.tax-summary-cats {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-1);
+  max-height: 6.5rem;
+  overflow-y: auto;
+}
+
+.tax-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  align-items: center;
+}
+
+.tax-toolbar-spacer {
+  flex: 1 1 auto;
+}
+
+/* --- Modal footer: destructive actions left, Save/Cancel right. --- */
+.tax-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  width: 100%;
+  flex-wrap: wrap;
+}
+
+.tax-footer-left,
+.tax-footer-right {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}

frontend/editor/src/proprietary/components/policies/TaxonomyEditor.tsx

@@ -0,0 +1,314 @@
+/**
+ * Editable view of a classification taxonomy: a table of categories, each with a
+ * collapsible, indented list of sub-categories (doc types), plus the
+ * free-standing tags. Purely presentational — it renders a draft and emits a new
+ * draft on every edit; the owner decides when to persist. Ids are never edited
+ * directly: they're derived from the label (lowercased, spaces → hyphens) and
+ * shown read-only. `readOnly` renders the same layout without edit affordances.
+ */
+
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import AddIcon from "@mui/icons-material/Add";
+import CloseIcon from "@mui/icons-material/Close";
+import DeleteOutlineIcon from "@mui/icons-material/DeleteOutlineOutlined";
+import ChevronRightIcon from "@mui/icons-material/ChevronRight";
+import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
+import { Input } from "@shared/components/Input";
+import { Button } from "@shared/components/Button";
+import { slugify } from "@app/utils/slug";
+import type {
+  ClassificationTaxonomy,
+  DocumentCategory,
+} from "@app/data/classificationTaxonomy";
+import "@app/components/policies/TaxonomyEditor.css";
+
+interface TaxonomyEditorProps {
+  value: ClassificationTaxonomy;
+  onChange: (next: ClassificationTaxonomy) => void;
+  readOnly?: boolean;
+}
+
+export function TaxonomyEditor({
+  value,
+  onChange,
+  readOnly = false,
+}: TaxonomyEditorProps) {
+  const { t } = useTranslation();
+  // Track expansion by category index (stable while editing, since ids change
+  // as labels are typed and rows aren't reordered).
+  const [expanded, setExpanded] = useState<Set<number>>(new Set([0]));
+  const [newTag, setNewTag] = useState("");
+
+  const toggle = (index: number) =>
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(index)) next.delete(index);
+      else next.add(index);
+      return next;
+    });
+
+  const setCategories = (categories: DocumentCategory[]) =>
+    onChange({ ...value, categories });
+
+  const updateCategory = (index: number, patch: Partial<DocumentCategory>) =>
+    setCategories(
+      value.categories.map((c, i) => (i === index ? { ...c, ...patch } : c)),
+    );
+
+  const renameCategory = (index: number, label: string) =>
+    updateCategory(index, { label, id: slugify(label) });
+
+  const addCategory = () => {
+    setExpanded((prev) => new Set(prev).add(value.categories.length));
+    setCategories([...value.categories, { id: "", label: "", docTypes: [] }]);
+  };
+
+  const removeCategory = (index: number) =>
+    setCategories(value.categories.filter((_, i) => i !== index));
+
+  const renameDocType = (catIndex: number, docIndex: number, label: string) =>
+    updateCategory(catIndex, {
+      docTypes: value.categories[catIndex].docTypes.map((d, i) =>
+        i === docIndex ? { id: slugify(label), label } : d,
+      ),
+    });
+
+  const addDocType = (catIndex: number) => {
+    setExpanded((prev) => new Set(prev).add(catIndex));
+    updateCategory(catIndex, {
+      docTypes: [...value.categories[catIndex].docTypes, { id: "", label: "" }],
+    });
+  };
+
+  const removeDocType = (catIndex: number, docIndex: number) =>
+    updateCategory(catIndex, {
+      docTypes: value.categories[catIndex].docTypes.filter(
+        (_, i) => i !== docIndex,
+      ),
+    });
+
+  const addTag = () => {
+    const tag = slugify(newTag);
+    if (tag === "" || value.tags.includes(tag)) return;
+    onChange({ ...value, tags: [...value.tags, tag] });
+    setNewTag("");
+  };
+
+  const removeTag = (tag: string) =>
+    onChange({ ...value, tags: value.tags.filter((tg) => tg !== tag) });
+
+  return (
+    <div className="tax-editor">
+      <div className="tax-table" role="table">
+        <div className="tax-head" role="row">
+          <span className="tax-head-label">
+            {t("policies.taxonomy.categoryLabel", "Category")}
+          </span>
+          <span className="tax-head-id">{t("policies.taxonomy.id", "ID")}</span>
+          {!readOnly && <span className="tax-head-actions" aria-hidden />}
+        </div>
+
+        {value.categories.length === 0 && (
+          <div className="tax-empty-row">
+            {t(
+              "policies.taxonomy.emptyCategories",
+              "No categories yet — add one to get started.",
+            )}
+          </div>
+        )}
+
+        {value.categories.map((category, catIndex) => {
+          const isOpen = expanded.has(catIndex);
+          return (
+            <div className="tax-group" key={catIndex}>
+              <div className="tax-row tax-row-category" role="row">
+                <button
+                  type="button"
+                  className="tax-toggle"
+                  onClick={() => toggle(catIndex)}
+                  aria-expanded={isOpen}
+                  aria-label={
+                    isOpen
+                      ? t("policies.taxonomy.collapse", "Collapse")
+                      : t("policies.taxonomy.expand", "Expand")
+                  }
+                >
+                  {isOpen ? (
+                    <ExpandMoreIcon sx={{ fontSize: "1.15rem" }} />
+                  ) : (
+                    <ChevronRightIcon sx={{ fontSize: "1.15rem" }} />
+                  )}
+                </button>
+                <div className="tax-name">
+                  {readOnly ? (
+                    <span className="tax-label-text">{category.label}</span>
+                  ) : (
+                    <Input
+                      inputSize="sm"
+                      value={category.label}
+                      onChange={(e) => renameCategory(catIndex, e.target.value)}
+                      placeholder={t(
+                        "policies.taxonomy.categoryLabel",
+                        "Category",
+                      )}
+                      aria-label={t(
+                        "policies.taxonomy.categoryLabel",
+                        "Category",
+                      )}
+                    />
+                  )}
+                  <span className="tax-subcount">
+                    {t("policies.taxonomy.subCount", "{{count}} sub", {
+                      count: category.docTypes.length,
+                    })}
+                  </span>
+                </div>
+                <code className="tax-id-text">{category.id}</code>
+                {!readOnly && (
+                  <button
+                    type="button"
+                    className="tax-icon-btn tax-icon-btn-danger"
+                    onClick={() => removeCategory(catIndex)}
+                    aria-label={t(
+                      "policies.taxonomy.removeCategory",
+                      "Remove category",
+                    )}
+                  >
+                    <DeleteOutlineIcon sx={{ fontSize: "1.15rem" }} />
+                  </button>
+                )}
+              </div>
+
+              {isOpen && (
+                <div className="tax-subs">
+                  {category.docTypes.map((docType, docIndex) => (
+                    <div
+                      className="tax-row tax-row-doctype"
+                      role="row"
+                      key={docIndex}
+                    >
+                      <div className="tax-name">
+                        {readOnly ? (
+                          <span className="tax-label-text">
+                            {docType.label}
+                          </span>
+                        ) : (
+                          <Input
+                            inputSize="sm"
+                            value={docType.label}
+                            onChange={(e) =>
+                              renameDocType(catIndex, docIndex, e.target.value)
+                            }
+                            placeholder={t(
+                              "policies.taxonomy.subLabel",
+                              "Sub-category",
+                            )}
+                            aria-label={t(
+                              "policies.taxonomy.subLabel",
+                              "Sub-category",
+                            )}
+                          />
+                        )}
+                      </div>
+                      <code className="tax-id-text">{docType.id}</code>
+                      {!readOnly && (
+                        <button
+                          type="button"
+                          className="tax-icon-btn tax-icon-btn-danger"
+                          onClick={() => removeDocType(catIndex, docIndex)}
+                          aria-label={t(
+                            "policies.taxonomy.removeSub",
+                            "Remove sub-category",
+                          )}
+                        >
+                          <DeleteOutlineIcon sx={{ fontSize: "1.05rem" }} />
+                        </button>
+                      )}
+                    </div>
+                  ))}
+                  {!readOnly && (
+                    <button
+                      type="button"
+                      className="tax-add-sub"
+                      onClick={() => addDocType(catIndex)}
+                    >
+                      <AddIcon sx={{ fontSize: "1rem" }} />
+                      {t("policies.taxonomy.addSub", "Add sub-category")}
+                    </button>
+                  )}
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+
+      {!readOnly && (
+        <Button
+          variant="outline"
+          size="sm"
+          leadingIcon={<AddIcon sx={{ fontSize: "1rem" }} />}
+          onClick={addCategory}
+        >
+          {t("policies.taxonomy.addCategory", "Add category")}
+        </Button>
+      )}
+
+      <div className="tax-tags">
+        <p className="pol-section-label">
+          {t("policies.taxonomy.tags", "Tags")}
+        </p>
+        <div className="tax-tag-list">
+          {value.tags.length === 0 && (
+            <span className="tax-empty">
+              {t("policies.taxonomy.noTags", "No tags yet.")}
+            </span>
+          )}
+          {value.tags.map((tag) => (
+            <span className="tax-tag" key={tag}>
+              <span className="tax-tag-label">{tag}</span>
+              {!readOnly && (
+                <button
+                  type="button"
+                  className="tax-tag-remove"
+                  onClick={() => removeTag(tag)}
+                  aria-label={t(
+                    "policies.taxonomy.removeTag",
+                    "Remove {{tag}}",
+                    { tag },
+                  )}
+                >
+                  <CloseIcon sx={{ fontSize: "0.85rem" }} />
+                </button>
+              )}
+            </span>
+          ))}
+        </div>
+        {!readOnly && (
+          <div className="tax-tag-add">
+            <Input
+              inputSize="sm"
+              value={newTag}
+              onChange={(e) => setNewTag(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.preventDefault();
+                  addTag();
+                }
+              }}
+              placeholder={t(
+                "policies.taxonomy.addTagPlaceholder",
+                "Add a tag",
+              )}
+              aria-label={t("policies.taxonomy.addTag", "Add a tag")}
+            />
+            <Button variant="ghost" size="sm" onClick={addTag}>
+              {t("policies.taxonomy.add", "Add")}
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/editor/src/proprietary/components/policies/TaxonomyEditorModal.tsx

@@ -0,0 +1,176 @@
+/**
+ * Full-screen ("fat") editor for the classification taxonomy — the roomy view the
+ * sidebar's Expand button opens. Hosts the {@link TaxonomyEditor} table plus an
+ * Import/Export toolbar and a footer holding the destructive actions (reset /
+ * start-from-scratch) and the Save/Cancel buttons. Editing is staged: nothing is
+ * persisted until Save, which stays disabled until the draft actually changes.
+ * The draft is owned by the caller so the sidebar summary reflects saved changes.
+ */
+
+import { useRef } from "react";
+import { useTranslation } from "react-i18next";
+import FileDownloadOutlinedIcon from "@mui/icons-material/FileDownloadOutlined";
+import FileUploadOutlinedIcon from "@mui/icons-material/FileUploadOutlined";
+import RestartAltIcon from "@mui/icons-material/RestartAlt";
+import DeleteSweepOutlinedIcon from "@mui/icons-material/DeleteSweepOutlined";
+import InfoOutlinedIcon from "@mui/icons-material/InfoOutlined";
+import { Modal } from "@shared/components/Modal";
+import { Button } from "@shared/components/Button";
+import { Banner } from "@shared/components/Banner";
+import { TaxonomyEditor } from "@app/components/policies/TaxonomyEditor";
+import type { ClassificationTaxonomy } from "@app/data/classificationTaxonomy";
+
+interface TaxonomyEditorModalProps {
+  open: boolean;
+  onClose: () => void;
+  draft: ClassificationTaxonomy;
+  onDraftChange: (next: ClassificationTaxonomy) => void;
+  onImportFile: (file: File) => void;
+  onExport: () => void;
+  /** Stage the built-in default into the draft. */
+  onReset: () => void;
+  /** Stage an empty taxonomy into the draft (build from scratch). */
+  onClear: () => void;
+  onSave: () => void;
+  dirty: boolean;
+  saving: boolean;
+  readOnly: boolean;
+  /** Save/reset (server) or import (file) failure to surface, if any. */
+  error: string | null;
+}
+
+export function TaxonomyEditorModal({
+  open,
+  onClose,
+  draft,
+  onDraftChange,
+  onImportFile,
+  onExport,
+  onReset,
+  onClear,
+  onSave,
+  dirty,
+  saving,
+  readOnly,
+  error,
+}: TaxonomyEditorModalProps) {
+  const { t } = useTranslation();
+  const fileInput = useRef<HTMLInputElement>(null);
+
+  const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    // Reset the input so picking the same file twice still fires onChange.
+    e.target.value = "";
+    if (file) onImportFile(file);
+  };
+
+  return (
+    <Modal
+      open={open}
+      onClose={onClose}
+      width="xl"
+      className="tax-modal"
+      title={t("policies.taxonomy.modalTitle", "Classification taxonomy")}
+      subtitle={t(
+        "policies.taxonomy.modalSubtitle",
+        "Shared with your whole team. Categories, their sub-categories, and tags the classifier uses.",
+      )}
+      footer={
+        <div className="tax-footer">
+          <div className="tax-footer-left">
+            {!readOnly && (
+              <>
+                <Button
+                  variant="ghost"
+                  accent="red"
+                  size="sm"
+                  leadingIcon={
+                    <DeleteSweepOutlinedIcon sx={{ fontSize: "1rem" }} />
+                  }
+                  onClick={onClear}
+                  disabled={saving}
+                >
+                  {t(
+                    "policies.taxonomy.startFromScratch",
+                    "Start from scratch",
+                  )}
+                </Button>
+                <Button
+                  variant="ghost"
+                  accent="red"
+                  size="sm"
+                  leadingIcon={<RestartAltIcon sx={{ fontSize: "1rem" }} />}
+                  onClick={onReset}
+                  disabled={saving}
+                >
+                  {t("policies.taxonomy.resetToDefault", "Reset to default")}
+                </Button>
+              </>
+            )}
+          </div>
+          <div className="tax-footer-right">
+            <Button variant="ghost" size="sm" onClick={onClose}>
+              {readOnly ? t("close", "Close") : t("cancel", "Cancel")}
+            </Button>
+            {!readOnly && (
+              <Button
+                variant="gradient"
+                size="sm"
+                onClick={onSave}
+                disabled={!dirty || saving}
+              >
+                {saving
+                  ? t("policies.taxonomy.saving", "Saving…")
+                  : t("policies.taxonomy.saveForTeam", "Save for team")}
+              </Button>
+            )}
+          </div>
+        </div>
+      }
+    >
+      <div className="tax-modal-body">
+        {error && (
+          <Banner
+            tone="danger"
+            icon={<InfoOutlinedIcon sx={{ fontSize: "1rem" }} />}
+            description={error}
+          />
+        )}
+        {!readOnly && (
+          <div className="tax-toolbar">
+            <Button
+              variant="outline"
+              size="sm"
+              leadingIcon={<FileUploadOutlinedIcon sx={{ fontSize: "1rem" }} />}
+              onClick={() => fileInput.current?.click()}
+            >
+              {t("policies.taxonomy.import", "Import JSON")}
+            </Button>
+            <Button
+              variant="outline"
+              size="sm"
+              leadingIcon={
+                <FileDownloadOutlinedIcon sx={{ fontSize: "1rem" }} />
+              }
+              onClick={onExport}
+            >
+              {t("policies.taxonomy.export", "Export JSON")}
+            </Button>
+            <input
+              ref={fileInput}
+              type="file"
+              accept="application/json,.json"
+              hidden
+              onChange={handleFile}
+            />
+          </div>
+        )}
+        <TaxonomyEditor
+          value={draft}
+          onChange={onDraftChange}
+          readOnly={readOnly}
+        />
+      </div>
+    </Modal>
+  );
+}

frontend/editor/src/proprietary/components/policies/policySelectionStore.ts

@@ -15,9 +15,16 @@ import type { PolicyDetailView } from "@app/types/policies";
 interface PolicySelection {
   selectedId: string | null;
   detailView: PolicyDetailView;
+  /** The policy-settings page (execution order) takes over the rail. Independent
+   *  of {@link selectedId} — it's a section-level view, not tied to one policy. */
+  settingsOpen: boolean;
 }
 
-let state: PolicySelection = { selectedId: null, detailView: "detail" };
+let state: PolicySelection = {
+  selectedId: null,
+  detailView: "detail",
+  settingsOpen: false,
+};
 const listeners = new Set<() => void>();
 
 function emit() {
@@ -37,6 +44,7 @@ function getSnapshot(): PolicySelection {
 const SERVER_SNAPSHOT: PolicySelection = {
   selectedId: null,
   detailView: "detail",
+  settingsOpen: false,
 };
 function getServerSnapshot(): PolicySelection {
   return SERVER_SNAPSHOT;
@@ -44,7 +52,7 @@ function getServerSnapshot(): PolicySelection {
 
 /** Open a policy's detail (resets the sub-view to the narrative). */
 export function selectPolicy(id: string | null) {
-  state = { selectedId: id, detailView: "detail" };
+  state = { selectedId: id, detailView: "detail", settingsOpen: false };
   emit();
 }
 
@@ -55,6 +63,19 @@ export function setPolicyDetailView(view: PolicyDetailView) {
   emit();
 }
 
+/** Open the policy-settings page (execution order). Clears any open policy. */
+export function openPolicySettings() {
+  state = { selectedId: null, detailView: "detail", settingsOpen: true };
+  emit();
+}
+
+/** Close the policy-settings page and return to the list. */
+export function closePolicySettings() {
+  if (!state.settingsOpen) return;
+  state = { ...state, settingsOpen: false };
+  emit();
+}
+
 /** Close the open policy and return to the list. */
 export function closePolicy() {
   selectPolicy(null);
@@ -62,7 +83,7 @@ export function closePolicy() {
 
 /** Reset to the initial state — used by tests to isolate the module store. */
 export function resetPolicySelection() {
-  state = { selectedId: null, detailView: "detail" };
+  state = { selectedId: null, detailView: "detail", settingsOpen: false };
   emit();
 }
 

frontend/editor/src/proprietary/components/policies/policyStatus.ts

@@ -22,6 +22,7 @@ export const STATUS_LABEL: Record<PolicyRowStatus, string> = {
  */
 export const ROW_ACCENT: Record<string, IconBadgeAccent> = {
   ingestion: "blue",
+  classification: "orange",
   security: "purple",
   compliance: "green",
   routing: "amber",

frontend/editor/src/proprietary/components/policies/policyToolChains.ts

@@ -8,6 +8,9 @@ export const POLICY_TOOL_CHAINS: Record<string, string[]> = {
   // Security: redact PII + watermark + sanitize (strips JS). Which are enabled
   // by default comes from the preset's defaultOperations, not this list.
   security: ["redact", "watermark", "sanitize"],
+  // Classification: a single backend step that classifies the document and
+  // writes the result into its metadata.
+  classification: ["classify"],
 };
 
 /** The configurable tool chain for a category, or null if it has none yet. */

frontend/editor/src/proprietary/components/policies/usePolicyAutoRun.chain.test.tsx

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// Two active upload policies, so the auto-run should CHAIN them: fire the first on
+// the upload, then the second on the first's output. Stub the contexts + network so
+// we can drive the dispatch against the REAL run store.
+vi.mock("@app/constants/featureFlags", () => ({ POLICIES_ENABLED: true }));
+const fileStubs: { id: string; name: string; derivedFromTool?: boolean }[] = [];
+vi.mock("@app/contexts/FileContext", () => ({
+  useAllFiles: () => ({ fileStubs }),
+  useFileManagement: () => ({ addFiles: vi.fn() }),
+  useFileContext: () => ({ consumeFiles: vi.fn() }),
+}));
+vi.mock("@app/hooks/usePolicies", () => ({
+  usePolicies: () => ({
+    policies: {
+      security: {
+        configured: true,
+        status: "active",
+        backendId: "backend-sec",
+        runOn: "upload",
+        order: 0,
+      },
+      classification: {
+        configured: true,
+        status: "active",
+        backendId: "backend-cls",
+        runOn: "upload",
+        order: 1,
+      },
+    },
+  }),
+}));
+vi.mock("@app/services/policyApi", () => ({
+  runStoredPolicy: vi.fn(),
+  getPolicyRun: vi.fn(),
+  downloadPolicyOutput: vi.fn(),
+  resolvePolicyRunTarget: () => "saas",
+}));
+vi.mock("@app/services/fileStorage", () => ({
+  fileStorage: { getStirlingFile: vi.fn(), getStirlingFileStub: vi.fn() },
+}));
+vi.mock("@app/contexts/IndexedDBContext", () => ({
+  useIndexedDB: () => ({ bumpRevision: vi.fn() }),
+}));
+
+import { usePolicyAutoRun } from "@app/components/policies/usePolicyAutoRun";
+import {
+  recordRunStart,
+  updateRun,
+  resetPolicyRuns,
+} from "@app/components/policies/policyRunStore";
+import { runStoredPolicy } from "@app/services/policyApi";
+import { fileStorage } from "@app/services/fileStorage";
+
+const runStored = vi.mocked(runStoredPolicy);
+const getFile = vi.mocked(fileStorage.getStirlingFile);
+
+/** Reset the shared file list between tests without swapping the array identity. */
+function setFileStubs(next: typeof fileStubs) {
+  fileStubs.length = 0;
+  fileStubs.push(...next);
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  localStorage.clear();
+  resetPolicyRuns();
+  setFileStubs([]);
+  runStored.mockReset();
+  getFile.mockReset();
+  getFile.mockResolvedValue({ size: 100 } as never);
+});
+afterEach(() => vi.useRealTimers());
+
+describe("auto-run ordered chaining", () => {
+  it("dispatches only the FIRST ordered policy on upload, not the whole set", async () => {
+    setFileStubs([{ id: "file-1", name: "doc.pdf" }]);
+    runStored.mockResolvedValue("run-sec");
+
+    renderHook(() => usePolicyAutoRun());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+
+    // The first policy (order 0) runs on the upload; the second waits for the chain.
+    expect(runStored).toHaveBeenCalledTimes(1);
+    expect(runStored).toHaveBeenCalledWith("backend-sec", [{ size: 100 }]);
+  });
+
+  it("chains the next policy onto a completed run's output", async () => {
+    // A first-policy run that has completed and imported its output as file-1-v2.
+    recordRunStart({
+      runId: "run-sec",
+      categoryId: "security",
+      fileId: "file-1",
+      fileName: "doc.pdf",
+      fileSize: 100,
+      target: "saas",
+      status: "PENDING",
+      outputs: [],
+      error: null,
+      startedAt: 0,
+    });
+    updateRun("run-sec", {
+      status: "COMPLETED",
+      imported: true,
+      outputFileIds: ["file-1-v2"],
+    });
+    runStored.mockResolvedValue("run-cls");
+
+    renderHook(() => usePolicyAutoRun());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+
+    // The next policy (order 1) fires on the first policy's output, not the original.
+    expect(runStored).toHaveBeenCalledWith("backend-cls", [{ size: 100 }]);
+  });
+});

frontend/editor/src/proprietary/components/policies/usePolicyAutoRun.ts

@@ -1,9 +1,13 @@
 /**
- * Auto-run controller: every enabled policy enforces on every uploaded
- * file. Watches the session's files and, for each (active policy × not-yet-run
- * file), fires a real backend run (`POST /api/v1/policies/{id}/run`) and polls it
- * to completion, recording progress in {@link policyRunStore} for the activity
- * feed.
+ * Auto-run controller: every enabled policy enforces on every uploaded file.
+ * Watches the session's files and fires a real backend run
+ * (`POST /api/v1/policies/{id}/run`) per file, polling it to completion and
+ * recording progress in {@link policyRunStore} for the activity feed.
+ *
+ * When several policies enforce on the same trigger they run as an ordered chain:
+ * the first fires on the upload, and each subsequent policy fires on the previous
+ * one's output once it lands — so their effects accumulate in the admin-defined
+ * order rather than racing to fork the same version.
  *
  * Headless — call it from {@link PolicyAutoRunController}, which is mounted once
  * wherever the editor is open so enforcement happens regardless of whether the
@@ -11,7 +15,7 @@
  * in the run store), so re-renders and remounts don't re-fire.
  */
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import {
   useAllFiles,
   useFileManagement,
@@ -141,6 +145,33 @@ export function usePolicyAutoRun(): void {
   // run so a folder-watch burst opens the modal once, not once per file.
   const firedLimitModal = useRef<Set<string>>(new Set());
 
+  // Active upload policies in execution order. When several enforce on upload they
+  // run as a chain — the first fires on the upload, each subsequent one on the
+  // previous policy's output — so their effects accumulate in a defined order
+  // instead of racing to fork the same version. Mirrors the dispatch filter
+  // (incl. the editor-source gate) so the chain honours the same eligibility.
+  const orderedUploadCategories = useMemo(
+    () =>
+      Object.entries(policies)
+        .filter(
+          ([, s]) =>
+            s.configured &&
+            s.status === "active" &&
+            s.backendId &&
+            (!s.sources ||
+              s.sources.length === 0 ||
+              s.sources.includes("editor")) &&
+            (s.runOn ?? "upload") === "upload",
+        )
+        .sort(([, a], [, b]) => (a.order ?? 0) - (b.order ?? 0))
+        .map(([id]) => id),
+    [policies],
+  );
+
+  // Runs whose chain-continuation we've already handled this session, so the next
+  // policy is dispatched exactly once per completed run.
+  const chained = useRef<Set<string>>(new Set());
+
   // Latest policies, read from inside the stable retry callback (which has no deps).
   const policiesRef = useRef(policies);
   policiesRef.current = policies;
@@ -204,46 +235,71 @@ export function usePolicyAutoRun(): void {
     [scheduleQueueRetry],
   );
 
-  // Dispatch: for each active policy × each session file not yet run, fire a run.
+  // Dispatch: fire only the FIRST upload policy on each not-yet-run file. The rest
+  // of the chain is dispatched by the chaining effect below, each on the previous
+  // policy's output, so the policies apply cumulatively in order.
   useEffect(() => {
     if (!POLICIES_ENABLED) return;
-    const active = Object.entries(policies).filter(
-      ([, s]) =>
-        s.configured &&
-        s.status === "active" &&
-        s.backendId &&
-        // Only auto-run on upload when the policy is set to run on upload
-        // (export-triggered policies enforce at export time instead).
-        (s.runOn ?? "upload") === "upload",
-    );
-    for (const [categoryId, s] of active) {
-      for (const stub of fileStubs) {
-        // Input-mode policies enforce only on files that actually entered the
-        // system as an upload — not on files a tool/automation produced in-app
-        // (versioned edits or independent artifacts like convert/split/merge).
-        // Those are enforced only by export-mode policies, at export time.
-        if (stub.derivedFromTool) continue;
-        const key = dispatchKey(categoryId, stub.id);
-        // Skip if already run (persisted) or a dispatch is in flight — the
-        // in-memory guard prevents double-firing during the async wait.
-        if (isDispatched(categoryId, stub.id) || dispatching.current.has(key)) {
-          continue;
-        }
-        dispatching.current.add(key);
-        void runPolicyOnFile(
-          categoryId,
-          s.backendId as string,
-          stub.id,
-          stub.name,
-        )
-          .catch(() => {
-            // runPolicyOnFile handles its own failures; this is just a backstop
-            // so an unexpected rejection never becomes an unhandled rejection.
-          })
-          .finally(() => dispatching.current.delete(key));
+    const firstCategory = orderedUploadCategories[0];
+    if (!firstCategory) return;
+    const backendId = policies[firstCategory]?.backendId;
+    if (!backendId) return;
+    for (const stub of fileStubs) {
+      // Input-mode policies enforce only on files that actually entered the
+      // system as an upload — not on files a tool/automation produced in-app
+      // (versioned edits or independent artifacts like convert/split/merge).
+      // Those are enforced only by export-mode policies, at export time.
+      if (stub.derivedFromTool) continue;
+      const key = dispatchKey(firstCategory, stub.id);
+      // Skip if already run (persisted) or a dispatch is in flight — the
+      // in-memory guard prevents double-firing during the async wait.
+      if (
+        isDispatched(firstCategory, stub.id) ||
+        dispatching.current.has(key)
+      ) {
+        continue;
       }
+      dispatching.current.add(key);
+      void runPolicyOnFile(firstCategory, backendId, stub.id, stub.name)
+        .catch(() => {
+          // runPolicyOnFile handles its own failures; this is just a backstop
+          // so an unexpected rejection never becomes an unhandled rejection.
+        })
+        .finally(() => dispatching.current.delete(key));
     }
-  }, [fileStubs, policies]);
+  }, [fileStubs, policies, orderedUploadCategories]);
+
+  // Chain: once a run has completed AND its output landed in the workspace, fire the
+  // next upload policy on that output. Only chains on success (a failed run has no
+  // output), and only once per run. isDispatched guards re-dispatch across reloads.
+  useEffect(() => {
+    if (!POLICIES_ENABLED) return;
+    for (const run of runs) {
+      if (run.status !== "COMPLETED" || !run.imported) continue;
+      if (chained.current.has(run.runId)) continue;
+      const nextCategory = nextUploadCategory(
+        orderedUploadCategories,
+        run.categoryId,
+      );
+      const outputId = run.outputFileIds?.[0];
+      if (!nextCategory || !outputId) {
+        // End of the chain (or nothing to chain onto): don't revisit this run.
+        chained.current.add(run.runId);
+        continue;
+      }
+      const backendId = policies[nextCategory]?.backendId;
+      // Next policy not ready yet (still reconciling) — retry when policies change.
+      if (!backendId) continue;
+      chained.current.add(run.runId);
+      if (isDispatched(nextCategory, outputId as FileId)) continue;
+      void runPolicyOnFile(
+        nextCategory,
+        backendId,
+        outputId as FileId,
+        run.fileName,
+      ).catch(() => {});
+    }
+  }, [runs, policies, orderedUploadCategories]);
 
   // Poll each in-flight run to a terminal state.
   useEffect(() => {
@@ -275,6 +331,7 @@ export function usePolicyAutoRun(): void {
       // input file it ran on (needs that input's stub, still in the workspace).
       const outputMode = policies[run.categoryId]?.outputMode ?? "new_version";
       const outputName = policies[run.categoryId]?.outputName ?? "";
+      const outputNamePosition = policies[run.categoryId]?.outputNamePosition;
       const parentStub = fileStubs.find((s) => (s.id as string) === run.fileId);
       void importOutputs(run, {
         addFiles,
@@ -282,6 +339,7 @@ export function usePolicyAutoRun(): void {
         bumpRevision,
         outputMode,
         outputName,
+        outputNamePosition,
         parentStub,
       }).finally(() => importing.current.delete(run.runId));
     }
@@ -314,9 +372,11 @@ interface ImportContext {
   bumpRevision: () => void;
   /** "new_file" adds the output as a separate file; "new_version" versions the input. */
   outputMode: "new_file" | "new_version";
-  /** Rename rule. Empty → keep the input's filename; set → use the policy's
-   *  renamed output (applied server-side per the name-position setting). */
+  /** Rename rule. Empty → keep the input's filename. */
   outputName: string;
+  /** Where the rename is applied: before ("prefix") or after ("suffix") the
+   *  base filename. Defaults to "suffix" when absent. */
+  outputNamePosition?: "prefix" | "suffix" | "auto-number";
   /** The input file's stub — required to version it; absent if it's been removed. */
   parentStub: StirlingFileStub | undefined;
 }
@@ -327,6 +387,31 @@ interface ImportContext {
  * don't, adopt it so the poll/import effects pick it up. Server-excluded ad-hoc runs and runs we
  * can't map to a configured category are skipped.
  */
+function applyOutputName(
+  inputFileName: string,
+  outputName: string,
+  position: "prefix" | "suffix" | "auto-number",
+): string {
+  const dot = inputFileName.lastIndexOf(".");
+  const base = dot > 0 ? inputFileName.slice(0, dot) : inputFileName;
+  const ext = dot > 0 ? inputFileName.slice(dot) : "";
+  if (position === "suffix") return `${base}_${outputName}${ext}`;
+  if (position === "prefix") return `${outputName}_${base}${ext}`;
+  // auto-number requires dedup state not available here — fall back to suffix.
+  return `${base}_${outputName}${ext}`;
+}
+
+/** The next upload policy after {@code categoryId} in the chain, or undefined if
+ *  it's last or no longer in the ordered set (e.g. paused since it ran). */
+function nextUploadCategory(
+  orderedUploadCategories: string[],
+  categoryId: string,
+): string | undefined {
+  const index = orderedUploadCategories.indexOf(categoryId);
+  if (index < 0) return undefined;
+  return orderedUploadCategories[index + 1];
+}
+
 async function reconcileServerRuns(
   policies: PoliciesByCategory,
 ): Promise<void> {
@@ -406,7 +491,11 @@ async function importOutputs(
   // rule the backend's auto-suffixed name (e.g. "_watermarked_sanitized") would
   // otherwise rename every output.
   const targetName = ctx.outputName
-    ? undefined // use the run's per-output (renamed) name below
+    ? applyOutputName(
+        run.fileName,
+        ctx.outputName,
+        ctx.outputNamePosition ?? "suffix",
+      )
     : run.fileName;
   const settled = await Promise.allSettled(
     pending.map(async (out) => {

frontend/editor/src/proprietary/data/classificationTaxonomy.ts

@@ -0,0 +1,302 @@
+/**
+ * Document-classification vocabulary — the single, type-safe source of truth.
+ *
+ * The Python engine can't import TypeScript, so this is GENERATED into
+ * `engine/src/stirling/agents/default_classification_taxonomy.generated.json` by
+ * `editor/scripts/generate-classification-taxonomy.mts`
+ * (`task frontend:classifier-categories`, drift-guarded by
+ * `task frontend:classifier-categories:check`). Edit THIS file, never the
+ * generated JSON.
+ *
+ * Shape mirrors the engine's `ClassificationTaxonomy` contract; the camelCase
+ * keys here map onto that model's aliases.
+ *
+ * Override points for later (kept simple now, designed to drop in):
+ *  - This is the built-in DEFAULT. A per-org / DB-configured taxonomy is meant to
+ *    layer on top, not replace this file.
+ *  - The engine already accepts a `taxonomy` per classify request; when one is
+ *    supplied it wins, and this default is the fallback.
+ *  - The backend `ClassifyTagController.resolveTaxonomyOverride()` is the seam to
+ *    load the caller's org/DB taxonomy and pass it through; today it returns none.
+ */
+
+/** A specific instrument within a category — category-scoped (e.g. `nda` only
+ *  under `contract`); the engine enforces it can't apply to another category. */
+export interface DocumentType {
+  id: string;
+  label: string;
+}
+
+export interface DocumentCategory {
+  id: string;
+  label: string;
+  /** Category-scoped tags. */
+  docTypes: DocumentType[];
+}
+
+export interface ClassificationTaxonomy {
+  /** Ordered most-common → least-common. */
+  categories: DocumentCategory[];
+  /** Loose, cross-cutting tags that aren't tied to any single category. */
+  tags: string[];
+}
+
+export const DEFAULT_CLASSIFICATION_TAXONOMY: ClassificationTaxonomy = {
+  categories: [
+    {
+      id: "invoice",
+      label: "Invoice",
+      docTypes: [
+        { id: "invoice", label: "Invoice" },
+        { id: "receipt", label: "Receipt" },
+        { id: "credit_note", label: "Credit note" },
+        { id: "purchase_order", label: "Purchase order" },
+        { id: "quote", label: "Quote" },
+      ],
+    },
+    {
+      id: "contract",
+      label: "Contract",
+      docTypes: [
+        { id: "nda", label: "Non-disclosure agreement" },
+        { id: "employment_agreement", label: "Employment agreement" },
+        { id: "service_agreement", label: "Service agreement" },
+        { id: "lease_agreement", label: "Lease agreement" },
+        { id: "master_service_agreement", label: "Master service agreement" },
+        { id: "statement_of_work", label: "Statement of work" },
+        { id: "terms_of_service", label: "Terms of service" },
+      ],
+    },
+    {
+      id: "financial_statement",
+      label: "Financial statement",
+      docTypes: [
+        { id: "balance_sheet", label: "Balance sheet" },
+        { id: "income_statement", label: "Income statement" },
+        { id: "cash_flow_statement", label: "Cash flow statement" },
+        { id: "bank_statement", label: "Bank statement" },
+        { id: "annual_report", label: "Annual report" },
+      ],
+    },
+    {
+      id: "report",
+      label: "Report",
+      docTypes: [
+        { id: "business_report", label: "Business report" },
+        { id: "project_report", label: "Project report" },
+        { id: "research_report", label: "Research report" },
+        { id: "status_report", label: "Status report" },
+        { id: "incident_report", label: "Incident report" },
+      ],
+    },
+    {
+      id: "letter",
+      label: "Letter",
+      docTypes: [
+        { id: "business_letter", label: "Business letter" },
+        { id: "cover_letter", label: "Cover letter" },
+        { id: "recommendation_letter", label: "Recommendation letter" },
+        { id: "complaint_letter", label: "Complaint letter" },
+        { id: "demand_letter", label: "Demand letter" },
+      ],
+    },
+    {
+      id: "form",
+      label: "Form",
+      docTypes: [
+        { id: "application_form", label: "Application form" },
+        { id: "registration_form", label: "Registration form" },
+        { id: "consent_form", label: "Consent form" },
+        { id: "survey", label: "Survey" },
+        { id: "questionnaire", label: "Questionnaire" },
+      ],
+    },
+    {
+      id: "resume",
+      label: "Resume",
+      docTypes: [
+        { id: "resume", label: "Resume" },
+        { id: "curriculum_vitae", label: "Curriculum vitae" },
+        { id: "portfolio", label: "Portfolio" },
+        { id: "reference_sheet", label: "Reference sheet" },
+      ],
+    },
+    {
+      id: "tax_form",
+      label: "Tax form",
+      docTypes: [
+        { id: "tax_return", label: "Tax return" },
+        { id: "w2", label: "W-2" },
+        { id: "w9", label: "W-9" },
+        { id: "form_1099", label: "Form 1099" },
+        { id: "vat_return", label: "VAT return" },
+      ],
+    },
+    {
+      id: "expense_report",
+      label: "Expense report",
+      docTypes: [
+        { id: "expense_report", label: "Expense report" },
+        { id: "reimbursement_request", label: "Reimbursement request" },
+        { id: "mileage_log", label: "Mileage log" },
+        { id: "per_diem_claim", label: "Per diem claim" },
+      ],
+    },
+    {
+      id: "presentation",
+      label: "Presentation",
+      docTypes: [
+        { id: "slide_deck", label: "Slide deck" },
+        { id: "pitch_deck", label: "Pitch deck" },
+        { id: "training_deck", label: "Training deck" },
+        { id: "webinar_deck", label: "Webinar deck" },
+      ],
+    },
+    {
+      id: "medical_record",
+      label: "Medical record",
+      docTypes: [
+        { id: "lab_result", label: "Lab result" },
+        { id: "prescription", label: "Prescription" },
+        { id: "discharge_summary", label: "Discharge summary" },
+        { id: "medical_history", label: "Medical history" },
+        { id: "imaging_report", label: "Imaging report" },
+        { id: "vaccination_record", label: "Vaccination record" },
+      ],
+    },
+    {
+      id: "legal_filing",
+      label: "Legal filing",
+      docTypes: [
+        { id: "court_filing", label: "Court filing" },
+        { id: "complaint", label: "Complaint" },
+        { id: "motion", label: "Motion" },
+        { id: "subpoena", label: "Subpoena" },
+        { id: "affidavit", label: "Affidavit" },
+        { id: "deposition", label: "Deposition" },
+      ],
+    },
+    {
+      id: "identity_document",
+      label: "Identity document",
+      docTypes: [
+        { id: "passport", label: "Passport" },
+        { id: "drivers_license", label: "Driver's license" },
+        { id: "national_id", label: "National ID" },
+        { id: "birth_certificate", label: "Birth certificate" },
+        { id: "visa", label: "Visa" },
+      ],
+    },
+    {
+      id: "insurance",
+      label: "Insurance",
+      docTypes: [
+        { id: "insurance_policy", label: "Insurance policy" },
+        { id: "insurance_claim", label: "Insurance claim" },
+        { id: "certificate_of_insurance", label: "Certificate of insurance" },
+        { id: "explanation_of_benefits", label: "Explanation of benefits" },
+      ],
+    },
+    {
+      id: "real_estate",
+      label: "Real estate",
+      docTypes: [
+        { id: "deed", label: "Deed" },
+        { id: "mortgage_agreement", label: "Mortgage agreement" },
+        { id: "property_appraisal", label: "Property appraisal" },
+        { id: "closing_disclosure", label: "Closing disclosure" },
+        { id: "title_report", label: "Title report" },
+      ],
+    },
+    {
+      id: "shipping",
+      label: "Shipping",
+      docTypes: [
+        { id: "bill_of_lading", label: "Bill of lading" },
+        { id: "packing_slip", label: "Packing slip" },
+        { id: "customs_declaration", label: "Customs declaration" },
+        { id: "delivery_note", label: "Delivery note" },
+        { id: "air_waybill", label: "Air waybill" },
+      ],
+    },
+    {
+      id: "hr_document",
+      label: "HR document",
+      docTypes: [
+        { id: "offer_letter", label: "Offer letter" },
+        { id: "performance_review", label: "Performance review" },
+        { id: "payslip", label: "Payslip" },
+        { id: "employee_handbook", label: "Employee handbook" },
+        { id: "termination_letter", label: "Termination letter" },
+        { id: "timesheet", label: "Timesheet" },
+      ],
+    },
+    {
+      id: "academic_record",
+      label: "Academic record",
+      docTypes: [
+        { id: "transcript", label: "Transcript" },
+        { id: "diploma", label: "Diploma" },
+        { id: "certificate", label: "Certificate" },
+        { id: "syllabus", label: "Syllabus" },
+        { id: "thesis", label: "Thesis" },
+        { id: "report_card", label: "Report card" },
+      ],
+    },
+    {
+      id: "marketing_material",
+      label: "Marketing material",
+      docTypes: [
+        { id: "brochure", label: "Brochure" },
+        { id: "flyer", label: "Flyer" },
+        { id: "case_study", label: "Case study" },
+        { id: "white_paper", label: "White paper" },
+        { id: "press_release", label: "Press release" },
+      ],
+    },
+    {
+      id: "technical_document",
+      label: "Technical document",
+      docTypes: [
+        { id: "user_manual", label: "User manual" },
+        { id: "specification", label: "Specification" },
+        { id: "api_documentation", label: "API documentation" },
+        { id: "installation_guide", label: "Installation guide" },
+        { id: "datasheet", label: "Datasheet" },
+        { id: "release_notes", label: "Release notes" },
+      ],
+    },
+  ],
+  tags: [
+    "finance",
+    "legal",
+    "medical",
+    "hr",
+    "tax",
+    "insurance",
+    "marketing",
+    "technical",
+    "operations",
+    "academic",
+    "government",
+    "draft",
+    "final",
+    "signed",
+    "unsigned",
+    "executed",
+    "expired",
+    "amended",
+    "void",
+    "confidential",
+    "internal",
+    "public",
+    "pii",
+    "phi",
+    "certified",
+    "notarized",
+    "scanned",
+    "redacted",
+    "template",
+    "urgent",
+  ],
+};

frontend/editor/src/proprietary/data/policyDefinitions.tsx

@@ -16,6 +16,7 @@ import PublicIcon from "@mui/icons-material/Public";
 import CloudIcon from "@mui/icons-material/Cloud";
 import EmailOutlinedIcon from "@mui/icons-material/EmailOutlined";
 import FolderOpenIcon from "@mui/icons-material/FolderOpen";
+import LabelOutlinedIcon from "@mui/icons-material/LabelOutlined";
 import type {
   PolicyCategory,
   PolicyConfigDef,
@@ -42,6 +43,14 @@ export const POLICY_CATEGORIES: PolicyCategory[] = [
     icon: <ShieldIcon sx={ICON_SX} />,
     desc: "Detect PII, encrypt, verify authenticity, control access, and certify documents.",
   },
+  {
+    id: "classification",
+    label: "Classification",
+    icon: <LabelOutlinedIcon sx={ICON_SX} />,
+    desc: "Identify each document's type on upload and tag its metadata for filing and search.",
+    // Needs the AI engine to classify; hidden from the policy list when it's off.
+    requiresAiEngine: true,
+  },
   {
     id: "compliance",
     label: "Compliance",
@@ -204,6 +213,16 @@ export const POLICY_CONFIG: Record<string, PolicyConfigDef> = {
     // output naming + retries are set in the wizard.
     fields: [],
   },
+  classification: {
+    summary:
+      "Classifies every uploaded document and writes the result to its metadata.",
+    rules: ["Classify", "Tag metadata"],
+    // Single backend step: classify the document via the AI engine and store the
+    // result in the document's StirlingPDFClassification metadata field.
+    defaultOperations: [{ operation: "classify", parameters: {} }],
+    scopeLabel: "All PDFs on this device",
+    fields: [],
+  },
   compliance: {
     summary:
       "Validates documents against regulatory frameworks before they leave the system.",

frontend/editor/src/proprietary/hooks/useClassificationTaxonomy.ts

@@ -0,0 +1,85 @@
+/**
+ * Loads and persists the team's classification taxonomy. The backend
+ * (`/api/v1/classification/taxonomy`) is the source of truth and is shared by
+ * the whole team; a team with none falls back to the built-in default. Editing
+ * is gated to team leaders / admins by the backend — the caller passes
+ * `canConfigure` (the same policy gate) to keep read-only users out of the save
+ * path.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  DEFAULT_CLASSIFICATION_TAXONOMY,
+  type ClassificationTaxonomy,
+} from "@app/data/classificationTaxonomy";
+import {
+  fetchTeamTaxonomy,
+  saveTeamTaxonomy,
+} from "@app/services/taxonomyBackend";
+
+export interface UseClassificationTaxonomy {
+  /** Server-truth taxonomy (or the built-in default when the team has none). */
+  taxonomy: ClassificationTaxonomy;
+  /** Whether the team has a stored taxonomy (vs. the built-in default). */
+  isCustom: boolean;
+  loading: boolean;
+  saving: boolean;
+  /** Last save failure, cleared on the next attempt. */
+  error: string | null;
+  /** Persist a taxonomy for the team; resolves once server state is updated. */
+  save: (next: ClassificationTaxonomy) => Promise<void>;
+}
+
+export function useClassificationTaxonomy(
+  enabled: boolean,
+): UseClassificationTaxonomy {
+  const [taxonomy, setTaxonomy] = useState<ClassificationTaxonomy>(
+    DEFAULT_CLASSIFICATION_TAXONOMY,
+  );
+  const [isCustom, setIsCustom] = useState(false);
+  const [loading, setLoading] = useState(enabled);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    setLoading(true);
+    void (async () => {
+      try {
+        const stored = await fetchTeamTaxonomy();
+        if (cancelled) return;
+        setTaxonomy(stored ?? DEFAULT_CLASSIFICATION_TAXONOMY);
+        setIsCustom(stored != null);
+      } catch {
+        // Backend down / not permitted — fall back to the default (read-only).
+        if (!cancelled) {
+          setTaxonomy(DEFAULT_CLASSIFICATION_TAXONOMY);
+          setIsCustom(false);
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled]);
+
+  const save = useCallback(async (next: ClassificationTaxonomy) => {
+    setSaving(true);
+    setError(null);
+    try {
+      const saved = await saveTeamTaxonomy(next);
+      setTaxonomy(saved);
+      setIsCustom(true);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Couldn't save the taxonomy.");
+      throw e;
+    } finally {
+      setSaving(false);
+    }
+  }, []);
+
+  return { taxonomy, isCustom, loading, saving, error, save };
+}

frontend/editor/src/proprietary/hooks/usePolicies.ts

@@ -14,6 +14,7 @@ import {
   onPoliciesChange,
   updatePolicy,
   resetPolicy,
+  reorderPolicies as persistPolicyOrder,
 } from "@app/services/policyStorage";
 import { loadPolicyCatalog } from "@app/services/policyCatalog";
 import {
@@ -90,7 +91,12 @@ export function usePolicies() {
         const decoded = byCategory.get(cat.id);
         reconciled[cat.id] = decoded
           ? decodedToState(decoded, local[cat.id]?.folderId)
-          : { ...local[cat.id], configured: false, status: "default" };
+          : {
+              ...local[cat.id],
+              configured: false,
+              status: "default",
+              backendId: undefined,
+            };
       }
       for (const [id, state] of Object.entries(reconciled)) {
         updatePolicy(id, state);
@@ -134,6 +140,7 @@ export function usePolicies() {
         reviewerEmail: result.reviewerEmail,
         outputMode: result.folder.outputMode,
         outputName: result.folder.outputName,
+        outputNamePosition: result.folder.outputNamePosition,
         runOn: result.folder.runOn,
       });
     },
@@ -170,6 +177,7 @@ export function usePolicies() {
         reviewerEmail: result.reviewerEmail,
         outputMode: result.folder.outputMode,
         outputName: result.folder.outputName,
+        outputNamePosition: result.folder.outputNamePosition,
         runOn: result.folder.runOn,
       });
     },
@@ -234,6 +242,7 @@ export function usePolicies() {
         reviewerEmail: result.reviewerEmail,
         outputMode: result.folder.outputMode,
         outputName: result.folder.outputName,
+        outputNamePosition: result.folder.outputNamePosition,
         runOn: result.folder.runOn,
       });
     },
@@ -242,14 +251,42 @@ export function usePolicies() {
 
   const pausePolicy = useCallback(async (id: string) => {
     const current = loadPolicies()[id];
-    if (current?.backendId) await setPolicyEnabled(current.backendId, false);
+    if (current?.backendId) {
+      await setPolicyEnabled(current.backendId, false).catch((err: unknown) => {
+        if (
+          (err as { response?: { status?: number } })?.response?.status === 404
+        ) {
+          updatePolicy(id, {
+            backendId: undefined,
+            configured: false,
+            status: "default",
+          });
+          return;
+        }
+        throw err;
+      });
+    }
     if (current?.folderId) await setPolicyFolderPaused(current.folderId, true);
     updatePolicy(id, { status: "paused" });
   }, []);
 
   const resumePolicy = useCallback(async (id: string) => {
     const current = loadPolicies()[id];
-    if (current?.backendId) await setPolicyEnabled(current.backendId, true);
+    if (current?.backendId) {
+      await setPolicyEnabled(current.backendId, true).catch((err: unknown) => {
+        if (
+          (err as { response?: { status?: number } })?.response?.status === 404
+        ) {
+          updatePolicy(id, {
+            backendId: undefined,
+            configured: false,
+            status: "default",
+          });
+          return;
+        }
+        throw err;
+      });
+    }
     if (current?.folderId) await setPolicyFolderPaused(current.folderId, false);
     updatePolicy(id, { status: "active" });
   }, []);
@@ -261,6 +298,15 @@ export function usePolicies() {
     resetPolicy(id);
   }, []);
 
+  /**
+   * Persist a new execution order for the given categories (in the sequence
+   * provided). Local-only: order drives client-side chained dispatch, so there's
+   * no backend round-trip. The change event re-renders every policies consumer.
+   */
+  const reorderPolicies = useCallback((orderedCategoryIds: string[]) => {
+    persistPolicyOrder(orderedCategoryIds);
+  }, []);
+
   /**
    * Ensure a configured policy has a *valid* backing folder (its editable
    * pipeline) and return its id. Self-heals a stale `folderId` — one that no
@@ -312,6 +358,7 @@ export function usePolicies() {
     pausePolicy,
     resumePolicy,
     deletePolicy,
+    reorderPolicies,
     ensurePolicyFolder,
   };
 }

frontend/editor/src/proprietary/hooks/usePolicyCatalog.ts

@@ -1,4 +1,5 @@
 import { useMemo } from "react";
+import { useAiEngineEnabled } from "@app/hooks/useAiEngineEnabled";
 import {
   loadPolicyCatalog,
   type PolicyCatalog,
@@ -10,7 +11,20 @@ import {
  * directly. Memoised; when the catalog becomes a backend fetch, this hook is
  * where loading/error state would be introduced — its consumers already treat
  * it as the single source of definitions.
+ *
+ * Categories flagged {@link PolicyCategory.requiresAiEngine} are hidden while the
+ * AI engine is off, so a policy only appears where it can actually run.
  */
 export function usePolicyCatalog(): PolicyCatalog {
-  return useMemo(() => loadPolicyCatalog(), []);
+  const aiEngineEnabled = useAiEngineEnabled();
+  return useMemo(() => {
+    const catalog = loadPolicyCatalog();
+    if (aiEngineEnabled) return catalog;
+    return {
+      ...catalog,
+      categories: catalog.categories.filter(
+        (category) => !category.requiresAiEngine,
+      ),
+    };
+  }, [aiEngineEnabled]);
 }

frontend/editor/src/proprietary/hooks/usePolicyFileBadges.ts

@@ -1,4 +1,10 @@
-import { useMemo } from "react";
+import {
+  useMemo,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react";
 import { usePolicyRuns } from "@app/components/policies/policyRunStore";
 import type { PolicyRunRecord } from "@app/components/policies/policyRunStore";
 import { useAllFiles } from "@app/contexts/FileContext";
@@ -18,8 +24,22 @@ const ACCENT_VAR: Record<string, string> = {
   green: "var(--color-green)",
   amber: "var(--color-amber)",
   red: "var(--color-red)",
+  orange: "var(--color-orange)",
 };
 
+/** Glyph size for the file-sidebar policy badge. */
+const BADGE_ICON_SIZE = "0.7rem";
+
+/** Reuse a policy category's own icon at badge size,
+ * so each badge reflects its policy */
+function toBadgeIcon(icon: ReactNode): ReactNode {
+  return isValidElement(icon)
+    ? cloneElement(icon as ReactElement<{ sx?: object }>, {
+        sx: { fontSize: BADGE_ICON_SIZE },
+      })
+    : icon;
+}
+
 /** Minimal provenance shape needed to resolve a file's inherited badges. */
 type LineageStub = {
   id: string;
@@ -58,6 +78,7 @@ export function buildPolicyBadgeMap(
   stubs: ReadonlyArray<LineageStub>,
   labelById: ReadonlyMap<string, string>,
   now: number,
+  iconById?: ReadonlyMap<string, ReactNode>,
 ): Map<string, FileItemPolicyRef[]> {
   // Direct badges: a file that IS a policy run's output.
   const directByFile = new Map<string, FileItemPolicyRef[]>();
@@ -71,6 +92,7 @@ export function buildPolicyBadgeMap(
         list.push({
           id: run.categoryId,
           name,
+          icon: iconById?.get(run.categoryId),
           accentColor: ACCENT_VAR[ROW_ACCENT[run.categoryId] ?? "blue"],
           recent,
         });
@@ -121,9 +143,17 @@ export function usePolicyFileBadges(): Map<string, FileItemPolicyRef[]> {
   const runs = usePolicyRuns();
   const { fileStubs } = useAllFiles();
   return useMemo(() => {
-    const labelById = new Map(
-      loadPolicyCatalog().categories.map((c) => [c.id, c.label]),
+    const categories = loadPolicyCatalog().categories;
+    const labelById = new Map(categories.map((c) => [c.id, c.label]));
+    const iconById = new Map<string, ReactNode>(
+      categories.map((c) => [c.id, toBadgeIcon(c.icon)]),
+    );
+    return buildPolicyBadgeMap(
+      runs,
+      fileStubs,
+      labelById,
+      Date.now(),
+      iconById,
     );
-    return buildPolicyBadgeMap(runs, fileStubs, labelById, Date.now());
   }, [runs, fileStubs]);
 }